Skip to content

docs: clarify auto_fixable in JSON actions[] is per-finding#392

Merged
BartWaardenburg merged 1 commit into
mainfrom
docs/issue-361-auto-fixable-per-finding
May 18, 2026
Merged

docs: clarify auto_fixable in JSON actions[] is per-finding#392
BartWaardenburg merged 1 commit into
mainfrom
docs/issue-361-auto-fixable-per-finding

Conversation

@BartWaardenburg
Copy link
Copy Markdown
Collaborator

Summary

The JSON actions[] array has two semantically distinct shapes of auto_fixable: per-rule (the rule type can be auto-fixed; constant across every finding for that issue type) and per-instance (the bool depends on the specific finding's payload, not the action type). The distinction matters for agents that filter on auto_fixable: true to decide what is safe to apply blindly.

Document per-finding evaluation across every surface. No behavior change.

  • Enum-level doc on IssueAction and per-field docs on FixAction.auto_fixable and AddToConfigAction.auto_fixable in crates/types/src/output.rs call out the rule and enumerate the four current per-instance flips.
  • New field_definitions: { actions[], actions[].auto_fixable } block in the check / health / dupes JSON _meta payloads carries the same wording (shared via two const strings in crates/cli/src/explain.rs so wording stays in sync).
  • docs/output-schema.json regenerated via cargo run -p fallow-cli --features schema-emit --bin fallow-schema-emit: three description fields updated on IssueAction, FixAction.auto_fixable, AddToConfigAction.auto_fixable.
  • VS Code + npm typed contracts (output-contract.d.ts) regenerated via pnpm run codegen:types so JSDoc reflects the new wording.
  • Two new unit tests in crates/cli/src/explain.rs assert the per-finding wording and the shared constants across all three _meta builders.
  • CHANGELOG entry under [Unreleased] -> Documentation.
  • Companion repos: matching updates in fallow-rs/docs (analysis/auto-fix.mdx adds a "per-finding semantics" section; cli/dead-code.mdx tightens the actions[] table row) and fallow-rs/fallow-skills (cli-reference.md table row + per-instance flip list).

The four currently active per-instance flips, all documented in the new prose:

  • remove-catalog-entry (unused-catalog-entries): true only when the finding's hardcoded_consumers array is empty (else fallow fix skips the entry to avoid breaking pnpm install).
  • remove-dependency vs move-dependency (dependency findings): primary action flips on used_in_workspaces.
  • add-to-config for ignoreExports (duplicate-exports): true only when a fallow config file exists on disk.
  • update-catalog-reference (unresolved-catalog-references): always false today; non-singleton on the wire so a future applier can promote it without a schema change.

All suppress-line and suppress-file actions remain uniformly false.

Closes #361.

Test plan

  • cargo test --workspace --all-targets (37 test results, 0 failures)
  • cargo clippy --workspace --all-targets -- -D warnings clean
  • cargo fmt --all -- --check clean
  • cargo doc --workspace --no-deps --document-private-items no warnings
  • pnpm run check:codegen clean after regen (both output-contract.d.ts files regenerated and committed)
  • cargo test -p fallow-cli --lib check_meta_documents_per_finding_auto_fixable passes (asserts the wording calls out PER FINDING, remove-catalog-entry, used_in_workspaces, ignoreExports)
  • Manual spot-check: cargo run -p fallow-cli --features schema-emit --bin fallow-schema-emit | diff docs/output-schema.json - shows only the three intended description updates
  • json-output-reviewer agent pass (APPROVE; one minor non-blocking note about omitting add-catalog-entry from the always-false bucket, intentionally out of scope: this PR documents per-instance flips, not every always-false action type)

The JSON `actions[]` array has two semantically distinct shapes of
`auto_fixable`: per-rule (the rule type can be auto-fixed; constant
across every finding for that issue type) and per-instance (the bool
depends on the specific finding's payload, not the action type). The
distinction matters for agents that filter on `auto_fixable: true` to
decide what is safe to apply blindly.

Document per-finding evaluation across every surface:

- Enum-level doc on `IssueAction` and per-field docs on
  `FixAction.auto_fixable` and `AddToConfigAction.auto_fixable` call
  out the rule and enumerate the four current per-instance flips.
- New `field_definitions: { actions[], actions[].auto_fixable }` block
  in the `check` / `health` / `dupes` JSON `_meta` payloads carries
  the same wording (shared via two const strings to keep wording in
  sync).
- `docs/output-schema.json` regenerated: three description fields
  updated on `IssueAction`, `FixAction.auto_fixable`,
  `AddToConfigAction.auto_fixable`.
- VS Code + npm typed contracts regenerated via
  `pnpm run codegen:types` so JSDoc reflects the new wording.

The four currently active per-instance flips:

- `remove-catalog-entry`: `true` only when `hardcoded_consumers` is
  empty (else fallow fix skips to avoid breaking pnpm install).
- `remove-dependency` vs `move-dependency`: primary action flips on
  `used_in_workspaces`.
- `add-to-config` for `ignoreExports`: `true` only when a fallow
  config file exists on disk.
- `update-catalog-reference`: always `false` today, non-singleton on
  the wire for forward compat.

All `suppress-line` / `suppress-file` actions remain uniformly false.

Two new unit tests in `crates/cli/src/explain.rs` assert the per-finding
wording and the shared constants across all three `_meta` builders.

No behavior change. Closes #361
@BartWaardenburg BartWaardenburg merged commit 7d66774 into main May 18, 2026
20 checks passed
@BartWaardenburg BartWaardenburg deleted the docs/issue-361-auto-fixable-per-finding branch May 18, 2026 08:43
@BartWaardenburg
Copy link
Copy Markdown
Collaborator Author

Released in v2.76.0.

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.

Document per-instance auto_fixable semantics in JSON schema + explain.rs

1 participant