msd-core/scripts/lint-state-field-drift.cjs

#!/usr/bin/env node
'use strict';

/**
 * Anti-divergence drift guard for the STATE.md FIELD-EXTRACTION FALLBACK
 * CHAIN (epic #3180, issue #3187, ADR-3180 Decision 4, spec §7.7).
 *
 * The derivation this guard protects is "read a STATE.md field: prefer the
 * YAML frontmatter scalar (string, trimmed-non-empty; or number/boolean
 * coerced to a string), else fall back to the body field via
 * `stateExtractField(body, bodyField)`". `src/state-document.cts` is
 * DESIGNATED the single canonical owner of this grammar (issue #3187 Phase
 * 5), but as of this guard's authorship (Phase 5's guard-first step, per
 * ADR-3180 Amendment 3's standing rule) the canonical function does not yet
 * exist there — this script is written to discover every existing
 * re-derivation BEFORE any src/ file is touched, exactly the ordering
 * `lint-plan-count-drift.cjs` and its siblings established.
 *
 * Per ADR-3180 Decision 4(a) this guard discovers call sites by SCANNING THE
 * WHOLE `src/` TREE, not by consulting an allowlist of known files. Per
 * Decision 4(d) that surface is widened further still: `src/` alone is
 * itself the forbidden allowlist, one directory wide, so this guard ALSO
 * scans the prompt-layer markdown (`gsd-core/workflows`, `commands`,
 * `agents`, `skills`) for a PROSE re-derivation of the same chain — see the
 * "PROMPT-LAYER PROSE DETECTION" section below `findStateFieldDrift`.
 *
 * DETECTION: FUNCTION-SCOPED CO-OCCURRENCE, not a bounded line-window.
 * An earlier draft of this guard used a fixed line-distance window between
 * the ladder and the fallback call. That shape was REJECTED: it produced a
 * documented "known miss" on live copies inside the very function it was
 * scanning (state.cts `cmdStateSnapshot`'s `Current Plan` / `Total Plans in
 * Phase` / `Status` / `Progress` / `Last Activity` reads all sit further
 * from the ladder than any defensible line count), which means the guard
 * could report "0 re-derivations" after only the nearest few copies were
 * migrated while several more of the SAME kind survived untouched in the
 * SAME function — "a zero it did not earn" (ADR-3180 Decision 4(a)). A fixed
 * N is also trivially gameable by reflow (Goodhart's law): moving a call one
 * line further from its ladder silences the guard without changing the
 * derivation at all. The window is dropped entirely; there is no magic
 * number anywhere in this detection.
 *
 * The invariant instead: a NAMED FUNCTION that BOTH (a) contains a
 * "frontmatter scalar coercion ladder" — the SAME operand compared via
 * `typeof OPERAND === 'number'` and `typeof OPERAND === 'boolean'`
 * (TYPEOF_TIER_CLAUSE_RE, order-independent, member/computed operands
 * included, an optional `typeof OPERAND === 'string'` tier tolerated
 * anywhere among them — see the ternary shape in `cmdStatePrune` below),
 * within LADDER_WINDOW_LINES of each other — ANYWHERE in its own body,
 * INCLUDING inside a nested closure it defines, AND (b) calls
 * `stateExtractField(` anywhere in that same body, is re-deriving the
 * fm-else-body fallback chain. EVERY `stateExtractField(` call line inside
 * such a function is reported, not just the first.
 *
 * LADDER DETECTION, evasion-resistant shapes (see "LADDER DETECTION DETAIL"
 * below for the full account, including the one shape still NOT caught):
 *   - operand may be a bare identifier (`v`), a dotted member expression
 *     (`fm.key`), or a computed access (`fm[key]`) — matched via
 *     OPERAND_SOURCE and compared as captured TEXT, not a bare-identifier
 *     backreference.
 *   - the two required tiers ('number', 'boolean') may appear in EITHER
 *     order; an optional third 'string' tier may sit anywhere among them.
 *   - the two clauses may sit on the SAME line (the classic single-line
 *     `||` chain) or on DIFFERENT lines within LADDER_WINDOW_LINES of each
 *     other — including as two entirely separate `if` statements, not just
 *     one expression wrapped across a line break.
 *
 * FUNCTION ATTRIBUTION. Two declaration shapes are recognised as opening a
 * new named function scope:
 *   - `function NAME(...) {` (FUNCTION_DECL_RE) — top-level OR nested, at
 *     any indentation. `src/smart-entry.cts`'s `fmScalar` (line 144) is this
 *     shape, and is itself top-level.
 *   - `const NAME = (...): ReturnType => {` (ARROW_CONST_RE) — an arrow
 *     function assigned to a `const`, with a block body (`=> {`, not an
 *     expression body like `=> ({...})`, which never opens a new function
 *     frame — its `{` is an object literal, still counted toward brace
 *     depth, but attributes no name). `src/state.cts`'s `cmdStateSnapshot`
 *     defines its `fmScalar` (line 1464) this way, NESTED inside
 *     `cmdStateSnapshot` itself.
 * `ARROW_CONST_RE`'s pattern requires `=>\s*\{` literally, so it only ever
 * matches a line that already carries its opening brace — pushed
 * immediately. `FUNCTION_DECL_RE` carries no such guarantee: a multi-line
 * signature (parameters and/or a return-type annotation spilling onto later
 * lines) matches on a line with NO `{` at all. An earlier version of this
 * guard pushed such a match immediately anyway, recording `openDepth` at the
 * ENCLOSING scope's depth rather than the function's own — for a top-level
 * function, `openDepth: 0`, and because real code never reaches negative
 * depth, a frame pushed with `openDepth: 0` could NEVER pop, sitting at the
 * bottom of the stack for the rest of the file and silently misattributing
 * every later line with no OTHER open frame to it. `src/state.cts`'s
 * `preferNewerLastActivity` (a 4-line signature, `{` on its own line) is the
 * live instance that surfaced this; it caused no observed false violation
 * only because nothing ever called `stateExtractField(` at true module scope
 * after it, not because the tracking was sound. `buildFunctionInfo` now
 * DEFERS a `FUNCTION_DECL_RE` match (`pendingDeclName`) across lines until
 * the first subsequent line whose brace count actually increases, and pushes
 * the frame THERE, with `openDepth` computed from that line's `depth` —
 * matching every other frame's push convention. A pending name is abandoned
 * (never pushed) if a `;` terminates the statement before any `{` appears —
 * a type-only declaration, `declare function`, or overload signature, none
 * of which open a body.
 * Function scopes NEST via a brace-depth stack: entering either shape pushes
 * a frame; the frame pops once brace depth returns below the depth recorded
 * when it was pushed. A line is attributed to the INNERMOST currently-open
 * named frame (falling back to whatever enclosing frame IS open — typically
 * the nearest enclosing top-level function — when a line sits between two
 * sibling nested scopes; module-level code with no open frame is
 * unattributed and therefore never a violation, matching "if you cannot
 * identify one" in the design brief).
 *
 * TRANSITIVE ladder attribution is what makes `cmdStateSnapshot` (whose
 * OWN top-level statements never spell the ladder themselves — only its
 * nested `fmScalar` closure does) still register as ladder-bearing: when
 * LADDER_RE matches a line, EVERY frame currently open on the stack at that
 * point — not just the innermost — is marked ladder-bearing, because a
 * nested closure's body is lexically part of every one of its enclosing
 * functions' own bodies. `stateExtractField(` calls are attributed to the
 * INNERMOST frame only (no transitivity needed there: the call already sits
 * directly inside whichever frame is innermost at that point).
 *
 * BRACE-DEPTH COUNTING runs over `scanCode`'s per-line, cross-file output
 * (see that function's own header for the full rationale and the concrete
 * bug its cross-line comment/template tracking fixes) — comments and
 * quoted/backtick string and template literal CONTENTS are already removed
 * before a single brace is counted, escape-aware and threaded across line
 * boundaries, so neither a brace inside a string (`{ label: '{' }`) nor one
 * inside a multi-line block comment or template literal perturbs the depth
 * count. It does NOT specially recognise regex literals (a `{` inside a
 * `/.../ ` quantifier, e.g. `/x{2,3}/`, is counted as a plain character);
 * see `scanCode`'s header for why every such literal actually present in
 * `src/` today is harmless (balanced on its own line).
 *
 * MUST-NOT-FLAG case verified by running the guard (the earlier "case
 * variant chain" exemption for `src/state.cts:1488` was WRONG and is
 * SUPERSEDED — see the header of the guard's initial version in git history
 * for the retracted reasoning; `cmdStateSnapshot` is ladder-bearing, so
 * *every* `stateExtractField(` call inside it, including line 1488, is
 * correctly a violation now):
 *   - `src/smart-entry.cts`'s `fmScalarKey` (lines 152-158): its own
 *     `typeof v === 'number' || typeof v === 'boolean'` ladder (line 156)
 *     reads a value out of a NESTED frontmatter object and never calls
 *     `stateExtractField(` anywhere in its own body — it is ladder-bearing
 *     but call-free, so it is correctly never flagged. This is the live
 *     control case proving the guard still distinguishes "has a ladder" from
 *     "re-derives the fallback chain": a ladder alone, with no body
 *     fallback call in the same function, is a different question (reading
 *     a nested frontmatter object, full stop) and stays silent.
 *   - Any ladder or `stateExtractField(` call appearing inside a `//` line
 *     comment or a `/* *\/`-style block comment (single- or multi-line).
 *     `scanCode` blanks comment text — cross-line-aware — before either
 *     regex runs, so prose describing this derivation is never mistaken for
 *     a copy of it (ADR-3180 Amendment 3's "trains readers to reflexively
 *     exempt documentation" note).
 *
 * FUNCTION-SCOPED EXEMPTIONS (per ADR-3180 Decision 4(a): NEVER a bare
 * whole-file allowlist — Decision 4(d) records that a whole-file exemption
 * on the owner is precisely how `getMilestoneInfo` stayed invisible to an
 * earlier guard). `src/state-document.cts` is the owner of this grammar;
 * its `stateFieldValue` (added for issue #3187 Phase 5, landed in this same
 * working tree while this guard was being authored — see the guard's commit
 * history / PR for the exact sequencing) IS the canonical
 * frontmatter-scalar-then-body-field chain, not a copy of it, so it is the
 * ONLY entry in FUNCTION_SCOPED_EXEMPTIONS. Every other function in
 * `state-document.cts` — including any future re-derivation added anywhere
 * else in that file — is still scanned and still flagged (mirrors
 * `lint-completion-ratio-drift.cjs`'s `FUNCTION_SCOPED_EXEMPTIONS` for
 * `clampPercent`/`clampPercentFromFraction`).
 *
 * Every regex below is small, bounded, and has no nested/overlapping
 * quantifiers; the string-literal and brace scans are plain escape-aware
 * character loops, not regexes, so there is nothing for a backtracking
 * engine to explore. `npm run lint:ci` runs CodeQL js/redos over this repo;
 * mirrors the ReDoS discipline of the sibling drift guards.
 *
 * The tree-walk / root-confinement / sanitizer machinery is SHARED with the
 * sibling drift guards via `scripts/lib/drift-scan.cjs` (ADR-3180 Decision
 * 4). This guard's detection shape needs no regex-literal extraction, so it
 * does not use `readRegexLiteralAt`; the reported fragment is simply the
 * trimmed source line, bounded to MAX_REGEX_LITERAL_LEN characters.
 *
 * LADDER DETECTION DETAIL (evasion history). An earlier version of this
 * guard's ladder pattern was a single regex, `typeof (\w+) === 'number' \|\|
 * typeof \1 === 'boolean'`, tested against ONE line. An isolated adversarial
 * review found three live-shaped ways past it, all verified to produce ZERO
 * violations against a real re-derivation:
 *   (a) a member-expression or computed operand — `typeof fm.key ===
 *       'number' || typeof fm.key === 'boolean'` — never matched, because
 *       the bare-identifier backreference (`\w+` then `\1`) cannot match
 *       `fm.key`/`fm[key]` at all.
 *   (b) the tiers in the opposite order — `typeof v === 'boolean' ||
 *       typeof v === 'number'` — never matched, because the pattern
 *       hardcoded 'number' before 'boolean' with no alternative ordering.
 *       This one is plausible from an ordinary code-review reformat, not
 *       deliberate evasion.
 *   (c) the ladder split across two lines, or written as two separate `if`
 *       statements instead of one `||` chain — never matched, because
 *       detection ran per-line with no tolerance for the pair spanning more
 *       than one line.
 * The fix: OPERAND_SOURCE (identifier / dotted member / computed access,
 * compared as captured TEXT rather than a bare-identifier backreference),
 * TYPEOF_TIER_CLAUSE_RE (one clause at a time, tier-order-independent,
 * collected via a `Map<operand, Set<tier>>`), and a small bounded
 * LADDER_WINDOW_LINES sliding window so the two required clauses need only
 * sit within a few lines of each other, not on the identical line. All
 * three evasion shapes above are now covered by
 * `tests/state-field-drift.test.cjs` (D3c/D3d/D3e).
 *
 * KNOWN, ACCEPTED limits of this scan (honest, not exhaustive by
 * construction — this is a bounded regex-based scan, not a parser):
 *   - Cross-function: a re-derivation whose ladder and fallback call sit in
 *     two DIFFERENT named functions with no shared enclosing scope (e.g. a
 *     ladder in one file-level helper, consumed by a caller in another
 *     function that itself calls `stateExtractField(` for an unrelated
 *     field) is not caught — this guard's unit is "one named function's own
 *     body, including its nested closures", not the whole call graph. That
 *     is left to code review, not this regex. This co-occurrence check is
 *     deliberately FUNCTION-SCOPED with NO line-distance window at all (see
 *     the module-level "DETECTION" note above) — do not confuse this with
 *     LADDER_WINDOW_LINES, which bounds a different, much tighter pairing
 *     (the ladder's own two clauses, which are always part of the SAME
 *     conditional expression by construction, not an arbitrary call
 *     anywhere later in the function).
 *   - Ladder clauses further apart than LADDER_WINDOW_LINES lines: a ladder
 *     whose 'number' and 'boolean' clauses are more than
 *     LADDER_WINDOW_LINES lines apart (e.g. separated by an unrelated
 *     intervening block of code, not just the couple of lines a single
 *     conditional or two adjacent `if`s span) is not caught. No such shape
 *     has been observed in this codebase; if one appears, raise
 *     LADDER_WINDOW_LINES rather than silently accepting the miss.
 *   - Non-`typeof`-shaped coercion checks: a ladder rewritten through a
 *     `switch (typeof v)`, a helper function abstracting the check (e.g.
 *     `isNumberOrBoolean(v)`), or any comparison operator other than
 *     `===` (e.g. `typeof v == 'number'`) is not recognised — the pattern
 *     is `typeof OPERAND === 'TIER'` literally, not "any type-coercion
 *     test with equivalent runtime behaviour."
 *   - Nested computed access: `a[b[c]]` is not modelled as a single
 *     operand — the computed-content class excludes `]`, so nested
 *     brackets truncate the captured operand at the first `]` rather than
 *     matching the whole expression. Not observed in this codebase's
 *     ladders today.
 *   - Whitespace-sensitive operand identity: `fm[key]` and `fm[ key ]` are
 *     compared as distinct operand TEXT (no normalisation), so a ladder
 *     whose two clauses format the same computed access differently could
 *     under-detect. Not observed in this codebase's ladders today.
 */

