@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/src/findings/self-check.ts

@@ -1,3 +1,4 @@
+import { CODE } from "../contract/contract.generated.ts";
 import { REPOSITORY_DOCUMENT } from "../config.ts";
 import type { Finding, FindingDetails, SuppressionEntry } from "../finding.ts";
 import type { InventorySymbol } from "../inventory.ts";
@@ -6,19 +7,12 @@ import type { Position } from "../position.ts";
 import {
   isDependencyCode,
   isUnsuppressibleCode,
-  STALE_SUPPRESSION,
-  SUPPRESSION_WITHOUT_REASON,
   type Mechanism,
   type Refusal,
   type SuppressionRecord,
 } from "../suppress.ts";
 import type { Emitter } from "./emitter.ts";
-
-/** 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 { bytewise } from "../text/compare.ts";
 
 /** The subject kind of a finding about a configured declaration. */
 const DECLARATION_SUBJECT = "configured-declaration";
@@ -39,7 +33,7 @@ export interface StaleRecord {
   readonly reports: readonly string[];
 }
 
-/** What the self-check family reads: the run's refused suppressions and its configured roots. */
+/** What the configuration family reads: the run's refused suppressions and its configured roots. */
 export interface SelfCheckFacts {
   /** The suppressions the grammar refused with a finding, in reading order. */
   readonly refusals: readonly Refusal[];
@@ -135,7 +129,7 @@ function refusedSuppressions(refusals: readonly Refusal[], files: FileRefs): rea
       suppressionRef(refused.symbol, refused.path, files),
       refused.site,
       `${WRITTEN[refused.mechanism]} for ${refused.code} ${
-        refused.reported === SUPPRESSION_WITHOUT_REASON
+        refused.reported === CODE.suppressionWithoutReason
           ? "carries no reason"
           : "names a symbol and no path"
       }`,
@@ -146,7 +140,7 @@ function refusedSuppressions(refusals: readonly Refusal[], files: FileRefs): rea
 
 /** One stale suppression as the report's stale-suppression record carries it. */
 export interface StaleSuppression {
-  readonly code: typeof STALE_SUPPRESSION;
+  readonly code: typeof CODE.staleSuppression;
   readonly mechanism: Mechanism;
   readonly entry: {
     readonly code: string;
@@ -178,10 +172,10 @@ export function staleSuppressions(
     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));
@@ -209,7 +203,7 @@ export function staleSuppressions(
           ? ""
           : `, and ${declared}`;
     return {
-      code: STALE_SUPPRESSION,
+      code: CODE.staleSuppression,
       mechanism: first.mechanism,
       entry: {
         code: first.code,
@@ -242,7 +236,7 @@ function unmatchedDeclarationFindings(
   unmatched: readonly UnmatchedDeclaration[],
 ): readonly Finding[] {
   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`,
@@ -262,7 +256,7 @@ export function unmatchedRootFindings(
 ): readonly Finding[] {
   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:
@@ -273,7 +267,7 @@ export function unmatchedRootFindings(
 }
 
 /**
- * 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/src/findings/unused-declarations.ts

@@ -1,7 +1,9 @@
+import { CODE } from "../contract/contract.generated.ts";
 import type { Finding } from "../finding.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
+import { testsUnseenAPI } from "./completion.ts";
 import { unreachableExports } from "./visibility-narrowing.ts";
 
 /** The kinds of declaration that are members of a class, an interface, a type or an enum. */
@@ -13,18 +15,18 @@ const MEMBERS: ReadonlySet<SymbolKind> = new Set([
 ]);
 
 /**
- * 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: ReadonlySet<SymbolKind> = new Set([
+const NOT_REPORTED_HERE: ReadonlySet<SymbolKind> = 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: Readonly<Record<SymbolKind, string>> = {
   file: "file",
   function: "function",
@@ -55,21 +57,24 @@ interface Judged {
   readonly deprecated: boolean;
   /** Whether the unreachable-export kind reports it. */
   readonly unreachable: boolean;
+  /** Whether it is a test with a target that is published API no declared consumer judges. */
+  readonly testsUnseenAPI: boolean;
 }
 
 /**
  * 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: Judged): string | undefined {
   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;
@@ -80,29 +85,33 @@ function codeOf(judged: Judged): string | undefined {
     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: InventorySymbol): string {
   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. */
@@ -127,15 +136,17 @@ function messageOf(code: string, judged: Judged): string {
   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"
+    code === CODE.unusedMember
       ? `${visibilityWord(symbol)}${word}`
       : symbol.kind === "export-alias"
         ? word
@@ -143,7 +154,7 @@ function messageOf(code: string, judged: Judged): string {
   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`;
@@ -195,21 +206,46 @@ function brandMembers(input: EmitterInput): ReadonlySet<string> {
 /** The kinds of member a brand is: a data member of a type or of a class. */
 const BRANDS: ReadonlySet<SymbolKind> = new Set(["type-member", "class-member"]);
 
-/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations: Emitter = (input) => familyFindings(input, false);
+/** The findings of the unused-declaration kinds, `DS1001` to `DS1004` and `DS1102` to `DS1104`. */
+export const unusedDeclarations: Emitter = (input) => [
+  ...emitterFindings(input, false),
+  ...unusedImports(input),
+];
+
+/**
+ * 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: EmitterInput): Finding[] {
+  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: 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`,
+          },
+        ],
+  );
+}
 
 /**
  * The finding each member of a dead container would carry were its container live: what
  * 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: Emitter = (input) => familyFindings(input, true);
+export const fallenMembers: Emitter = (input) => emitterFindings(input, true);
 
-/** The family's findings, or, where `fallen` is set, its dead containers' members' alone. */
-function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
+/** This emitter's findings, or, where `fallen` is set, its dead containers' members' alone. */
+function emitterFindings(input: EmitterInput, fallen: boolean): Finding[] {
   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: ReadonlySet<string> | undefined;
 
   const found: Finding[] = [];
@@ -229,11 +265,12 @@ function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
       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;
     }

package/src/findings/visibility-narrowing.ts

@@ -1,16 +1,14 @@
+import { CODE } from "../contract/contract.generated.ts";
 import type { Finding } from "../finding.ts";
 import { OUTSIDE, type Graph } from "../graph.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
 import { declarationKey } from "../ref.ts";
 import type { RootKind } from "../roots.ts";
+import { runnerCalls } from "../sweep.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { writeOnlyDeclarations } from "./reads-and-writes.ts";
 
-const UNNECESSARY_EXPORT = "DS1101";
-const UNREACHABLE_EXPORT = "DS1103";
-const REDUNDANT_EXPORT_KEYWORD = "DS1104";
-
 /** How far the references to one declaration reach, from the narrowest. */
 type Reach = "file" | "package" | "outside";
 
@@ -21,7 +19,7 @@ type Reach = "file" | "package" | "outside";
  */
 const PUBLISHING: ReadonlySet<RootKind> = new Set<RootKind>(["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: Partial<Readonly<Record<SymbolKind, string>>> = {
   function: "function",
   class: "class",
@@ -51,8 +49,37 @@ function publishes(kinds: ReadonlySet<RootKind> | undefined): boolean {
   return [...(kinds ?? [])].some((kind) => PUBLISHING.has(kind));
 }
 
+/**
+ * The root kinds that name a file without entering it by its exports: a configuration
+ * string or a script token runs the file, and no tool reads a name it exports.
+ */
+const RUN_ONLY: ReadonlySet<RootKind> = new Set<RootKind>(["configuration-string", "script"]);
+
+/** Whether a root makes its file an entry file, or its declaration an entry, which a tool may read by name. */
 function entersByName(kinds: ReadonlySet<RootKind> | undefined): boolean {
-  return [...(kinds ?? [])].some((kind) => !PUBLISHING.has(kind));
+  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: ReadonlySet<RootKind> = new Set<RootKind>(["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: ReadonlySet<RootKind> | undefined,
+  symbol: InventorySymbol,
+): boolean {
+  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))
+  );
 }
 
 /**
@@ -121,8 +148,8 @@ function wordOf(symbol: InventorySymbol): string {
 
 /** The visibility each narrowing code names, which only the narrowing codes carry. */
 const NARROWER: Readonly<Record<string, "file" | "package">> = {
-  [REDUNDANT_EXPORT_KEYWORD]: "file",
-  [UNNECESSARY_EXPORT]: "package",
+  [CODE.redundantExportKeyword]: "file",
+  [CODE.unnecessaryExport]: "package",
 };
 
 function findingOf(symbol: InventorySymbol, code: string, message: string): Finding {
@@ -163,7 +190,7 @@ function narrowing(
     world.writeOnly.has(declarationKey(symbol.ref, symbol.position.path)) ||
     symbol.kind === "export-alias" ||
     entersByName(facts.rootedBy[at]) ||
-    entersByName(facts.rootedBy[file]) ||
+    fileEntersByName(facts.rootedBy[file], symbol) ||
     (facts.named[at] ?? 0) === 0
   ) {
     return undefined;
@@ -176,7 +203,7 @@ function narrowing(
       }
       return findingOf(
         symbol,
-        REDUNDANT_EXPORT_KEYWORD,
+        CODE.redundantExportKeyword,
         `exported ${word} is referenced only inside the file that declares it`,
       );
     case "package":
@@ -185,7 +212,7 @@ function narrowing(
       }
       return findingOf(
         symbol,
-        UNNECESSARY_EXPORT,
+        CODE.unnecessaryExport,
         `exported ${word} is referenced only inside the package that declares it`,
       );
     default:
@@ -198,7 +225,7 @@ function narrowing(
  * 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: Facts,
@@ -213,7 +240,7 @@ function unreachable(
     (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;
@@ -224,13 +251,13 @@ function unreachable(
       : "has no reference in the target";
   return findingOf(
     symbol,
-    UNREACHABLE_EXPORT,
+    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
@@ -239,13 +266,13 @@ function unreachable(
 export function narrowings(input: EmitterInput): readonly Finding[] {
   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;
+    input.config.analysis.generated_files === "include" ? undefined : input.files.generated;
 
   const findings: Finding[] = [];
   facts.graph.symbols.forEach((symbol, at) => {
@@ -253,8 +280,13 @@ export function narrowings(input: EmitterInput): readonly Finding[] {
       return;
     }
     const candidate = candidates.get(symbol.id);
+    // A declaration of test code, a test file's or test-support code's, that only test code
+    // references is a candidate, live in the run that counts test references.
+    const live =
+      candidate === undefined ||
+      (facts.graph.test[at] === true && !candidate.unreferencedTest && !candidate.testOfDeadCode);
     const found =
-      candidate === undefined
+      candidate === undefined || live
         ? narrowing(facts, at, symbol, world)
         : unreachable(facts, at, symbol, candidate, input);
     if (found !== undefined) {
@@ -281,5 +313,5 @@ export function unreachableExports(input: EmitterInput): ReadonlySet<string> {
   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: Emitter = narrowings;

package/src/findings-pass.ts

@@ -4,8 +4,9 @@
  * verdict a report carries beside them.
  */
 
+import { EXIT_CLEAN, EXIT_FINDINGS, EXIT_PENDING } from "./contract/contract.generated.ts";
 import type { AnalysisInputs } from "./analysis.ts";
-import { fails, type Config } from "./config.ts";
+import { fails, type ResolvedConfig } from "./config.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type { CompletedFinding, Finding } from "./finding.ts";
 import { decidedFindings, type Withheld } from "./findings/emitters.ts";
@@ -23,7 +24,8 @@ import {
   type Ledger,
 } from "./suppress.ts";
 import type { Provenance, Recorded } from "./suppress-file.ts";
-import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.ts";
+import { bytewise } from "./text/compare.ts";
+import { PRODUCT } from "./product.ts";
 
 /** The counts a report's totals carry beside its findings. */
 interface PassTotals {
@@ -49,25 +51,14 @@ export interface PassResult {
   readonly ledger: Ledger;
 }
 
-/** The exit code of a report holding at least one pending finding. */
-export const EXIT_PENDING = 4;
-
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /** The canonical order: path, line, column, code, then the symbol reference. */
 function canonical(a: Finding, b: Finding): number {
   return (
-    compare(a.position.path, b.position.path) ||
+    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)
   );
 }
 
@@ -118,7 +109,7 @@ export function findingsPass(inputs: AnalysisInputs): PassResult {
  * suppression is stale or a finding's severity reaches the configured failing severity;
  * clean otherwise.
  */
-export function verdictOf(result: PassResult, config: Config): number {
+export function verdictOf(result: PassResult, config: ResolvedConfig): number {
   if (result.totals.pending > 0) {
     return EXIT_PENDING;
   }
@@ -126,7 +117,7 @@ export function verdictOf(result: PassResult, config: Config): number {
     return EXIT_FINDINGS;
   }
   const failing = result.findings.some((finding) =>
-    fails(finding.severity, config.reporters.failOn),
+    fails(finding.severity, config.reporters.fail_on),
   );
   return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
@@ -164,5 +155,5 @@ export function rowKey(row: Recorded): string {
 
 /** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */
 export function analyzerProvenance(version: string): Provenance {
-  return { analyzer: "deadset-ts", version };
+  return { analyzer: PRODUCT, version };
 }

package/src/framework-lifecycle.ts

@@ -55,8 +55,8 @@ function resolveContracts<Brand>(
   contracts: readonly LifecycleContract[],
 ): readonly ResolvedContract[] {
   const entries: DeclarationEntry[] = contracts.flatMap((contract) => [
-    ...contract.components,
-    ...contract.bases,
+    ...(contract.components ?? []),
+    ...(contract.bases ?? []),
   ]);
   const resolved = resolveEntries(project, held, entries);
   let next = 0;
@@ -67,8 +67,8 @@ function resolveContracts<Brand>(
   };
   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),
   }));
 }
 
@@ -243,11 +243,11 @@ function byBases<Brand>(
  */
 export function frameworkLifecycle<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
   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),
@@ -256,7 +256,7 @@ export function frameworkLifecycle<Brand>(input: DetectorInput<Brand>): readonly
     return [];
   }
   const ids = new Set(components.map((one) => one.id));
-  const sides: readonly ClassSide[] = input.ts.lifecycleContracts.some((contract) =>
+  const sides: readonly ClassSide[] = input.ts.lifecycle_contracts.some((contract) =>
     contract.members.some((name) => name.endsWith(":static")),
   )
     ? ["instance", "static"]

package/src/fs/document.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.ts";
+import type { Host } from "../host.ts";
+import { failureExit } from "../failure.ts";
+import { joinPath, relativePath } from "../paths.ts";
+import { message } from "../product.ts";
+import { utf8Bytes } from "../reporters/sha256.ts";
+import { UsageError } from "../usage.ts";
+
+function unreadable(label: string, reason: string): Error {
+  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: string, text: string): void {
+  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: Host,
+  targetRoot: string,
+  name: string,
+  label = name,
+  refuse: (label: string, reason: string) => Error = unreadable,
+): string | undefined {
+  const attempt = <T>(read: () => T): T => {
+    try {
+      return read();
+    } catch (error: unknown) {
+      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;
+}