@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.20

package/dist/src/entries/workflow-steps.js

@@ -0,0 +1,345 @@
+/**
+ * The command strings beside a target root's packages: a CI workflow's `run:` steps, the git
+ * hooks, the hook managers' commands and scripts and the makefile's recipe lines, each with the
+ * directory it runs in. A workflow or hook manager file is read by `text/yaml.ts`, and one it does not
+ * read gives no command; each command is read by `commands/read.ts`.
+ */
+import { pathsNamed, readCommands } from "../commands/read.js";
+import { PART } from "../commands/shell.js";
+import { isRecord } from "../json-document.js";
+import { joinPath, resolvePath } from "../paths.js";
+import { filesIn } from "../fs/tree.js";
+import { yamlDocument } from "../text/yaml.js";
+const WORKFLOWS = ".github/workflows";
+/** The directories whose every file is a git hook script, run as the shell runs it. */
+const HOOK_DIRS = [".husky", ".githooks"];
+/** The key setting the directory a workflow step, or each step a `defaults.run` covers, runs in. */
+const WORKING_DIRECTORY = "working-directory";
+const HOOK_MANAGERS = [
+    { name: ".pre-commit-config.yaml", key: "entry" },
+    ...["lefthook.yml", "lefthook.yaml", ".lefthook.yml"].map((name) => ({
+        name,
+        key: "run",
+        dirKey: "root",
+        scripts: true,
+    })),
+];
+/**
+ * The directories lefthook searches for a hook's scripts after the file's `source_dir` and
+ * `source_dir_local`: https://github.com/evilmartians/lefthook/blob/master/internal/command/run.go
+ */
+const LEFTHOOK_DIRS = [".config/lefthook", ".config/lefthook-local"];
+/** The names GNU make reads a makefile under, in the order it tries them. */
+const MAKEFILES = ["GNUmakefile", "makefile", "Makefile"];
+function readText(host, path) {
+    try {
+        return host.readFile(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text a YAML scalar's value stands for, or `undefined` for a collection or a null. */
+function scalarText(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+        ? String(value)
+        : undefined;
+}
+/** The `defaults.run.working-directory` one mapping writes, as YAML decodes it. */
+function defaultDirectory(mapping) {
+    const defaults = mapping["defaults"];
+    const run = isRecord(defaults) ? defaults["run"] : undefined;
+    return isRecord(run) ? scalarText(run[WORKING_DIRECTORY]) : undefined;
+}
+/**
+ * Every command one workflow or hook manager file writes under `key`, in every mapping of the
+ * document, each with the directory it runs in: its mapping's `dirKey` value, else, in a workflow
+ * file, the innermost `defaults.run.working-directory` of a mapping holding it, else `root`. A
+ * file `yamlDocument` does not read gives none.
+ */
+function keyedCommands(text, root, key, dirKey) {
+    const found = [];
+    const visit = (node, inherited) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                visit(item, inherited);
+            }
+            return;
+        }
+        if (!isRecord(node)) {
+            return;
+        }
+        const here = (dirKey === WORKING_DIRECTORY ? defaultDirectory(node) : undefined) ?? inherited;
+        const command = scalarText(node[key]);
+        if (command !== undefined && command.trim() !== "") {
+            const written = (dirKey === undefined ? undefined : scalarText(node[dirKey])) ?? here;
+            found.push({
+                text: command,
+                dir: written === undefined
+                    ? root
+                    : written.includes("${{")
+                        ? undefined
+                        : resolvePath(root, written),
+            });
+        }
+        for (const value of Object.values(node)) {
+            visit(value, here);
+        }
+    };
+    visit(yamlDocument(text), undefined);
+    return found;
+}
+/**
+ * The command lefthook runs for each script a lefthook file's hooks name, each key of a hook's
+ * `scripts` and each `script` of a job in its `jobs`, a group's among them, from each directory
+ * it searches: its `runner`, then the path `<dir>/<hook>/<name>` quoted as lefthook quotes it,
+ * run in the target root: https://lefthook.dev/configuration/Scripts/
+ */
+function lefthookScripts(text, root) {
+    const document = yamlDocument(text);
+    if (!isRecord(document)) {
+        return [];
+    }
+    const dirs = [
+        scalarText(document["source_dir"]) ?? ".lefthook/",
+        scalarText(document["source_dir_local"]) ?? ".lefthook-local/",
+        ...LEFTHOOK_DIRS,
+    ];
+    const found = [];
+    const add = (hook, name, runner) => {
+        for (const dir of dirs) {
+            const path = `'${joinPath(dir, hook, name).replaceAll("'", "'\\''")}'`;
+            found.push({
+                text: runner === undefined || runner.trim() === "" ? path : `${runner} ${path}`,
+                dir: root,
+            });
+        }
+    };
+    const jobs = (hook, list) => {
+        for (const job of Array.isArray(list) ? list : []) {
+            const script = isRecord(job) ? scalarText(job["script"]) : undefined;
+            if (isRecord(job) && script !== undefined) {
+                add(hook, script, scalarText(job["runner"]));
+            }
+            const group = isRecord(job) ? job["group"] : undefined;
+            jobs(hook, isRecord(group) ? group["jobs"] : undefined);
+        }
+    };
+    for (const [hook, value] of Object.entries(document)) {
+        const scripts = isRecord(value) ? value["scripts"] : undefined;
+        for (const [name, options] of Object.entries(isRecord(scripts) ? scripts : {})) {
+            add(hook, name, isRecord(options) ? scalarText(options["runner"]) : undefined);
+        }
+        jobs(hook, isRecord(value) ? value["jobs"] : undefined);
+    }
+    return found;
+}
+/** The path of each git hook script at `root`, every file in {@link HOOK_DIRS}. */
+function hookScripts(host, root) {
+    return HOOK_DIRS.flatMap((dir) => filesIn(host, joinPath(root, dir), () => true).map((name) => joinPath(root, dir, name)));
+}
+/** The makefile make reads at `root`, the first of {@link MAKEFILES} there. */
+function makefileAt(host, root) {
+    return MAKEFILES.map((name) => joinPath(root, name)).find((candidate) => host.kindOf(candidate) === "file");
+}
+/**
+ * One recipe line as make hands it to the shell: each `$$` a `$`, and each reference to a
+ * variable or a function, which make expands first, a part only the run knows:
+ * https://www.gnu.org/software/make/manual/html_node/Reference.html
+ */
+function expandedByMake(line) {
+    let expanded = "";
+    for (let at = 0; at < line.length; at += 1) {
+        const char = line.charAt(at);
+        const next = line.charAt(at + 1);
+        if (char !== "$") {
+            expanded += char;
+        }
+        else if (next === "$") {
+            expanded += "$";
+            at += 1;
+        }
+        else {
+            let end = at + 1;
+            if (next === "(" || next === "{") {
+                const close = next === "(" ? ")" : "}";
+                for (let depth = 0; end < line.length; end += 1) {
+                    depth += line.charAt(end) === next ? 1 : line.charAt(end) === close ? -1 : 0;
+                    if (depth === 0) {
+                        break;
+                    }
+                }
+            }
+            expanded += PART;
+            at = Math.min(end, line.length);
+        }
+    }
+    return expanded;
+}
+/**
+ * Each recipe line of the target root's makefile: a line that starts with a tab, joined with
+ * the lines a trailing `\` continues it onto, less the `@`, `-` and `+` make reads before it,
+ * as make expands it. Make runs each line in a shell of its own.
+ */
+function recipeLines(host, root) {
+    const path = makefileAt(host, root);
+    const text = path === undefined ? undefined : readText(host, path);
+    return (text ?? "")
+        .replace(/\\\r?\n/gu, " ")
+        .split(/\r?\n/u)
+        .filter((line) => line.startsWith("\t"))
+        .map((line) => ({
+        text: expandedByMake(line.slice(1).replace(/^[@+-]+/u, "")),
+        dir: root,
+    }));
+}
+/**
+ * Every command the target root's workflow steps, git hooks, hook managers and makefile run:
+ * the `run:` steps of the workflow files in `.github/workflows`, each file in `.husky` and
+ * `.githooks` as one shell script, the `entry:` commands of `.pre-commit-config.yaml`, the
+ * `run:` commands and the scripts of a lefthook file and the makefile's recipe lines.
+ */
+export function workflowCommands(host, targetRoot) {
+    const root = resolvePath(host.workingDirectory(), targetRoot);
+    const workflows = filesIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name));
+    return [
+        ...workflows.flatMap((name) => keyedCommands(readText(host, joinPath(root, WORKFLOWS, name)) ?? "", root, "run", WORKING_DIRECTORY)),
+        ...hookScripts(host, root).map((path) => ({
+            text: readText(host, path) ?? "",
+            dir: root,
+        })),
+        ...HOOK_MANAGERS.flatMap(({ name, key, dirKey, scripts }) => {
+            const text = readText(host, joinPath(root, name)) ?? "";
+            return [
+                ...keyedCommands(text, root, key, dirKey),
+                ...(scripts === true ? lefthookScripts(text, root) : []),
+            ];
+        }),
+        ...recipeLines(host, root),
+    ];
+}
+/**
+ * The whole text of each file {@link workflowCommands} reads a command from, each workflow file,
+ * git hook, hook manager file and makefile at the target root, which the dependency rule reads.
+ */
+export function commandFileTexts(host, targetRoot) {
+    return commandFiles(host, targetRoot).flatMap(({ path }) => readText(host, path) ?? []);
+}
+/** Each file {@link workflowCommands} reads a command from, with the key a YAML file writes its commands under. */
+function commandFiles(host, targetRoot) {
+    const root = resolvePath(host.workingDirectory(), targetRoot);
+    return [
+        ...filesIn(host, joinPath(root, WORKFLOWS), (name) => /\.ya?ml$/u.test(name)).map((name) => ({
+            path: joinPath(root, WORKFLOWS, name),
+            key: "run",
+        })),
+        ...hookScripts(host, root).map((path) => ({ path, key: undefined })),
+        ...HOOK_MANAGERS.map(({ name, key }) => ({ path: joinPath(root, name), key })),
+        ...[makefileAt(host, root) ?? []].flat().map((path) => ({ path, key: undefined })),
+    ];
+}
+/**
+ * The filters of a workflow's `on` key, which name the files and refs whose change triggers it
+ * and run none: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore
+ */
+const TRIGGER_FILTERS = new Set([
+    "paths",
+    "paths-ignore",
+    "branches",
+    "branches-ignore",
+    "tags",
+    "tags-ignore",
+]);
+/**
+ * The values of one YAML file that are no command, each with its key: every scalar but one
+ * written under `key`, which is read as a command string, and one of a trigger filter. A file
+ * `yamlDocument` does not read is one value, its whole text. No key and no comment is a value.
+ */
+function yamlValues(text, key) {
+    const document = yamlDocument(text);
+    if (document === undefined) {
+        return [{ text, shell: false }];
+    }
+    const found = [];
+    // `trigger` is 1 for the value of the top-level `on`, a map of events, and 2 for an event's.
+    const visit = (node, under, trigger = 0) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                visit(item, under);
+            }
+        }
+        else if (isRecord(node)) {
+            for (const [name, value] of Object.entries(node)) {
+                const on = node === document && (name === "on" || name === "true");
+                if ((name !== key || scalarText(value) === undefined) &&
+                    !(trigger === 2 && TRIGGER_FILTERS.has(name))) {
+                    visit(value, name, on ? 1 : trigger === 1 ? 2 : 0);
+                }
+            }
+        }
+        else {
+            const value = scalarText(node);
+            if (value !== undefined) {
+                found.push({ text: value, shell: false, ...(under === undefined ? {} : { key: under }) });
+            }
+        }
+    };
+    visit(document, undefined);
+    return found;
+}
+/**
+ * The lines of a makefile that are no recipe line, joined with the lines a trailing `\`
+ * continues them onto, each without the comment a `#` make does not read as escaped starts.
+ */
+function makefileValues(text) {
+    return text
+        .replace(/\\\r?\n/gu, " ")
+        .split(/\r?\n/u)
+        .filter((line) => !line.startsWith("\t"))
+        .map((line) => line.replace(/(?<!\\)#.*$/u, ""))
+        .filter((line) => line.trim() !== "")
+        .map((line) => ({ text: line, shell: false }));
+}
+/**
+ * The texts layer 3 reads of the target root's command files: each command string, and each
+ * value of a workflow file, a hook manager file and the makefile that is no command.
+ */
+function heldTexts(host, targetRoot) {
+    const makefile = makefileAt(host, resolvePath(host.workingDirectory(), targetRoot));
+    return [
+        ...workflowCommands(host, targetRoot).map(({ text }) => ({ text, shell: true })),
+        ...commandFiles(host, targetRoot).flatMap(({ path, key }) => {
+            const text = readText(host, path);
+            return text === undefined
+                ? []
+                : key !== undefined
+                    ? yamlValues(text, key)
+                    : path === makefile
+                        ? makefileValues(text)
+                        : [];
+        }),
+    ];
+}
+/** Reads the target root's workflow steps, git hooks, hook managers and makefile. */
+export function readWorkflows(host, targetRoot) {
+    return {
+        readings: workflowCommands(host, targetRoot).map(({ text, dir }) => readCommands(text, dir)),
+        texts: commandFileTexts(host, targetRoot),
+        held: heldTexts(host, targetRoot),
+    };
+}
+/**
+ * The own files the target root's workflow steps, git hooks and recipes run or name, as
+ * `pathsNamed` reads each command.
+ */
+export function workflowEntries(workflows, files) {
+    const found = [];
+    for (const reading of workflows.readings) {
+        for (const { path, written } of pathsNamed(reading)) {
+            for (const file of files.named(path)) {
+                found.push({ file, source: written });
+            }
+        }
+    }
+    return found;
+}

package/dist/src/enum-group.js

@@ -6,7 +6,8 @@
  * or `unknown` expression asserted to it, or bound to a variable or returned from a
  * function it annotates, where a number counts too. An enum's own value converts nothing.
  */
-import { isArrowFunction, isAsExpression, isElementAccessExpression, isEnumDeclaration, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isIdentifier, isMethodDeclaration, isNoSubstitutionTemplateLiteral, isParenthesizedExpression, isParenthesizedTypeNode, isPropertyAccessExpression, isReturnStatement, isStringLiteral, isVariableDeclaration, SyntaxKind, } from "@typescript/native/ast";
+import { isArrowFunction, isAsExpression, isElementAccessExpression, isEnumDeclaration, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isIdentifier, isMethodDeclaration, isNoSubstitutionTemplateLiteral, isParenthesizedTypeNode, isPropertyAccessExpression, isReturnStatement, isStringLiteral, isVariableDeclaration, SyntaxKind, } from "@typescript/native/ast";
+import { parenthesesRemoved } from "./unwrap.js";
 import { TypeFlags } from "@typescript/native/sync";
 import { aliasChains } from "./alias-chain.js";
 import { nodeKey } from "./inventory.js";
@@ -16,14 +17,6 @@ import { isAnswered, UNANSWERED } from "./query.js";
 const NUMBER = TypeFlags.NumberLike;
 const STRING = TypeFlags.StringLike;
 const DECODED = TypeFlags.Any | TypeFlags.Unknown;
-/** The expression one node is, through however many parentheses are written around it. */
-function unparenthesized(node) {
-    let held = node;
-    while (isParenthesizedExpression(held)) {
-        held = held.expression;
-    }
-    return held;
-}
 /**
  * The name node a type node names its declaration by: the identifier of a type
  * reference, the right side of a qualified one, through parentheses. A type that is no
@@ -45,7 +38,7 @@ function typeName(type) {
 }
 /** The name node an expression names an object by: an identifier, or a property access's name. */
 function objectName(expression) {
-    const held = unparenthesized(expression);
+    const held = parenthesesRemoved(expression);
     if (isIdentifier(held)) {
         return held;
     }

package/dist/src/erased-stores.js

@@ -6,10 +6,11 @@
  * either stores. A store into an erased property of a type the analyzed program does not
  * declare hands the value to the code that declares it.
  */
-import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isElementAccessExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isNumericLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadElement, isStringLiteral, isVariableDeclaration, SyntaxKind, } from "@typescript/native/ast";
+import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isElementAccessExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isNumericLiteral, isObjectLiteralExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadElement, isStringLiteral, isVariableDeclaration, SyntaxKind, } from "@typescript/native/ast";
 import { SymbolFlags, TypeFlags } from "@typescript/native/sync";
 import { must } from "./query.js";
 import { checkedTypes } from "./value-reach.js";
+import { parenthesesRemoved } from "./unwrap.js";
 /** The types that keep nothing of the value they are given. */
 const ERASED = TypeFlags.Any | TypeFlags.Unknown;
 /** The array methods whose arguments become elements of the array they are called on. */
@@ -20,9 +21,6 @@ function literalKey(node) {
         ? node.text
         : undefined;
 }
-function unwrapped(node) {
-    return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
 /**
  * Whether a variable declaration's type can differ from what is stored in it: it carries an
  * annotation, or it has neither an annotation nor an initializer, so its type evolves.
@@ -76,8 +74,8 @@ function propertyAt(source, name) {
  * here, and a default value is stored in its target too.
  */
 function patternTargets(pattern, from, out) {
-    const target = unwrapped(pattern);
-    const source = from.path.length === 0 ? unwrapped(from.value) : from.value;
+    const target = parenthesesRemoved(pattern);
+    const source = from.path.length === 0 ? parenthesesRemoved(from.value) : from.value;
     const into = (element, step, literal) => {
         patternTargets(element, literal === undefined
             ? { value: from.value, path: [...from.path, step] }

package/dist/src/exempt-classes.js

@@ -1,62 +1,4 @@
-/**
- * The exemption classes of the Contract's vocabulary, in its order: each class's name, its
- * languages and, for a TypeScript class, which private members it may retain. The rows are
- * written out, as the fixed severity codes are, and a test holds them equal to the Contract.
- * A class name is a type, so a table or a record naming a class outside the vocabulary, or
- * one of another language only, does not compile.
- */
-/** Every class of the vocabulary, in the order the Contract lists them. */
-export const EXEMPTION_CLASSES = [
-    {
-        class: "interface-satisfaction",
-        languages: ["go", "ts"],
-        typescriptVisibility: { private: false, privateName: false },
-    },
-    { class: "encoding-reflection", languages: ["go"] },
-    { class: "format-verb-contract", languages: ["go"] },
-    { class: "errors-duck-typing", languages: ["go"] },
-    {
-        class: "enum-group",
-        languages: ["go", "ts"],
-        typescriptVisibility: { private: false, privateName: false },
-    },
-    {
-        class: "generated-file",
-        languages: ["go", "ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-    { class: "linkname-cgo-asm-plugin", languages: ["go"] },
-    {
-        class: "template-field",
-        languages: ["go", "ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-    {
-        class: "reflective-lookup",
-        languages: ["go", "ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-    {
-        class: "decorator",
-        languages: ["ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-    {
-        class: "injection-container",
-        languages: ["ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-    {
-        class: "framework-lifecycle",
-        languages: ["ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-    {
-        class: "serialization-contract",
-        languages: ["ts"],
-        typescriptVisibility: { private: true, privateName: false },
-    },
-];
+import { EXEMPTION_CLASSES } from "./contract/contract.generated.js";
 function runsOnTS(row) {
     const languages = row.languages;
     return languages.includes("ts");
@@ -69,7 +11,3 @@ const VISIBILITY = new Map(TS_ROWS.map((row) => [row.class, row.typescriptVisibi
 export function typescriptVisibilityOf(exemptionClass) {
     return VISIBILITY.get(exemptionClass) ?? { private: false, privateName: false };
 }
-/** Whether one name is a class of the vocabulary, whichever language it runs on. */
-export function isExemptionClass(name) {
-    return EXEMPTION_CLASSES.some((row) => row.class === name);
-}

package/dist/src/exempt.js

@@ -6,26 +6,17 @@
  * which records held something back. It names no class's detector: the composition
  * hands it the table of the classes it has.
  */
-import { ConfigError } from "./config.js";
-import { EXEMPTION_CLASSES, isExemptionClass, TS_EXEMPTION_CLASSES, typescriptVisibilityOf, } from "./exempt-classes.js";
+import { EXEMPTION_CLASSES } from "./contract/contract.generated.js";
+import { TS_EXEMPTION_CLASSES, typescriptVisibilityOf, } from "./exempt-classes.js";
 import { byPosition, positionKey } from "./position.js";
 import { Unanswerable } from "./query.js";
-import { sweep } from "./sweep.js";
+import { bytewise } from "./text/compare.js";
 /**
- * The classes `exemptions.disabled` switches off. A name is refused unless the
- * vocabulary holds it; a class that runs on another language only is admitted and
- * switches nothing off here, so one configuration serves every analyzer.
+ * The classes `exemptions.disabled` switches off. A class that runs on another language
+ * only switches nothing off here, so one configuration serves every analyzer.
  */
 export function disabledClasses(config) {
-    const disabled = new Set();
-    for (const name of config.exemptionsDisabled) {
-        if (!isExemptionClass(name)) {
-            const known = EXEMPTION_CLASSES.map((row) => row.class).join(", ");
-            throw new ConfigError("malformed", "exemptions.disabled", `exemptions.disabled: ${JSON.stringify(name)} is not an exemption class: the classes are ${known}`);
-        }
-        disabled.add(name);
-    }
-    return disabled;
+    return new Set(config.exemptions.disabled);
 }
 /**
  * Whether a class whose row states `allowed` may retain a member of one visibility. A
@@ -40,20 +31,8 @@ function retainable(allowed, visibility) {
     }
     return true;
 }
-/**
- * The kinds of declaration each class can hold back, which a detector that stops holds
- * back whole. A class with no row here holds back every declaration but a file.
- */
-const RETAINABLE = new Map([
-    ["interface-satisfaction", new Set(["method", "class-member"])],
-    ["enum-group", new Set(["enum-member"])],
-    ["injection-container", new Set(["method", "class-member"])],
-    ["framework-lifecycle", new Set(["method", "class-member"])],
-    [
-        "serialization-contract",
-        new Set(["method", "class-member", "interface-method", "type-member"]),
-    ],
-]);
+/** The kinds of declaration each class can hold back, which a detector that stops holds back whole. */
+const RETAINABLE = new Map(EXEMPTION_CLASSES.flatMap((row) => "ts" in row.retainsKinds ? [[row.class, new Set(row.retainsKinds.ts)]] : []));
 /** The detail of a record a detector that could not finish holds. */
 const UNANSWERED_DETAIL = "kept live by a question the checker did not answer";
 /** Whether one record is held by a detector that could not finish. */
@@ -76,7 +55,7 @@ function detected(exemptionClass, detect, input) {
         }
         const kinds = RETAINABLE.get(exemptionClass);
         return input.held.symbols
-            .filter((symbol) => (kinds === undefined ? symbol.kind !== "file" : kinds.has(symbol.kind)))
+            .filter((symbol) => kinds?.has(symbol.kind) === true)
             .map((symbol) => ({ id: symbol.id, detail: UNANSWERED_DETAIL, site: symbol.position }));
     }
 }
@@ -106,11 +85,19 @@ export function evidenceRecords(input, detectors, disabled) {
                 site: evidence.site,
                 ...(evidence.whileLive === undefined ? {} : { whileLive: evidence.whileLive }),
                 ...(evidence.implementing === undefined ? {} : { implementing: evidence.implementing }),
+                ...(evidence.whileWritten === undefined ? {} : { whileWritten: evidence.whileWritten }),
             });
         }
     }
     return found;
 }
+/**
+ * The records that hold given the declarations a write the mode counts stores into: one
+ * that holds only while written holds where its declaration is among them.
+ */
+export function writtenRecords(records, written) {
+    return records.flatMap(({ whileWritten, ...record }) => whileWritten === undefined || written.has(record.id) ? [record] : []);
+}
 /** The records that hold under one mode, beside the evidence a production mode found in a test file. */
 export function heldRecords(records, holding) {
     const found = [];
@@ -125,20 +112,13 @@ export function heldRecords(records, holding) {
     }
     return { records: exemptionsOf(found), inTestFiles };
 }
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    return a < b ? -1 : 1;
-}
 /**
  * Records as a run holds them: ordered by site, then class, then declaration, and one
  * per declaration, class, detail and file it holds while live, the one at the first
  * site. A fact found at many sites, or by several projects, is one record.
  */
 export function exemptionsOf(found) {
-    const ordered = [...found].sort((a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id));
+    const ordered = [...found].sort((a, b) => byPosition(a.site, b.site) || bytewise(a.class, b.class) || bytewise(a.id, b.id));
     const seen = new Set();
     return ordered.filter((record) => {
         const fact = [record.id, record.class, record.detail, record.whileLive ?? ""].join("\u0000");
@@ -149,13 +129,6 @@ export function exemptionsOf(found) {
         return true;
     });
 }
-/**
- * The records that hold while the component files at `live` are live: every record that
- * holds whatever is live, and each one a live file's markup holds, as a record of the run.
- */
-export function holdingWhile(records, live) {
-    return exemptionsOf(records.flatMap(({ whileLive, ...record }) => whileLive === undefined || live.has(whileLive) ? [record] : []));
-}
 /** The records per declaration, each declaration's in the order given. */
 function byDeclaration(records) {
     const grouped = new Map();
@@ -171,26 +144,8 @@ function byDeclaration(records) {
     return grouped;
 }
 /**
- * The records that held back a declaration: one some configuration's graph, swept
- * again with no exemption and its marks, judges a candidate, whatever another
- * configuration answers, or one in `writeOnly`, which the run would report as written
- * and never read without the record's read. A declaration a relation or a mark holds
- * live in every configuration is held back by no record. The order is the
- * declarations' site order, and for one declaration the input's.
- */
-export function retainedIn(matrix, input, writeOnly = new Set()) {
-    const exempt = input.exempt ?? [];
-    if (exempt.length === 0) {
-        return [];
-    }
-    const bare = { marked: input.marked, mode: input.mode };
-    const dead = new Set(matrix.graphs.flatMap((graph) => sweep(graph, bare).candidates.map((candidate) => candidate.id)));
-    const held = byDeclaration(exempt.filter((record) => dead.has(record.id) || writeOnly.has(record.id)));
-    return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
-}
-/**
- * One line per held-back declaration, in site order: its reference, then each record's
- * class, site and detail, all separated by tabs.
+ * One line per held-back declaration, in site order: its reference and position, then
+ * each record's class, site and detail, all separated by tabs.
  */
 export function retainedLines(symbols, retained) {
     const held = byDeclaration(retained);
@@ -204,6 +159,6 @@ export function retainedLines(symbols, retained) {
             positionKey(record.site),
             record.detail,
         ]);
-        return [[symbol.ref, ...fields].join("\t")];
+        return [[symbol.ref, positionKey(symbol.position), ...fields].join("\t")];
     });
 }