@shrkcrft/boundaries 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/util/glob-list-liveness-input.js

@@ -0,0 +1,65 @@
+import { isNegatedGlob, UnitDeadWeight } from '@shrkcrft/core';
+/**
+ * THE observation predicate for a gate-plane glob unit (round 13). Every
+ * gate-plane reporter — `gates coverage` / `gates try` / `quality`
+ * (`buildGateCoverage`), `policy-lint` (`runPolicyLint`), and each plane
+ * engine's rule-emptiness check (`settleGlobLists`) — builds its core
+ * `settleUnitLiveness` input here, so a glob and its marker are read one way
+ * everywhere:
+ *
+ *   unit                                  | exists | live
+ *   --------------------------------------+--------+------
+ *   inclusion glob, not dead              | yes    | yes   (`it now matches N file(s)`)
+ *   inclusion glob, dead, matched > 0     | yes    | no    (every match excluded by the list's own negations)
+ *   inclusion glob, dead, matched 0       | no     | no    (its target does not exist)
+ *   negation that excludes a file         | yes    | yes
+ *   negation that excludes nothing        | no     | no
+ *
+ * `exists` is RAW target existence — it decides a MARKED unit (intended-empty,
+ * or went-live), so an acceptance never says "does not exist yet" about a glob
+ * whose files exist but are all excluded. `live` is the one dead-unit decision
+ * (`globListUnits`) negated — it decides an unmarked unit, and whether a
+ * went-live unit is effective. A glob in front of an unread file is not dead
+ * (`globListUnits`), so it reads live, never intended-empty.
+ *
+ * Advisory weight: a dead gate glob is listed and withholds the ✓, it moves
+ * the exit only under `--fail-on-dead-units`; record B (the acceptance) is
+ * emitted for any intended-empty unit.
+ */
+export function globListLivenessInput(request) {
+    const observations = [];
+    for (const l of request.lists) {
+        const deadBy = new Map(l.units.dead.map((d) => [d.glob, d]));
+        const excludes = new Map(l.units.negations.map((n) => [n.glob, n.excludes]));
+        const effective = new Map((l.units.measures ?? []).map((m) => [m.glob, m.effective]));
+        for (const glob of new Set(l.globs)) {
+            const dead = deadBy.get(glob);
+            const negation = isNegatedGlob(glob);
+            const exists = dead === undefined || (!dead.negation && dead.matched > 0);
+            const live = dead === undefined;
+            const count = negation ? excludes.get(glob) : live ? effective.get(glob) : dead?.matched;
+            const liveBecause = !exists
+                ? undefined
+                : negation
+                    ? `it now excludes ${count ?? 'a'} file${count === 1 || count === undefined ? '' : 's'}`
+                    : `it now matches ${count ?? 'a'} file${count === 1 || count === undefined ? '' : 's'}`;
+            observations.push({
+                list: l.list,
+                unit: glob,
+                label: l.label !== undefined ? `${l.label}: ${glob}` : glob,
+                exists,
+                live,
+                ...(dead !== undefined ? { matched: dead.matched, deadReason: dead.reason } : {}),
+                ...(liveBecause !== undefined ? { liveBecause } : {}),
+            });
+        }
+    }
+    return {
+        ...(request.subject !== undefined ? { subject: request.subject } : {}),
+        unitLabel: 'globs',
+        weight: UnitDeadWeight.Advisory,
+        observations,
+        marks: request.marks,
+        deadSummary: 'select or exclude nothing',
+    };
+}

package/dist/util/i-dead-glob-unit.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One glob of a gate-plane list that does nothing (`globListUnits`).
+ *
+ * An inclusion glob is dead when it selects nothing that survives the list's
+ * negations; a negation is dead when it EXCLUDES nothing from its own list's
+ * positive set. The `reason` says which, in the words every surface prints.
+ */
+export interface IDeadGlobUnit {
+    /** The glob as written (a negation keeps its `!`). */
+    readonly glob: string;
+    readonly negation: boolean;
+    /**
+     * Inclusion glob: the files it matched before the list's negations (0, or
+     * all of them excluded). Negation: the size of the positive set it failed to
+     * touch.
+     */
+    readonly matched: number;
+    /**
+     * `matched 0 files`, `matches only files the list's negations exclude (N)`,
+     * or `excludes nothing — none of the N file(s) the other globs select match it`.
+     */
+    readonly reason: string;
+}
+//# sourceMappingURL=i-dead-glob-unit.d.ts.map