const path = require('node:path');
const driftScan = require('./lib/drift-scan.cjs');
const { MAX_REGEX_LITERAL_LEN, sanitizeForReport, scanTree } = driftScan;

// A ladder operand: a bare identifier (`v`), a dotted member expression
// (`fm.key`, `fm.a.b`), or a computed/bracket access (`fm[key]`), repeated
// via a single bounded alternation. No nested/overlapping quantifiers: the
// bracket-content class (`[^\]\r\n]{1,80}`) is one bounded character class,
// not a quantifier nested inside another quantifier, so there is nothing
// for a backtracking engine to explore. The captured TEXT (not a bare-
// identifier backreference) is what two clauses are compared against for
// "same operand" — see TYPEOF_TIER_CLAUSE_RE below and buildFunctionInfo's
// ladder-window accumulation.
const OPERAND_SOURCE = String.raw`[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*|\[[^\]\r\n]{1,80}\])*`;

// One ladder clause: `typeof OPERAND === 'TIER'`, TIER being one of the
// three coercion tiers this derivation ever compares against. Run with the
// `g` flag over a single line's `detect` text so every clause that line
// carries is collected (a single-line `||` chain carries two or three; a
// clause split onto its own line, or written as a standalone `if`, carries
// one). No trailing `\b` after the closing quote: the quote itself is
// already an unambiguous, non-word boundary — see the historical note this
// replaced for why a trailing `\b` there silently matches nothing at all.
const TYPEOF_TIER_CLAUSE_RE = new RegExp(String.raw`\btypeof\s+(${OPERAND_SOURCE})\s*===\s*'(number|boolean|string)'`, 'g');

