@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.11

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

@@ -1,7 +1,9 @@
+import { CODE } from "../contract/contract.generated.js";
 import { positionKey } from "../position.js";
 import { declarationKey } from "../ref.js";
-/** The containers whose type parameters `DS1303` reports: a function and a class method. */
-const SIGNATURES = new Set(["function", "method"]);
+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) {
     const { matrix, sweep } = input.swept;
     return {
@@ -75,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}`;
@@ -133,7 +135,7 @@ function writeOnlySymbols(run) {
             run.candidates.has(symbol.id)) {
             continue;
         }
-        found.push(findingAbout(symbol, "DS1301", writeOnlyMessage(run, namedBy, symbol, held), {
+        found.push(findingAbout(symbol, CODE.writeOnlySymbol, writeOnlyMessage(run, namedBy, symbol, held), {
             writePositions: held.writes,
         }));
     }
@@ -157,23 +159,24 @@ function unnamed(run, kind) {
     });
 }
 /**
- * `DS1302`: a member of an enum declaration that nothing names. A member an enum-group
+ * `DS1005`: a member of an enum declaration that nothing names. A member an enum-group
  * record holds back is no candidate, so a member a conversion can produce never reaches
  * this kind.
  */
 function unusedEnumMembers(run) {
-    return unnamed(run, "enum-member").map((symbol) => findingAbout(symbol, "DS1302", `enum member ${symbol.name} is named nowhere`));
+    return unnamed(run, "enum-member").map((symbol) => findingAbout(symbol, CODE.unusedEnumMember, `enum member ${symbol.name} is named nowhere`));
 }
 /**
- * `DS1303`: a type parameter of a function or a class method that neither the
- * declaration's signature nor its body names. A type parameter of a class, an interface,
- * a type alias or a method signature belongs to a type declaration and is never
- * reported, because a phantom parameter makes two instantiations distinct types.
+ * `DS1006`: a type parameter of a function, a class method or a type alias that neither
+ * the declaration's signature nor its body names. An alias names no type of its own, so
+ * a parameter its type never names makes no two instantiations distinct. One of a class,
+ * an interface or a method signature is never reported: a class or an interface merges
+ * only with declarations of the same parameters.
  */
 function unusedTypeParameters(run) {
     return unnamed(run, "type-parameter")
         .filter((symbol) => SIGNATURES.has(run.symbols.get(symbol.parent)?.kind ?? ""))
-        .map((symbol) => findingAbout(symbol, "DS1303", `type parameter ${symbol.name} is named in neither its signature nor its body`));
+        .map((symbol) => findingAbout(symbol, CODE.unusedTypeParameter, `type parameter ${symbol.name} is named in neither its signature nor its body`));
 }
 /**
  * The keys of the declarations the write-only kind reports, whatever the
@@ -184,8 +187,8 @@ export function writeOnlyDeclarations(input) {
     return new Set(writeOnlySymbols(indexed(input)).map((finding) => declarationKey(finding.symbol.ref, finding.position.path)));
 }
 /**
- * The findings of the reads-and-writes family, `DS1300` to `DS1399`, in code order and
- * each code's in site order.
+ * The findings of the reads-and-writes kinds, `DS1301`, `DS1005` and `DS1006`, in that
+ * order and each code's in site order.
  */
 export const readsAndWrites = (input) => {
     const run = indexed(input);

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

@@ -1,10 +1,8 @@
+import { CODE } from "../contract/contract.generated.js";
 import { REPOSITORY_DOCUMENT } from "../config.js";
 import { FIXED_SEVERITY_CODES } from "../kinds.js";
-import { isDependencyCode, isUnsuppressibleCode, STALE_SUPPRESSION, SUPPRESSION_WITHOUT_REASON, } from "../suppress.js";
-/** The code a configured root that matches nothing is reported under. */
-const UNMATCHED_ROOT = "DS1704";
-/** The code a configured declaration that names nothing is reported under. */
-const UNMATCHED_DECLARATION = "DS1706";
+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. */
@@ -63,7 +61,7 @@ function suppressionRef(symbol, path, files) {
 }
 /** One finding per refused suppression: the grammar's reason refusal and its scope refusal. */
 function refusedSuppressions(refusals, files) {
-    return refusals.map((refused) => aboutSuppression(refused.reported, suppressionRef(refused.symbol, refused.path, files), refused.site, `${WRITTEN[refused.mechanism]} for ${refused.code} ${refused.reported === SUPPRESSION_WITHOUT_REASON
+    return refusals.map((refused) => aboutSuppression(refused.reported, suppressionRef(refused.symbol, refused.path, files), refused.site, `${WRITTEN[refused.mechanism]} for ${refused.code} ${refused.reported === CODE.suppressionWithoutReason
         ? "carries no reason"
         : "names a symbol and no path"}`, { mechanism: refused.mechanism, entry: writtenEntry(refused) }));
 }
@@ -83,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));
@@ -112,7 +110,7 @@ export function staleSuppressions(stale, files) {
                 ? ""
                 : `, and ${declared}`;
         return {
-            code: STALE_SUPPRESSION,
+            code: CODE.staleSuppression,
             mechanism: first.mechanism,
             entry: {
                 code: first.code,
@@ -141,7 +139,7 @@ function documentPosition(document) {
  */
 function unmatchedDeclarationFindings(unmatched) {
     return unmatched.map((one) => ({
-        code: UNMATCHED_DECLARATION,
+        code: CODE.unmatchedConfiguredDeclaration,
         position: documentPosition(one.document),
         symbol: { ref: one.ref, kind: DECLARATION_SUBJECT, name: one.ref, sizeLines: 1 },
         message: `${one.key} entry names no declaration in any project`,
@@ -157,7 +155,7 @@ function unmatchedDeclarationFindings(unmatched) {
 export function unmatchedRootFindings(sources, document) {
     const position = documentPosition(document);
     return sources.map((source) => ({
-        code: UNMATCHED_ROOT,
+        code: CODE.unmatchedRoot,
         position,
         symbol: { ref: source, kind: ROOT_SUBJECT, name: source, sizeLines: 1 },
         message: source.includes("*") || source.includes("?")
@@ -166,7 +164,7 @@ export function unmatchedRootFindings(sources, document) {
     }));
 }
 /**
- * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
+ * The findings of the configuration family, `DS9000` to `DS9099`: a suppression refused for
  * carrying no reason or naming no path, and a configured root or declaration that named
  * nothing. A
  * suppression that matched nothing is a record of the report's stale suppressions, which

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

@@ -1,3 +1,5 @@
+import { CODE } from "../contract/contract.generated.js";
+import { testsUnseenAPI } from "./completion.js";
 import { unreachableExports } from "./visibility-narrowing.js";
 /** The kinds of declaration that are members of a class, an interface, a type or an enum. */
 const MEMBERS = new Set([
@@ -7,17 +9,17 @@ const MEMBERS = new Set([
     "enum-member",
 ]);
 /**
- * The kinds of declaration no code of this family reports: an interface and a method an
+ * The kinds of declaration no code of this emitter reports: an interface and a method an
  * interface declares are the interface kinds' subjects, and a type parameter is the
  * subject of the unused-type-parameter kind or of none.
  */
-const NOT_THIS_FAMILY = new Set([
+const NOT_REPORTED_HERE = new Set([
     "file",
     "interface",
     "interface-method",
     "type-parameter",
 ]);
-/** The reader's word for each kind of declaration a finding of the family names. */
+/** The reader's word for each kind of declaration a finding of this emitter names. */
 const WORDS = {
     file: "file",
     function: "function",
@@ -41,15 +43,16 @@ const TEST_OF_DEAD_CODE = "every target symbol this test references is reported
  * The code one candidate is reported under, or none, each symbol once under the most
  * specific code: a test of dead code first; no other test-file declaration or enum
  * member nothing names; a test-support declaration test code references as test-only
- * use; then deprecation, a test reference, and the unreferenced codes, an unimportable
- * unused export being the unreachable kind's.
+ * use; then deprecation, a test reference, or only dead production references beside a
+ * test that stays, and the unreferenced codes, an unimportable unused export being the
+ * unreachable kind's.
  */
 function codeOf(judged) {
     const { candidate, symbol } = judged;
     if (candidate.testOfDeadCode) {
-        return "DS1005";
+        return judged.testsUnseenAPI ? undefined : CODE.testOfDeadCode;
     }
-    if ((judged.test && !candidate.unreferencedTest) || NOT_THIS_FAMILY.has(symbol.kind)) {
+    if ((judged.test && !candidate.unreferencedTest) || NOT_REPORTED_HERE.has(symbol.kind)) {
         return undefined;
     }
     const referenced = candidate.productionRefs + candidate.testRefs > 0;
@@ -60,28 +63,30 @@ function codeOf(judged) {
         return unreferencedCode(symbol);
     }
     if (candidate.heldByTests === candidate.id) {
-        return "DS1004";
+        return CODE.testOnlyUse;
     }
     if (candidate.productionRefs === 0 && judged.deprecated) {
-        return "DS1006";
+        return CODE.deprecatedUnused;
     }
-    if (candidate.productionRefs === 0 && candidate.testRefs > 0) {
-        return "DS1004";
+    if (candidate.testRefs > 0 &&
+        (candidate.productionRefs === 0 ||
+            (candidate.relation === "reachability" && candidate.keptByTests))) {
+        return CODE.testOnlyUse;
     }
     if (MEMBERS.has(symbol.kind)) {
-        return "DS1003";
+        return CODE.unusedMember;
     }
     if (!symbol.exported) {
-        return "DS1002";
+        return CODE.unusedUnexported;
     }
-    return judged.unreachable ? undefined : "DS1001";
+    return judged.unreachable ? undefined : CODE.unusedExported;
 }
 /** The code a declaration nothing references carries, by its shape and its visibility. */
 function unreferencedCode(symbol) {
     if (MEMBERS.has(symbol.kind)) {
-        return "DS1003";
+        return CODE.unusedMember;
     }
-    return symbol.exported ? "DS1001" : "DS1002";
+    return symbol.exported ? CODE.unusedExported : CODE.unusedUnexported;
 }
 /** The visibility a member's message names, where it narrows the member's reach. */
 function visibilityWord(symbol) {
@@ -104,14 +109,16 @@ function messageOf(code, judged) {
     const { candidate, symbol } = judged;
     const word = WORDS[symbol.kind];
     switch (code) {
-        case "DS1005":
+        case CODE.testOfDeadCode:
             return TEST_OF_DEAD_CODE;
-        case "DS1006":
+        case CODE.deprecatedUnused:
             return `deprecated ${word} has no production reference`;
-        case "DS1004":
-            return `${word} is referenced only from test files and never from production code`;
+        case CODE.testOnlyUse:
+            return candidate.productionRefs === 0
+                ? `${word} is referenced only from test files and never from production code`
+                : `${word} is referenced only from test files and from declarations that are themselves dead`;
     }
-    const subject = code === "DS1003"
+    const subject = code === CODE.unusedMember
         ? `${visibilityWord(symbol)}${word}`
         : symbol.kind === "export-alias"
             ? word
@@ -119,7 +126,7 @@ function messageOf(code, judged) {
     if (candidate.relation === "reachability") {
         return `${subject} is referenced only from declarations that are themselves dead`;
     }
-    if (code === "DS1001") {
+    if (code === CODE.unusedExported) {
         return `${subject} has no reference in the target and none from any loaded consumer`;
     }
     return `${subject} has no reference in the target`;
@@ -161,22 +168,22 @@ function brandMembers(input) {
 }
 /** The kinds of member a brand is: a data member of a type or of a class. */
 const BRANDS = new Set(["type-member", "class-member"]);
-/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+/** The findings of the unused-declaration kinds, `DS1001` to `DS1004` and `DS1102` to `DS1104`. */
 export const unusedDeclarations = (input) => [
-    ...familyFindings(input, false),
+    ...emitterFindings(input, false),
     ...unusedImports(input),
 ];
 /**
- * The import bindings their file never reads, under the unexported code. A generated
- * file's are the generator's to remove unless the run includes generated files.
+ * The import bindings their file never reads. A generated file's are the generator's to
+ * 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
         ? []
         : [
             {
-                code: "DS1002",
+                code: CODE.unusedImport,
                 position: binding.position,
                 symbol: { ref: binding.ref, kind: "import", name: binding.name, sizeLines: 1 },
                 message: `import binding ${binding.name} is never read in its file`,
@@ -188,12 +195,13 @@ function unusedImports(input) {
  * a record on such a member is matched against, since the report carries the container's
  * finding rather than one of the member's own.
  */
-export const fallenMembers = (input) => familyFindings(input, true);
-/** The family's findings, or, where `fallen` is set, its dead containers' members' alone. */
-function familyFindings(input, fallen) {
+export const fallenMembers = (input) => emitterFindings(input, true);
+/** This emitter's findings, or, where `fallen` is set, its dead containers' members' alone. */
+function emitterFindings(input, fallen) {
     const union = input.swept.matrix.union;
     const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
     const unreachable = unreachableExports(input);
+    const unseenAPI = testsUnseenAPI(input);
     let brands;
     const found = [];
     for (const candidate of input.swept.sweep.candidates) {
@@ -212,10 +220,11 @@ function familyFindings(input, fallen) {
             test: union.test[at] === true,
             deprecated: input.deprecated.has(symbol.id),
             unreachable: unreachable.has(symbol.id),
+            testsUnseenAPI: candidate.testOfDeadCode && unseenAPI(candidate.id),
         };
         const code = codeOf(judged);
         if (code === undefined ||
-            (code === "DS1003" && (brands ??= brandMembers(input)).has(symbol.id))) {
+            (code === CODE.unusedMember && (brands ??= brandMembers(input)).has(symbol.id))) {
             continue;
         }
         const endLine = Math.max(symbol.position.line, symbol.endLine);

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

@@ -1,17 +1,15 @@
+import { CODE } from "../contract/contract.generated.js";
 import { OUTSIDE } from "../graph.js";
 import { declarationKey } from "../ref.js";
 import { runnerCalls } from "../sweep.js";
 import { writeOnlyDeclarations } from "./reads-and-writes.js";
-const UNNECESSARY_EXPORT = "DS1101";
-const UNREACHABLE_EXPORT = "DS1103";
-const REDUNDANT_EXPORT_KEYWORD = "DS1104";
 /**
  * The root kinds by which a consumer importing the package reaches a declaration. A
  * declaration or a file rooted by any other kind is entered by something that names it
  * from outside the reference graph: a runtime, a tool, a framework or the configuration.
  */
 const PUBLISHING = new Set(["manifest-entry", "published-api"]);
-/** The reader's word for each kind of declaration this family reports. */
+/** The reader's word for each kind of declaration this emitter reports. */
 const WORDS = {
     function: "function",
     class: "class",
@@ -34,12 +32,17 @@ const RUN_ONLY = new Set(["configuration-string", "script"]);
 function entersByName(kinds) {
     return [...(kinds ?? [])].some((kind) => !PUBLISHING.has(kind) && !RUN_ONLY.has(kind));
 }
+/**
+ * The root kinds whose root of a file enters no export by name: a document's import roots
+ * each export it imports, so an export it does not import is judged as in any file.
+ */
+const PER_NAME = new Set(["document-import"]);
 /**
  * Whether the roots of a declaration's file enter it by name: a test runner's root
  * enters only an export the runner calls, so another export of a test file is judged.
  */
 function fileEntersByName(kinds, symbol) {
-    const entering = [...(kinds ?? [])].filter((kind) => !PUBLISHING.has(kind) && !RUN_ONLY.has(kind));
+    const entering = [...(kinds ?? [])].filter((kind) => !PUBLISHING.has(kind) && !RUN_ONLY.has(kind) && !PER_NAME.has(kind));
     return (entering.some((kind) => kind !== "test-runner") || (entering.length > 0 && runnerCalls(symbol)));
 }
 /**
@@ -104,8 +107,8 @@ function wordOf(symbol) {
 }
 /** The visibility each narrowing code names, which only the narrowing codes carry. */
 const NARROWER = {
-    [REDUNDANT_EXPORT_KEYWORD]: "file",
-    [UNNECESSARY_EXPORT]: "package",
+    [CODE.redundantExportKeyword]: "file",
+    [CODE.unnecessaryExport]: "package",
 };
 function findingOf(symbol, code, message) {
     const { path, line, column } = symbol.position;
@@ -148,12 +151,12 @@ function narrowing(facts, at, symbol, world) {
             if (facts.published[file] === true && !closed) {
                 return undefined;
             }
-            return findingOf(symbol, REDUNDANT_EXPORT_KEYWORD, `exported ${word} is referenced only inside the file that declares it`);
+            return findingOf(symbol, CODE.redundantExportKeyword, `exported ${word} is referenced only inside the file that declares it`);
         case "package":
             if (!closed || !publishes(facts.rootedBy[at])) {
                 return undefined;
             }
-            return findingOf(symbol, UNNECESSARY_EXPORT, `exported ${word} is referenced only inside the package that declares it`);
+            return findingOf(symbol, CODE.unnecessaryExport, `exported ${word} is referenced only inside the package that declares it`);
         default:
             return undefined;
     }
@@ -163,7 +166,7 @@ function narrowing(facts, at, symbol, world) {
  * export no code outside the target can import, because the manifest declares
  * `exports` and no root reaches it. Each arm yields to a more specific kind, so one
  * declaration is reported once: a test whose every subject is dead, an interface, a
- * declaration only a test file references, and a deprecated one.
+ * declaration only a test file references or a test that stays keeps, and a deprecated one.
  */
 function unreachable(facts, at, symbol, candidate, input) {
     if (!input.boundary.encapsulated ||
@@ -171,17 +174,17 @@ function unreachable(facts, at, symbol, candidate, input) {
         (facts.rootedBy[at]?.size ?? 0) > 0 ||
         candidate.testOfDeadCode ||
         symbol.kind === "interface" ||
-        (candidate.productionRefs === 0 && candidate.testRefs > 0) ||
+        (candidate.testRefs > 0 && (candidate.productionRefs === 0 || candidate.keptByTests)) ||
         (candidate.productionRefs === 0 && input.deprecated.has(symbol.id))) {
         return undefined;
     }
     const found = candidate.relation === "reachability"
         ? "is referenced only from declarations that are themselves dead"
         : "has no reference in the target";
-    return findingOf(symbol, UNREACHABLE_EXPORT, `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`);
+    return findingOf(symbol, CODE.unreachableExport, `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`);
 }
 /**
- * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`. A finding
+ * The visibility-narrowing kinds over one run: `DS1501`, `DS1101` and `DS1503`. A finding
  * about a symbol a declared cross-language edge names is reported here like any other, and
  * the edge's evaluation then holds it pending, because the edge stands for a reference from
  * outside the file and the package whose use is decided in the other language. A
@@ -190,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) {
@@ -229,5 +232,5 @@ export function unreachableExports(input) {
     }
     return found;
 }
-/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+/** The findings of the visibility-narrowing kinds, `DS1501`, `DS1101` and `DS1503`. */
 export const visibilityNarrowing = narrowings;

package/dist/src/findings-pass.js

@@ -3,27 +3,20 @@
  * applied and the declared edges evaluated, and the stale suppressions, the totals and the
  * verdict a report carries beside them.
  */
+import { EXIT_CLEAN, EXIT_FINDINGS, EXIT_PENDING } from "./contract/contract.generated.js";
 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";
-import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.js";
-/** The exit code of a report holding at least one pending finding. */
-export const EXIT_PENDING = 4;
-/** 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
@@ -73,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;
 }
 /**
@@ -100,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,52 @@
+/**
+ * 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 { failureExit } from "../failure.js";
+import { joinPath, relativePath } from "../paths.js";
+import { message } from "../product.js";
+import { utf8Bytes } from "../reporters/sha256.js";
+import { UsageError } from "../usage.js";
+function unreadable(label, reason) {
+    return failureExit("unreadable-document", `${label}: ${reason}: make it a regular file inside the target root that the run can read, or remove it`);
+}
+/** 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`);
+    }
+}
+/**
+ * The text of the document `name` at the absolute `targetRoot`, undefined where nothing is
+ * there. One whose name resolves outside the target root or to anything but a regular file,
+ * or whose read fails, is refused by `refuse` naming it `label`, nothing read from it. A
+ * document past the bound is read one byte past it and refused as {@link refuseOverBound} does.
+ */
+export function readTargetDocument(host, targetRoot, name, label = name, refuse = unreadable) {
+    const attempt = (read) => {
+        try {
+            return read();
+        }
+        catch (error) {
+            throw refuse(label, message(error));
+        }
+    };
+    const path = joinPath(targetRoot, name);
+    const kind = attempt(() => host.kindOf(path));
+    if (kind === "absent") {
+        return undefined;
+    }
+    const real = attempt(() => host.realPath(path));
+    if (relativePath(attempt(() => host.realPath(targetRoot)), real) === undefined) {
+        throw refuse(label, `resolves to ${real}, outside the target root`);
+    }
+    if (kind !== "file") {
+        throw refuse(label, "is not a regular file");
+    }
+    const text = attempt(() => host.readFile(real, CONFIG_MAX_BYTES + 1));
+    refuseOverBound(label, text);
+    return text;
+}

package/dist/src/fs/manifest.js

@@ -0,0 +1,72 @@
+import { isRecord } from "../json-document.js";
+import { joinPath } from "../paths.js";
+import { message } from "../product.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";
+/** The manifest members a package declares the packages it depends on under. */
+export const DEPENDENCY_SECTIONS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
+/** 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;
+}
+/** The manifest in one directory, as {@link ManifestRead} tells its states apart. */
+export function readManifestAt(host, dir) {
+    if (!holdsManifest(host, dir)) {
+        return { kind: "absent" };
+    }
+    let text;
+    try {
+        text = host.readFile(joinPath(dir, MANIFEST));
+    }
+    catch (error) {
+        return { kind: "unread", reason: message(error) };
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+    return isRecord(value) ? { kind: "read", manifest: value } : { kind: "malformed" };
+}
+/** Whether one directory holds a manifest file. */
+export function holdsManifest(host, dir) {
+    return host.kindOf(joinPath(dir, MANIFEST)) === "file";
+}