package/dist/util/i-dead-glob-unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-dead-glob-unit.d.ts","sourceRoot":"","sources":["../../src/util/i-dead-glob-unit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/dist/util/i-dead-glob-unit.js

@@ -0,0 +1 @@
+export {};

package/dist/util/i-glob-list-units.d.ts

@@ -0,0 +1,25 @@
+import type { IGlobUnitMeasure } from '../scan/i-glob-unit-measure.js';
+import type { IDeadGlobUnit } from './i-dead-glob-unit.js';
+import type { IGlobNegation } from './i-glob-negation.js';
+/** One glob list's units, judged by `globListUnits`: the dead ones, the live negations, and how many were checked. */
+export interface IGlobListUnits {
+    readonly dead: readonly IDeadGlobUnit[];
+    /** Negations that exclude at least one file, with the count. */
+    readonly negations: readonly IGlobNegation[];
+    /** Distinct globs (negations included) examined. */
+    readonly checked: number;
+    /**
+     * True when the list's OWN negations emptied it: its inclusion globs matched
+     * at least one file, every one of them is excluded, and no unread entry the
+     * list keeps in scope could hold a survivor. A rule over such a list that
+     * matched nothing is the author's `!` at work — not a stale selector.
+     */
+    readonly allExcluded: boolean;
+    /**
+     * Every distinct glob's measure (`measureGlobList`: an inclusion glob's raw
+     * and effective matches, a negation's exclusions) — what a went-live unit's
+     * sentence quotes (`it now matches 3 file(s)`). Set by `globListUnits`.
+     */
+    readonly measures?: readonly IGlobUnitMeasure[];
+}
+//# sourceMappingURL=i-glob-list-units.d.ts.map

package/dist/util/i-glob-list-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-glob-list-units.d.ts","sourceRoot":"","sources":["../../src/util/i-glob-list-units.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,sHAAsH;AACtH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACjD"}

package/dist/util/i-glob-list-units.js

@@ -0,0 +1 @@
+export {};

package/dist/util/i-glob-liveness-list.d.ts

@@ -0,0 +1,23 @@
+import type { IGlobListUnits } from './i-glob-list-units.js';
+/**
+ * One gate-plane glob list as the liveness settle observes it (round 13).
+ *
+ * `list` is the marker ledger's `list` for these globs — `files`, `to.files`,
+ * `watchFiles`, `generatedGlob`, or a side-qualified `declared.files` when a
+ * rule reads several sources (`qualifyListPath`); the marks handed to the
+ * settle must be qualified the same way. `units` is the list judged by the one
+ * dead-unit decision (`globListUnits`).
+ */
+export interface IGlobLivenessList {
+    readonly list: string;
+    /**
+     * Display prefix for each unit of this list. Set when the rule reads more
+     * than one list: a unit then prints `<label>: <glob>` — today's dead-glob
+     * selector (`declared: src/moved/*.ts`). Absent: the bare glob.
+     */
+    readonly label?: string;
+    /** The globs as the loader normalised them (a negation keeps its `!`). */
+    readonly globs: readonly string[];
+    readonly units: IGlobListUnits;
+}
+//# sourceMappingURL=i-glob-liveness-list.d.ts.map

package/dist/util/i-glob-liveness-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-glob-liveness-list.d.ts","sourceRoot":"","sources":["../../src/util/i-glob-liveness-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC"}

package/dist/util/i-glob-liveness-list.js

@@ -0,0 +1 @@
+export {};

package/dist/util/i-glob-liveness-request.d.ts

@@ -0,0 +1,11 @@
+import type { IUnitMark } from '@shrkcrft/core';
+import type { IGlobLivenessList } from './i-glob-liveness-list.js';
+/** Every glob list one gate rule reads, and its markers — the input of the one gate-plane glob settle (round 13). */
+export interface IGlobLivenessRequest {
+    /** The rule id; it becomes the coverage records' `subject`. */
+    readonly subject?: string;
+    readonly lists: readonly IGlobLivenessList[];
+    /** The rule's / sources' `expectEmptyUnits`, qualified exactly like the lists' `list`. */
+    readonly marks: readonly IUnitMark[];
+}
+//# sourceMappingURL=i-glob-liveness-request.d.ts.map