// A ladder is CONFIRMED when the SAME operand carries both a 'number' clause
// and a 'boolean' clause (in either order; an additional 'string' clause
// anywhere among them does not prevent this) within this many consecutive
// lines of each other. Small and bounded, and DELIBERATELY NOT the same
// concept as the ladder-to-`stateExtractField(` co-occurrence check, which
// stays function-scoped with no window at all (see the module header's
// "DETECTION" and "LADDER DETECTION DETAIL" notes for why these two
// pairings are not interchangeable).
const LADDER_WINDOW_LINES = 6;

// The body-fallback call whose presence, inside a ladder-bearing function,
// makes that function a re-derivation of the "frontmatter-else-body" grammar.
const STATE_EXTRACT_FIELD_CALL_RE = /\bstateExtractField\(/;

// Named function scope openers. Each requires its own opening `{` on the
// SAME line as the signature — see the header's "FUNCTION ATTRIBUTION"
// paragraph for the documented limitation and why it does not affect either
// real copy this guard was written against.
//   - `function NAME(...) {` — top-level OR nested, any indentation.
const FUNCTION_DECL_RE = /\bfunction\s+([A-Za-z_$][\w$]*)\s*\(/;
//   - `const NAME = (...): ReturnType => {` — block-bodied arrow assigned to
//     a const. `[^)]*` and `[^=]*` are bounded, single-purpose character
//     classes (no nested/overlapping quantifiers): the former stops at the
//     parameter list's closing paren, the latter at the arrow itself.
const ARROW_CONST_RE = /\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*\([^)]*\)\s*(?::\s*[^=]+)?=>\s*\{/;

// ADR-3180 Decision 4(d): a guard's scan surface is every AUTHORED surface
// that can EXPRESS the derivation, not `src/` — reading "whole-repo scan" as
// "the whole `src/` tree" is itself the forbidden allowlist, one directory
// wide. This derivation is expressed in TWO languages: TypeScript under
// `src/` (the ladder + `stateExtractField(` shape PASS 1/2 above detect), and
// PROSE in the workflow/command/agent/skill markdown that ships to every
// runtime — `gsd-core/workflows/smart-entry.md`'s "Extract: `status`
// (frontmatter `status:` or body `**Status:**`)" is exactly this chain,
// hand-described rather than called. `SCAN_DIRS` therefore covers both;
// `findPromptFieldDrift` (below `findStateFieldDrift`) is the markdown-side
// detector, dispatched by extension in `scanRepo`'s `onFile`. Mirrors
// `lint-planning-prompt-drift.cjs`'s own prompt-layer surface exactly
// (`gsd-core/workflows`, `commands`, `agents`, `skills`).
const SCAN_DIRS = ['src', 'gsd-core/workflows', 'commands', 'agents', 'skills'];
const SCAN_EXT = new Set(['.cts', '.ts', '.mts', '.md']);

// The designated owner (issue #3187 Phase 5, ADR-3180 §7.7).
const OWNER_FILE = path.join('src', 'state-document.cts');

// Per ADR-3180 Decision 4(a): function-scoped, NEVER a bare file allowlist —
// Decision 4(d) records that a whole-file exemption on the owner is
// precisely how `getMilestoneInfo` stayed invisible to an earlier guard.
// Only `stateFieldValue` itself is exempt: it IS the canonical
// frontmatter-scalar-then-body-field chain (holds the ladder AND calls
// `stateExtractField(` by construction, in its own body — that is its whole
// job), not a copy of it. Every OTHER function in this same file — including
// any future re-derivation added anywhere else in state-document.cts — is
// still scanned and still flagged; nothing else in this file is exempt.
const FUNCTION_SCOPED_EXEMPTIONS = new Map([[OWNER_FILE, new Set(['stateFieldValue'])]]);

/**
 * Tokenize the WHOLE file into TWO parallel per-line views, from ONE
 * single-pass, escape-aware character scan (not a regex — no backtracking
 * cost to bound):
 *   - `detect[i]`: comments stripped, but string/template literal contents
 *     KEPT VERBATIM (quotes included). This is what the detection regexes
 *     (LADDER_RE / STATE_EXTRACT_FIELD_CALL_RE / FUNCTION_DECL_RE /
 *     ARROW_CONST_RE) run against — they need the literal quoted text
 *     `'number'` / `'boolean'` to still be present.
 *   - `braces[i]`: comments AND string/template literal CONTENTS stripped,
 *     used only for brace-depth counting, so a brace character written
 *     inside a string (e.g. `{ label: '{' }`) never perturbs the count.
 *
 * This REPLACES two earlier, narrower designs in turn:
 *   1. Two independent per-line helpers (`stripComments` + a separate
 *      `stripStringLiterals`), each with no cross-line state. That design
 *      missed a `/* ... *\/`-style block comment whose CLOSING line also
 *      carries trailing real code (e.g. a `catch { /* comment` opener
 *      followed by ` * more comment. *\/ }` on a later line): the old
 *      per-line `stripComments` heuristic ("a line whose trimmed text starts
 *      with `*` is entirely comment") blanked that closing line WHOLESALE,
 *      silently dropping the real `}` it also carried, which left a
 *      function's brace-depth frame permanently open and made every LATER
 *      `stateExtractField(` call in the file — inside unrelated functions —
 *      inherit that stale frame's ladder-bearing status (`src/state.cts`'s
 *      `cmdStateValidate`, which has no ladder of its own, was falsely
 *      flagged this way).
 *   2. A single merged output that dropped string CONTENTS unconditionally.
 *      That fixed (1) but broke detection outright: LADDER_RE needs the
 *      literal text `'number'`/`'boolean'` (with quotes) to match, and a
 *      merged output that strips quote contents for brace-safety also
 *      erases the very tokens the ladder regex looks for — every ladder
 *      line silently stopped matching. Two views, not one, is what lets
 *      each consumer see what it actually needs.
 *
 * `inBlockComment` and `inTemplate` are threaded ACROSS lines so a block
 * comment or a multi-line backtick template literal spanning several source
 * lines is tracked correctly regardless of what trails its closing
 * delimiter. Regex literals are NOT specially recognised (documented,
 * narrow, known limitation, same as the sibling drift guards'
 * `readRegexLiteralAt`-free scans): a `/` is only ever treated as a comment
 * opener when immediately followed by another `/` or `*`, so an ordinary
 * regex literal's slashes pass through as plain characters and any brace
 * inside one (e.g. `/x{2,3}/`) is counted like any other character —
 * verified harmless for every regex literal actually present in `src/`
 * today because each is balanced (equal opens/closes) on its own line, so it
 * never desyncs the running depth total even though the individual
 * characters are not "understood" as a literal.
 */
function scanCode(lines) {
  const detect = new Array(lines.length);
  const braces = new Array(lines.length);
  let inBlockComment = false;
  let inTemplate = false;
  for (let li = 0; li < lines.length; li++) {
    const line = lines[li];
    let outDetect = '';
    let outBraces = '';
    let i = 0;
    if (inTemplate) {
      const start = i;
      while (i < line.length) {
        if (line[i] === '\\') {
          i += 2;
          continue;
        }
        if (line[i] === '`') {
          i++;
          inTemplate = false;
          break;
        }
        i++;
      }
      outDetect += line.slice(start, i); // template contents kept verbatim for detect
      if (inTemplate) {
        detect[li] = outDetect;
        braces[li] = ''; // whole line still inside the unterminated template
        continue;
      }
    }
    while (i < line.length) {
      if (inBlockComment) {
        const close = line.indexOf('*/', i);
        if (close === -1) {
          i = line.length;
          break;
        }
        i = close + 2;
        inBlockComment = false;
        continue;
      }
      const ch = line[i];
      if (ch === '/' && line[i + 1] === '/') {
        i = line.length; // rest of line is a line comment
        break;
      }
      if (ch === '/' && line[i + 1] === '*') {
        inBlockComment = true;
        i += 2;
        continue;
      }
      if (ch === "'" || ch === '"') {
        const quote = ch;
        const start = i;
        let j = i + 1;
        while (j < line.length) {
          if (line[j] === '\\') {
            j += 2; // escape consumes the next character, whatever it is
            continue;
          }
          if (line[j] === quote) {
            j++;
            break;
          }
          j++;
        }
        outDetect += line.slice(start, j); // string kept verbatim for detect
        // (nothing appended to outBraces — string contents excluded from depth counting)
        i = j;
        continue;
      }
      if (ch === '`') {
        const start = i;
        let j = i + 1;
        let closed = false;
        while (j < line.length) {
          if (line[j] === '\\') {
            j += 2;
            continue;
          }
          if (line[j] === '`') {
            j++;
            closed = true;
            break;
          }
          j++;
        }
        if (!closed) {
          outDetect += line.slice(start); // rest of line kept verbatim for detect
          inTemplate = true;
          i = line.length;
          break;
        }
        outDetect += line.slice(start, j); // template kept verbatim for detect
        i = j;
        continue;
      }
      outDetect += ch;
      outBraces += ch;
      i++;
    }
    detect[li] = outDetect;
    braces[li] = outBraces;
  }
  return { detect, braces };
}

/**
 * Pure: find every unsanctioned STATE.md field-extraction fallback-chain
 * re-derivation in `text`. `relPath` is the repo-relative path, used both to
 * report file:line and to apply the function-scoped owner exemptions above.
 *
 * Two passes over the same line array:
 *   PASS 1 walks the file once, maintaining a brace-depth stack of open
 *     named function frames, and records which function NAMES are
 *     ladder-bearing (transitively — see the header's "TRANSITIVE ladder
 *     attribution" paragraph) and, per source line, which frame is
 *     INNERMOST at that line (for call attribution) — {@link buildFunctionInfo}.
 *   PASS 2 walks the lines again; any `stateExtractField(` call whose
 *     innermost enclosing function is ladder-bearing (and not
 *     function-scoped-exempt) is a violation.
 * Returns [{ line, found }].
 */
function buildFunctionInfo(lines) {
  const { detect, braces } = scanCode(lines);
  const ladderBearing = new Set();
  const innermostAt = new Array(lines.length).fill(null);
  const stack = []; // { name, openDepth }
  let depth = 0;
  // A `function NAME(` match whose own line carries no `{` (a multi-line
  // signature — parameters and/or a return-type annotation spilling onto
  // later lines before the body opens) — awaiting the line that actually
  // carries its opening brace. See the header's "FUNCTION ATTRIBUTION"
  // paragraph and this function's own doc comment for why this cannot be
  // pushed onto `stack` immediately: pushing it with `openDepth` recorded
  // BEFORE its own `{` is counted produces a frame whose `openDepth` is the
  // ENCLOSING scope's depth, not its own — for a top-level function that is
  // `openDepth: 0`, and since real code never reaches negative depth, a
  // frame pushed with `openDepth: 0` can NEVER pop (`depth < 0` never
  // fires): it would sit at the bottom of `stack` for the rest of the file,
  // and every subsequent line with no OTHER open frame would be
  // misattributed to it. `ARROW_CONST_RE` never needs this deferral — its
  // pattern requires `=>\s*\{` literally, so it only ever matches on a line
  // that already carries the brace.
  let pendingDeclName = null;
  // LADDER WINDOW: a rolling buffer of every `typeof OPERAND === 'TIER'`
  // clause seen in the last LADDER_WINDOW_LINES lines, oldest-first. On
  // each line, new clauses from that line are appended, then entries older
  // than the window are pruned from the front. A ladder is confirmed the
  // moment the SAME operand has accumulated both a 'number' and a
  // 'boolean' entry inside the buffer — order-independent, and regardless
  // of whether the two clauses came from one `||` chain split across
  // lines, one single-line chain, or two entirely separate `if`
  // statements. See LADDER_WINDOW_LINES's own comment for why this is
  // bounded small and is NOT the same concept as the (unbounded,
  // function-scoped) ladder-to-`stateExtractField(` co-occurrence below.
  const recentClauses = []; // { line, operand, tier }
  for (let i = 0; i < lines.length; i++) {
    const detectCode = detect[i];
    const braceCode = braces[i];

    let immediateName = null;
    if (detectCode.trim()) {
      const arrowMatch = ARROW_CONST_RE.exec(detectCode);
      if (arrowMatch) {
        immediateName = arrowMatch[1];
      } else {
        const declMatch = FUNCTION_DECL_RE.exec(detectCode);
        // A NEW `function NAME(` match replaces any still-pending name
        // rather than stacking deferrals — this scanner tracks at most one
        // pending declaration at a time (two `function` keywords on
        // consecutive lines with neither closing its signature first is not
        // a shape that occurs in this codebase's style).
        if (declMatch) pendingDeclName = declMatch[1];
      }
    }

    const opens = (braceCode.match(/\{/g) || []).length;
    const closes = (braceCode.match(/\}/g) || []).length;
    depth += opens - closes;

    if (immediateName) stack.push({ name: immediateName, openDepth: depth });

    if (pendingDeclName) {
      if (opens > 0) {
        // First line whose brace count actually increases — its `{` is
        // counted in THIS line's `opens`, so `depth` here correctly
        // reflects "inside the function", matching every other frame's
        // convention (push AFTER updating depth for the pushing line).
        stack.push({ name: pendingDeclName, openDepth: depth });
        pendingDeclName = null;
      } else if (detectCode.includes(';')) {
        // The statement terminated before any `{` appeared — a type-only
        // declaration, an ambient `declare function`, or an overload
        // signature, none of which open a function body. Abandon the
        // pending name rather than stranding it to match a `{` that
        // belongs to unrelated later code. (A `;` inside a string literal
        // on this line would also trigger this — accepted, narrow, known
        // limitation: a default-parameter string containing `;` on the
        // SAME line as an unterminated multi-line signature has not been
        // observed in this codebase.)
        pendingDeclName = null;
      }
    }

    while (stack.length > 0 && depth < stack[stack.length - 1].openDepth) stack.pop();

    innermostAt[i] = stack.length > 0 ? stack[stack.length - 1].name : null;

    if (detectCode.trim()) {
      TYPEOF_TIER_CLAUSE_RE.lastIndex = 0;
      let clauseMatch;
      while ((clauseMatch = TYPEOF_TIER_CLAUSE_RE.exec(detectCode)) !== null) {
        recentClauses.push({ line: i, operand: clauseMatch[1], tier: clauseMatch[2] });
      }
    }
    // Prune clauses that have fallen outside the small bounded ladder window.
    while (recentClauses.length > 0 && recentClauses[0].line <= i - LADDER_WINDOW_LINES) {
      recentClauses.shift();
    }

    let ladderConfirmed = false;
    if (recentClauses.length > 0) {
      const tiersByOperand = new Map();
      for (const clause of recentClauses) {
        let tiers = tiersByOperand.get(clause.operand);
        if (!tiers) {
          tiers = new Set();
          tiersByOperand.set(clause.operand, tiers);
        }
        tiers.add(clause.tier);
      }
      for (const tiers of tiersByOperand.values()) {
        if (tiers.has('number') && tiers.has('boolean')) {
          ladderConfirmed = true;
          break;
        }
      }
    }

    if (ladderConfirmed) {
      // Transitive: every frame currently open (not just the innermost) is
      // ladder-bearing, because a nested closure's body is lexically part of
      // every one of its enclosing functions' own bodies.
      for (const frame of stack) ladderBearing.add(frame.name);
    }
  }
  return { ladderBearing, innermostAt, detect };
}

// ─── PROMPT-LAYER PROSE DETECTION (ADR-3180 Decision 4(d)) ─────────────────
//
// The SAME #1760 fallback chain — "prefer the frontmatter scalar, else fall
// back to the body field" — expressed as MARKDOWN PROSE describing the
// derivation to an agent, rather than TypeScript re-deriving it. Detection is
// intentionally narrow, mirroring `lint-planning-prompt-drift.cjs`'s own
// precedent: a markdown line is a prose re-derivation only when it carries
// ALL FOUR, on the SAME line:
//   (a) a backtick-quoted YAML-style frontmatter key token — a lowercase
//       identifier immediately followed by a colon, inside backticks, e.g.
//       `` `status:` ``. `FRONTMATTER_KEY_TOKEN_RE`.
//   (b) a backtick-quoted Markdown BOLD body-field token, e.g.
//       `` `**Status:**` ``. `BODY_BOLD_TOKEN_RE`.
//   (c) the word "frontmatter" (case-insensitive, word-bounded) anywhere on
//       the line.
//   (d) the word "body" (case-insensitive, word-bounded) anywhere on the
//       line.
// (c) and (d) are what distinguish a line DESCRIBING an fm-then-body
// PRECEDENCE from a line that merely happens to carry two backtick-quoted
// tokens shaped like (a) and (b) for unrelated reasons — both words are
// required so an incidental co-occurrence (e.g. a table row naming an
// unrelated frontmatter key and, several columns over, an unrelated bold
// body label) cannot false-positive on tokens alone.
// All four regexes are small, bounded, single fixed character classes with
// no nested/overlapping quantifiers — nothing for a backtracking engine to
// explore (`npm run lint:ci` runs CodeQL js/redos over this repo, the same
// discipline `findStateFieldDrift`'s own regexes document above).
const FRONTMATTER_KEY_TOKEN_RE = /`[a-z][a-z0-9_]*:`/;
const BODY_BOLD_TOKEN_RE = /`\*\*[^*`]{1,80}\*\*`/;
const FRONTMATTER_WORD_RE = /\bfrontmatter\b/i;
const BODY_WORD_RE = /\bbody\b/i;

// Per ADR-3180 Decision 4(d)/(e): `gsd-core/workflows/smart-entry.md`'s
// Fallback step 1 ("`gsd-tools` itself is broken") is a PERMANENT, by-
// construction exemption — NOT debt with an owner, and therefore NOT
// modelled as `lint-planning-prompt-drift.cjs`'s shrink-only ratchet
// baseline (which exists specifically to acknowledge sites with a removal
// issue, per Decision 4(e)). This site can never be migrated onto
// `src/state-document.cjs`'s `stateFieldValue`: the surrounding step exists
// PRECISELY for when the CLI itself cannot run (`Cannot find module ...` /
// Node crash — probed one line above this one), so by construction it cannot
// call the canonical owner it is standing in for. Fabricating a "removal
// issue" for something that can never be removed would misrepresent it as
// ratchetable debt it is not.
//
// Keyed on (file, TRIMMED source text) — never a line number, which churns
// on any unrelated edit to the same file — mirroring the ratchet's own key
// shape (`lint-planning-prompt-drift.cjs`) even though this exemption is not
// itself a ratchet. `file` uses the SAME native-separator relPath shape as
// `OWNER_FILE`/`FUNCTION_SCOPED_EXEMPTIONS` above (this guard does not
// POSIX-normalize elsewhere, so this exemption does not either, for
// consistency within the one file).
const PROMPT_LAYER_EXEMPTIONS = new Map([
  [
    path.join('gsd-core', 'workflows', 'smart-entry.md'),
    new Map([
      [
        "- Read `.planning/STATE.md` (frontmatter + body) with the Read tool. Extract: `status` (frontmatter `status:` or body `**Status:**`), `Phase:` from the body, `total_phases`/`percent` from a nested `progress:` frontmatter object if present, and any `## Blockers` items.",
        'gsd-tools-down fallback (smart-entry.md Fallback step 1): runs only when gsd-tools itself cannot run, so it cannot call the canonical owner it substitutes for — permanent by construction, not removable debt.',
      ],
    ]),
  ],
]);

