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

package/dist/util/blank-run-hazard.js

@@ -0,0 +1,450 @@
+/**
+ * Static lint: does this regex backtrack quadratically on a BLANKED buffer?
+ *
+ * A non-`all` `scan` zone blanks comments and strings into runs of spaces
+ * (newlines kept, so line numbers stay true). A pattern that is fast on real
+ * source becomes O(run²) on such a buffer when:
+ *
+ *   - (leading) an alternative's first mandatory construct — after only
+ *     optional groups or non-restricting zero-width atoms — is a
+ *     whitespace-consuming quantifier. Every offset of a run is a start, and
+ *     each start re-scans the rest of the run. A start restricted to newlines
+ *     (`(?:^|\n)`) is only a hazard when the quantifier also crosses newlines
+ *     (`\s*`); `[ \t]*` then stops at the end of its line.
+ *   - (adjacent) two whitespace-consuming quantifiers touch, separated only by
+ *     optional items or whitespace-capable atoms — `\s*(?:<x>)?\s*=`, a lazy
+ *     `[^;'"]*?` next to `\s*` — so the engine re-partitions each run between
+ *     them.
+ *
+ * Measured: one such pattern took 3 ms on raw text and 5,402 ms on the
+ * blanked buffer of the same file. This cannot be caught by tests over
+ * ordinary source; it is caught here, from the pattern text, before it runs.
+ *
+ * Deterministic and advisory: a small tokenizer over the regex source, no
+ * regex engine involved. It over-approximates (lookarounds are treated as
+ * transparent; flags are ignored), which is the right direction for a hint.
+ */
+export function findBlankRunHazards(source) {
+    const { alts } = parseAlternatives(source, 0);
+    const found = new Map();
+    const report = (h) => {
+        const key = `${h.shape}@${h.index}`;
+        const prev = found.get(key);
+        // A repeated group is analysed twice; keep the WIDEST reach seen, so a
+        // newline-crossing hazard is never under-reported as line-bounded.
+        if (!prev || (h.crossesNewline && !prev.crossesNewline))
+            found.set(key, h);
+    };
+    for (const alt of alts)
+        analyzeSeq(source, alt, { start: START_ANYWHERE, pending: null }, report);
+    return [...found.values()].sort((a, b) => a.index - b.index || a.shape.localeCompare(b.shape));
+}
+const NONE = { space: false, newline: false };
+const BOTH = { space: true, newline: true };
+/** A quantifier whose upper bound exceeds this is treated as unbounded. */
+const UNBOUNDED_ABOVE = 256;
+/** Where a match may still START inside a blank run, given what the pattern consumed so far. */
+const START_RESTRICTED = 0;
+const START_LINE = 1;
+const START_ANYWHERE = 2;
+// ── parser ──────────────────────────────────────────────────────────────────
+function parseAlternatives(src, from) {
+    const alts = [[]];
+    let i = from;
+    while (i < src.length) {
+        const ch = src[i];
+        if (ch === ')')
+            break;
+        if (ch === '|') {
+            alts.push([]);
+            i += 1;
+            continue;
+        }
+        const item = parseItem(src, i);
+        i = item.i;
+        let node = item.node;
+        const q = parseQuantifier(src, i);
+        if (q) {
+            i = q.i;
+            if (node.t === 'atom' || node.t === 'group')
+                node = { ...node, min: q.min, max: q.max, end: i };
+        }
+        alts[alts.length - 1].push(node);
+    }
+    return { alts, i };
+}
+function parseQuantifier(src, i) {
+    const ch = src[i];
+    let min;
+    let max;
+    let j;
+    if (ch === '*')
+        [min, max, j] = [0, Infinity, i + 1];
+    else if (ch === '+')
+        [min, max, j] = [1, Infinity, i + 1];
+    else if (ch === '?')
+        [min, max, j] = [0, 1, i + 1];
+    else if (ch === '{') {
+        const m = /^\{(\d+)(?:(,)(\d*))?\}/.exec(src.slice(i));
+        if (!m)
+            return undefined; // a literal `{`
+        min = Number(m[1]);
+        max = m[2] === undefined ? min : m[3] === '' || m[3] === undefined ? Infinity : Number(m[3]);
+        j = i + m[0].length;
+    }
+    else
+        return undefined;
+    if (src[j] === '?')
+        j += 1; // lazy — same set of partitions, different order
+    return { min, max, i: j };
+}
+function parseItem(src, i) {
+    const ch = src[i];
+    if (ch === '(')
+        return parseGroup(src, i);
+    if (ch === '[') {
+        const cls = parseClass(src, i);
+        return { node: atom(cls.chars, i, cls.i), i: cls.i };
+    }
+    if (ch === '\\') {
+        const esc = parseEscape(src, i, false);
+        if (esc.anchor !== undefined) {
+            return { node: { t: 'anchor', restricting: esc.anchor, start: i, end: esc.i }, i: esc.i };
+        }
+        return { node: atom(esc.chars, i, esc.i), i: esc.i };
+    }
+    if (ch === '^' || ch === '$')
+        return { node: { t: 'anchor', restricting: true, start: i, end: i + 1 }, i: i + 1 };
+    if (ch === '.')
+        return { node: atom({ space: true, newline: false }, i, i + 1), i: i + 1 };
+    return { node: atom(charOf(ch.charCodeAt(0)), i, i + 1), i: i + 1 };
+}
+function atom(chars, start, end) {
+    return { t: 'atom', chars, start, end, min: 1, max: 1 };
+}
+function parseGroup(src, i) {
+    let j = i + 1;
+    let look = false;
+    if (src[j] === '?') {
+        const next = src[j + 1];
+        if (next === ':')
+            j += 2;
+        else if (next === '=' || next === '!') {
+            look = true;
+            j += 2;
+        }
+        else if (next === '<' && (src[j + 2] === '=' || src[j + 2] === '!')) {
+            look = true;
+            j += 3;
+        }
+        else if (next === '<') {
+            const close = src.indexOf('>', j + 2);
+            j = close === -1 ? src.length : close + 1;
+        }
+        else
+            j += 1;
+    }
+    const inner = parseAlternatives(src, j);
+    const end = inner.i < src.length ? inner.i + 1 : inner.i;
+    if (look)
+        return { node: { t: 'look', alts: inner.alts, start: i, end }, i: end };
+    return { node: { t: 'group', alts: inner.alts, start: i, end, min: 1, max: 1 }, i: end };
+}
+/** A character class: which blank-run characters it matches. */
+function parseClass(src, i) {
+    let j = i + 1;
+    const negated = src[j] === '^';
+    if (negated)
+        j += 1;
+    let space = false;
+    let newline = false;
+    let first = true;
+    let prevCode;
+    while (j < src.length) {
+        const ch = src[j];
+        if (ch === ']' && !(first && false))
+            break;
+        first = false;
+        if (ch === '-' && prevCode !== undefined && src[j + 1] !== undefined && src[j + 1] !== ']') {
+            // A range `a-b`: covers a blank char when it spans it.
+            const hi = src[j + 1] === '\\' ? parseEscape(src, j + 1, true) : undefined;
+            const hiCode = hi?.code ?? src.charCodeAt(j + 1);
+            if (prevCode <= 0x20 && hiCode >= 0x20)
+                space = true;
+            if (prevCode <= 0x0a && hiCode >= 0x0a)
+                newline = true;
+            j = hi ? hi.i : j + 2;
+            prevCode = undefined;
+            continue;
+        }
+        if (ch === '\\') {
+            const esc = parseEscape(src, j, true);
+            if (esc.chars.space)
+                space = true;
+            if (esc.chars.newline)
+                newline = true;
+            prevCode = esc.code;
+            j = esc.i;
+            continue;
+        }
+        const code = ch.charCodeAt(0);
+        if (code === 0x20)
+            space = true;
+        if (code === 0x0a)
+            newline = true;
+        prevCode = code;
+        j += 1;
+    }
+    const end = j < src.length ? j + 1 : j;
+    // `[]` matches nothing; `[^]` matches everything — both fall out of the rule.
+    return { chars: negated ? { space: !space, newline: !newline } : { space, newline }, i: end };
+}
+/**
+ * One escape. `anchor` is set for `\b` (restricting) / `\B` (not) outside a
+ * class; `code` for a single-character escape (so a class range can use it).
+ */
+function parseEscape(src, i, inClass) {
+    const c = src[i + 1];
+    if (c === undefined)
+        return { chars: NONE, i: i + 1 };
+    const j = i + 2;
+    switch (c) {
+        case 's':
+        case 'D':
+        case 'W':
+            return { chars: BOTH, i: j };
+        case 'S':
+        case 'd':
+        case 'w':
+            return { chars: NONE, i: j };
+        case 'b':
+            return inClass ? { chars: NONE, i: j, code: 8 } : { chars: NONE, i: j, anchor: true };
+        case 'B':
+            return { chars: NONE, i: j, anchor: false };
+        case 'n':
+            return { chars: charOf(0x0a), i: j, code: 0x0a };
+        case 'r':
+            return { chars: NONE, i: j, code: 0x0d };
+        case 't':
+            return { chars: NONE, i: j, code: 0x09 };
+        case 'f':
+            return { chars: NONE, i: j, code: 0x0c };
+        case 'v':
+            return { chars: NONE, i: j, code: 0x0b };
+        case '0':
+            return { chars: NONE, i: j, code: 0 };
+        case 'x': {
+            const m = /^[0-9a-fA-F]{2}/.exec(src.slice(j));
+            if (!m)
+                return { chars: NONE, i: j };
+            const code = parseInt(m[0], 16);
+            return { chars: charOf(code), i: j + 2, code };
+        }
+        case 'u': {
+            const braced = /^\{([0-9a-fA-F]+)\}/.exec(src.slice(j));
+            const plain = /^[0-9a-fA-F]{4}/.exec(src.slice(j));
+            const hex = braced?.[1] ?? plain?.[0];
+            if (hex === undefined)
+                return { chars: NONE, i: j };
+            const code = parseInt(hex, 16);
+            return { chars: charOf(code), i: j + (braced ? braced[0].length : 4), code };
+        }
+        case 'c':
+            return { chars: NONE, i: j + 1 };
+        case 'k': {
+            const close = src.indexOf('>', j);
+            return { chars: NONE, i: close === -1 ? src.length : close + 1 };
+        }
+        case 'p':
+        case 'P': {
+            const m = /^\{([^}]*)\}/.exec(src.slice(j));
+            const name = m?.[1] ?? '';
+            const end = m ? j + m[0].length : j;
+            if (c === 'P')
+                return { chars: BOTH, i: end };
+            if (/^(White_Space|space)$/i.test(name))
+                return { chars: BOTH, i: end };
+            if (/^(Z|Zs|Separator|Space_Separator)$/i.test(name))
+                return { chars: { space: true, newline: false }, i: end };
+            return { chars: NONE, i: end };
+        }
+        default:
+            if (c >= '1' && c <= '9' && !inClass) {
+                // A backreference — what it matches is not known statically.
+                let k = j;
+                while (k < src.length && src[k] >= '0' && src[k] <= '9')
+                    k += 1;
+                return { chars: NONE, i: k };
+            }
+            return { chars: charOf(c.charCodeAt(0)), i: j, code: c.charCodeAt(0) };
+    }
+}
+function charOf(code) {
+    return { space: code === 0x20, newline: code === 0x0a };
+}
+// ── analysis ────────────────────────────────────────────────────────────────
+function wsCapable(c) {
+    return c.space || c.newline;
+}
+function overlaps(a, b) {
+    return (a.space && b.space) || (a.newline && b.newline);
+}
+function unionChars(a, b) {
+    return { space: a.space || b.space, newline: a.newline || b.newline };
+}
+function joinPending(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return { chars: unionChars(a.chars, b.chars), at: Math.min(a.at, b.at) };
+}
+function join(a, b) {
+    return { start: Math.max(a.start, b.start), pending: joinPending(a.pending, b.pending) };
+}
+/** State after consuming ONE mandatory character-matching item that is not an unbounded ws quantifier. */
+function afterConsume(entry, chars) {
+    const start = entry.start === START_RESTRICTED
+        ? START_RESTRICTED
+        : chars.space
+            ? entry.start
+            : chars.newline
+                ? START_LINE
+                : START_RESTRICTED;
+    // A mandatory character that can itself be blank does NOT separate two
+    // whitespace quantifiers (`\s*\n\s*` still re-partitions the run).
+    return { start, pending: wsCapable(chars) ? entry.pending : null };
+}
+/**
+ * The blank chars a repeated group can consume when its body is made only of
+ * whitespace-capable atoms (and optional / non-restricting items) — i.e. when
+ * `(?:\s)+` behaves exactly like `\s+`. `undefined` otherwise.
+ */
+function groupWsChars(alts) {
+    let acc;
+    for (const alt of alts) {
+        let sawWs = false;
+        let pure = true;
+        let chars = NONE;
+        for (const n of alt) {
+            if (n.t === 'anchor') {
+                if (n.restricting)
+                    pure = false;
+                continue;
+            }
+            if (n.t === 'look')
+                continue;
+            if (n.t === 'atom') {
+                if (wsCapable(n.chars)) {
+                    sawWs = true;
+                    chars = unionChars(chars, n.chars);
+                }
+                else if (n.min > 0)
+                    pure = false;
+                continue;
+            }
+            const inner = groupWsChars(n.alts);
+            if (inner) {
+                sawWs = true;
+                chars = unionChars(chars, inner);
+            }
+            else if (n.min > 0)
+                pure = false;
+        }
+        if (pure && sawWs)
+            acc = acc ? unionChars(acc, chars) : chars;
+    }
+    return acc;
+}
+function describe(src, start, end) {
+    return src.slice(start, end);
+}
+/** A whitespace-consuming unbounded quantifier — the construct every hazard is made of. */
+function onWsQuantifier(src, chars, start, end, min, entry, report) {
+    const frag = describe(src, start, end);
+    let startMode = entry.start;
+    if (entry.start === START_ANYWHERE || (entry.start === START_LINE && chars.newline)) {
+        report({
+            shape: 'leading',
+            index: start,
+            fragment: frag,
+            message: entry.start !== START_ANYWHERE
+                ? `\`${frag}\` runs from every line start of a blank run across the lines below it — O(lines × run) per blanked comment`
+                : chars.newline
+                    ? `\`${frag}\` can start a match at every offset of a blank run and re-scan the rest of it — O(run²) per blanked comment or string`
+                    : `\`${frag}\` can start a match at every offset of a blanked line and re-scan the rest of that line — O(line²) per blanked line`,
+            // Reach: a quantifier that cannot consume `\n` stops at the end of its
+            // line, so its cost on a blanked buffer is per LINE, not per run.
+            crossesNewline: chars.newline,
+            ...(entry.start === START_LINE ? { fromLineStart: true } : {}),
+        });
+        // One leading finding per alternative is enough — later constructs are
+        // reached only through it.
+        startMode = START_RESTRICTED;
+    }
+    if (entry.pending && overlaps(entry.pending.chars, chars)) {
+        const pairFrag = describe(src, entry.pending.at, end);
+        report({
+            shape: 'adjacent',
+            index: entry.pending.at,
+            fragment: pairFrag,
+            message: `\`${pairFrag}\` puts two whitespace-consuming quantifiers side by side with nothing mandatory between them — the engine re-partitions every blank run between them, O(run²)`,
+            // The re-partitioning spans lines only when BOTH sides can take `\n`;
+            // overlapping on spaces alone, it is bounded by each line.
+            crossesNewline: entry.pending.chars.newline && chars.newline,
+        });
+    }
+    const mine = { chars, at: start };
+    // A skippable quantifier leaves the previous one still "open" as well.
+    const pending = min === 0 ? joinPending(entry.pending, mine) : mine;
+    const nextStart = startMode === START_RESTRICTED ? START_RESTRICTED : min === 0 ? startMode : startMode;
+    return { start: nextStart, pending };
+}
+function analyzeNode(src, node, entry, report) {
+    switch (node.t) {
+        case 'anchor':
+            return node.restricting ? { start: START_RESTRICTED, pending: null } : entry;
+        case 'look':
+            // Hazards INSIDE a lookaround still cost time; the lookaround itself
+            // consumes nothing, so it is transparent to its neighbours.
+            for (const alt of node.alts)
+                analyzeSeq(src, alt, { start: START_RESTRICTED, pending: null }, report);
+            return entry;
+        case 'atom': {
+            if (node.max > UNBOUNDED_ABOVE && wsCapable(node.chars)) {
+                return onWsQuantifier(src, node.chars, node.start, node.end, node.min, entry, report);
+            }
+            const after = afterConsume(entry, node.chars);
+            return node.min === 0 ? join(entry, after) : after;
+        }
+        case 'group': {
+            const repeatedWs = node.max > UNBOUNDED_ABOVE ? groupWsChars(node.alts) : undefined;
+            if (repeatedWs) {
+                // `(?:\s)+` is `\s+` — judge it as one quantifier.
+                for (const alt of node.alts)
+                    analyzeSeq(src, alt, { start: START_RESTRICTED, pending: null }, report);
+                return onWsQuantifier(src, repeatedWs, node.start, node.end, node.min, entry, report);
+            }
+            let exit = analyzeAlternatives(src, node.alts, entry, report);
+            if (node.max > 1) {
+                // A repeated group feeds its own entry: catch a body adjacent to itself.
+                exit = analyzeAlternatives(src, node.alts, join(entry, exit), report);
+            }
+            return node.min === 0 ? join(entry, exit) : exit;
+        }
+    }
+}
+function analyzeAlternatives(src, alts, entry, report) {
+    let exit;
+    for (const alt of alts) {
+        const out = analyzeSeq(src, alt, entry, report);
+        exit = exit ? join(exit, out) : out;
+    }
+    return exit ?? entry;
+}
+function analyzeSeq(src, seq, entry, report) {
+    let state = entry;
+    for (const node of seq)
+        state = analyzeNode(src, node, state, report);
+    return state;
+}

