feat: mxcli search --fail-on-match exits 1 on a hit, 0 on none

[stagknee]

Part of #1477. It was split out of #1478 at review, and it is independent of that PR because it is based on main.

What it does

mxcli search … --fail-on-match turns a search into a gate:

Exit status	Meaning
0	no hit
1	at least one hit
2	the search could not run (an unbalanced ", an unknown project)

Results are printed as before (a JSON array under --json). Without the flag a hit still exits 0, and the SEARCH statement is unchanged.

How

• SearchOptions{Strict bool} and Executor.SearchWith return the hit count.
• Strict returns the index's error for a query it can't run. Without it, the error is swallowed as "no matches", as before. A gate needs this difference, because "nothing found" and "could not look" are not the same answer.
• The command maps the count and the error to the exit status. It closes the executor and the log before os.Exit(1).
• Docs: a "Failing on a match" section in docs-site/src/tools/search.md, plus the help text, the syntax entry and a CHANGELOG entry under Added.

Evidence

• Tests: TestSearchFailOnMatch_ExitCode, TestSearchWithoutFailOnMatch_HitExitsZero, TestSearchFailOnMatch_UnrunnableQueryExitsTwo, TestSearchWith_ReturnsTheNumberOfHits and TestSearchWith_StrictReportsAQueryTheIndexRejects (in table and JSON formats).

  • With the implementation stashed, the exit-code tests fail (the flag is unknown, so they exit 1, and the unrunnable-query test gets 1 instead of 2), and the executor tests don't compile.
  • HitExitsZero is a regression guard and passes both ways.

• Real app (Mendix 11.12.5):

  Command	Exit
  --fail-on-match on a hit	1
  --fail-on-match on no hit	0
  --fail-on-match on "unbalanced	2
  --fail-on-match on an unknown project	2
  the same hit without the flag	0

• Windows: the failing tests across mdl/executor and cmd/mxcli are the same set as on main.

• Linux (golang:1.26.6-bookworm, ANTLR 4.13.2, as in CI): make grammar build test check-mdl check-findings check-conformance check-migration-reference lint-go all pass.

--exclude-marketplace (#1493) also adds a field to SearchOptions. Whichever PR lands second will need a small rebase, and I'll do it.

🤖 Generated with Claude Code

[github-actions]

AI Code Review

Summary

The PR adds --fail-on-match flag to mxcli search to make it exit 1 on hits, 0 on no hits, and 2 on errors. Changes span CLI flag handling, executor logic for hit counting and error propagation, tests, documentation, and syntax help. No MDL grammar changes are involved.

Critical Issues

None found.

Moderate Issues

None found.

Minor Issues

None found.

What Looks Good

• Atomic scope: Focused solely on adding the --fail-on-match flag without touching unrelated areas.
• Thorough testing: Includes unit tests for exit codes, hit counting, and error handling; regression guards; real-app validation.
• Clear documentation: Docs updated with exit status table, examples, and help text.
• Correct error propagation: Distinguishes "no matches" (exit 0) from "could not run" (exit 2) when flag is set.
• Clean resource management: Closes executor and logger before os.Exit(1) to avoid leaks.
• Consistent patterns: Follows existing code style, uses helper functions (searchWith, SearchOptions), and maintains backward compatibility.
• Changelog entry: Properly categorized under "Added".

Recommendation

Approve. The PR is ready for merge. No blocking issues identified.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source