@cplieger/deadset-ts 8.0.0-dev.6 → 8.0.0-dev.8

package/dist/src/entry-point-gaps.js

@@ -7,6 +7,7 @@
  * Every row carries a reason, because the list is read where the rows are shown
  * one at a time: beside a finding, or in a report's declared gaps.
  */
+import { bytewise } from "./text/compare.js";
 /** What is declined for a tool whose own conventions are entered only through its configuration files. */
 const EVERY_CONVENTION = "every file it loads by its own convention beyond its configuration files";
 /** Why a tool whose own conventions are not read declines them. */
@@ -291,15 +292,8 @@ const PARTLY_ENTERED = [
         reason: NOT_LITERAL,
     },
 ];
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    return a < b ? -1 : 1;
-}
 /** Every declined entry-point convention, ordered by tool and then by convention. */
 export const DECLINED_CONVENTIONS = [
     ...UNREAD_TOOLS.map((tool) => ({ tool, convention: EVERY_CONVENTION, reason: UNREAD })),
     ...PARTLY_ENTERED,
-].sort((a, b) => compare(a.tool, b.tool) || compare(a.convention, b.convention));
+].sort((a, b) => bytewise(a.tool, b.tool) || bytewise(a.convention, b.convention));

package/dist/src/entry-points.js

@@ -10,17 +10,18 @@
  * value that is not a literal is not evaluated and not guessed, so a file it would
  * have named is entered by nothing here.
  */
-import { isArrayLiteralExpression, isAsExpression, isCallExpression, isExportAssignment, isIdentifier, isMetaProperty, isNewExpression, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isSatisfiesExpression, isStringLiteral, SyntaxKind, } from "@typescript/native/ast";
+import { isArrayLiteralExpression, isCallExpression, isExportAssignment, isIdentifier, isMetaProperty, isNewExpression, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isPropertyAccessExpression, isPropertyAssignment, isStringLiteral, SyntaxKind, } from "@typescript/native/ast";
 import { SymbolFlags } from "@typescript/native/sync";
 import { configurationFiles, filesNamedBy, moduleStrings, } from "./configuration-files.js";
 import { buildScriptEntries } from "./build-scripts.js";
-import { globExpression } from "./glob.js";
 import { htmlEntries } from "./html-entries.js";
 import { documentEntries } from "./mdx-entries.js";
 import { dirnamePath, relativePath, resolvePath } from "./paths.js";
 import { UNANSWERED } from "./query.js";
 import { computedLoadDirectory, leadingLiteral } from "./unseen-loads.js";
 import { workflowEntries } from "./workflow-steps.js";
+import { unwrapped } from "./unwrap.js";
+import { globExpression } from "./text/glob.js";
 /** The extensions the test runner and the browser-test runner load a configuration from. */
 const MODULE_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
 /** The tool file names the configuration form does not cover. */
@@ -69,14 +70,6 @@ function literalOf(node) {
     }
     return undefined;
 }
-/** The expression a wrapper that changes no value holds: parentheses and type assertions. */
-function unwrapped(node) {
-    let at = node;
-    while (isParenthesizedExpression(at) || isAsExpression(at) || isSatisfiesExpression(at)) {
-        at = at.expression;
-    }
-    return at;
-}
 /**
  * The object literals one configuration file's default export is written as: the
  * literal itself, or each literal argument of the call it is, at any depth of calls.

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

@@ -11,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

@@ -7,26 +7,17 @@
  * hands it the table of the classes it has.
  */
 import { EXEMPTION_CLASSES } from "./contract/contract.generated.js";
-import { ConfigError } from "./config.js";
-import { isExemptionClass, TS_EXEMPTION_CLASSES, typescriptVisibilityOf, } from "./exempt-classes.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
@@ -122,20 +113,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");

package/dist/src/file-facts.js

@@ -3,10 +3,10 @@
  * file below the target root, whether or not a project includes it, and the files a
  * program holds by inclusion rather than by an import.
  */
-import { IGNORED_DIRECTORIES } from "./discover.js";
 import { packageScope } from "./inventory.js";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
 import { renderRef } from "./ref.js";
+import { filesBelow } from "./fs/tree.js";
 /** A file name the compiler reads as a source file. */
 const SOURCE_FILE = /\.(?:ts|tsx|mts|cts)$/u;
 /** A file name the compiler reads as a declaration file, which no build emits code from. */
