Skip to content

feat(#1): exit code semantics for CI and git hook integration - #7

Merged
machado144 merged 4 commits into
mainfrom
feat/1-exit-code-semantics
Apr 2, 2026
Merged

machado144 merged 4 commits into
mainfrom
feat/1-exit-code-semantics

Conversation

@machado144

Copy link
Copy Markdown
Contributor

Closes #1

Changes

  • Exit 1 when clones are detected — git hooks and CI pipelines can now gate on dupehound scan
  • Exit 0 when no clones found (clean codebase)
  • Exit 2 on tool errors (bad path, invalid format, etc.) — distinguishable from "clones found"
  • --exit-zero flag — forces exit 0 regardless of findings, for reporting pipelines that must not fail
  • Fixed a logic bug where the exit code check was placed after an early return nil in the stdout output path

Usage

# pre-commit hook — blocks commit if duplicates exist
dupehound scan --path .
# exit 1 → commit blocked

# CI reporting step — collects results without failing the pipeline
dupehound scan --path . --format json --output report.json --exit-zero

Test plan

  • TestExitCode_ClonesFound_ExitsOne — exit code 1 when duplicates found
  • TestExitCode_NoClonesFound_ExitsZero — exit code 0 when clean
  • TestExitCode_ExitZeroFlag_SuppressesOne — --exit-zero forces exit 0 even with clones
  • TestExitCode_ToolError_ExitsTwo — exit code 2 on bad path
  • All existing tests updated to use --exit-zero where they care about output content, not exit code
  • 85/85 tests pass

- exit 1 when clones found, exit 0 when clean, exit 2 on tool error
- add --exit-zero flag to force exit 0 regardless of findings
- fix scan action to check clone count after both stdout and file output paths
- update integration tests to use --exit-zero where output content is the concern
- add four dedicated exit code tests covering all code paths
- add pull-requests: write permission to validate-title job
- replace invalid 'model' input with correct AI_PROVIDER/AI_MODEL/AI_API_KEY
- pass GEMINI_API_KEY via with.AI_API_KEY instead of env var
- replace external semantic-pr action with inline conventional commits check
  that posts a PR comment on failure (matches aigate pattern)
- fix reviewforge inputs: GITHUB_TOKEN/AI_PROVIDER/AI_MODEL/AI_API_KEY as with: inputs
- add CUSTOM_RULES_FILE pointing to .github/reviewforge-rules.txt with dupehound-specific
  focus areas (tokenizer correctness, exit codes, off-by-one in line ranges)
- move permissions to workflow level (contents: read, pull-requests: write)
- allow *.txt in structlint to cover .github/reviewforge-rules.txt
@github-actions

github-actions Bot commented Apr 2, 2026 •

Copy link
Copy Markdown

StructLint — All checks passed

43 rules validated against .structlint.yaml. No violations found.

View full run · Powered by StructLint

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Core Changes

This PR introduces a robust exit code contract for dupehound, enhancing its integration capabilities with CI pipelines and git hooks. The tool now exits with:

  • 0: No duplicate code found (clean run).
  • 1: Duplicate code detected.
  • 2: A tool error occurred (e.g., invalid path, bad arguments).

A new --exit-zero flag has been added to allow users to suppress the exit code 1 (clones found) for reporting-only scenarios. A critical bug was fixed where the tool would always exit 0 when outputting to stdout, even if clones were found, preventing proper exit code propagation.

Additionally, the GitHub Actions workflow has been updated to:

  • Implement custom Conventional Commits validation for PR titles, including commenting on the PR if the title is invalid.
  • Integrate reviewforge with custom review rules defined in .github/reviewforge-rules.txt.
  • Update structlint configuration to allow .txt files.

Concerns

None. The changes are well-tested, address a clear need, and improve the tool's usability and integration.

Verdict

Approve


Code review performed by GEMINI - gemini-2.5-flash.

Comment thread actions/scan.go
if outFile == "" {
fmt.Print(output)
return nil
} else {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION] The logic here correctly ensures that the clone detection check and subsequent exit code logic are always reached, regardless of whether output is printed to stdout or a file. This fixes the bug where return nil would short-circuit the exit code determination for stdout cases.

Comment thread main.go
@@ -48,6 +49,11 @@ func main() {
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION] Changing Log.Fatal to Log.Error is a good improvement. Log.Fatal typically calls os.Exit(1) by default, which would conflict with the new exit code 2 for general tool errors. Explicitly logging an error and then calling os.Exit(2) provides clearer control over the exit code semantics.

test.yml now triggers on push to main as well as PRs — this is what
distinguishes it from pr.yml (which is PR automation only: title check,
AI review, structlint). Both files serve different purposes with no overlap.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Core Changes

This PR introduces a robust exit code contract for dupehound, making it more suitable for CI/CD pipelines and git hooks. The tool now exits with:

  • 0: No duplicates found (clean run).
  • 1: Duplicates found.
  • 2: A tool error occurred (e.g., invalid path, bad arguments).

A new --exit-zero flag has been added to allow users to suppress the exit code 1 when clones are found, which is useful for reporting-only pipelines that should not fail.

Key changes include:

  • Refactoring the scan action to correctly handle output to stdout/file and then evaluate the exit code based on clone detection and the --exit-zero flag.
  • Updating the main function to catch helpers.ErrClonesFound and exit with code 1, while other errors result in exit code 2.
  • Comprehensive integration tests for all new exit code scenarios.
  • CI workflow enhancements: PR title validation using Conventional Commits, splitting the test workflow into distinct test, vuln, and lint jobs for better clarity and parallelization, and integrating reviewforge with custom review rules.

Concerns

  • The custom script for PR title validation, while functional, is more verbose and less maintainable than using a dedicated GitHub Action for Conventional Commits validation. It also duplicates logic that could be handled by a more specialized tool.

Verdict

Approve: The core changes to the exit code semantics are critical for the usability of dupehound in automated environments and are well-implemented and thoroughly tested. The CI improvements are also valuable additions. The concern about the PR title validation script is minor and does not warrant requesting changes.


Code review performed by GEMINI - gemini-2.5-flash.

Comment thread .github/workflows/pr.yml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TITLE: ${{ github.event.pull_request.title }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION] While this custom script works, using a dedicated GitHub Action for Conventional Commits (like amannn/action-semantic-pull-request which was previously used) is generally more robust, easier to maintain, and less prone to shell scripting errors. Consider reverting to a dedicated action or encapsulating this logic in a reusable composite action if custom behavior is strictly necessary.

Comment thread actions/scan.go
@@ -73,13 +73,15 @@ func (a *ScanAction) Execute(c *cli.Context) error {
outFile := c.String("output")
if outFile == "" {
fmt.Print(output)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[CRITICAL] This change correctly moves the return nil statement, ensuring that the exit code logic is always evaluated after outputting the report. In the previous version, if outFile was empty, the function would return early, bypassing the check for report.TotalClones > 0 and always exiting with 0, which was a logic bug for the intended exit code contract.

Comment thread helpers/errors.go
ErrInvalidMinLines = errors.New("min-lines must be greater than 0")
ErrInvalidMinTokens = errors.New("min-tokens must be greater than 0")
ErrPathNotFound = errors.New("path does not exist")
// ErrClonesFound is returned by the scan action when duplicates are detected.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION] The addition of ErrClonesFound is crucial for distinguishing between a successful scan with findings and a tool error, allowing main() to return the correct exit code (1 vs. 2). The comment clearly explains its purpose.

Comment thread integration/cli_test.go
@@ -90,7 +90,7 @@ func TestScanDetectsDuplicate(t *testing.T) {
writeFile(t, dir, "a.go", "package main\n\n"+block)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION] It's good practice to update existing tests that expect clones to be found to use the --exit-zero flag when the test's primary focus is on the content of the output rather than the exit code. This prevents the tests from failing due to the new exit code semantics.

Comment thread integration/cli_test.go
t.Errorf("window merging broken: %d large clones, expected 1", large)
}
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[SUGGESTION] These new integration tests are excellent. They thoroughly cover the new exit code contract, ensuring that the tool behaves as expected in all defined scenarios (clones found, no clones, --exit-zero flag, and tool errors). This significantly improves the reliability of the CLI.

@machado144
machado144 merged commit a923b77 into main Apr 2, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: exit code semantics for CI and git hook integration

1 participant

⌂ 换网址