@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/witness/run.d.ts

@@ -0,0 +1,299 @@
+import type { Pin } from "../gates/pin.ts";
+import type { DangerousStateMember, WitnessSpec } from "./spec.ts";
+/**
+ * THE RED-WITNESS HARNESS (kernel plan M2, M2-P2 step 3, step 4, step 5).
+ *
+ * A test guards a behavior only when it has been demonstrated RED against a
+ * dangerous state that intersects the phase diff and GREEN at head, in a
+ * pinned isolated run. This module evaluates one witness spec: refusal
+ * rules (a) to (g) first, each producing `red` with a reason naming its
+ * source, then per-member execution in a scratch clone the harness owns.
+ *
+ * ISOLATION (M2-C-4). Every member is evaluated in its own scratch clone
+ * under a directory this run created with mkdtemp. The caller's repository
+ * is only ever READ (git read commands and file reads through the delivered
+ * probes); after any run its HEAD and working tree are untouched.
+ *
+ * PINS (M2-C-5, and work-history decision D-P2-1). The delivered pin is
+ * five fields including ctimeMs, which userspace cannot restore, so pins
+ * bracket EACH TEST EXECUTION rather than the mutate-restore cycle: the red
+ * runs are bracketed by a pin pair over the dangerous tree they actually
+ * execute, and the green head run by a pair over the head tree. A
+ * difference inside either pair is `error` naming the path and the fields.
+ *
+ * REPORTER PIN (MECHANISMS.md, "Parsing another program's reporter
+ * output"). The child is always invoked with an explicit
+ * `--test-reporter tap`; a stream that does not open with `TAP version` is
+ * an error naming the expected and observed formats, never a widened parse.
+ *
+ * C-2 and C-3: children run in the foreground via spawnSync with a
+ * timeout; nothing here probes a process, detaches, or touches /proc.
+ */
+export interface WitnessHooks {
+    /**
+     * DOCUMENTED IN-HARNESS TEST HOOK (M2-P2 criterion 7, M2R-009). Called
+     * once per member, between the green run's start and end pins, with the
+     * clone's absolute path. Exists so a pin witness can rewrite a file
+     * byte-identically inside the pinned window and prove the five-field pin
+     * catches it. Never set outside tests.
+     */
+    betweenPins?: (cloneDir: string) => void;
+}
+export interface DiffFile {
+    path: string;
+    /** git name-status letter (A, M, D, R...). */
+    status: string;
+    /** New-side [start, end] line ranges of changed hunks, 1-based inclusive. */
+    hunks: Array<[number, number]>;
+}
+export interface PhaseDiff {
+    baseSha: string;
+    headSha: string;
+    /**
+     * The merge base of base and head, which is the revision the `base...head`
+     * three-dot diff below is actually taken against. Anything asking "what did
+     * this phase change" must read the old side HERE and not at `baseSha`: on a
+     * branch that has fallen behind, `baseSha` carries commits the branch never
+     * saw, and reading them as the branch's own starting point reproduces the
+     * two-dot misreading of standing warning 13.
+     *
+     * It falls back to `baseSha` when git computes no merge base, and THAT
+     * FALLBACK IS UNREACHABLE THROUGH THIS FUNCTION, which is said here rather
+     * than left for a reader to assume it is a tested path. Measured 2026-08-15
+     * on two orphan roots in one repository: `git merge-base A B` exits 1 with no
+     * output, and `git diff --name-status --no-renames A...B` exits 128 with
+     * `fatal: <A>...<B>: no merge base`. The diff below is the same three-dot
+     * form, so `computePhaseDiff` returns `ok: false` on the diff and never
+     * reaches the assignment. The fallback stays because the alternative is
+     * `"".trim()` silently becoming a sha-shaped empty string, which is a worse
+     * failure than an unreachable line.
+     */
+    mergeBaseSha: string;
+    files: Map<string, DiffFile>;
+}
+export interface EvaluationInputs {
+    repoRoot: string;
+    headSha: string;
+    /**
+     * The ref or sha resolved per clone against the FETCHED remote (M2-P2
+     * step 7: merge-time re-verification is the `--baseline` parameter).
+     */
+    baselineRef: string;
+    diff: PhaseDiff;
+    destructiveCommands: string[];
+    behaviors: Set<string>;
+    /** Repo-relative test file path -> source at the audited head. */
+    testFiles: Map<string, string>;
+    /** Changed files the spawn grep matched (rule (f) derivation). */
+    spawningChangedFiles: string[];
+    scratchRoot: string;
+    /**
+     * Indices into `spec.dangerousStates` that THIS PHASE AUTHORED, which is
+     * the exact scope of rule (d). Empty for a stored witness the phase did not
+     * touch, and empty is the whole of "rule (d) does not apply here".
+     *
+     * This replaced a file-granular `phaseOwn: boolean`. The boolean was decided
+     * by the spec FILE appearing in the diff and then gated a PER MEMBER
+     * obligation, so any edit to any member imposed rule (d) on every sibling
+     * member of the same file. See `phaseOwnedMemberIndices` in ../witness/spec.ts
+     * for the derivation and for why an unreadable baseline owns everything.
+     */
+    phaseOwnedMembers: ReadonlySet<number>;
+    hooks?: WitnessHooks;
+}
+export interface MemberRun {
+    exitCode: number;
+    red: boolean;
+    failedNamedTests: string[];
+    passedNamedTests: string[];
+    missingNamedTests: string[];
+}
+export interface PinPairRecord {
+    start: Pin;
+    end: Pin;
+    equal: boolean;
+}
+export interface MemberRecord {
+    index: number;
+    member: DangerousStateMember;
+    description: string;
+    baselineSha?: string;
+    /** The applied dangerous-state diff, verbatim (git diff output). */
+    appliedDiff?: string;
+    mutatedLines?: {
+        file: string;
+        lines: number[];
+    };
+    preservesAssertedText?: boolean;
+    rate?: {
+        red: number;
+        total: number;
+    };
+    runs: MemberRun[];
+    redPins?: PinPairRecord;
+    greenPins?: PinPairRecord;
+    headGreen?: boolean;
+    unreachedArm?: {
+        file: string;
+        lines: number[];
+        greenTests: string[];
+    };
+    problem?: string;
+}
+export type WitnessStatus = "green" | "red" | "error";
+export interface WitnessEvaluation {
+    witness: string;
+    specPath: string;
+    behavior: string;
+    status: WitnessStatus;
+    reasons: string[];
+    textAsserting: boolean;
+    assertedPatterns: string[];
+    testFiles: string[];
+    captures?: Array<{
+        path: string;
+        sha256: string;
+        provenance: string;
+    }>;
+    members: MemberRecord[];
+}
+interface GitResult {
+    ok: boolean;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    reason: string;
+}
+export declare function gitIn(cwd: string, args: string[]): GitResult;
+/**
+ * Compute the phase diff base...head: changed files with status and the
+ * new-side line ranges of every changed hunk.
+ */
+export declare function computePhaseDiff(repoRoot: string, base: string, head: string): {
+    ok: true;
+    diff: PhaseDiff;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The spawn grep of rule (f), over the changed files' head-state contents.
+ * Exactly the plan's four tokens (M2-P2 step 4 rule (f)): a wider pattern
+ * (for example a bare `exec(`) false-positives on `RegExp.exec` calls and
+ * would derive a capture obligation from a file that spawns nothing.
+ */
+export declare const SPAWN_GREP: RegExp;
+/**
+ * The shell form of rule (f)'s derivation (CR-H2). A POSIX shell script that
+ * spawns another program and PARSES its output contains none of the four JS
+ * tokens, so `SPAWN_GREP` is blind to exactly where M1's V-2 lived
+ * (`bin/fm-*.sh` classifying git contention output). A shell spawn-and-parse
+ * is derived as the conjunction of two signals over the script text:
+ *   - SPAWN: another program's output is captured (a pipeline `|`, a command
+ *     substitution `$(...)` or backticks, or stdin consumed by `read`/`while
+ *     read`);
+ *   - PARSE: that output is classified or transformed (`grep`, `awk`, `sed`,
+ *     `cut`, `tr`, a `case` branch, or a `[[ ... =~ ... ]]` regex test).
+ * The conjunction is deliberately narrow: a script that only runs a command
+ * for its exit status, with no capture and no classifier, is not "in that
+ * state" and is not burdened with a capture obligation. What this does NOT
+ * cover is stated in the work history (rule (f), shell residue).
+ */
+export declare const SHELL_SPAWN: RegExp;
+export declare const SHELL_PARSE: RegExp;
+/** True when the shell script text both spawns a program and parses its output. */
+export declare function shellSpawnsAndParses(text: string): boolean;
+export interface TapTestPoint {
+    name: string;
+    ok: boolean;
+    skipped: boolean;
+}
+export type TapParse = {
+    ok: true;
+    tests: TapTestPoint[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Parse a PINNED tap stream. The format is a controlled input: the child
+ * was invoked with `--test-reporter tap`, so a stream that does not open
+ * with `TAP version` is a reporter-pin failure naming both formats, never
+ * something to parse anyway.
+ */
+export declare function parseTapStream(text: string): TapParse;
+export interface TextAssertionDerivation {
+    textAsserting: boolean;
+    /** Document paths (repo-relative) the named tests' sources read. */
+    documents: string[];
+    /** Regex sources and literals the assertions apply to those contents. */
+    patterns: string[];
+}
+/**
+ * Rule (g)'s text-assertion detection, DERIVED from the named tests'
+ * sources rather than declared: a source that reads a document from a path
+ * outside `src/` and `test/` (a workflow, a manifest, a configuration
+ * document) and ASSERTS THAT DOCUMENT'S TEXT is text-asserting. The
+ * assertion is tied to the read result (a variable binding or an inline
+ * read), never a free-floating assert form, so a read consumed by a project
+ * function stays behaviour. Detection is syntactic and fails CONSERVATIVELY:
+ * a recognised assert form whose pattern is not statically extractable still
+ * marks the witness text-asserting (subject to rule (g)) rather than
+ * returning false. The derivation's limits are stated in the work history.
+ */
+export declare function deriveTextAssertions(sources: string[]): TextAssertionDerivation;
+/**
+ * Resolve named tests to the repo-relative test files whose head-state
+ * source contains the name literally. A name found nowhere is a spec
+ * defect the caller turns into a red reason.
+ */
+export declare function resolveNamedTests(tests: string[], testFiles: Map<string, string>): {
+    files: string[];
+    missing: string[];
+};
+/**
+ * The 1-based line numbers a find text occupies, across every occurrence,
+ * multi-line finds included (a single-line scan misses those, and rule (d)
+ * plus the unreached-arm report both need the true span).
+ */
+export declare function findOccurrenceLines(body: string, find: string): number[];
+interface CloneOutcome {
+    dir?: string;
+    reason?: string;
+}
+/**
+ * Create a scratch clone of the audited repository at the audited head,
+ * with `origin` pointing at the audited repository's own origin when it
+ * has one (so baselines resolve against the real remote after a fetch,
+ * never a stale local ref), else at the audited repository itself.
+ */
+export declare function makeClone(repoRoot: string, headSha: string, scratchRoot: string, label: string): CloneOutcome;
+/**
+ * Evaluate one witness spec end to end. Refusal rules first; then, per
+ * declared dangerous-state member, a scratch clone, the member applied, the
+ * named tests run red `repeats` times, head restored, the named tests run
+ * green, everything pinned and recorded.
+ */
+export declare function evaluateWitness(spec: WitnessSpec, specPath: string, inputs: EvaluationInputs): WitnessEvaluation;
+/** Create the scratch root this harness owns; the caller removes it. */
+export declare function makeScratchRoot(): string;
+/** Remove a scratch root created by makeScratchRoot. */
+export declare function removeScratchRoot(root: string): void;
+/**
+ * Read the head-state sources of every test file under `test/`, from git
+ * rather than the working tree, because on pull_request events the checkout
+ * is a synthetic merge commit and the audited head is `--head`.
+ */
+export declare function readTestFilesAtHead(repoRoot: string, headSha: string): {
+    ok: true;
+    files: Map<string, string>;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Resolve the absolute path of a repository root, refusing a non-directory. */
+export declare function resolveRepoRoot(path: string): {
+    root?: string;
+    reason?: string;
+};
+export {};