/**
 * Pure: find every prose re-derivation of the STATE.md field-extraction
 * fallback chain in a markdown file's `text`. Returns `[{ line, found }]` for
 * every UNEXEMPTED match — `relPath` (native-separator, matching
 * `PROMPT_LAYER_EXEMPTIONS`'s keys) is consulted only for the exemption
 * lookup, exactly as `findStateFieldDrift` consults it for
 * `FUNCTION_SCOPED_EXEMPTIONS`.
 */
function findPromptFieldDrift(text, relPath) {
  const out = [];
  const lines = text.split('\n');
  const exemptTexts = PROMPT_LAYER_EXEMPTIONS.get(relPath) || null;
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (!FRONTMATTER_KEY_TOKEN_RE.test(line)) continue;
    if (!BODY_BOLD_TOKEN_RE.test(line)) continue;
    if (!FRONTMATTER_WORD_RE.test(line)) continue;
    if (!BODY_WORD_RE.test(line)) continue;
    const trimmed = line.trim();
    if (exemptTexts && exemptTexts.has(trimmed)) continue;
    out.push({ line: i + 1, found: trimmed.slice(0, MAX_REGEX_LITERAL_LEN) });
  }
  return out;
}

function findStateFieldDrift(text, relPath) {
  const out = [];
  const lines = text.split('\n');
  const exemptFunctions = FUNCTION_SCOPED_EXEMPTIONS.get(relPath) || null;
  const { ladderBearing, innermostAt, detect } = buildFunctionInfo(lines);

  for (let i = 0; i < lines.length; i++) {
    const detectCode = detect[i];
    if (!detectCode.trim()) continue;
    if (!STATE_EXTRACT_FIELD_CALL_RE.test(detectCode)) continue;

    const fn = innermostAt[i];
    if (!fn || !ladderBearing.has(fn)) continue;
    if (exemptFunctions && exemptFunctions.has(fn)) continue;

    out.push({ line: i + 1, found: lines[i].trim().slice(0, MAX_REGEX_LITERAL_LEN) });
  }
  return out;
}

