madr-lint 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -5,6 +5,38 @@ type MdastNodeType = Root['type'] | Nodes['type'];
 type MdastNode = Root | Nodes;
 /** Severity levels supported by every rule. */
 type Severity = 'error' | 'warn';
+/**
+ * A raw-text edit: replace `content.slice(range[0], range[1])` with `text`.
+ * Offsets are into the ORIGINAL WHOLE-FILE content (frontmatter included) —
+ * the applier's coordinate space. Rules never build these directly; they call
+ * the `Fixer` helpers, which translate body (mdast) offsets to whole-file
+ * offsets. See ADR-0008.
+ */
+interface TextEdit {
+    range: readonly [number, number];
+    text: string;
+}
+/**
+ * Helpers handed to a rule's `fix` thunk. Range / offset arguments are in
+ * BODY (mdast) coordinates — the same space as `node.position.*.offset` — and
+ * the fixer adds the stripped-frontmatter length so the returned `TextEdit`
+ * carries whole-file offsets. Keep the surface minimal: replace, insert, remove.
+ */
+interface Fixer {
+    /** Replace the body range with `text`. */
+    replaceRange(range: readonly [number, number], text: string): TextEdit;
+    /** Insert `text` at a body offset (zero-width edit). */
+    insertAt(offset: number, text: string): TextEdit;
+    /** Delete the body range. */
+    remove(range: readonly [number, number]): TextEdit;
+}
+/**
+ * A lazy fix producer. Invoked ONLY when fixing is requested (zero cost on a
+ * normal lint). Returns one edit, several, or `null` to decline (e.g. the
+ * concrete fix is not mechanically safe for this occurrence). A rule may only
+ * attach a fix when its `meta.fixable === 'code'`.
+ */
+type FixFn = (fixer: Fixer) => TextEdit | TextEdit[] | null;
 /**
  * The reserved rule name used for internal-error diagnostics. A real rule
  * cannot register with this name (the registry should reject collisions).
@@ -33,6 +65,21 @@ interface RuleMeta<TOptions = Record<string, unknown>> {
     };
     /** messageId -> template string with {{placeholders}}. */
     messages: Record<string, string>;
+    /**
+     * messageId -> machine-actionable remediation template, parallel to
+     * `messages` and interpolated the same way. Partial: declare an entry only
+     * where a concrete, mechanical fix exists; omit where the fix is inherently
+     * contextual. The runner resolves the entry for a reported messageId into
+     * `Diagnostic.suggestion` (null when absent). See issue #67.
+     */
+    suggestions?: Record<string, string>;
+    /**
+     * Whether this rule can produce autofixes. `'code'` = the rule may attach a
+     * `fix` thunk to `context.report(...)`; the runner honors it only for
+     * fixable rules and routes a fix from a non-fixable rule through
+     * `core/internal-error` (a rule bug). Defaults to `false`. See ADR-0008.
+     */
+    fixable?: 'code' | false;
     /** Default options merged with user config. */
     defaultOptions: TOptions;
     /** AJV JSON Schema for options. Validated at runRule time. */
@@ -60,6 +107,33 @@ interface Diagnostic {
     };
     /** Data for placeholder interpolation in messages[messageId]. */
     data?: Record<string, unknown>;