package/dist/util/i-glob-liveness-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-glob-liveness-request.d.ts","sourceRoot":"","sources":["../../src/util/i-glob-liveness-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,qHAAqH;AACrH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC"}

package/dist/util/i-glob-liveness-request.js

@@ -0,0 +1 @@
+export {};

package/dist/util/i-glob-negation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A LIVE negation of a gate-plane glob list and what it removes: the files its
+ * list's inclusion globs select that it takes out of scope (read, or matched
+ * but unread). `gates coverage` prints each one, so the scope a `!` narrowed is
+ * visible on the surface the author already reads.
+ */
+export interface IGlobNegation {
+    /** The negation as written (`!src/**\/*.spec.ts`). */
+    readonly glob: string;
+    /** Files it excludes from the list's positive set (at least 1). */
+    readonly excludes: number;
+}
+//# sourceMappingURL=i-glob-negation.d.ts.map

package/dist/util/i-glob-negation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-glob-negation.d.ts","sourceRoot":"","sources":["../../src/util/i-glob-negation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/util/i-glob-negation.js

@@ -0,0 +1 @@
+export {};

package/dist/util/matched-files.d.ts

@@ -0,0 +1,22 @@
+import type { IUnreadFile } from './unread-file.js';
+/**
+ * What the one reader returns: every glob-matched file it READ, and every
+ * glob-matched file it did NOT read, with the reason.
+ *
+ * The second half is the point. A reader that drops an over-cap file without
+ * saying so turns "a forbidden token in a 1.7MB file" into "examined 1 of 1 ✓":
+ * every plane counted its expected scope from what was read, so the dropped
+ * file was invisible to every coverage record built on top of it. Returning
+ * the unread files next to the read ones means no caller can build coverage
+ * without choosing, explicitly, what to do with them.
+ */
+export interface IMatchedFiles {
+    /**
+     * Project-relative POSIX path → content, for every matched file that was
+     * read. A fresh map per call, because callers filter and partition it.
+     */
+    readonly files: Map<string, string>;
+    /** Matched files the reader did not read, sorted by path. */
+    readonly unread: readonly IUnreadFile[];
+}
+//# sourceMappingURL=matched-files.d.ts.map

package/dist/util/matched-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matched-files.d.ts","sourceRoot":"","sources":["../../src/util/matched-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC"}

package/dist/util/matched-files.js

@@ -0,0 +1 @@
+export {};

package/dist/util/negation-cause.d.ts

@@ -0,0 +1,15 @@
+import type { IGlobNegation } from './i-glob-negation.js';
+/**
+ * THE cause of a list its OWN negations emptied — its inclusion globs matched
+ * files and every one was excluded as written — for the policy plane's skip
+ * and coverage reasons. Not a stale selector, and never worded as one.
+ */
+export declare function allExcludedCause(negations: readonly IGlobNegation[]): string;
+/**
+ * THE skip reason of an extraction SOURCE its own negations emptied (round 12
+ * review, R12-DOC-2) — the words `gates coverage` prints for the same rule, so
+ * `check wiring`, `gates check` and the NOT VERIFIED line no longer say "0
+ * files matched the source globs" (a file DID match, then was excluded).
+ */
+export declare function emptiedByNegationsReason(negations: readonly IGlobNegation[]): string;
+//# sourceMappingURL=negation-cause.d.ts.map

package/dist/util/negation-cause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negation-cause.d.ts","sourceRoot":"","sources":["../../src/util/negation-cause.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAO1D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAEpF"}

package/dist/util/negation-cause.js