package/dist/util/dead-glob-units.d.ts

@@ -0,0 +1,46 @@
+import type { IDeadGlobUnit } from './i-dead-glob-unit.js';
+import type { IGlobListUnits } from './i-glob-list-units.js';
+import type { IUnreadFile } from './unread-file.js';
+/**
+ * THE dead-unit decision for a gate-plane glob list — every plane that reports
+ * a dead glob (an extraction source, a policy rule's `files`, a command
+ * baseline's `watchFiles` probe) reads it here, so "is this glob live?" is not
+ * answered three slightly different ways.
+ *
+ * `positivePaths` is what the walk returned (it may be a union wider than this
+ * list — only paths one of THIS list's inclusion globs matches are its positive
+ * set); `unread` is the reader's unread entries.
+ *
+ * - An INCLUSION glob is dead when it selects nothing that survives the list's
+ *   negations and is in front of no unread entry the list keeps in scope:
+ *   `matched 0 files`, or `matches only files the list's negations exclude (N)`.
+ * - A NEGATION is alive when it removes at least one file from its own list's
+ *   positive set (a read file, or a matched-but-unread one), or could match
+ *   beneath an unlistable directory the list's inclusion globs reach. Otherwise
+ *   it is dead with `excludes nothing — none of the N file(s) the other globs
+ *   select match it`. A negation is never judged by what it matches on its own:
+ *   it matches nothing by itself; it subtracts. (Before round 12 every `!` read
+ *   "matched 0 files", and `--fail-on-dead-units` failed load-bearing exclusions.)
+ *
+ * The boundary plane words its exemption `!` the same way ("exempts none of the
+ * N file(s) the rule's from globs match"): one liveness rule for one syntax.
+ */
+export declare function globListUnits(positivePaths: readonly string[], unread: readonly IUnreadFile[], globs: readonly string[]): IGlobListUnits;
+/**
+ * {@link globListUnits} over the one reader's POSITIVE walk of `globs`
+ * (`readMatchingFiles`, memoised under `withFileReadCache`, so a plane that
+ * already read the same list pays nothing twice), read and unread entries
+ * alike. For a plane that selects files by a bare list — a generated rule's
+ * `generatedGlob`, a doc-reference rule's `files` (pass its `dotDirsNamedBy`,
+ * so the walk is the one the rule reads). An extraction source comes through
+ * here too, via `sourceGlobUnits`.
+ *
+ * The engine entry normalises idempotently (round 13): a loaded list is plain
+ * strings and passes through; a hand-built `{ pattern, expectEmpty }` entry
+ * is judged as its pattern; a MALFORMED entry is never handed to a glob reader
+ * and never silently dropped — it is reported as a dead unit naming the problem.
+ */
+export declare function readGlobListUnits(projectRoot: string, rawGlobs: readonly string[], excludeDirs?: ReadonlySet<string>, allowDotDirs?: ReadonlySet<string>): IGlobListUnits;
+/** The dead units of one glob list — {@link globListUnits}`.dead`. */
+export declare function deadGlobUnits(positivePaths: readonly string[], unread: readonly IUnreadFile[], globs: readonly string[]): readonly IDeadGlobUnit[];
+//# sourceMappingURL=dead-glob-units.d.ts.map

package/dist/util/dead-glob-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-glob-units.d.ts","sourceRoot":"","sources":["../../src/util/dead-glob-units.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,cAAc,CA0DhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,EAC5C,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,cAAc,CAUhB;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,SAAS,aAAa,EAAE,CAE1B"}

package/dist/util/dead-glob-units.js

@@ -0,0 +1,116 @@
+import { normalizeUnitList, unitProblemsOf } from '@shrkcrft/core';
+import { globListParts, globMayMatchUnder, globToRegex, matchesAny, measureGlobList } from "../scan/glob.js";
+import { isUnreadDirectory, unreadEntryMatches } from "./read-scope-coverage.js";
+import { readMatchingFiles } from "./walk-files.js";
+/**
+ * THE dead-unit decision for a gate-plane glob list — every plane that reports
+ * a dead glob (an extraction source, a policy rule's `files`, a command
+ * baseline's `watchFiles` probe) reads it here, so "is this glob live?" is not
+ * answered three slightly different ways.
+ *
+ * `positivePaths` is what the walk returned (it may be a union wider than this
+ * list — only paths one of THIS list's inclusion globs matches are its positive
+ * set); `unread` is the reader's unread entries.
+ *
+ * - An INCLUSION glob is dead when it selects nothing that survives the list's
+ *   negations and is in front of no unread entry the list keeps in scope:
+ *   `matched 0 files`, or `matches only files the list's negations exclude (N)`.
+ * - A NEGATION is alive when it removes at least one file from its own list's
+ *   positive set (a read file, or a matched-but-unread one), or could match
+ *   beneath an unlistable directory the list's inclusion globs reach. Otherwise
+ *   it is dead with `excludes nothing — none of the N file(s) the other globs
+ *   select match it`. A negation is never judged by what it matches on its own:
+ *   it matches nothing by itself; it subtracts. (Before round 12 every `!` read
+ *   "matched 0 files", and `--fail-on-dead-units` failed load-bearing exclusions.)
+ *
+ * The boundary plane words its exemption `!` the same way ("exempts none of the
+ * N file(s) the rule's from globs match"): one liveness rule for one syntax.
+ */
+export function globListUnits(positivePaths, unread, globs) {
+    const { include, exclude } = globListParts(globs);
+    const measures = measureGlobList(positivePaths, globs);
+    const negationsAsWritten = exclude.map((n) => `!${n}`);
+    const unreadFilesInScope = unread.filter((u) => !isUnreadDirectory(u) && matchesAny(u.path, include));
+    const dead = [];
+    const negations = [];
+    let positiveSize;
+    for (const m of measures) {
+        if (!m.negation) {
+            if (m.effective > 0)
+                continue;
+            // Reaching an unread file, or beneath an unlistable directory, that the
+            // list keeps in scope is matching something it could not examine — never dead.
+            if (unread.some((u) => unreadEntryMatches(u, [m.glob, ...negationsAsWritten])))
+                continue;
+            // Every raw hit here was excluded — count the unread ones too, so a glob
+            // whose only match is an excluded over-cap file never reads "matched 0 files".
+            const includeRe = globToRegex(m.glob);
+            const hits = m.matched + unreadFilesInScope.filter((u) => includeRe.test(u.path)).length;
+            dead.push({
+                glob: m.glob,
+                negation: false,
+                matched: hits,
+                reason: hits === 0 ? 'matched 0 files' : `matches only files the list's negations exclude (${hits})`,
+            });
+            continue;
+        }
+        const pattern = m.glob.slice(1);
+        const re = globToRegex(pattern);
+        const excludes = m.effective + unreadFilesInScope.filter((u) => re.test(u.path)).length;
+        if (excludes > 0) {
+            negations.push({ glob: m.glob, excludes });
+            continue;
+        }
+        // A directory whose files were never enumerated may hold what it excludes.
+        const mayExcludeUnlisted = unread.some((u) => isUnreadDirectory(u) &&
+            include.some((g) => globMayMatchUnder(g, u.path)) &&
+            globMayMatchUnder(pattern, u.path));
+        if (mayExcludeUnlisted)
+            continue;
+        positiveSize ??=
+            positivePaths.filter((p) => matchesAny(p, include)).length + unreadFilesInScope.length;
+        dead.push({
+            glob: m.glob,
+            negation: true,
+            matched: positiveSize,
+            reason: `excludes nothing — none of the ${positiveSize} file(s) the other globs select match it`,
+        });
+    }
+    // Emptied by its own negations: nothing an inclusion glob matched survives,
+    // a live negation removed something (so the positive set was not empty), and
+    // no unread entry the list keeps in scope could hold a survivor.
+    const allExcluded = negations.length > 0 &&
+        !measures.some((m) => !m.negation && m.effective > 0) &&
+        !unread.some((u) => unreadEntryMatches(u, globs));
+    return { dead, negations, checked: measures.length, allExcluded, measures };
+}
+/**
+ * {@link globListUnits} over the one reader's POSITIVE walk of `globs`
+ * (`readMatchingFiles`, memoised under `withFileReadCache`, so a plane that
+ * already read the same list pays nothing twice), read and unread entries
+ * alike. For a plane that selects files by a bare list — a generated rule's
+ * `generatedGlob`, a doc-reference rule's `files` (pass its `dotDirsNamedBy`,
+ * so the walk is the one the rule reads). An extraction source comes through
+ * here too, via `sourceGlobUnits`.
+ *
+ * The engine entry normalises idempotently (round 13): a loaded list is plain
+ * strings and passes through; a hand-built `{ pattern, expectEmpty }` entry
+ * is judged as its pattern; a MALFORMED entry is never handed to a glob reader
+ * and never silently dropped — it is reported as a dead unit naming the problem.
+ */
+export function readGlobListUnits(projectRoot, rawGlobs, excludeDirs = new Set(), allowDotDirs = new Set()) {
+    const normalized = normalizeUnitList(rawGlobs, 'files');
+    const globs = normalized.ok ? normalized.value.units : rawGlobs.filter((g) => typeof g === 'string');
+    const malformed = normalized.ok
+        ? []
+        : unitProblemsOf(normalized.error).map((reason) => ({ glob: '(malformed entry)', negation: false, matched: 0, reason }));
+    if (globs.length === 0)
+        return { dead: malformed, negations: [], checked: 0, allExcluded: false };
+    const matched = readMatchingFiles(projectRoot, globs, excludeDirs, allowDotDirs);
+    const units = globListUnits([...matched.files.keys()], matched.unread, globs);
+    return malformed.length > 0 ? { ...units, dead: [...units.dead, ...malformed] } : units;
+}
+/** The dead units of one glob list — {@link globListUnits}`.dead`. */
+export function deadGlobUnits(positivePaths, unread, globs) {
+    return globListUnits(positivePaths, unread, globs).dead;
+}

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

@@ -0,0 +1,31 @@
+import { type IUnitLivenessInput } from '@shrkcrft/core';
+import type { IGlobLivenessRequest } from './i-glob-liveness-request.js';
+/**
+ * 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 declare function globListLivenessInput(request: IGlobLivenessRequest): IUnitLivenessInput;
+//# sourceMappingURL=glob-list-liveness-input.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"glob-list-liveness-input.d.ts","sourceRoot":"","sources":["../../src/util/glob-list-liveness-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,kBAAkB,EAAyB,MAAM,gBAAgB,CAAC;AAC/G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,kBAAkB,CAoCvF"}