docs: clarify auto_fixable in JSON actions[] is per-finding#392
Merged
Conversation
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
Collaborator
Author
|
Released in v2.76.0. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The JSON
actions[]array has two semantically distinct shapes ofauto_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 onauto_fixable: trueto decide what is safe to apply blindly.Document per-finding evaluation across every surface. No behavior change.
IssueActionand per-field docs onFixAction.auto_fixableandAddToConfigAction.auto_fixableincrates/types/src/output.rscall out the rule and enumerate the four current per-instance flips.field_definitions: { actions[], actions[].auto_fixable }block in thecheck/health/dupesJSON_metapayloads carries the same wording (shared via two const strings incrates/cli/src/explain.rsso wording stays in sync).docs/output-schema.jsonregenerated viacargo run -p fallow-cli --features schema-emit --bin fallow-schema-emit: three description fields updated onIssueAction,FixAction.auto_fixable,AddToConfigAction.auto_fixable.output-contract.d.ts) regenerated viapnpm run codegen:typesso JSDoc reflects the new wording.crates/cli/src/explain.rsassert the per-finding wording and the shared constants across all three_metabuilders.[Unreleased]-> Documentation.fallow-rs/docs(analysis/auto-fix.mdxadds a "per-finding semantics" section;cli/dead-code.mdxtightens theactions[]table row) andfallow-rs/fallow-skills(cli-reference.mdtable row + per-instance flip list).The four currently active per-instance flips, all documented in the new prose:
remove-catalog-entry(unused-catalog-entries):trueonly when the finding'shardcoded_consumersarray is empty (elsefallow fixskips the entry to avoid breakingpnpm install).remove-dependencyvsmove-dependency(dependency findings): primary action flips onused_in_workspaces.add-to-configforignoreExports(duplicate-exports):trueonly when a fallow config file exists on disk.update-catalog-reference(unresolved-catalog-references): alwaysfalsetoday; non-singleton on the wire so a future applier can promote it without a schema change.All
suppress-lineandsuppress-fileactions remain uniformlyfalse.Closes #361.
Test plan
cargo test --workspace --all-targets(37 test results, 0 failures)cargo clippy --workspace --all-targets -- -D warningscleancargo fmt --all -- --checkcleancargo doc --workspace --no-deps --document-private-itemsno warningspnpm run check:codegenclean after regen (bothoutput-contract.d.tsfiles regenerated and committed)cargo test -p fallow-cli --lib check_meta_documents_per_finding_auto_fixablepasses (asserts the wording calls outPER FINDING,remove-catalog-entry,used_in_workspaces,ignoreExports)cargo run -p fallow-cli --features schema-emit --bin fallow-schema-emit | diff docs/output-schema.json -shows only the three intended description updatesadd-catalog-entryfrom the always-false bucket, intentionally out of scope: this PR documents per-instance flips, not every always-false action type)