fix(cli): explicitly named files with unrecognized languages are skipped silently with exit 0

[dekobon]

Current behavior

bca metrics -p notes.txt produces no output, no message, and exit 0 — verified. Only with -w does the tool reveal "warning: skipping file with unrecognized language: notes.txt" (big-code-analysis-cli/src/dispatch.rs:138).

Why it's a UX problem

Asymmetry with #596, which made a nonexistent explicit path a hard error (exit 1). An existing explicit file the tool cannot parse is the same class of user error — the user named one file and got nothing back — yet it stays completely silent. Warnings-off-by-default is defensible for directory walks (a tree full of READMEs and configs would be noisy); it is not defensible for explicitly enumerated files, where silence reads as "this file has no metrics".

Proposed 2.0 design

When a seed path is an explicit file (not the product of a directory expansion) whose language is unrecognized, warn on stderr by default — or error, with --language as the escape hatch for files whose extension lies about their content. Directory-walk skips stay gated behind -w.

Breaking

Yes — new stderr output (or a new error) for invocations that today exit 0 silently.

Found by the 2026-06 follow-up 2.0 UX audit. Rolls up under #505.
Related: #596.

---

Resolution Plan

Decision settled (design audit, 2026-06-10)

Warn always for explicit unrecognized files; exit 1 only when NO output was
produced. An explicitly-named file whose language is unrecognized always
warns on stderr (not gated behind -w); the run exits 1 only when the net
result is empty — i.e. every named file was unrecognized — mirroring #596's
"you asked and got nothing." A mixed run (recognized .rs + an unrecognized
.txt) still succeeds (exit 0) with a visible warning. --language is the
escape hatch for files whose extension lies. Directory-walk skips stay gated
behind -w.

Steps

1. Distinguish explicit seed files from directory-expansion products in the
   walker (the dispatch already knows seed origin near
   big-code-analysis-cli/src/dispatch.rs:138). For an explicit file with an
   unrecognized language, emit the skip warning unconditionally (route through
   style(cli): unify diagnostic prefixes across the binary #609's warn() once it lands).
2. Track whether any analyzable output was produced. If the run produced zero
   results and at least one explicit file was skipped for unrecognized
   language, exit 1 with a clear message (parallel to refactor(cli)!: default walk commands to "." and fail on nonexistent --paths #596's nonexistent-path
   error). Otherwise exit 0.
3. Leave directory-walk unrecognized-language skips gated behind -w (a tree of
   READMEs/configs must not be noisy).
4. Tests: bca metrics -p notes.txt → warning + exit 1 (was silent exit 0);
   bca metrics src/lib.rs notes.txt → analyzes lib.rs, warns about notes.txt,
   exit 0; --language rust -p notes.txt parses it; directory walk over a
   tree with a README stays quiet without -w.
5. CHANGELOG ## [Unreleased]: (breaking) entry, deferred to 2.0 (new
   stderr output + possible exit-1).
6. make pre-commit.

Related

• refactor(cli)!: default walk commands to "." and fail on nonexistent --paths #596 (nonexistent explicit path → exit 1, the parallel this completes), style(cli): unify diagnostic prefixes across the binary #609
  (warn() helper). Rolls up under track(2.0): breaking-change roadmap for the 2.x major bump #505.

Assessment

Dimension	Rating
Difficulty	Low
Complexity	Medium
Priority	High

[dekobon]

Resolved in #713 — the milestone-2.0 breaking-change batch (branch feat/2.0). Closing per the batch sign-off; will also auto-close on merge.