@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/gates/citations.d.ts

@@ -0,0 +1,408 @@
+import type { GateResultFields } from "./result.ts";
+import type { SchemaDocument } from "./validate.ts";
+/**
+ * THE CITATION LINTER (kernel plan M2, M2-P5).
+ *
+ * FIX ROUND ONE (2026-08-06). The round-one hazard review (`delivery/review/
+ * clean-room-m2-p5-hazard.md`) found the delivered gate exits RED on the
+ * head that delivered it (CR-1015) and reds on pre-existing content a PR did
+ * not touch (CR-1016). Both trace to ONE mechanism: the gate lints the
+ * WHOLE BODY of every changed file, and cannot tell a citation a document
+ * MAKES from one it QUOTES, nor a line the PR wrote from a line that was
+ * already there. The arbitration (`delivery/review/arbitration-m2-p5.md`)
+ * settles two design questions that this round implements rather than
+ * re-litigates:
+ *
+ *   M2-D-21 (diff-read scope): a citation is resolved only when it was
+ *   ADDED or MODIFIED in the diff `base...head`, computed per changed HUNK.
+ *   The `citationRequired` vacuous guard still asks whether the document AS
+ *   A WHOLE makes at least one citation (not hunk-scoped).
+ *
+ *   M2-D-22 (made vs quoted): a citation inside an inline code span
+ *   (backticks) or a fenced code block is QUOTED, not made, and is never
+ *   resolved. This is the convention the repository already follows
+ *   (writing `src/nope.ts:1` in prose to mean "this does not resolve").
+ *
+ * The same round also closes, at the mechanism rather than the instance:
+ *
+ *   CR-1017: every content read (the document under lint, and every cited
+ *   target) is now taken from the GIT OBJECT at the `--head` revision via
+ *   `git cat-file`, never from the working tree / `cwd`. A gate told to
+ *   judge revision X now judges X regardless of what is checked out.
+ *   Structural side effect, verified rather than assumed (see the module's
+ *   `readGitBlob`/`gitObjectType` doc comment): this ALSO closes CR-1018,
+ *   because a git tree has no ".." entry and cannot be escaped by a
+ *   traversal string, and CR-1021 (the vanish race), because the file list
+ *   and the content it names now come from the SAME fixed git objects
+ *   instead of two different clocks (a commit graph and a live filesystem).
+ *
+ *   CR-1019: a `@sha256:` suffix that is present but does not match the
+ *   64-lowercase-hex shape is `red` naming the malformed suffix, never
+ *   silently dropped to a hash-free citation.
+ *
+ *   CR-1020: the vacuous guard counts SUBSTANTIVE citations (not quoted,
+ *   not a citation to the document's own path), so a document that only
+ *   cites itself no longer satisfies it.
+ *
+ *   CR-1022: root classification checks EVERY declared root for the
+ *   concrete path under test (never returns on the first match); a path
+ *   matching more than one root is `ambiguous`, refused rather than
+ *   guessed. The shipped default config's local and external match lists
+ *   are DISJOINT (the local `bin` pattern is narrowed to `bin/*.ts`, the
+ *   real files this checkout ships there, rather than `bin/**`, which used
+ *   to overlap `bin/fm-*.sh` and depended on undocumented array order to
+ *   resolve correctly), so the ambiguity check has nothing to silently
+ *   paper over in the shipped configuration.
+ *
+ *   CR-1023/1024/1025/1026: the grammar's token boundary is Unicode-aware
+ *   (a token cannot be fabricated by resuming a match after a colon,
+ *   backslash or a non-ASCII letter), a malformed trailing continuation
+ *   (`:3-`, `:3.5`, a non-ASCII hyphen) is `red` naming the leftover text
+ *   rather than silently truncated, leading zeros are an explicitly
+ *   documented and intentional relaxation, and a content hash is computed
+ *   over the cited lines with any trailing `\r` stripped, so a CRLF
+ *   checkout does not red on a normalization difference.
+ *
+ * HAZARD CLASS (T-007, M2-D-18), restated because it still drives every
+ * design choice below: "a linter over documents it does not own, walking a
+ * tree supplied by configuration." M2-C-6 IS OBEYED BY REUSE, NOT
+ * REIMPLEMENTATION, adapted to the substrate this round moves reads onto:
+ * the config schema document (the one remaining filesystem read) still goes
+ * through the delivered `classifyEntry`/`readRegularFileIfPresent` from
+ * `src/task.ts`; every git-object read goes through `readGitBlob`/
+ * `gitObjectType`, this module's ONE answer to "may this git path be
+ * treated as file content", which establishes the object's TYPE (blob,
+ * tree, commit, or missing) before ever treating its output as text, the
+ * same probe-then-open shape `classifyEntry` uses for the filesystem. The
+ * one-shot inventory (unrelated to any `--head`, a live report over the
+ * actual checkout) is UNCHANGED by this round and still walks the
+ * filesystem through `classifyEntry`, because that is genuinely what it
+ * examines.
+ *
+ * THE RECOGNIZED GRAMMAR (step 2), stated once here and nowhere else:
+ *
+ *   path:LINE                  a single line
+ *   path:START-END              an inclusive line range
+ *   (either form) + @sha256:<64 lowercase hex>
+ *                               content-hash suffix: the cited line(s),
+ *                               joined by "\n" with any trailing "\r"
+ *                               stripped per line and no trailing newline,
+ *                               must hash to the given digest
+ *
+ * `path` is one or more `[A-Za-z0-9_./-]` characters ending in a recognized
+ * extension (ts, tsx, js, mjs, cjs, sh, md, json, yaml, yml). The token
+ * boundary is Unicode-aware on BOTH sides: a match cannot start immediately
+ * after a letter (any script), digit, `_`, `.`, `/`, `:` or `\`, and cannot
+ * end immediately before anything other than whitespace, end of text, a
+ * closing bracket/quote, or a `.` not itself followed by a digit (CR-1023,
+ * CR-1024). Leading zeros in the line/range numbers are accepted and
+ * normalized by decimal parsing (`:007` means line 7); this is an
+ * intentional relaxation, not an oversight (CR-1025).
+ *
+ * SECOND CALL SITE (R-025), grammar and mechanism UNCHANGED by this round:
+ * a plan review invokes the SAME executable, `node src/gates/citations.ts
+ * --result <file> --evidence <dir> --base <ref> [--head <ref>]`. CR-1017's
+ * fix is exactly what makes this call site trustworthy: `--head` now
+ * selects the CONTENT judged, not only the file list.
+ *
+ * ESCALATED, NOT THIS PHASE'S TO FIX (arbitration, final section): whether
+ * a `required` gate that reaches `not-applicable` should fail the aggregate
+ * is an M2-wide policy question for M2-P9, not resolved here. A review
+ * citing only an external root (verifying nothing) reaches `not-applicable`
+ * rather than `red` for that same, already-escalated reason.
+ *
+ * CI PRECONDITIONS THIS GATE REQUIRES (delivery/STATE.md's CR-902
+ * carry-forward): `fetch-depth: 0` in the checkout step, so `base` and
+ * `head` are both fetchable commits, not shallow-clone-absent ones.
+ */
+export interface CitationRoot {
+    name: string;
+    description?: string;
+    /** Explicit path globs. Segments separated by "/"; "*" matches within one
+     * segment, "**" matches zero or more whole segments. No other wildcard. */
+    match: string[];
+}
+export interface CitationConfig {
+    version: number;
+    /** Local roots: this checkout. */
+    roots: CitationRoot[];
+    /** Roots naming a repository this checkout does not contain. */
+    externalRoots: CitationRoot[];
+    /** Path globs identifying the configured document set (M2-D-10: diff-scoped
+     * at gate run time; walked in full only by the one-shot inventory). */
+    documents: string[];
+    /** The subset of `documents` in which zero SUBSTANTIVE citations is red
+     * (M2R-014's narrowed vacuous guard; CR-1020: substantive excludes quoted
+     * tokens and a citation to the document's own path). */
+    citationRequired: string[];
+}
+/**
+ * THE ONE COMMITTED CONFIGURATION (step 2; CR-1022 fix round).
+ *
+ * `roots[0].match` no longer includes `bin/**`. It used to, and `bin/fm-
+ * lock.sh` matched BOTH that pattern and the external `firstmate` root's
+ * `bin/fm-*.sh`; the two-root match was resolved correctly only because the
+ * code checked external roots before local ones, an implicit, undeclared
+ * precedence the hazard review named as fragile (CR-1022). The local
+ * pattern is narrowed to `bin/*.ts`, the actual files this checkout ships
+ * in `bin/` (today, `bin/tiphys.ts`), which shares no path with any
+ * `externalRoots` glob. The two root lists are therefore DISJOINT by
+ * construction, and `classifyPathAgainstRoots` needs no precedence rule at
+ * all: it checks every root and refuses ambiguity outright (CR-1022).
+ *
+ * Orchestrator decision (2026-08-07, under DR-0015; the owner delegated this
+ * scope call and is not an approval step in execution; reversible, owner may
+ * override): the gate governs FORWARD-CLAIMING delivery docs, NOT the
+ * historical delivery RECORD. Rationale recorded in
+ * delivery/work-history/m2-citations-scope.md. The `delivery/review/` and
+ * `delivery/work-history/` trees are records of what was examined at the
+ * time they were written; their `path:line` refs were valid when authored
+ * and drift as the code moves. Once the exit harness runs the full gate set
+ * on every doc PR, requiring a record's citations to still RESOLVE at head
+ * is the wrong policy: it re-litigates settled history against current code.
+ * So both trees are removed from `documents`, and review from
+ * `citationRequired`. The docs whose claims MUST hold against current code
+ * stay gated: the `delivery/plan/`, `delivery/verification/`,
+ * `delivery/decisions/`, `delivery/requirements/` trees and `delivery/STATE.md`
+ * are documents; the `delivery/plan/` and `delivery/verification/` trees are
+ * citationRequired. Anti-fabrication is preserved on every forward-claiming
+ * doc; the drift of the historical record is no longer a gate failure.
+ */
+export declare const DEFAULT_CITATION_CONFIG: CitationConfig;
+export declare function citationConfigSchema(): SchemaDocument;
+export declare function citationConfigSchemaPath(): string;
+export declare function validateCitationConfigDocument(document: unknown): string[];
+export interface AmbiguousGlob {
+    glob: string;
+    roots: string[];
+}
+/**
+ * Config-load-time check: the identical glob STRING declared under more
+ * than one root. This is separate from, and does not replace,
+ * `classifyPathAgainstRoots`'s per-citation check (CR-1022): this one
+ * answers "did the config author write the same glob twice", which is
+ * decidable from the config alone; that one answers "does THIS concrete
+ * path match glob patterns from more than one root", which needs the
+ * concrete string and cannot be answered from the config in isolation.
+ */
+export declare function findAmbiguousGlobs(config: CitationConfig): AmbiguousGlob[];
+export declare function findOrphanCitationRequired(config: CitationConfig): string[];
+export declare function matchesGlob(pattern: string, path: string): boolean;
+export declare function matchesAny(globs: string[], path: string): boolean;
+export type RootClassification = {
+    kind: "external";
+    root: string;
+} | {
+    kind: "local";
+    root: string;
+} | {
+    kind: "unmatched";
+} | {
+    kind: "ambiguous";
+    roots: string[];
+};
+/**
+ * Checks EVERY declared root (both lists, in full) rather than returning on
+ * the first match (CR-1022's named defect). A path matching exactly one
+ * root, of either kind, resolves to that root. A path matching two or more
+ * roots is `ambiguous`, named with every matching root, and is never
+ * guessed by declaration order. The shipped `DEFAULT_CITATION_CONFIG` has
+ * no overlap between its local and external match lists (see that
+ * constant's own doc comment), so this can only fire on a genuine
+ * configuration mistake, not on ordinary use.
+ */
+export declare function classifyPathAgainstRoots(config: CitationConfig, path: string): RootClassification;
+export interface CitationToken {
+    raw: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    /** Set only when a `@sha256:` suffix was present AND valid (64 lowercase hex). */
+    hash?: string;
+    /** True when a `@sha256:` suffix was attempted but did not validate (CR-1019). */
+    hashMalformed: boolean;
+    /** Non-undefined when unsafe text immediately follows the recognized token
+     * with no separating whitespace (CR-1024): the citation is malformed, not
+     * silently narrowed. */
+    trailingMalformed?: string;
+    offset: number;
+}
+/**
+ * THE ONE GRAMMAR SCAN. Quoted-range exclusion (M2-D-22) and hunk-scoping
+ * (M2-D-21) are separate, composable passes over this function's output,
+ * not a second implementation of citation recognition.
+ */
+export declare function extractCitations(text: string): CitationToken[];
+/**
+ * Lines of a file body, 1-indexed by position in the returned array. A
+ * single trailing newline is not counted as an extra blank line; a
+ * completely empty body has zero lines.
+ */
+export declare function splitLines(body: string): string[];
+/**
+ * Character ranges (half-open `[start, end)`, sorted) that are QUOTED
+ * rather than MADE: fenced code blocks (opened and closed by a line whose
+ * first non-space run is 3+ of the same fence character, `` ` `` or `~`,
+ * matched by CommonMark's own rule of "same character, at least as long
+ * to close") and inline code spans (a run of one or more backticks,
+ * matched by the NEXT run of the SAME length on the same line). This is a
+ * deliberately LINE-ORIENTED simplification: it does not handle an inline
+ * span whose content itself contains a shorter backtick run (needing a
+ * longer delimiter per CommonMark), which does not occur anywhere in this
+ * repository's corpus (verified by the one-shot inventory finding no
+ * citation whose surrounding text uses that construct).
+ */
+export declare function computeQuotedRanges(body: string): Array<[number, number]>;
+export type TouchedLines = {
+    kind: "all";
+} | {
+    kind: "ranges";
+    ranges: Array<[number, number]>;
+};
+export type GitObjectRead = {
+    kind: "blob";
+    body: string;
+} | {
+    kind: "missing";
+} | {
+    kind: "irregular";
+    reason: string;
+} | {
+    kind: "error";
+    reason: string;
+};
+/**
+ * THE ONE ANSWER to "may this git path be treated as file content"
+ * (M2-C-6, adapted to the git-object substrate CR-1017 moves reads onto).
+ * `git cat-file -t <rev>:<path>` establishes the object's TYPE before its
+ * content is ever read, the same probe-then-open shape `classifyEntry`
+ * uses for the filesystem: `blob` is the only type this function reads;
+ * `tree` (a directory) and `commit` (a submodule gitlink) are `irregular`,
+ * named with the observed type, never opened as if they were text; a path
+ * git reports as not existing at this revision is `missing`, which is not
+ * an error (the normal shape of "the diff added a new document," or of a
+ * dangling citation).
+ *
+ * VERIFIED, not assumed (T-006): `git cat-file -t HEAD:src/../../etc/passwd`
+ * and `git cat-file -t HEAD:src/../delivery/STATE.md` (a traversal that
+ * WOULD land on a real in-repo file if resolved as a filesystem path) both
+ * report "does not exist", because git's tree lookup treats the path
+ * segment-by-segment against actual tree entries and no tree can contain a
+ * `..` entry; there is no filesystem-style traversal to close, because the
+ * data structure this function reads from has no parent pointer to walk
+ * (CR-1018, closed structurally rather than by a denylist).
+ */
+export declare function gitObjectType(cwd: string, rev: string, path: string): {
+    kind: "type";
+    type: string;
+} | {
+    kind: "missing";
+} | {
+    kind: "error";
+    reason: string;
+};
+export declare function readGitBlob(cwd: string, rev: string, path: string): GitObjectRead;
+export type CitationResolution = {
+    kind: "resolved";
+    detail: string;
+} | {
+    kind: "unresolved";
+    detail: string;
+} | {
+    kind: "unverifiable-external";
+    root: string;
+    detail: string;
+}
+/** M2-C-6: the cited target is present and is not a git blob / not a
+ * regular file, depending on which read strategy is in use. */
+ | {
+    kind: "read-error";
+    path: string;
+    reason: string;
+};
+/** How to fetch a cited target's content: git-object (the registered gate,
+ * CR-1017) or filesystem (the one-shot inventory, which examines the live
+ * checkout by design). Parameterizing the read is what keeps resolution ONE
+ * implementation across both call sites (never a second one). */
+export type TargetReader = (path: string) => GitObjectRead;
+export declare function gitTargetReader(cwd: string, rev: string): TargetReader;
+export declare function filesystemTargetReader(repoRoot: string): TargetReader;
+export declare function resolveCitation(config: CitationConfig, token: CitationToken, readTarget: TargetReader): CitationResolution;
+export interface DocumentAnalysis {
+    /** Non-quoted, non-self tokens: what the vacuous guard asks about,
+     * whole-document, never hunk-scoped (arbitration M2-D-21). */
+    substantiveCount: number;
+    /** Every non-quoted token, self included (for reporting). */
+    totalNonQuoted: number;
+    resolved: number;
+    /** Resolved, but the citation's path equals the citing document's own
+     * path (CR-1020): correctness is still checked, but it does not count
+     * toward `resolved` units or the vacuous guard. */
+    selfResolved: number;
+    unverifiableExternal: number;
+    unresolvedDetails: string[];
+}
+export type DocumentAnalysisOutcome = {
+    kind: "analyzed";
+    analysis: DocumentAnalysis;
+} | {
+    kind: "read-error";
+    path: string;
+    reason: string;
+};
+/**
+ * THE ONE COUNTING PASS. `touched` selects which tokens are actually
+ * RESOLVED (M2-D-21: hunk ranges for the registered gate, `{kind:"all"}`
+ * for the one-shot inventory, which has no diff to scope by). The vacuous
+ * `substantiveCount` is NEVER hunk-scoped, per the arbitration: a document
+ * makes at least one citation, or it does not, independent of what this
+ * particular diff touched.
+ */
+export declare function analyzeDocument(config: CitationConfig, body: string, relativePath: string, touched: TouchedLines, readTarget: TargetReader): DocumentAnalysisOutcome;
+export declare function listConfiguredDocuments(repoRoot: string, config?: CitationConfig, startDir?: string): string[];
+export interface InventoryRow {
+    path: string;
+    /** resolved + selfResolved + unresolved + unverifiableExternal. */
+    total: number;
+    /** Includes self-resolved citations (folded in for this report; the
+     * registered gate's `units` excludes them, see `runCitationsGate`). */
+    resolved: number;
+    unresolved: number;
+    unverifiableExternal: number;
+}
+export declare function inventoryDeliveryTree(repoRoot: string, config?: CitationConfig, startDir?: string): InventoryRow[];
+export interface CitationsGateOptions {
+    cwd: string;
+    base?: string;
+    head?: string;
+    config?: CitationConfig;
+}
+/**
+ * The kernel gate entry. Lints only citations ADDED or MODIFIED in the diff
+ * `base...head` (M2-D-21), reading every byte of content -- the document
+ * under lint AND every cited local target -- from the git object at `head`
+ * (CR-1017), never from `cwd`'s working tree.
+ *
+ * `--base` absent is `error`, never `not-applicable` (M2-C-3), checked
+ * independently of the runner's own `diff-touches` precondition because
+ * R-025's second call site invokes this function directly.
+ *
+ * THE VACUOUS GUARD (M2R-014, M2-D-21, CR-1020): a `citationRequired`
+ * document with zero SUBSTANTIVE citation tokens anywhere in the WHOLE
+ * document (not quoted, not a citation to its own path) is `red`. This is
+ * intentionally NOT hunk-scoped: the arbitration is explicit that "the
+ * document as a whole makes at least one citation" is the question, so a
+ * PR that edits one unrelated line of an otherwise-empty required document
+ * still reds on it, and a PR that adds the document's first real citation
+ * still turns it green.
+ *
+ * NOT-APPLICABLE WHEN NOTHING SUBSTANTIVE WAS VERIFIED: M2-C-2 forbids a
+ * green record with zero units, so a changed set whose only in-scope
+ * citations are quoted, self-referential, or external resolves
+ * `not-applicable` rather than a fabricated green. Because `citations` is
+ * registered `required`, this still fails the aggregate; that is the
+ * escalated, M2-wide policy question the arbitration assigns to M2-P9, not
+ * this gate.
+ */
+export declare function runCitationsGate(options: CitationsGateOptions): GateResultFields;
+export declare function main(argv: string[]): number;