@@ -0,0 +1,21 @@
+/** `!src/**\/*.spec.ts (1 file), !docs/drafts/** (3 files)` — each negation with what it excluded. */
+function describeNegations(negations) {
+    return negations.map((n) => `${n.glob} (${n.excludes} file${n.excludes === 1 ? '' : 's'})`).join(', ');
+}
+/**
+ * THE cause of a list its OWN negations emptied — its inclusion globs matched
+ * files and every one was excluded as written — for the policy plane's skip
+ * and coverage reasons. Not a stale selector, and never worded as one.
+ */
+export function allExcludedCause(negations) {
+    return `every file its inclusion globs select is excluded by its own negations (${describeNegations(negations)})`;
+}
+/**
+ * THE skip reason of an extraction SOURCE its own negations emptied (round 12
+ * review, R12-DOC-2) — the words `gates coverage` prints for the same rule, so
+ * `check wiring`, `gates check` and the NOT VERIFIED line no longer say "0
+ * files matched the source globs" (a file DID match, then was excluded).
+ */
+export function emptiedByNegationsReason(negations) {
+    return `matched nothing after its own negations: every file its inclusion globs select is excluded (${describeNegations(negations)})`;
+}

package/dist/util/plane-scan-exclude-dirs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * THE scan scope of every data-defined plane walk: the project-relative
+ * directories the walk prunes. Today that is the SharkCraft asset/config dir,
+ * when it sits inside the project. Its `.ts` files hold the rule definitions
+ * themselves, so a rule would otherwise match (and self-report) its own
+ * definition.
+ *
+ * Every verb and every aggregate that walks a plane reads it here: `policy-lint`,
+ * `check wiring`, `wiring explain | unprovided | orphans`, `registry …`,
+ * `baseline`, `generated`, `docs references`, `gates check | coverage | try`,
+ * `quality`, `finish`, `shrk gate` and MCP. Before round 11 each derived it
+ * inline, and several did not derive it at all. So `check wiring` and `gates
+ * check` (or `policy-lint` and `shrk gate`) walked different trees for the SAME
+ * rule, and one read 1 where the other read 0 ✓.
+ */
+export declare function planeScanExcludeDirs(projectRoot: string, sharkcraftDir: string | null | undefined): string[];
+//# sourceMappingURL=plane-scan-exclude-dirs.d.ts.map

package/dist/util/plane-scan-exclude-dirs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane-scan-exclude-dirs.d.ts","sourceRoot":"","sources":["../../src/util/plane-scan-exclude-dirs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAI5G"}

package/dist/util/plane-scan-exclude-dirs.js

@@ -0,0 +1,22 @@
+import * as nodePath from 'node:path';
+/**
+ * THE scan scope of every data-defined plane walk: the project-relative
+ * directories the walk prunes. Today that is the SharkCraft asset/config dir,
+ * when it sits inside the project. Its `.ts` files hold the rule definitions
+ * themselves, so a rule would otherwise match (and self-report) its own
+ * definition.
+ *
+ * Every verb and every aggregate that walks a plane reads it here: `policy-lint`,
+ * `check wiring`, `wiring explain | unprovided | orphans`, `registry …`,
+ * `baseline`, `generated`, `docs references`, `gates check | coverage | try`,
+ * `quality`, `finish`, `shrk gate` and MCP. Before round 11 each derived it
+ * inline, and several did not derive it at all. So `check wiring` and `gates
+ * check` (or `policy-lint` and `shrk gate`) walked different trees for the SAME
+ * rule, and one read 1 where the other read 0 ✓.
+ */
+export function planeScanExcludeDirs(projectRoot, sharkcraftDir) {
+    if (!sharkcraftDir)
+        return [];
+    const rel = nodePath.relative(projectRoot, sharkcraftDir).split(nodePath.sep).join('/');
+    return rel && !rel.startsWith('..') ? [rel] : [];
+}

package/dist/util/read-glob-list-liveness.d.ts

@@ -0,0 +1,20 @@
+import type { ISettledUnitLiveness, IUnitMark } from '@shrkcrft/core';
+import type { IGlobListUnits } from './i-glob-list-units.js';
+/**
+ * ONE glob list, judged off the one reader's positive walk
+ * (`readGlobListUnits`, memoised under `withFileReadCache`) and settled with
+ * its markers (`settleGlobLists`) — for an engine that selects files by a bare
+ * list and must decide its rule's emptiness: a registry's / idiom role's /
+ * extractor baseline's source `files`, a generated rule's `generatedGlob`, a
+ * doc-reference rule's `files` (pass its `dotDirsNamedBy`, so the walk is the
+ * one the rule reads). `marks` are the list's own (`list` equal to `list`).
+ */
+export declare function readGlobListLiveness(projectRoot: string, list: string, globs: readonly string[], marks: readonly IUnitMark[], options?: {
+    readonly subject?: string;
+    readonly excludeDirs?: ReadonlySet<string>;
+    readonly allowDotDirs?: ReadonlySet<string>;
+}): {
+    readonly units: IGlobListUnits;
+    readonly liveness: ISettledUnitLiveness;
+};
+//# sourceMappingURL=read-glob-list-liveness.d.ts.map

