@tiphys/kernel 0.0.0 → 0.1.0

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

@@ -0,0 +1,284 @@
+/**
+ * THE COVERAGE CHECKER (kernel plan M2, M2-P6).
+ *
+ * "No orphans" as a check with an exit code: every id in an INVENTORY
+ * document lands in exactly one row of a COVERAGE-TABLE document, a bucket
+ * value that does not match a declared kind is named rather than silently
+ * uncounted, a bucket kind that requires a note (`parked`) is red when the
+ * note is empty, and a coverage-table row whose id is absent from the
+ * inventory (a renumbering) is named as phantom coverage.
+ *
+ * HAZARD CLASS (T-007, M2-D-18): arithmetic over two documents that can
+ * drift, where a total can add up while a row is lost. Named defenses,
+ * each tied to a criterion:
+ *
+ *   - a renumbering that leaves a bucket row pointing at a dead id: the
+ *     PHANTOM check (every coverage-table row's id is required to be in
+ *     the inventory), independent of the orphan check (every inventory id
+ *     is required to have a coverage-table row).
+ *   - a duplicated id INSIDE the inventory document itself (fix round 1,
+ *     CR-985): counted once as a unit is not the same claim as "appears
+ *     once in the text", so `units` is the count of DISTINCT ids and a
+ *     repeated id is its own named finding (`duplicate-inventory-id`),
+ *     symmetric with the coverage side's `double-bucketed` check.
+ *     **CORRECTED CLAIM (fix round 1): an earlier revision of this comment
+ *     said the orphan and phantom checks "scan in opposite directions on
+ *     purpose, so neither can compensate for the other's blind spot." That
+ *     was false for cardinality: a duplicated inventory id defeated BOTH
+ *     of them (it is not an orphan, because a coverage row exists; it is
+ *     not phantom, because the id is genuinely in the inventory), and
+ *     inflated every count while staying green. The true property is
+ *     narrower: orphan and phantom together catch every EXISTENCE
+ *     mismatch (an id present on one side and not the other); cardinality
+ *     mismatches (an id present more than once on one side) need the
+ *     separate check named above, and a row lost from BOTH documents
+ *     needs the `expectedUnits` check below, because the two documents
+ *     still agree with each other in that case and existence/cardinality
+ *     checks over agreeing documents find nothing.
+ *   - a row lost from BOTH documents (fix round 1, CR-986): the previous
+ *     bullet's residue. An optional `expectedUnits` config field states
+ *     the anchor no arithmetic over the two documents alone can produce;
+ *     a computed unit count that does not equal it is the
+ *     `expected-units-mismatch` finding. This repository's real config
+ *     sets it to 115 (kernel plan v1 Appendix A's stated total).
+ *   - a bucket value matching no declared kind, silently uncounted: every
+ *     bucket-kind pattern is compiled ANCHORED (`^(?:pattern)$`) and tested
+ *     against the whole cell; a value none of them match is the
+ *     `unknown-kind` finding, named by id and value, never absorbed into a
+ *     nearby kind by a partial match.
+ *   - a bucket value matching MORE than one declared kind (fix round 1,
+ *     CR-992): resolved by silent first-match-wins until this round; now
+ *     the `ambiguous-kind` finding, naming every kind that matched, rather
+ *     than one kind's `requiresNote` silently never being consulted.
+ *   - an empty inventory producing a green with nothing examined: `units`
+ *     is always the number of DISTINCT ids the inventory actually
+ *     produced, and this module never constructs a `GateResult` except
+ *     through `makeGateResult`, whose M2-C-2 rewrite turns a
+ *     green-with-zero-units record into `error` with `vacuous: true`.
+ *     This gate does not duplicate that rule; it relies on the shared
+ *     constructor the way M2-C-6 requires reuse of `classifyEntry` rather
+ *     than a second implementation of "may this path be read".
+ *   - a milestone extraction that cannot produce the totals the plan
+ *     states: the milestone view and the kind view are two INDEPENDENT
+ *     tallies computed from the same classification pass (`perKind` keyed
+ *     by the bucket kind's name, `perMilestone` keyed by the pattern's
+ *     first capture group when present, else by the kind's own name), so
+ *     the two views can be compared against each other and against the
+ *     plan's stated totals rather than one being asserted to imply the
+ *     other.
+ *   - a finding whose outcome cell is present but empty:
+ *     `checkFindingOutcomeParity` treats an empty outcome as a named
+ *     failure distinct from a missing row, so "the row exists" and "the
+ *     row says something" are not conflated. Fix round 1, CR-987: "empty"
+ *     is ONE shared predicate (`isEmptyCell`, below), applied wherever a
+ *     note or an outcome is tested, so whitespace-only and zero-width-only
+ *     content (U+200B, which `String.prototype.trim` does not strip) is
+ *     empty on both sides rather than only where a trim happened to run.
+ *   - a finding-to-outcome report carrying a PHANTOM outcome (fix round 1,
+ *     CR-988): `checkFindingOutcomeParity` used to scan inventory ids
+ *     only, so a report row for an id absent from the inventory (the
+ *     renumbering shape the coverage side's phantom check exists for) was
+ *     silently accepted. Now symmetric: a phantom outcome row is named.
+ *
+ * M2-C-6: the inventory path, the coverage-table path and an optional
+ * `--config` document are all supplied by configuration and none of them
+ * is a path this module created, so every read goes through
+ * `readRegularFileIfPresent` (which itself routes through `classifyEntry`),
+ * never a bare `readFileSync`. A named pipe at any of the three paths is
+ * `error` naming the path and the observed type, and this module never
+ * blocks on one. Fix round 1, CR-989: the same discipline now applies to
+ * the WRITE side inside the evidence directory (`counts.json`): a refused
+ * or failed write there used to be computed and discarded, leaving a
+ * silent green with empty evidence; it is now loud and makes the gate
+ * `error`, the same way a refused result-path write already did.
+ *
+ * Fix round 1 also closes the REGEX MECHANISM (CR-990/991/992): every
+ * config-supplied pattern (both `idPattern`s and every `bucketKinds[].pattern`)
+ * is VALIDATED (compiles, and is rejected if it matches a known
+ * catastrophic-backtracking shape) before it is ever executed, and every
+ * EXECUTION of a config-supplied pattern is BOUNDED by a wall-clock timeout
+ * (`boundedExec`, below), so neither a malformed pattern (CR-990, used to
+ * throw with no result record written) nor a ReDoS pattern (CR-991, used
+ * to hang indefinitely) can defeat this gate; CR-992 (overlapping kinds)
+ * is folded into the same fix because it is the same "a config string is
+ * trusted further than its syntax justifies" mechanism one property over.
+ */
+/** One row of the `bucketKinds` config. */
+export interface BucketKindConfig {
+    kind: string;
+    /** Regex source, compiled anchored `^(?:pattern)$` against a bucket value. */
+    pattern: string;
+    requiresNote: boolean;
+}
+export interface DocumentConfig {
+    path: string;
+    /** Regex source, compiled anchored, tested against a row's first cell. */
+    idPattern: string;
+}
+export interface CoverageTableConfig extends DocumentConfig {
+    /** 0-based cell index (cell 0 is the id) holding the bucket value. */
+    bucketColumn: number;
+    /** 0-based cell index holding the note. */
+    noteColumn: number;
+}
+export interface CoverageConfig {
+    inventory: DocumentConfig;
+    coverageTable: CoverageTableConfig;
+    bucketKinds: BucketKindConfig[];
+    /**
+     * CR-986: the exact expected count of DISTINCT inventory ids. Optional;
+     * when absent, no floor is enforced. A row deleted from BOTH documents
+     * leaves the two documents agreeing with each other, which every other
+     * check in this module is powerless against, so this is a config-stated
+     * anchor rather than a derived one.
+     */
+    expectedUnits?: number;
+}
+/**
+ * THE KERNEL CONFIG (kernel plan M2-P6 step 2): this repository's real
+ * pair and the four bucket kinds the plan states verbatim. It is a plain
+ * exported constant, not a checked-in data file, because M2-C-1's
+ * verification-first reading of the plan's files-to-touch list for this
+ * phase names the module, its schema and its test, and no committed
+ * configuration document alongside them; a `--config` flag (validated
+ * against `coverage-config.schema.json`) exists for a caller that wants a
+ * different pair, and every fixture test in `test/coverage-gate.test.ts`
+ * uses it rather than editing this constant.
+ */
+export declare const KERNEL_COVERAGE_CONFIG: CoverageConfig;
+/**
+ * THE SHARED EMPTINESS PREDICATE (fix round 1, CR-987).
+ *
+ * Before this round, `checkCoverage`'s note check compared a value already
+ * passed through `String.prototype.trim` (applied once, at extraction) to
+ * `""`, and `checkFindingOutcomeParity`'s outcome check compared a value
+ * that was never trimmed at all to `""`. Two definitions, only one of
+ * which trimmed, and NEITHER strips a zero-width character: `trim()`
+ * removes Unicode whitespace (which includes U+00A0 and U+FEFF) but not
+ * U+200B ZERO WIDTH SPACE, U+200C ZERO WIDTH NON-JOINER or U+200D ZERO
+ * WIDTH JOINER, so a cell or an outcome containing only one of those reads
+ * as non-empty to a bare `=== ""` comparison, trimmed or not. One
+ * predicate, called at every point this module asks "is this empty",
+ * closes both instances at once.
+ */
+export declare function isEmptyCell(value: string): boolean;
+/** Wall-clock bound on one regex execution. Measured (this round): a real
+ * catastrophic pattern, `(a+)+b` against 30 a's, which never returns on
+ * its own, is interrupted within 251-267ms under this mechanism; a safe
+ * pattern executes in under a millisecond, so the bound is not on the
+ * critical path for any pattern this repository's own config uses. */
+export declare const REGEX_EXEC_TIMEOUT_MS = 250;
+export declare class RegexBoundExceededError extends Error {
+}
+/**
+ * Execute `compiled.exec(value)` inside a v8 context with a wall-clock
+ * timeout. `node:vm`'s `timeout` option interrupts synchronous JavaScript
+ * execution, INCLUDING regex backtracking (v8 checks for the termination
+ * request during a regex match, not only between statements), which is
+ * why this bound can stop a hung `.exec()` where a plain try/catch around
+ * a synchronous call cannot: a catastrophic match never throws on its
+ * own, it simply never returns. Measured directly (this round): the same
+ * `(a+)+b` pattern against inputs of length 18 through 40 completes in
+ * under 40ms up to length 22, then 63ms, 302ms, and is interrupted at the
+ * 250ms bound from length 26 onward, rather than running to the multi-
+ * second and then multi-minute times the unbounded engine produces at
+ * length 26 and 40.
+ */
+export declare function boundedExec(compiled: RegExp, value: string): RegExpExecArray | null;
+/**
+ * A STATIC heuristic for the single most common catastrophic-backtracking
+ * shape (fix round 1, CR-991): a parenthesised group containing an
+ * unbounded quantifier (`+` or `*`), itself immediately followed by
+ * another unbounded quantifier, e.g. `(a+)+`, `(a*)+`, `(a+)*`. This is
+ * exactly the shape the round's own red witness constructs
+ * (`(a+)+b`). It is a heuristic, not a proof: it does not see every
+ * catastrophic shape (a documented residue below), which is why every
+ * EXECUTION is also bounded by `boundedExec` regardless of whether a
+ * pattern passes this check.
+ */
+export declare function catastrophicShapeReason(pattern: string): string | undefined;
+/**
+ * Validate one config-supplied pattern SOURCE before it is ever compiled
+ * into a live regex the gate will execute (fix round 1, CR-990/991):
+ * compiles cleanly, and does not match the static catastrophic-shape
+ * heuristic. `label` identifies which config field failed, so a config
+ * error names the field, not just "a pattern".
+ */
+export declare function validatePatternSource(label: string, pattern: string): string | undefined;
+/**
+ * Validate every config-supplied pattern this module will ever compile
+ * and execute: both `idPattern`s and every `bucketKinds[].pattern`. Run
+ * once per config, before the config is used, so a malformed or dangerous
+ * pattern is a named CONFIG error (a clean result record) rather than an
+ * uncaught exception with no record (CR-990) or an unbounded hang
+ * (CR-991).
+ */
+export declare function validateConfigPatterns(config: CoverageConfig): string | undefined;
+interface TableRow {
+    id: string;
+    cells: string[];
+    line: number;
+}
+/**
+ * Walk a document's lines and return every markdown-table row whose first
+ * cell matches `idPattern` (compiled anchored). Separator rows
+ * (`|---|:--:|---|`) are skipped by construction: every cell in one matches
+ * `/^:?-+:?$/`, which cannot also match a realistic id pattern, but the
+ * separator test is applied explicitly rather than relied on implicitly, so
+ * a future id pattern that could coincide does not silently absorb one.
+ * Every match against a config-supplied pattern is BOUNDED (fix round 1,
+ * `boundedExec`), so a hostile `idPattern` cannot hang this walk.
+ */
+export declare function extractIdRows(text: string, idPattern: string): TableRow[];
+export type CoverageFindingKind = "orphan" | "double-bucketed" | "phantom" | "unknown-kind" | "ambiguous-kind" | "missing-note" | "duplicate-inventory-id" | "expected-units-mismatch";
+export interface CoverageFinding {
+    kind: CoverageFindingKind;
+    id: string;
+    detail: string;
+}
+export interface CoverageReport {
+    totalInventoryIds: number;
+    perKind: Record<string, number>;
+    perMilestone: Record<string, number>;
+    findings: CoverageFinding[];
+}
+/**
+ * The core check. Pure: takes the two documents' TEXT (already read through
+ * M2-C-6's guarded read at the call site) and the config, and returns a
+ * report with nothing hidden inside a status string.
+ */
+export declare function checkCoverage(config: CoverageConfig, inventoryText: string, coverageTableText: string): CoverageReport;
+/**
+ * R-089b, THE FINDING-TO-OUTCOME PARITY CONTRACT (M2-P6 step 4).
+ *
+ * Section 2 item 2 of the M2 plan states that the report contract does not
+ * exist yet, so this module defines its own input shape and M3's report
+ * schema must emit it or supersede it. The shape declared here:
+ *
+ *   inventoryIds: string[]           every id that must be resolved
+ *   findings: { id: string; outcome: string }[]   the report's rows
+ *
+ * A CONFORMING future report is a list of `{id, outcome}` pairs, one row
+ * per id, `outcome` a non-empty string. This function does not care what
+ * the outcome STRING says (that is a judgement M3 owns); it only checks
+ * that every id got exactly one non-empty say. Fix round 1 adds the
+ * direction the original version lacked: a report row whose id is not in
+ * the inventory at all (CR-988, a PHANTOM outcome, symmetric with
+ * `checkCoverage`'s phantom finding) is also named, not silently accepted.
+ */
+export interface FindingOutcomeRow {
+    id: string;
+    outcome: string;
+}
+export interface FindingParityResult {
+    ok: boolean;
+    checked: number;
+    missing: string[];
+    duplicated: string[];
+    empty: string[];
+    /** CR-988: report rows whose id is absent from `inventoryIds`. */
+    phantom: string[];
+}
+export declare function checkFindingOutcomeParity(inventoryIds: string[], findings: FindingOutcomeRow[]): FindingParityResult;
+export declare function main(argv: string[]): number;
+export {};