+    /**
+     * Machine-actionable remediation, resolved by the runner at report time from
+     * `rule.meta.suggestions[messageId]` (interpolated with `data`, exactly like
+     * the message). `null` when the rule declares no suggestion for this
+     * messageId. Every runner-produced diagnostic sets this. See issue #67.
+     */
+    suggestion: string | null;
+    /**
+     * The rule's documentation URL (`rule.meta.docs.url`), resolved by the runner
+     * so consumers need not reconstruct it from `ruleName`. `core/internal-error`
+     * diagnostics point at the repository; a rule without a docs URL yields `''`.
+     */
+    docsUrl: string;
+    /**
+     * Whether an autofix is available for THIS diagnostic — the rule is
+     * `meta.fixable: 'code'` AND attached a `fix` thunk here. Durable (serialized
+     * to the cache and json output; reporters render a 🔧 marker). Every
+     * runner-produced diagnostic sets this. See ADR-0008 / issue #28.
+     */
+    fixable: boolean;
+    /**
+     * The live fix producer, present only when `fixable` is true. TRANSIENT — a
+     * closure, so it is dropped by JSON serialization (cache / json output) and
+     * absent on cache-hydrated diagnostics. Consumed by the autofix applier
+     * (`src/core/fix.ts`) after suppression + baseline filtering. See ADR-0008.
+     */
+    fix?: FixFn;
 }
 interface RuleContext<TOptions = Record<string, unknown>> {
     /** The file being linted. */
@@ -86,10 +160,27 @@ interface RuleContext<TOptions = Record<string, unknown>> {
         line: number;
         column: number;
     }> | null;
+    /**
+     * Body-coordinate offset RANGE of the effective value for `metadata` keys
+     * whose value came from the v2 leading list AND was a single contiguous text
+     * token (no inline markup). Autofix uses this to target the value precisely
+     * (e.g. rewrite the status value in place). Frontmatter-sourced keys are
+     * absent — frontmatter is stripped before mdast parsing, so it has no body
+     * offset and needs YAML-aware rewriting instead. null when nothing qualifies.
+     * See ADR-0008.
+     */
+    metadataValueLoc: Record<string, {
+        start: number;
+        end: number;
+    }> | null;
     /** User-merged options for this rule (validated against rule.meta.schema). */
     options: TOptions;
-    /** Emit a diagnostic. */
-    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'path'>): void;
+    /**
+     * Emit a diagnostic. `suggestion` / `docsUrl` / `fixable` are resolved by the
+     * runner. A rule may pass a `fix` thunk ONLY when its `meta.fixable` is
+     * `'code'` (otherwise the runner routes it through `core/internal-error`).
+     */
+    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'path' | 'suggestion' | 'docsUrl' | 'fixable'>): void;
 }
 /**
  * Visitor map dispatched during single-pass mdast traversal.
@@ -156,9 +247,9 @@ interface ProjectRuleContext<TOptions = Record<string, unknown>> {
     /**
      * Emit a diagnostic. Unlike per-file rules, project rules MUST set
      * `path` explicitly — the runner cannot infer which file the
-     * diagnostic relates to.
+     * diagnostic relates to. `suggestion` / `docsUrl` are resolved by the runner.
      */
-    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity'>): void;
+    report(diagnostic: Omit<Diagnostic, 'ruleName' | 'severity' | 'suggestion' | 'docsUrl' | 'fixable'>): void;
 }
 /**
  * A cross-file rule. Receives all parsed files at once and reports
@@ -177,6 +268,79 @@ type AnyRule<TOptions = Record<string, unknown>> = Rule<TOptions> | ProjectRule<
 /** Type guard distinguishing project rules from per-file rules. */
 declare function isProjectRule(rule: AnyRule): rule is ProjectRule;
 
+/** Fixpoint iteration cap (matches ESLint's autofix passes). */
+declare const MAX_FIX_PASSES = 10;
+/**
+ * Build a `Fixer` whose helpers take BODY offsets and emit whole-file
+ * `TextEdit`s by adding `frontmatterOffset` (the length gray-matter stripped).
+ */
+declare function makeFixer(base: number): Fixer;
+/**
+ * Apply text edits to `content` in a single pass. Edits are sorted by start
+ * offset; any edit overlapping a previously-applied one is dropped (first wins).
+ * Invalid ranges (non-integer, negative, inverted, out of bounds) are dropped.
+ * Whole-file offsets in, new string out.
+ */
+declare function applyEdits(content: string, edits: readonly TextEdit[]): string;
+/**
+ * Counting variant of `applyEdits`: `applied` is the number of edits that
+ * actually LANDED (post overlap/bounds filtering) — the honest source for
+ * `summary.fixed`, which must not count dropped edits. Exported for the
+ * cross-file fixpoint (`lintAndFix`), which applies project-rule edits per file
+ * and needs the landed count.
+ */
+declare function applyEditsCounted(content: string, edits: readonly TextEdit[]): {
+    text: string;
+    applied: number;
+};
+/**
+ * Invoke each diagnostic's `fix` thunk (if any) with a `Fixer` built for
+ * `content`, flattening arrays and skipping thunks that decline (return null).
+ * The frontmatter offset is derived from `content` so translation always
+ * matches the exact bytes being edited.
+ */
+declare function collectFixes(diagnostics: readonly Diagnostic[], content: string): TextEdit[];
+/**
+ * Collect CROSS-FILE (project-rule) fixes, grouped by the file each edits.
+ * A project diagnostic names the file it targets via `diagnostic.path`; its fix
+ * emits an edit for THAT file. Unlike per-file fixes, project fixes operate in
+ * WHOLE-FILE coordinates: they may edit YAML frontmatter, which body (mdast)
+ * coordinates strip, so there is no frontmatter shift to add — the fixer's base
+ * is 0. See #29 (ADR-0008's per-file edit-set seam).
+ *
+ * `contentByPath(path)` returns the current content of a target file, or
+ * undefined if it is not in the fix set (its edits are then skipped). At most
+ * ONE fix contributes per file per pass — a second insertion at the same spot
+ * would duplicate a key; the fixpoint re-runs the project pass so the runners-up
+ * re-evaluate against the now-edited file (and typically decline).
+ */
+declare function collectProjectFixes(diagnostics: readonly Diagnostic[], contentByPath: (path: string) => string | undefined): Map<string, TextEdit[]>;
+interface FixFileResult {
+    /** Content after the fixpoint loop (unchanged if nothing applied). */
+    fixedContent: string;
+    /** Diagnostics of the FINAL content (post-suppression / -baseline via `lint`). */
+    remaining: Diagnostic[];
+    /** Whether any edit actually changed the content. */
+    changed: boolean;
+    /** Number of applied passes (0 when nothing was fixed). */
+    passes: number;
+    /** Edits that actually LANDED across all passes (dropped edits excluded). */
+    applied: number;
+}
+/**
+ * Drive the autofix fixpoint for ONE file. `lint(content)` must return the
+ * REPORTED diagnostics for `content` — already suppression- and
+ * baseline-filtered — carrying live `fix` thunks. The loop lints at the top of
+ * every iteration, so `remaining` always reflects the returned `fixedContent`.
+ * Stops when: no edits remain, an edit makes no progress, or `maxPasses` is hit.
+ */
+declare function fixFileContent(originalContent: string, lint: (content: string) => Diagnostic[], maxPasses?: number): FixFileResult;
+/**
+ * Produce a unified diff between `before` and `after` for display. Returns an
+ * empty string when the two are identical.
+ */
+declare function unifiedDiff(path: string, before: string, after: string): string;
+
 /**
  * Thrown when a rule's merged options fail AJV validation against
  * `rule.meta.schema`. Distinct from generic `Error` so callers can
@@ -284,11 +448,31 @@ interface ParsedFile {
      * effective value is list-sourced.
      */
     metadataLoc: Record<string, MetadataPosition> | null;