@@ -30,30 +30,7 @@ function lastLine(text) {
  * that cannot be read is skipped, as discovery skips it.
  */
 export function sourcePaths(host, targetRoot) {
-    const found = [];
-    const pending = [""];
-    for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
-        let entries;
-        try {
-            entries = host.readDirectory(joinPath(targetRoot, dir));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
-            if (entry.directory) {
-                if (!IGNORED_DIRECTORIES.has(entry.name)) {
-                    pending.push(path);
-                }
-                continue;
-            }
-            if (SOURCE_FILE.test(entry.name) && !DECLARATION_FILE.test(entry.name)) {
-                found.push(path);
-            }
-        }
-    }
-    return found.sort((a, b) => (a < b ? -1 : 1));
+    return filesBelow(host, targetRoot, (name) => SOURCE_FILE.test(name) && !DECLARATION_FILE.test(name));
 }
 /**
  * Every source file below the target root, in path order. A file that cannot be read is

package/dist/src/findings/completion.js

@@ -41,8 +41,9 @@ function everyDeclaredLoaded(boundary) {
  * naming its family, else the code's default.
  */
 function severityOf(input, code, fallback) {
-    const { config } = input;
-    return (config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback);
+    const { severity } = input.config;
+    const key = [code, code.slice(0, FAMILY_KEY_LENGTH)].find((one) => Object.hasOwn(severity, one));
+    return key === undefined ? fallback : (severity[key] ?? fallback);
 }
 /**
  * The declarations the roots name as a library's published API, each public member of a
@@ -165,7 +166,7 @@ function testUsedSubjects(input) {
 function rootsCeiling(input, finding, candidate, configurations) {
     const unreachable = candidate?.relation === "reachability" || finding.unreachableOnly === true;
     const unseen = new Set((input.files.unseenLoads ?? []).map((load) => load.configuration));
-    const complete = input.config.ts.rootsComplete && !configurations.some((one) => unseen.has(one));
+    const complete = input.config.ts.roots_complete && !configurations.some((one) => unseen.has(one));
     return unreachable && !complete ? "probable" : "certain";
 }
 /**
@@ -460,7 +461,7 @@ function dialed(finding, minConfidence) {
  * root withholds itself alone.
  */
 export function dialsOf(input, findings) {
-    const minConfidence = input.config.analysis.minConfidence;
+    const minConfidence = input.config.analysis.min_confidence;
     const components = new Set(findings
         .filter((finding) => finding.component.root &&
         dialed({ ...finding, confidence: componentConfidenceOf(finding) }, minConfidence))

package/dist/src/findings/emitters.js

@@ -86,7 +86,7 @@ function atPossible(input) {
     const { config } = input;
     return {
         ...input,
-        config: { ...config, analysis: { ...config.analysis, minConfidence: "possible" } },
+        config: { ...config, analysis: { ...config.analysis, min_confidence: "possible" } },
     };
 }
 /**

package/dist/src/findings/intra-function.js

@@ -98,7 +98,7 @@ export const intraFunction = (input) => {
         return symbol === undefined ? [] : [symbol.id];
     }));
     const { declared, loaded } = input.boundary.consumers;
-    const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+    const closed = input.config.consumers.complete && declared.every((id) => loaded.includes(id));
     const published = (id) => {
         const symbol = byId.get(id);
         return (symbol !== undefined &&

package/dist/src/findings/non-code-artifacts.js

@@ -10,8 +10,8 @@ const FILE_START = 1;
  * derived matrix is never complete.
  */
 function completeMatrix(config) {
-    return (config.analysis.matrixComplete &&
-        config.analysis.configurations.some((entry) => entry.shape === "project"));
+    return (config.analysis.matrix.complete &&
+        config.analysis.configurations.some((entry) => "project" in entry));
 }
 /** One finding about a whole file. */
 function fileFinding(code, file, message) {

package/dist/src/findings/reads-and-writes.js

@@ -1,6 +1,7 @@
 import { CODE } from "../contract/contract.generated.js";
 import { positionKey } from "../position.js";
 import { declarationKey } from "../ref.js";
+import { bytewise } from "../text/compare.js";
 /** The containers whose type parameters `DS1006` reports: a function, a class method and a type alias. */
 const SIGNATURES = new Set(["function", "method", "type"]);
 function indexed(input) {
@@ -76,7 +77,7 @@ function writeOnlyMessage(run, namedBy, symbol, held) {
         : "never read";
     const cascade = [
         ...parametersOnlyNamedBy(run, namedBy, symbol).map((name) => `type parameter ${name}`),
-        ...[...held.alone].sort().map((name) => `import ${name}`),
+        ...[...held.alone].sort(bytewise).map((name) => `import ${name}`),
     ];
     const word = SUBJECT_WORDS[symbol.kind] ?? "member";
     const message = `${word} ${symbol.name} is written ${writes} and ${read}`;

package/dist/src/findings/self-check.js

@@ -2,6 +2,7 @@ import { CODE } from "../contract/contract.generated.js";
 import { REPOSITORY_DOCUMENT } from "../config.js";
 import { FIXED_SEVERITY_CODES } from "../kinds.js";
 import { isDependencyCode, isUnsuppressibleCode, } from "../suppress.js";
+import { bytewise } from "../text/compare.js";
 /** The subject kind of a finding about a configured declaration. */
 const DECLARATION_SUBJECT = "configured-declaration";
 /** The subject kind of a finding about a suppression record. */
@@ -80,10 +81,10 @@ export function staleSuppressions(stale, files) {
         bySite.set(key, held);
     }
     return [...bySite.values()].map(({ first, records }) => {
-        const codes = [...new Set(records.map((one) => one.record.code))].sort();
+        const codes = [...new Set(records.map((one) => one.record.code))].sort(bytewise);
         const reports = [...new Set(records.flatMap((one) => one.reports))]
             .filter((code) => !codes.includes(code))
-            .sort();
+            .sort(bytewise);
         const rows = codes.filter(isUnsuppressibleCode);
         const dependencies = first.mechanism === "inline" ? codes.filter(isDependencyCode) : [];
         const settable = rows.filter((code) => !FIXED_SEVERITY_CODES.includes(code));

package/dist/src/findings/unused-declarations.js

@@ -178,7 +178,7 @@ export const unusedDeclarations = (input) => [
  * remove unless the run includes generated files.
  */
 function unusedImports(input) {
-    const generated = input.config.analysis.generatedFiles === "include" ? undefined : input.files.generated;
+    const generated = input.config.analysis.generated_files === "include" ? undefined : input.files.generated;
     return input.intraFunction.imports.flatMap((binding) => binding.used || generated?.has(binding.position.path) === true
         ? []
         : [

package/dist/src/findings/visibility-narrowing.js

@@ -193,10 +193,10 @@ function unreachable(facts, at, symbol, candidate, input) {
 export function narrowings(input) {
     const facts = factsOf(input.swept.matrix.union);
     const { declared, loaded } = input.boundary.consumers;
-    const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+    const closed = input.config.consumers.complete && declared.every((id) => loaded.includes(id));
     const world = { closed, writeOnly: writeOnlyDeclarations(input) };
     const candidates = new Map(input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
-    const generated = input.config.analysis.generatedFiles === "include" ? undefined : input.files.generated;
+    const generated = input.config.analysis.generated_files === "include" ? undefined : input.files.generated;
     const findings = [];
     facts.graph.symbols.forEach((symbol, at) => {
         if (generated?.has(symbol.position.path) === true) {

package/dist/src/findings-pass.js

@@ -8,20 +8,15 @@ import { fails } from "./config.js";
 import { decidedFindings } from "./findings/emitters.js";
 import { fileRefsOf, staleSuppressions, } from "./findings/self-check.js";
 import { isDependencySubject, isRowSubject, pairs, suppressionCounts, } from "./suppress.js";
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    return a < b ? -1 : 1;
-}
+import { bytewise } from "./text/compare.js";
+import { PRODUCT } from "./product.js";
 /** The canonical order: path, line, column, code, then the symbol reference. */
 function canonical(a, b) {
-    return (compare(a.position.path, b.position.path) ||
+    return (bytewise(a.position.path, b.position.path) ||
         a.position.line - b.position.line ||
         a.position.column - b.position.column ||
-        compare(a.code, b.code) ||
-        compare(a.symbol.ref, b.symbol.ref));
+        bytewise(a.code, b.code) ||
+        bytewise(a.symbol.ref, b.symbol.ref));
 }
 /**
  * The pass over one run. The emitter table decides every record against every finding the
@@ -71,7 +66,7 @@ export function verdictOf(result, config) {
     if (result.totals.staleSuppressions > 0) {
         return EXIT_FINDINGS;
     }
-    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.failOn));
+    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.fail_on));
     return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 /**
@@ -98,5 +93,5 @@ export function rowKey(row) {
 }
 /** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */
 export function analyzerProvenance(version) {
-    return { analyzer: "deadset-ts", version };
+    return { analyzer: PRODUCT, version };
 }

package/dist/src/framework-lifecycle.js

@@ -16,8 +16,8 @@ import { must } from "./query.js";
 /** Every contract's components and bases, resolved in one pass over the entries. */
 function resolveContracts(project, held, contracts) {
     const entries = contracts.flatMap((contract) => [
-        ...contract.components,
-        ...contract.bases,
+        ...(contract.components ?? []),
+        ...(contract.bases ?? []),
     ]);
     const resolved = resolveEntries(project, held, entries);
     let next = 0;
@@ -28,8 +28,8 @@ function resolveContracts(project, held, contracts) {
     };
     return contracts.map((contract) => ({
         contract,
-        components: take(contract.components.length),
-        bases: take(contract.bases.length),
+        components: take(contract.components?.length ?? 0),
+        bases: take(contract.bases?.length ?? 0),
     }));
 }
 /** The classes a decorator or a call the contracts' components name makes a component. */
@@ -160,11 +160,11 @@ function byBases(project, held, chains, contracts) {
  */
 export function frameworkLifecycle(input) {
     const { project, held, targetRoot } = input;
-    if (input.ts.lifecycleContracts.length === 0) {
+    if (input.ts.lifecycle_contracts.length === 0) {
         return [];
     }
     const chains = aliasChains(project, held);
-    const contracts = resolveContracts(project, held, input.ts.lifecycleContracts);
+    const contracts = resolveContracts(project, held, input.ts.lifecycle_contracts);
     const components = [
         ...byComponents(project, held, chains, contracts),
         ...byBases(project, held, chains, contracts),
@@ -173,7 +173,7 @@ export function frameworkLifecycle(input) {
         return [];
     }
     const ids = new Set(components.map((one) => one.id));
-    const sides = input.ts.lifecycleContracts.some((contract) => contract.members.some((name) => name.endsWith(":static")))
+    const sides = input.ts.lifecycle_contracts.some((contract) => contract.members.some((name) => name.endsWith(":static")))
         ? ["instance", "static"]
         : ["instance"];
     const members = sides.map((side) => classMembers(project, held, ids, side));

package/dist/src/fs/document.js

@@ -0,0 +1,59 @@
+/**
+ * The one read of a document the target holds at its root, which a checkout under analysis
+ * controls: the repository configuration, the ignore file, the baseline and the edges
+ * document. The read stays inside the target root, takes a regular file alone, and holds no
+ * more of it than the Contract's document bound.
+ */
+import { CONFIG_MAX_BYTES } from "../contract/config.generated.js";
+import { joinPath, relativePath } from "../paths.js";
+import { message } from "../product.js";
+import { utf8Bytes } from "../reporters/sha256.js";
+import { UsageError } from "../usage.js";
+/**
+ * A document at the target root that is not one to read: its name resolves outside the
+ * target root or to anything but a regular file, or the read fails. Nothing is read from
+ * it, and the run ends with the failure code.
+ */
+export class TargetDocumentError extends Error {
+    constructor(label, reason) {
+        super(`${label}: ${reason}`);
+        this.name = "TargetDocumentError";
+    }
+}
+/** Refuses a document past the Contract's bound with the usage code, naming it `label`. */
+export function refuseOverBound(label, text) {
+    if (utf8Bytes(text).length > CONFIG_MAX_BYTES) {
+        throw new UsageError(`${label}: holds more than ${String(CONFIG_MAX_BYTES)} bytes`);
+    }
+}
+/** What `read` returns, or its throw as the document's {@link TargetDocumentError}. */
+function attempt(label, read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        throw new TargetDocumentError(label, message(error));
+    }
+}
+/**
+ * The text of the document `name` at the absolute `targetRoot`, undefined where nothing is
+ * there, each refusal naming it `label`. A document past the bound is read one byte past
+ * it and refused as {@link refuseOverBound} refuses it.
+ */
+export function readTargetDocument(host, targetRoot, name, label = name) {
+    const path = joinPath(targetRoot, name);
+    const kind = attempt(label, () => host.kindOf(path));
+    if (kind === "absent") {
+        return undefined;
+    }
+    const real = attempt(label, () => host.realPath(path));
+    if (relativePath(attempt(label, () => host.realPath(targetRoot)), real) === undefined) {
+        throw new TargetDocumentError(label, `resolves to ${real}, outside the target root`);
+    }
+    if (kind !== "file") {
+        throw new TargetDocumentError(label, "is not a regular file");
+    }
+    const text = attempt(label, () => host.readFile(real, CONFIG_MAX_BYTES + 1));
+    refuseOverBound(label, text);
+    return text;
+}

package/dist/src/fs/manifest.js

@@ -0,0 +1,43 @@
+import { isRecord } from "../json-document.js";
+import { joinPath } from "../paths.js";
+/** The file a package's manifest is read from. */
+export const MANIFEST = "package.json";
+/** The directory a package manager installs packages into, whose files are no project's own. */
+export const INSTALLED_PACKAGES = "node_modules";
+/** Whether one path passes through an installed-packages directory. */
+export function inInstalledPackages(path) {
+    return path.split("/").includes(INSTALLED_PACKAGES);
+}
+/** One JSON file's text and decoded value, or undefined where it cannot be read or parsed. */
+export function readDocument(host, path) {
+    let text;
+    try {
+        text = host.readFile(path);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return { text, value: JSON.parse(text) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One JSON file's decoded value, or undefined where it cannot be read or parsed. */
+export function readJSON(host, path) {
+    return readDocument(host, path)?.value;
+}
+/**
+ * The manifest in one directory, decoded, or undefined where none reads as an object. A
+ * manifest this program cannot read declares nothing, the same answer as an absent one:
+ * the package manager owns the refusal of a manifest it rejects.
+ */
+export function manifestAt(host, dir) {
+    const value = readJSON(host, joinPath(dir, MANIFEST));
+    return isRecord(value) ? value : undefined;
+}
+/** Whether one directory holds a manifest file. */
+export function holdsManifest(host, dir) {
+    return host.kindOf(joinPath(dir, MANIFEST)) === "file";
+}

package/dist/src/fs/tree.js

@@ -0,0 +1,88 @@
+import { ancestors, joinPath, resolvePath } from "../paths.js";
+import { LANGUAGE_ROWS } from "../contract/contract.generated.js";
+import { LANGUAGE } from "../product.js";
+import { bytewise } from "../text/compare.js";
+import { globExpression } from "../text/glob.js";
+/** The directories no walk of the tree enters, by the patterns the language's row names. */
+const SKIPPED_DIRECTORIES = LANGUAGE_ROWS[LANGUAGE].skippedDirectories.map(globExpression);
+function skipped(name) {
+    return SKIPPED_DIRECTORIES.some((pattern) => pattern.test(name));
+}
+/** One file's text without its line ending, or undefined where it cannot be read. */
+function lineOf(host, path) {
+    try {
+        return host.readFile(path).replace(/\r?\n$/u, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The repository whose working tree holds `dir`: the nearest directory at or above it with a
+ * `.git`. A `.git` file, which a linked worktree or a submodule holds, names the repository's
+ * directory on its `gitdir:` line; that directory's `commondir` file, where it has one, names
+ * the directory shared with the main worktree, which holds `info/exclude`:
+ * https://git-scm.com/docs/gitrepository-layout
+ */
+export function repositoryOf(host, dir) {
+    for (const root of ancestors(dir)) {
+        const dotGit = joinPath(root, ".git");
+        const kind = host.kindOf(dotGit);
+        if (kind === "directory") {
+            return { root, exclude: joinPath(dotGit, "info/exclude") };
+        }
+        if (kind === "file") {
+            const named = /^gitdir: (.+)$/u.exec(lineOf(host, dotGit) ?? "")?.[1];
+            const gitDir = named === undefined ? undefined : resolvePath(root, named);
+            const common = gitDir === undefined ? undefined : lineOf(host, joinPath(gitDir, "commondir"));
+            const shared = gitDir === undefined || common === undefined ? gitDir : resolvePath(gitDir, common);
+            return { root, exclude: shared === undefined ? undefined : joinPath(shared, "info/exclude") };
+        }
+    }
+    return undefined;
+}
+/** The entries of one directory, none where it cannot be read. */
+export function entriesOf(host, dir) {
+    try {
+        return host.readDirectory(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** The names of the files directly in `dir` whose name `accepts`, in bytewise order. */
+export function filesIn(host, dir, accepts) {
+    return entriesOf(host, dir)
+        .filter((entry) => !entry.directory && accepts(entry.name))
+        .map((entry) => entry.name)
+        .sort(bytewise);
+}
+/** The names of the directories directly in `dir` a walk enters, in bytewise order. */
+export function directoriesIn(host, dir) {
+    return entriesOf(host, dir)
+        .filter((entry) => entry.directory && !skipped(entry.name))
+        .map((entry) => entry.name)
+        .sort(bytewise);
+}
+/**
+ * Every file below `root` whose name `accepts`, by its path relative to `root` in bytewise
+ * order, read in no skipped directory.
+ */
+export function filesBelow(host, root, accepts) {
+    const found = [];
+    const pending = [""];
+    for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+        for (const entry of entriesOf(host, joinPath(root, dir))) {
+            const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+            if (!entry.directory) {
+                if (accepts(entry.name)) {
+                    found.push(path);
+                }
+            }
+            else if (!skipped(entry.name)) {
+                pending.push(path);
+            }
+        }
+    }
+    return found.sort(bytewise);
+}