package/dist/util/read-glob-list-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-glob-list-liveness.d.ts","sourceRoot":"","sources":["../../src/util/read-glob-list-liveness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC,GACL;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,CAQ7E"}

package/dist/util/read-glob-list-liveness.js

@@ -0,0 +1,20 @@
+import { readGlobListUnits } from "./dead-glob-units.js";
+import { settleGlobLists } from "./settle-glob-lists.js";
+/**
+ * ONE glob list, judged off the one reader's positive walk
+ * (`readGlobListUnits`, memoised under `withFileReadCache`) and settled with
+ * its markers (`settleGlobLists`) — for an engine that selects files by a bare
+ * list and must decide its rule's emptiness: a registry's / idiom role's /
+ * extractor baseline's source `files`, a generated rule's `generatedGlob`, a
+ * doc-reference rule's `files` (pass its `dotDirsNamedBy`, so the walk is the
+ * one the rule reads). `marks` are the list's own (`list` equal to `list`).
+ */
+export function readGlobListLiveness(projectRoot, list, globs, marks, options = {}) {
+    const units = readGlobListUnits(projectRoot, globs, options.excludeDirs, options.allowDotDirs);
+    const liveness = settleGlobLists({
+        ...(options.subject !== undefined ? { subject: options.subject } : {}),
+        lists: [{ list, globs, units }],
+        marks: marks.filter((m) => m.list === list),
+    });
+    return { units, liveness };
+}

package/dist/util/read-scope-coverage.d.ts

