Skip to content

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

@BartWaardenburg

Description

@BartWaardenburg

Follow-up to #335.

The JSON actions[] array has two semantically distinct shapes of auto_fixable:

  1. Per-rule: the rule type can be auto-fixed (most actions today). Constant across every finding for that issue type. Example: every remove-export action has auto_fixable: true.
  2. Per-instance: the bool depends on the specific finding's payload, not the issue type. Example (since fallow fix: auto-remove unused entries from pnpm-workspace.yaml #335): remove-catalog-entry is auto_fixable: true when hardcoded_consumers is empty, false otherwise. Sibling: update-catalog-reference from Unresolved catalog reference: warn when consumer uses catalog:X but X catalog lacks the package #334 is auto_fixable: false until available_in_catalogs has exactly one entry.

The distinction matters for agents that filter on auto_fixable: true to decide what's safe to apply blindly. Per-instance semantics is the correct model (matches ESLint's RuleFix | RuleFix[] | null return shape), but it's currently undocumented.

Proposed solution

  • Add a _meta entry in crates/cli/src/explain.rs documenting auto_fixable as per-instance ("evaluated per finding") and citing the issue types that currently use per-instance flipping.
  • Add the same note to docs/output-schema.json next to the actions[].auto_fixable field definition.
  • Update fallow-docs/analysis/auto-fix.mdx and fallow-skills cli-reference.md with the same wording.

Low-priority polish; no behavior change.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions