feat: --no-fail-public — report unused public declarations without failing the build

[claude]

Requested by Łukasz Komoszyński · Slack thread

Before

--set-exit-if-changed fails the build on any unused declaration. The only way to avoid failing on public API — which is legitimately "unused" from a library or workspace package's own perspective — is --no-public, which hides those findings entirely. You could either see the public findings or gate CI on private ones, never both in a single run.

After

--no-fail-public keeps public findings in the report but excludes them from the exit code, so CI can surface unused public API as advisory while still failing only on unused private declarations. The default is unchanged (--fail-public on): --set-exit-if-changed still fails on anything unless you opt out.

ciach . --set-exit-if-changed --no-fail-public   # report public, gate on private

Why

Requested for leancode_flutter_template's CI (leancode_flutter_template#730), where the workspace has intentional-but-unused public API for downstream generated apps. This lets one ciach run both report everything and gate on private only, instead of choosing between the two.

How

• New negatable flag --fail-public (default true) in lib/src/cli/args.dart, next to the --public group.
• In bin/ciach.dart, the exit-code decision now computes a failing subset of result.unused; when --fail-public is off it excludes public findings using ciach's existing public/private determination (UnusedDeclaration.isPrivate, i.e. isPrivateName — the same rule --no-public uses to filter), returning 1 iff the subset is non-empty.
• The report path is unchanged — public findings are still printed. With --no-public (public already filtered out) --no-fail-public is a no-op.
• Precedent: doc-only findings already report without counting toward the exit code; this extends the same "report but don't fail" treatment to public findings on demand.
• Added a CLI exit-code test (test/cli_exit_code_test.dart) driving the real binary against the sample_pkg fixture, asserting exit 0 for public-only + --no-fail-public, exit 1 when a private finding is present, and exit 1 for --set-exit-if-changed alone.

---

Generated by Claude Code