@@ -0,0 +1,90 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import type { IMatchedFiles } from './matched-files.js';
+import type { IReadScope } from './read-scope.js';
+import type { IUnreadFile } from './unread-file.js';
+/** How a coverage gap names a file the reader skipped for its size. */
+export declare const READ_CAP_REASON = "over the 1MB read cap";
+/** How a coverage gap names a regenerated file skipped for its size. */
+export declare const REGEN_CAP_REASON = "over the 2MB regen read cap";
+/** How a coverage gap names a directory the walk could not list. */
+export declare const UNLISTABLE_DIR_REASON = "unlistable (a directory whose files were never enumerated)";
+/** The one sentence naming why a set of files went unread. */
+export declare function unreadReason(unread: readonly IUnreadFile[]): string;
+/** True for the entry of a directory the walk could not list (its path ends in `/`). */
+export declare function isUnreadDirectory(u: IUnreadFile): boolean;
+/** Is project-relative `path` beneath the unlistable-directory entry `u`? */
+export declare function unreadDirectoryContains(u: IUnreadFile, path: string): boolean;
+/**
+ * THE "is this unread entry in front of these globs?" test, for every plane.
+ * A file: the list SELECTS its path (`globListSelects` — an inclusion glob
+ * matches, no negation does). A directory the walk could not list: an
+ * inclusion glob could match something beneath it (`globMayMatchUnder`) and no
+ * negation covers ALL of it (`globCoversAllUnder`) — its files were never
+ * enumerated, so no rule over that tree may claim it examined them, unless the
+ * list itself excludes every one of them.
+ */
+export declare function unreadEntryMatches(u: IUnreadFile, globs: readonly string[]): boolean;
+/**
+ * The exemption side of {@link unreadEntryMatches}: do `globs` take the WHOLE
+ * entry out of scope? A file: the list selects it. A directory: one inclusion
+ * glob covers everything beneath it (`globCoversAllUnder`) and no negation
+ * could carve part of it back out (`globMayMatchUnder`) — an exemption
+ * covering part of an unlistable directory leaves the rest a gap.
+ */
+export declare function unreadEntryWhollyMatches(u: IUnreadFile, globs: readonly string[]): boolean;
+/**
+ * The unread entries a selector's globs are in front of, optionally only those
+ * in a changeset. Sorted by path.
+ *
+ * Under a changeset, an unlistable directory contributes the CHANGED files
+ * beneath it that the globs match (each unreadable: its directory could not be
+ * listed) — the changeset is the scope, so the gap is named by file.
+ */
+export declare function unreadMatching(unread: readonly IUnreadFile[], globs: readonly string[], changed?: ReadonlySet<string>): IUnreadFile[];
+/**
+ * One rule's read scope over a read the caller already did: the read files
+ * its globs match, and the unread ones. `changed` narrows both to a changeset,
+ * which is deliberate narrowing and not a gap.
+ */
+export declare function readScopeOf(matched: IMatchedFiles, globs: readonly string[], changed?: ReadonlySet<string>): IReadScope;
+/** Merge several read scopes (a rule's sides), counting each unread path once. */
+export declare function mergeReadScopes(read: number, scopes: readonly (readonly IUnreadFile[])[]): IReadScope;
+/**
+ * The read scope of SEVERAL lists over one read (a registration idiom's three
+ * roles, every idiom of a graph): a file counts once when ANY list selects it,
+ * and each list's unread entries are taken from that list alone.
+ *
+ * Never flatten the lists into one and call {@link readScopeOf}: a negation
+ * subtracts from its own list only, and a flattened union would let one role's
+ * `!x` hide another role's file.
+ */
+export declare function readScopeOfLists(matched: IMatchedFiles, lists: readonly (readonly string[])[], changed?: ReadonlySet<string>): IReadScope;
+/**
+ * True when a rule's scope holds a file the reader did not read. Such a rule's
+ * zero is never "matched nothing": it matched a file it could not examine. So
+ * it is PARTIAL (2), never a `failOnEmpty` failure (1), and never a pass.
+ */
+export declare function readScopeHasUnread(scope: IReadScope | undefined): boolean;
+/**
+ * THE rule for folding the one reader's unread files into a rule's coverage.
+ *
+ * With no unread file in scope, the plane's own record is returned unchanged.
+ * Otherwise the rule examined `read` of the `read + unread` files its globs
+ * MATCHED: unit `files`, and each unread path named with its reason
+ * (`examined 1 of 2 files, 1 over the 1MB read cap: src/big.ts`).
+ *
+ * The file record REPLACES the plane's record rather than sitting next to it.
+ * Every count the plane derived (tokens, content units, entries, references)
+ * came from an incomplete read, so it misses whatever the unread file holds.
+ * CLAUDE.md's loud-skip rule applies: a number derived from an incomplete input
+ * is reported NOT VERIFIED, never as a number. Any acceptance on the plane
+ * record (`registeredExtras`, `expectEmpty`, `--allow-empty`) is dropped with
+ * it, because none of them accepted an unread file.
+ */
+export declare function readScopeCoverage(plane: IVerdictCoverage, scope: IReadScope | undefined): IVerdictCoverage;
+/**
+ * A short human clause for a rule's unread files, for skip reasons and hints:
+ * `1 matched file over the 1MB read cap (src/big.ts)`.
+ */
+export declare function describeUnread(unread: readonly IUnreadFile[], shown?: number): string;
+//# sourceMappingURL=read-scope-coverage.d.ts.map

package/dist/util/read-scope-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-scope-coverage.d.ts","sourceRoot":"","sources":["../../src/util/read-scope-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAOpD,uEAAuE;AACvE,eAAO,MAAM,eAAe,0BAA2D,CAAC;AAExF,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,gCAAkE,CAAC;AAEhG,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,+DAA+D,CAAC;AAElG,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CASnE;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIpF;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI1F;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC5B,WAAW,EAAE,CAef;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC5B,UAAU,CAMZ;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,SAAS,WAAW,EAAE,CAAC,EAAE,GAAG,UAAU,CAIrG;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACrC,OAAO,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC5B,UAAU,CAOZ;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAEzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,gBAAgB,CAa1G;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,SAAI,GAAG,MAAM,CAIhF"}

package/dist/util/read-scope-coverage.js

