sequant 2.2.0 → 2.4.0

package/dist/src/lib/cli-ui/scrollback-harness.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Virtual-terminal harness for renderer regression tests (#647).
+ *
+ * The test stub embedded in TTYRenderer (see {@link
+ * ./run-renderer.ts#TTYTestStub}) mocks `log-update` itself — it cannot reveal
+ * whether the real `log-update` actually erases prior frames once the terminal
+ * scrolls. That gap is what allowed #624's fix to ship green while the
+ * underlying duplicate-header bug remained.
+ *
+ * This harness models a real terminal:
+ *   - bounded visible viewport (rows × cols)
+ *   - unbounded scrollback that captures every line that scrolls off the top
+ *   - the ANSI escape vocabulary that `log-update@7` + `ansi-escapes`
+ *     actually emit (cursor up/down/forward/back, eraseLine variants,
+ *     SGR colour stripping, private mode set/reset, save/restore)
+ *
+ * With it, a test can wire the production renderer through a real
+ * `createLogUpdate` instance, replay an event sequence, and assert on
+ * `(visible + scrollback)` to catch any duplicate-header rendering — the
+ * exact regression #647 was opened for.
+ */
+import { createLogUpdate } from "log-update";
+export interface VirtualTerminalOptions {
+    rows: number;
+    cols: number;
+    /** Newline mode. POSIX shells default to ONLCR which translates `\n` to
+     *  `\r\n`, so most apps see "move down + col 0". Default true. */
+    onlcr?: boolean;
+}
+/**
+ * Minimal vt100 model: visible grid + scrollback + cursor. Strips SGR colour
+ * codes (they're styling, not content) and ignores private-mode toggles
+ * (cursor hide/show). Implements the cursor and erase escapes that
+ * `log-update@7` actually emits.
+ */
+export declare class VirtualTerminal {
+    readonly rows: number;
+    readonly cols: number;
+    private readonly onlcr;
+    /** visible[row][col] = char (always single-codepoint slot). */
+    visible: string[][];
+    /** Scrollback grows oldest-first as rows shift off the top. */
+    scrollback: string[];
+    cursorRow: number;
+    cursorCol: number;
+    constructor(opts: VirtualTerminalOptions);
+    write(text: string): void;
+    /** Visible viewport as a list of trimmed-right rows. */
+    getVisibleLines(): string[];
+    /** Single multi-line string of (scrollback + visible). */
+    getAllText(): string;
+    /** Match count of the regex against (scrollback + visible). */
+    countOccurrences(pattern: RegExp): number;
+    private putChar;
+    private linefeed;
+    /** Returns the index AFTER the consumed escape sequence. */
+    private handleEscape;
+    private handleCSI;
+    private executeCSI;
+    private eraseLine;
+    private eraseFromCursorToEndOfLine;
+    private eraseFromStartOfLineToCursor;
+    private eraseFromCursorToEndOfScreen;
+    private eraseFromStartOfScreenToCursor;
+    private eraseScreen;
+}
+/**
+ * Bundle a VirtualTerminal with a real `log-update` instance writing into it
+ * and a matching `stdoutWrite` for renderer event-line writes. Both paths hit
+ * the same VT, mirroring real-terminal interleaving.
+ *
+ * Production runs frequently hit a width/height mismatch between what
+ * `log-update` reads from `process.stdout` and what the real terminal actually
+ * uses (e.g. `process.stdout.columns` is undefined under `npx` so log-update
+ * falls back to 80 while the terminal is 200 cols). Those mismatches cause
+ * `previousLineCount` to under- or over-count the rows log-update actually
+ * wrote, breaking `eraseLines` and leaving stale rows in scrollback. The
+ * `streamColumns` / `streamRows` overrides let tests reproduce this without
+ * needing a real PTY.
+ */
+export interface TerminalHarness {
+    vt: VirtualTerminal;
+    logUpdate: ReturnType<typeof createLogUpdate>;
+    stdoutWrite: (s: string) => void;
+    /**
+     * Out-of-band write that lands in the same VT as `logUpdate` and
+     * `stdoutWrite` — mirrors how a real pty merges stderr writes with stdout
+     * when both descriptors point at the same terminal. log-update has no
+     * knowledge of these writes, so they advance the cursor in ways
+     * `previousLineCount` cannot account for. Use this to reproduce the
+     * Mechanism #2-class bug (out-of-band writes break log-update's cursor
+     * model) that #647 AC-1 capture diagnosed.
+     */
+    stderrWrite: (s: string) => void;
+}
+export interface HarnessOptions extends VirtualTerminalOptions {
+    /**
+     * Width log-update is told about via `stream.columns`. Defaults to
+     * `opts.cols` (matched terminal). Override to simulate a mismatch where
+     * log-update wraps at one width but the real terminal wraps at another.
+     */
+    streamColumns?: number;
+    /**
+     * Height log-update is told about via `stream.rows`. Defaults to
+     * `opts.rows`. Override to simulate `process.stdout.rows = undefined`
+     * (the `npx` symptom): pass `undefined` explicitly via the harness's stream
+     * by setting this to a non-positive number — log-update then falls through
+     * to its internal `defaultHeight ?? 24`.
+     */
+    streamRows?: number;
+}
+export declare function createTerminalHarness(opts: HarnessOptions): TerminalHarness;

package/dist/src/lib/cli-ui/scrollback-harness.js

@@ -0,0 +1,294 @@
+/**
+ * Virtual-terminal harness for renderer regression tests (#647).
+ *
+ * The test stub embedded in TTYRenderer (see {@link
+ * ./run-renderer.ts#TTYTestStub}) mocks `log-update` itself — it cannot reveal
+ * whether the real `log-update` actually erases prior frames once the terminal
+ * scrolls. That gap is what allowed #624's fix to ship green while the
+ * underlying duplicate-header bug remained.
+ *
+ * This harness models a real terminal:
+ *   - bounded visible viewport (rows × cols)
+ *   - unbounded scrollback that captures every line that scrolls off the top
+ *   - the ANSI escape vocabulary that `log-update@7` + `ansi-escapes`
+ *     actually emit (cursor up/down/forward/back, eraseLine variants,
+ *     SGR colour stripping, private mode set/reset, save/restore)
+ *
+ * With it, a test can wire the production renderer through a real
+ * `createLogUpdate` instance, replay an event sequence, and assert on
+ * `(visible + scrollback)` to catch any duplicate-header rendering — the
+ * exact regression #647 was opened for.
+ */
+import { createLogUpdate } from "log-update";
+const ESC = "";
+/**
+ * Minimal vt100 model: visible grid + scrollback + cursor. Strips SGR colour
+ * codes (they're styling, not content) and ignores private-mode toggles
+ * (cursor hide/show). Implements the cursor and erase escapes that
+ * `log-update@7` actually emits.
+ */
+export class VirtualTerminal {
+    rows;
+    cols;
+    onlcr;
+    /** visible[row][col] = char (always single-codepoint slot). */
+    visible;
+    /** Scrollback grows oldest-first as rows shift off the top. */
+    scrollback = [];
+    cursorRow = 0;
+    cursorCol = 0;
+    constructor(opts) {
+        this.rows = opts.rows;
+        this.cols = opts.cols;
+        this.onlcr = opts.onlcr ?? true;
+        this.visible = Array.from({ length: this.rows }, () => Array(this.cols).fill(" "));
+    }
+    // ---------------------------------------------------------------- input
+    write(text) {
+        let i = 0;
+        while (i < text.length) {
+            const ch = text[i];
+            if (ch === ESC) {
+                i = this.handleEscape(text, i);
+                continue;
+            }
+            if (ch === "\n") {
+                this.linefeed();
+                i++;
+                continue;
+            }
+            if (ch === "\r") {
+                this.cursorCol = 0;
+                i++;
+                continue;
+            }
+            if (ch === "\b") {
+                if (this.cursorCol > 0)
+                    this.cursorCol--;
+                i++;
+                continue;
+            }
+            this.putChar(ch);
+            i++;
+        }
+    }
+    // ---------------------------------------------------------------- output
+    /** Visible viewport as a list of trimmed-right rows. */
+    getVisibleLines() {
+        return this.visible.map((row) => row.join("").replace(/\s+$/, ""));
+    }
+    /** Single multi-line string of (scrollback + visible). */
+    getAllText() {
+        const visibleText = this.getVisibleLines().join("\n");
+        if (this.scrollback.length === 0)
+            return visibleText;
+        return this.scrollback.join("\n") + "\n" + visibleText;
+    }
+    /** Match count of the regex against (scrollback + visible). */
+    countOccurrences(pattern) {
+        const text = this.getAllText();
+        const flags = pattern.flags.includes("g")
+            ? pattern.flags
+            : pattern.flags + "g";
+        const globalPattern = new RegExp(pattern.source, flags);
+        const matches = text.match(globalPattern);
+        return matches?.length ?? 0;
+    }
+    // ------------------------------------------------------- internal: text
+    putChar(ch) {
+        if (this.cursorCol >= this.cols) {
+            // Auto-wrap into the next row. Most terminals do this; log-update wraps
+            // upstream so this rarely triggers in practice.
+            this.cursorCol = 0;
+            this.linefeed();
+        }
+        this.visible[this.cursorRow][this.cursorCol] = ch;
+        this.cursorCol++;
+    }
+    linefeed() {
+        if (this.cursorRow + 1 < this.rows) {
+            this.cursorRow++;
+        }
+        else {
+            // Bottom of viewport: scroll the top row into scrollback.
+            const top = this.visible.shift();
+            this.scrollback.push(top.join("").replace(/\s+$/, ""));
+            this.visible.push(Array(this.cols).fill(" "));
+            // Cursor stays clamped at last visible row.
+        }
+        if (this.onlcr)
+            this.cursorCol = 0;
+    }
+    // --------------------------------------------------- internal: escapes
+    /** Returns the index AFTER the consumed escape sequence. */
+    handleEscape(text, start) {
+        // Bare ESC at end → consume.
+        if (start + 1 >= text.length)
+            return text.length;
+        const next = text[start + 1];
+        // CSI: ESC [ ... <final>
+        if (next === "[") {
+            return this.handleCSI(text, start + 2);
+        }
+        // OSC: ESC ] ... BEL or ESC \
+        if (next === "]") {
+            let i = start + 2;
+            while (i < text.length) {
+                if (text[i] === "")
+                    return i + 1;
+                if (text[i] === ESC && text[i + 1] === "\\")
+                    return i + 2;
+                i++;
+            }
+            return text.length;
+        }
+        // 2-byte non-CSI escapes: ESC 7 / ESC 8 (save/restore — cursor only,
+        // safe to ignore for our uses).
+        return start + 2;
+    }
+    handleCSI(text, start) {
+        let i = start;
+        let isPrivate = false;
+        if (text[i] === "?" || text[i] === ">" || text[i] === "<") {
+            isPrivate = true;
+            i++;
+        }
+        let params = "";
+        while (i < text.length && /[0-9;]/.test(text[i])) {
+            params += text[i];
+            i++;
+        }
+        if (i >= text.length)
+            return text.length;
+        const final = text[i];
+        i++;
+        this.executeCSI(params, final, isPrivate);
+        return i;
+    }
+    executeCSI(params, final, isPrivate) {
+        const parts = params.length === 0 ? [] : params.split(";").map((p) => parseInt(p, 10));
+        const n = (idx, def) => {
+            const v = parts[idx];
+            return v === undefined || isNaN(v) ? def : v;
+        };
+        // Private modes (e.g. ?25l/?25h cursor hide/show) — ignore.
+        if (isPrivate)
+            return;
+        switch (final) {
+            case "A": // cursor up
+                this.cursorRow = Math.max(0, this.cursorRow - n(0, 1));
+                return;
+            case "B": // cursor down (no scroll)
+                this.cursorRow = Math.min(this.rows - 1, this.cursorRow + n(0, 1));
+                return;
+            case "C": // cursor forward
+                this.cursorCol = Math.min(this.cols - 1, this.cursorCol + n(0, 1));
+                return;
+            case "D": // cursor back
+                this.cursorCol = Math.max(0, this.cursorCol - n(0, 1));
+                return;
+            case "E": // cursor next line
+                this.cursorRow = Math.min(this.rows - 1, this.cursorRow + n(0, 1));
+                this.cursorCol = 0;
+                return;
+            case "F": // cursor prev line
+                this.cursorRow = Math.max(0, this.cursorRow - n(0, 1));
+                this.cursorCol = 0;
+                return;
+            case "G": // cursor absolute column (1-based)
+                this.cursorCol = Math.min(this.cols - 1, Math.max(0, n(0, 1) - 1));
+                return;
+            case "H": // cursor position (1-based row;col)
+            case "f":
+                this.cursorRow = Math.min(this.rows - 1, Math.max(0, n(0, 1) - 1));
+                this.cursorCol = Math.min(this.cols - 1, Math.max(0, n(1, 1) - 1));
+                return;
+            case "J": {
+                // erase in display
+                const mode = n(0, 0);
+                if (mode === 0)
+                    this.eraseFromCursorToEndOfScreen();
+                else if (mode === 1)
+                    this.eraseFromStartOfScreenToCursor();
+                else if (mode === 2 || mode === 3)
+                    this.eraseScreen();
+                return;
+            }
+            case "K": {
+                // erase in line
+                const mode = n(0, 0);
+                if (mode === 0)
+                    this.eraseFromCursorToEndOfLine();
+                else if (mode === 1)
+                    this.eraseFromStartOfLineToCursor();
+                else if (mode === 2)
+                    this.eraseLine();
+                return;
+            }
+            case "S": // scroll up
+            case "T": // scroll down
+            case "m": // SGR colour — ignore (we don't model styling)
+            case "s": // save cursor
+            case "u": // restore cursor
+            case "n": // device status report — ignore
+            case "h": // set mode — ignore
+            case "l": // reset mode — ignore
+                return;
+        }
+    }
+    eraseLine() {
+        for (let c = 0; c < this.cols; c++)
+            this.visible[this.cursorRow][c] = " ";
+    }
+    eraseFromCursorToEndOfLine() {
+        for (let c = this.cursorCol; c < this.cols; c++)
+            this.visible[this.cursorRow][c] = " ";
+    }
+    eraseFromStartOfLineToCursor() {
+        for (let c = 0; c <= this.cursorCol; c++)
+            this.visible[this.cursorRow][c] = " ";
+    }
+    eraseFromCursorToEndOfScreen() {
+        this.eraseFromCursorToEndOfLine();
+        for (let r = this.cursorRow + 1; r < this.rows; r++) {
+            for (let c = 0; c < this.cols; c++)
+                this.visible[r][c] = " ";
+        }
+    }
+    eraseFromStartOfScreenToCursor() {
+        for (let r = 0; r < this.cursorRow; r++) {
+            for (let c = 0; c < this.cols; c++)
+                this.visible[r][c] = " ";
+        }
+        this.eraseFromStartOfLineToCursor();
+    }
+    eraseScreen() {
+        for (let r = 0; r < this.rows; r++) {
+            for (let c = 0; c < this.cols; c++)
+                this.visible[r][c] = " ";
+        }
+    }
+}
+export function createTerminalHarness(opts) {
+    const vt = new VirtualTerminal(opts);
+    const stream = {
+        write: (chunk) => {
+            vt.write(chunk);
+            return true;
+        },
+        columns: opts.streamColumns ?? opts.cols,
+        rows: opts.streamRows ?? opts.rows,
+        isTTY: true,
+    };
+    // log-update reads `stream.columns` / `stream.rows` defensively; the cast is
+    // safe because we exercise only those fields plus `write`.
+    const lu = createLogUpdate(stream, {
+        showCursor: true,
+    });
+    return {
+        vt,
+        logUpdate: lu,
+        stdoutWrite: (s) => vt.write(s),
+        stderrWrite: (s) => vt.write(s),
+    };
+}

package/dist/src/lib/heuristics/behavior-rule-detector.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Behavior-Rule Detector (issue #552)
+ *
+ * Shared heuristic for `/spec` (proactive) and `/qa` (reactive) phases that
+ * detects when an AC describes a *behavior rule* (e.g. "default becomes X",
+ * "always include Y", "never skip Z") and, when triggered, surfaces all
+ * touchpoints in the codebase that likely implement the rule.
+ *
+ * Behavior rules are routinely duplicated across a skill prompt
+ * (LLM-interpreted) AND the runtime TypeScript that backs it. Without this
+ * detector, edits land at one site and the other goes stale — see issue #533
+ * (motivating miss; documented in `references/behavior-rule-detection.md`).
+ *
+ * Three exported functions:
+ * - `detectBehaviorRule` — cheap keyword check; gates the more expensive greps
+ * - `findTouchpoints`   — used by `/spec` to enumerate likely implementations
+ * - `findSurvivingInverseSymbols` — used by `/qa` to flag OLD-rule survivors
+ *   inside the diff blast radius
+ *
+ * The keyword set is the source of truth in this file (per the /spec Open
+ * Question on keyword location). The reference doc cites it.
+ *
+ * @example
+ * ```typescript
+ * import { detectBehaviorRule, findTouchpoints } from "./behavior-rule-detector.ts";
+ *
+ * const detection = detectBehaviorRule(ac);
+ * if (detection.triggered) {
+ *   const hits = findTouchpoints(ac, process.cwd());
+ *   for (const h of hits) console.log(`${h.path}:${h.line}  ${h.snippet}`);
+ * }
+ * ```
+ */
+import type { AcceptanceCriterion } from "../workflow/state-schema.js";
+/**
+ * Behavior keywords whose presence (≥2 distinct, OR matching the explicit
+ * pattern below) signals an AC describes a rule rather than a localized fix.
+ * Tunable here; cited from `references/behavior-rule-detection.md`.
+ */
+export declare const BEHAVIOR_KEYWORDS: readonly ["default", "always", "never", "rule", "behavior", "skip"];
+export type BehaviorKeyword = (typeof BEHAVIOR_KEYWORDS)[number];
+/** A single touchpoint hit (file location matching a behavior-rule symbol). */
+export interface TouchpointHit {
+    path: string;
+    line: number;
+    snippet: string;
+}
+export interface BehaviorRuleDetection {
+    triggered: boolean;
+    keywords: BehaviorKeyword[];
+    matchedPattern?: string;
+}
+/**
+ * Detect whether an AC describes a behavior rule.
+ *
+ * Trigger conditions:
+ * 1. ≥2 distinct {@link BEHAVIOR_KEYWORDS} present in the AC description
+ *    (case-insensitive, word-boundary match), OR
+ * 2. Description matches one of the {@link EXPLICIT_PATTERNS}
+ *    (e.g. "always X unless Y").
+ *
+ * Returns `triggered: false` for empty or undefined descriptions, single
+ * keyword matches without an explicit pattern, and file-specific ACs
+ * ("Update line 42 of foo.ts").
+ */
+export declare function detectBehaviorRule(ac: AcceptanceCriterion): BehaviorRuleDetection;
+/**
+ * Find touchpoints in the codebase that likely implement the behavior rule
+ * described by `ac`. Returns `[]` when {@link detectBehaviorRule} does not
+ * trigger (cheap short-circuit per the /spec performance budget).
+ *
+ * Heuristic:
+ *  - Extract identifier-like symbols from the AC (backticked strings, file
+ *    paths with extensions, ALL_CAPS / camelCase / kebab-case identifiers).
+ *  - Walk {@link TOUCHPOINT_ROOTS}; for each line in matching files, mark a
+ *    hit if the line contains any extracted symbol OR ≥2 distinct AC
+ *    behavior keywords.
+ *  - Hits are deduplicated by `path:line` and capped (per-file: 3, total: 200)
+ *    to keep `/spec` output readable (callers can re-run with a tighter scope
+ *    if needed).
+ */
+export declare function findTouchpoints(ac: AcceptanceCriterion, repoRoot: string): TouchpointHit[];
+/**
+ * Find OLD-rule survivors inside the diff blast radius. Used by `/qa` to flag
+ * an AC `NOT_MET` when the inverse of the asserted rule still has live code.
+ *
+ * Differs from {@link findTouchpoints}:
+ *  - Scope is `diffPaths` (caller is responsible for pre-expanding to 1-hop
+ *    importers when desired — this avoids embedding a TS-only importer scanner
+ *    here and keeps the function language-agnostic).
+ *  - Search terms are *inverse* keywords derived from the AC's keywords (and
+ *    inverse English phrasing as a fallback when no symbols match).
+ */
+export declare function findSurvivingInverseSymbols(ac: AcceptanceCriterion, repoRoot: string, diffPaths: string[]): TouchpointHit[];