+    /**
+     * Body-coordinate offset RANGE of the effective value for keys whose value
+     * came from the v2 leading list AND was a single contiguous text token (no
+     * inline markup), verified to slice back to the exact value. Autofix targets
+     * the value precisely with this. Frontmatter-won keys are absent (frontmatter
+     * is stripped before parsing → no body offset). null when nothing qualifies.
+     */
+    metadataValueLoc: Record<string, {
+        start: number;
+        end: number;
+    }> | null;
     /** mdast root of the body (frontmatter stripped). */
     ast: Root;
     /** Body content with frontmatter stripped. */
     body: string;
 }
+/**
+ * Character length of the frontmatter block that gray-matter strips from the
+ * front of `content` — i.e. the offset at which the body begins in the whole
+ * file. mdast positions are body-relative, so `fileOffset = bodyOffset +
+ * frontmatterOffset(content)`. gray-matter never mutates the body, so the body
+ * is always an exact suffix and this length is exact (verified across CRLF and
+ * leading-newline inputs). Used by the autofix fixer. See ADR-0008.
+ */
+declare function frontmatterOffset(content: string): number;
 /**
  * Parse a Markdown file: extract YAML frontmatter via gray-matter, then
  * feed the body into mdast-util-from-markdown directly (per ADR-0002,
@@ -458,4 +642,4 @@ interface MadrLintConfig {
  */
 declare function defineConfig(config: MadrLintConfig): MadrLintConfig;
 
-export { type AnyRule, BASELINE_VERSION, type Baseline, type BaselineApplyResult, type Diagnostic, type FileContext, INTERNAL_ERROR_RULE_NAME, type MadrLintConfig, type MadrVersion, type MdastNode, type MdastNodeType, type ParsedFile, type ProjectFile, type ProjectRule, type ProjectRuleContext, type Rule, type RuleContext, type RuleListeners, type RuleMeta, RuleOptionsError, type RuleSeverity, type RunRuleOptions, type Severity, applyBaseline, baselinePath, buildBaseline, buildProjectFile, defineConfig, extractListMetadata, isProjectRule, loadBaseline, parseFile, recommended, index as rules, runRule, runRulesOnFile, runRulesOnProject, serializeBaseline, writeBaseline };
+export { type AnyRule, BASELINE_VERSION, type Baseline, type BaselineApplyResult, type Diagnostic, type FileContext, type FixFileResult, type FixFn, type Fixer, INTERNAL_ERROR_RULE_NAME, MAX_FIX_PASSES, type MadrLintConfig, type MadrVersion, type MdastNode, type MdastNodeType, type ParsedFile, type ProjectFile, type ProjectRule, type ProjectRuleContext, type Rule, type RuleContext, type RuleListeners, type RuleMeta, RuleOptionsError, type RuleSeverity, type RunRuleOptions, type Severity, type TextEdit, applyBaseline, applyEdits, applyEditsCounted, baselinePath, buildBaseline, buildProjectFile, collectFixes, collectProjectFixes, defineConfig, extractListMetadata, fixFileContent, frontmatterOffset, isProjectRule, loadBaseline, makeFixer, parseFile, recommended, index as rules, runRule, runRulesOnFile, runRulesOnProject, serializeBaseline, unifiedDiff, writeBaseline };