@@ -0,0 +1,173 @@
+import { globCoversAllUnder, globListParts, globListSelects, globMayMatchUnder } from "../scan/glob.js";
+import { UnreadFileReason } from "./unread-file-reason.js";
+import { MAX_REGEN_FILE_BYTES, MAX_SCAN_FILE_BYTES } from "./walk-files.js";
+/** At most this many unread paths ride on one coverage record. */
+const UNREAD_LABEL_CAP = 20;
+/** How a coverage gap names a file the reader skipped for its size. */
+export const READ_CAP_REASON = `over the ${MAX_SCAN_FILE_BYTES / 1_000_000}MB read cap`;
+/** How a coverage gap names a regenerated file skipped for its size. */
+export const REGEN_CAP_REASON = `over the ${MAX_REGEN_FILE_BYTES / 1_000_000}MB regen read cap`;
+/** How a coverage gap names a directory the walk could not list. */
+export const UNLISTABLE_DIR_REASON = 'unlistable (a directory whose files were never enumerated)';
+/** The one sentence naming why a set of files went unread. */
+export function unreadReason(unread) {
+    const kinds = new Set(unread.map((u) => u.reason));
+    const parts = [
+        ...(kinds.has(UnreadFileReason.OverReadCap) ? [READ_CAP_REASON] : []),
+        ...(kinds.has(UnreadFileReason.OverRegenCap) ? [REGEN_CAP_REASON] : []),
+        ...(kinds.has(UnreadFileReason.Unreadable) ? ['unreadable'] : []),
+        ...(kinds.has(UnreadFileReason.UnreadableDirectory) ? [UNLISTABLE_DIR_REASON] : []),
+    ];
+    return parts.length > 0 ? parts.join(' or ') : READ_CAP_REASON;
+}
+/** True for the entry of a directory the walk could not list (its path ends in `/`). */
+export function isUnreadDirectory(u) {
+    return u.reason === UnreadFileReason.UnreadableDirectory;
+}
+/** Is project-relative `path` beneath the unlistable-directory entry `u`? */
+export function unreadDirectoryContains(u, path) {
+    return isUnreadDirectory(u) && (u.path === './' || path.startsWith(u.path));
+}
+/**
+ * THE "is this unread entry in front of these globs?" test, for every plane.
+ * A file: the list SELECTS its path (`globListSelects` — an inclusion glob
+ * matches, no negation does). A directory the walk could not list: an
+ * inclusion glob could match something beneath it (`globMayMatchUnder`) and no
+ * negation covers ALL of it (`globCoversAllUnder`) — its files were never
+ * enumerated, so no rule over that tree may claim it examined them, unless the
+ * list itself excludes every one of them.
+ */
+export function unreadEntryMatches(u, globs) {
+    if (!isUnreadDirectory(u))
+        return globListSelects(u.path, globs);
+    const { include, exclude } = globListParts(globs);
+    return include.some((g) => globMayMatchUnder(g, u.path)) && !exclude.some((n) => globCoversAllUnder(n, u.path));
+}
+/**
+ * The exemption side of {@link unreadEntryMatches}: do `globs` take the WHOLE
+ * entry out of scope? A file: the list selects it. A directory: one inclusion
+ * glob covers everything beneath it (`globCoversAllUnder`) and no negation
+ * could carve part of it back out (`globMayMatchUnder`) — an exemption
+ * covering part of an unlistable directory leaves the rest a gap.
+ */
+export function unreadEntryWhollyMatches(u, globs) {
+    if (!isUnreadDirectory(u))
+        return globListSelects(u.path, globs);
+    const { include, exclude } = globListParts(globs);
+    return include.some((g) => globCoversAllUnder(g, u.path)) && !exclude.some((n) => globMayMatchUnder(n, u.path));
+}
+/**
+ * The unread entries a selector's globs are in front of, optionally only those
+ * in a changeset. Sorted by path.
+ *
+ * Under a changeset, an unlistable directory contributes the CHANGED files
+ * beneath it that the globs match (each unreadable: its directory could not be
+ * listed) — the changeset is the scope, so the gap is named by file.
+ */
+export function unreadMatching(unread, globs, changed) {
+    if (changed === undefined)
+        return unread.filter((u) => unreadEntryMatches(u, globs));
+    const out = new Map();
+    for (const u of unread) {
+        if (!isUnreadDirectory(u)) {
+            if (changed.has(u.path) && globListSelects(u.path, globs))
+                out.set(u.path, u);
+            continue;
+        }
+        for (const path of changed) {
+            if (!out.has(path) && unreadDirectoryContains(u, path) && globListSelects(path, globs)) {
+                out.set(path, { path, reason: UnreadFileReason.Unreadable });
+            }
+        }
+    }
+    return [...out.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * One rule's read scope over a read the caller already did: the read files
+ * its globs match, and the unread ones. `changed` narrows both to a changeset,
+ * which is deliberate narrowing and not a gap.
+ */
+export function readScopeOf(matched, globs, changed) {
+    let read = 0;
+    for (const path of matched.files.keys()) {
+        if ((changed === undefined || changed.has(path)) && globListSelects(path, globs))
+            read += 1;
+    }
+    return { read, unread: unreadMatching(matched.unread, globs, changed) };
+}
+/** Merge several read scopes (a rule's sides), counting each unread path once. */
+export function mergeReadScopes(read, scopes) {
+    const seen = new Map();
+    for (const list of scopes)
+        for (const u of list)
+            if (!seen.has(u.path))
+                seen.set(u.path, u);
+    return { read, unread: [...seen.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+}
+/**
+ * The read scope of SEVERAL lists over one read (a registration idiom's three
+ * roles, every idiom of a graph): a file counts once when ANY list selects it,
+ * and each list's unread entries are taken from that list alone.
+ *
+ * Never flatten the lists into one and call {@link readScopeOf}: a negation
+ * subtracts from its own list only, and a flattened union would let one role's
+ * `!x` hide another role's file.
+ */
+export function readScopeOfLists(matched, lists, changed) {
+    let read = 0;
+    for (const path of matched.files.keys()) {
+        if (changed !== undefined && !changed.has(path))
+            continue;
+        if (lists.some((l) => globListSelects(path, l)))
+            read += 1;
+    }
+    return mergeReadScopes(read, lists.map((l) => unreadMatching(matched.unread, l, changed)));
+}
+/**
+ * True when a rule's scope holds a file the reader did not read. Such a rule's
+ * zero is never "matched nothing": it matched a file it could not examine. So
+ * it is PARTIAL (2), never a `failOnEmpty` failure (1), and never a pass.
+ */
+export function readScopeHasUnread(scope) {
+    return scope !== undefined && scope.unread.length > 0;
+}
+/**
+ * THE rule for folding the one reader's unread files into a rule's coverage.
+ *
+ * With no unread file in scope, the plane's own record is returned unchanged.
+ * Otherwise the rule examined `read` of the `read + unread` files its globs
+ * MATCHED: unit `files`, and each unread path named with its reason
+ * (`examined 1 of 2 files, 1 over the 1MB read cap: src/big.ts`).
+ *
+ * The file record REPLACES the plane's record rather than sitting next to it.
+ * Every count the plane derived (tokens, content units, entries, references)
+ * came from an incomplete read, so it misses whatever the unread file holds.
+ * CLAUDE.md's loud-skip rule applies: a number derived from an incomplete input
+ * is reported NOT VERIFIED, never as a number. Any acceptance on the plane
+ * record (`registeredExtras`, `expectEmpty`, `--allow-empty`) is dropped with
+ * it, because none of them accepted an unread file.
+ */
+export function readScopeCoverage(plane, scope) {
+    if (scope === undefined || scope.unread.length === 0)
+        return plane;
+    const unread = scope.unread;
+    return {
+        unit: 'files',
+        expected: scope.read + unread.length,
+        examined: scope.read,
+        unexamined: unread.slice(0, UNREAD_LABEL_CAP).map((u) => u.path),
+        unexaminedTotal: unread.length,
+        reason: unreadReason(unread),
+        ...(plane.root !== undefined ? { root: plane.root } : {}),
+        ...(plane.subject !== undefined ? { subject: plane.subject } : {}),
+    };
+}
+/**
+ * A short human clause for a rule's unread files, for skip reasons and hints:
+ * `1 matched file over the 1MB read cap (src/big.ts)`.
+ */
+export function describeUnread(unread, shown = 3) {
+    const names = unread.slice(0, shown).map((u) => u.path);
+    const more = unread.length > shown ? `, +${unread.length - shown} more` : '';
+    return `${unread.length} matched file(s) ${unreadReason(unread)} (${names.join(', ')}${more})`;
+}