/**
 * Scan the authored source tree (TypeScript under `src/`, prose in the
 * prompt-layer markdown — ADR-3180 Decision 4(d)) and return every
 * unsanctioned re-derivation, each annotated with the repo-relative file
 * path. Dispatches by extension: `.md` files run the prose detector
 * (`findPromptFieldDrift`), everything else (`.cts`/`.ts`/`.mts`) runs the
 * code detector (`findStateFieldDrift`) — the two derivations are expressed
 * in different languages and need different detection shapes over the same
 * scan surface.
 */
function scanRepo(root) {
  return scanTree({
    root,
    scanDirs: SCAN_DIRS,
    scanExt: SCAN_EXT,
    onFile(rel, text) {
      // `rel` is already the REAL (canonical) path (scanTree resolves
      // symlinks before calling onFile), so this — and
      // FUNCTION_SCOPED_EXEMPTIONS/PROMPT_LAYER_EXEMPTIONS above, also keyed
      // on `rel` — match consistently regardless of which symlink reached
      // the file.
      const finder = path.extname(rel) === '.md' ? findPromptFieldDrift : findStateFieldDrift;
      return finder(text, rel).map((d) => ({ file: rel, ...d }));
    },
  });
}

function main() {
  const root = path.join(__dirname, '..');
  const violations = scanRepo(root);
  if (violations.length === 0) {
    process.stdout.write('ok state-field-drift: no unsanctioned STATE.md field-extraction fallback-chain re-derivations found\n');
    return;
  }
  process.stderr.write('state-field-drift: independent re-derivation(s) of the STATE.md frontmatter-else-body field\n');
  process.stderr.write('fallback chain found. Route these call sites through src/state-document.cjs\n');
  process.stderr.write('`stateFieldValue` (issue #3187, ADR-3180 §7.7) instead of re-deriving the ladder:\n');
  for (const d of violations) {
    // `d.file` is exactly as attacker-controlled as `d.found`: a repo can
    // legally track a filename containing control bytes / bidi overrides,
    // and it is a fork-PR-authored value reaching a CI log the same way the
    // matched line text does — sanitize it at the same reporting boundary.
    process.stderr.write(`  ${sanitizeForReport(d.file)}:${d.line}  ${sanitizeForReport(d.found)}\n`);
  }
  process.exitCode = 1;
}

if (require.main === module) main();

module.exports = {
  findStateFieldDrift,
  findPromptFieldDrift,
  buildFunctionInfo,
  scanRepo,
  OPERAND_SOURCE,
  TYPEOF_TIER_CLAUSE_RE,
  LADDER_WINDOW_LINES,
  STATE_EXTRACT_FIELD_CALL_RE,
  FUNCTION_DECL_RE,
  ARROW_CONST_RE,
  OWNER_FILE,
  FUNCTION_SCOPED_EXEMPTIONS,
  FRONTMATTER_KEY_TOKEN_RE,
  BODY_BOLD_TOKEN_RE,
  PROMPT_LAYER_EXEMPTIONS,
  SCAN_DIRS,
  SCAN_EXT,
  scanCode,
  MAX_REGEX_LITERAL_LEN,
};