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

package/src/findings/visibility-narrowing.ts

@@ -1,17 +1,15 @@
+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 { OUTSIDE, type Graph } from "../liveness/graph.ts";
+import { WORDS, type InventorySymbol } from "../inventory.ts";
+import type { Candidate } from "../liveness/sweep.ts";
 import { declarationKey } from "../ref.ts";
-import type { RootKind } from "../roots.ts";
-import { runnerCalls } from "../sweep.ts";
+import type { RootKind } from "../roots/root-set.ts";
+import { runnerCalls } from "../liveness/sweep.ts";
+import { exposedTypes, exposes } from "../exposure.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";
 
@@ -22,18 +20,6 @@ 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. */
-const WORDS: Partial<Readonly<Record<SymbolKind, string>>> = {
-  function: "function",
-  class: "class",
-  interface: "interface",
-  type: "type alias",
-  enum: "enum",
-  namespace: "namespace",
-  variable: "variable",
-  "export-alias": "re-export",
-};
-
 /** Per declaration of the run, the facts both rules read. */
 interface Facts {
   readonly graph: Graph;
@@ -145,14 +131,10 @@ function topLevelExport(facts: Facts, at: number, symbol: InventorySymbol): bool
   return symbol.exported && parent !== OUTSIDE && facts.graph.symbols[parent]?.kind === "file";
 }
 
-function wordOf(symbol: InventorySymbol): string {
-  return WORDS[symbol.kind] ?? symbol.kind;
-}
-
 /** 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 {
@@ -184,7 +166,11 @@ function narrowing(
   facts: Facts,
   at: number,
   symbol: InventorySymbol,
-  world: { readonly closed: boolean; readonly writeOnly: ReadonlySet<string> },
+  world: {
+    readonly closed: boolean;
+    readonly writeOnly: ReadonlySet<string>;
+    readonly exposed: ReadonlySet<string> | "every";
+  },
 ): Finding | undefined {
   const { closed } = world;
   const file = facts.fileOf[at] ?? OUTSIDE;
@@ -198,7 +184,7 @@ function narrowing(
   ) {
     return undefined;
   }
-  const word = wordOf(symbol);
+  const word = WORDS[symbol.kind];
   switch (facts.reach[at]) {
     case "file":
       if (facts.published[file] === true && !closed) {
@@ -206,16 +192,16 @@ function narrowing(
       }
       return findingOf(
         symbol,
-        REDUNDANT_EXPORT_KEYWORD,
+        CODE.redundantExportKeyword,
         `exported ${word} is referenced only inside the file that declares it`,
       );
     case "package":
-      if (!closed || !publishes(facts.rootedBy[at])) {
+      if (!closed || !publishes(facts.rootedBy[at]) || exposes(world.exposed, symbol)) {
         return undefined;
       }
       return findingOf(
         symbol,
-        UNNECESSARY_EXPORT,
+        CODE.unnecessaryExport,
         `exported ${word} is referenced only inside the package that declares it`,
       );
     default:
@@ -234,7 +220,7 @@ function unreachable(
   facts: Facts,
   at: number,
   symbol: InventorySymbol,
-  candidate: MatrixCandidate,
+  candidate: Candidate,
   input: EmitterInput,
 ): Finding | undefined {
   if (
@@ -254,13 +240,13 @@ function unreachable(
       : "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`,
+    CODE.unreachableExport,
+    `exported ${WORDS[symbol.kind]} ${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
@@ -269,13 +255,23 @@ 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 world = { closed, writeOnly: writeOnlyDeclarations(input) };
+  const closed = input.config.consumers.complete && declared.every((id) => loaded.includes(id));
+  const world = {
+    closed,
+    writeOnly: writeOnlyDeclarations(input),
+    exposed: closed
+      ? exposedTypes(
+          facts.graph,
+          facts.reach.map((reach) => reach === "outside"),
+          input.boundary.carriers,
+        )
+      : new Set<string>(),
+  };
   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) => {
@@ -316,5 +312,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";
@@ -15,15 +16,10 @@ import {
   type StaleRecord,
   type StaleSuppression,
 } from "./findings/self-check.ts";
-import {
-  isDependencySubject,
-  isRowSubject,
-  pairs,
-  suppressionCounts,
-  type Ledger,
-} from "./suppress.ts";
+import { namesKind, pairs, suppressionCounts, 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 +45,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 +103,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 +111,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;
 }
@@ -140,15 +125,14 @@ export interface RecordableFinding {
 
 /**
  * The rows one round of a baseline write records from its findings, in their order. A
- * finding about a row of a document other than a dependency row is not recorded: no record
- * withholds one, so a row recording it would be stale on the first read back. Two findings
- * that would record the same row, two parts of one declaration under one code, record it
- * once.
+ * finding no baseline row can name is not recorded: a row recording it would be stale on
+ * the first read back. Two findings that would record the same row, two parts of one
+ * declaration under one code, record it once.
  */
 export function recordedFindings(findings: readonly RecordableFinding[]): readonly Recorded[] {
   const rows = new Map<string, Recorded>();
   for (const finding of findings) {
-    if (isRowSubject(finding.symbol.kind) && !isDependencySubject(finding.symbol.kind)) {
+    if (!namesKind(finding.symbol.kind, "baseline")) {
       continue;
     }
     const row = { code: finding.code, symbol: finding.symbol.ref, path: finding.position.path };
@@ -164,5 +148,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

@@ -1,9 +1,10 @@
 /**
- * The framework-lifecycle class: a member a `ts.lifecycle_contracts` entry lists is held
- * back on each class that is the entry's component, being a class a decorator or a call
- * the entry's `components` name is attached to or passes, or one extending, directly or
- * through a chain, a class its `bases` name. A component's members are its type's, so a
- * member a base class declares answers for every subclass.
+ * The framework-lifecycle class: a member a lifecycle contract lists is held back on each
+ * class that is the contract's component, being a class a decorator or a call the
+ * contract's `components` name is attached to or passes, or one extending, directly or
+ * through a chain, a class its `bases` name. The contracts are the platform's custom
+ * elements and each `ts.lifecycle_contracts` entry. A component's members are its type's,
+ * so a member a base class declares answers for every subclass.
  */
 
 import {
@@ -26,13 +27,37 @@ import {
   resolveEntries,
   spelledEntry,
   type ResolvedEntry,
-} from "./configured-declarations.ts";
+} from "./roots/configured-declarations.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { renderPosition } from "./position.ts";
 import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 
+/**
+ * The platform's own contract (references-ts.38): `CustomElementRegistry.define` reads
+ * these members off the class it registers, its constructor's and its prototype's
+ * (https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-define),
+ * and calls each callback as a custom element reaction.
+ */
+const CUSTOM_ELEMENTS: LifecycleContract = {
+  components: [{ global: "CustomElementRegistry.define" }],
+  members: [
+    "observedAttributes:static",
+    "disabledFeatures:static",
+    "formAssociated:static",
+    "connectedCallback",
+    "disconnectedCallback",
+    "connectedMoveCallback",
+    "adoptedCallback",
+    "attributeChangedCallback",
+    "formAssociatedCallback",
+    "formResetCallback",
+    "formDisabledCallback",
+    "formStateRestoreCallback",
+  ],
+};
+
 /** One class that is a component of one contract, and what says it is. */
 interface Component {
   readonly contract: LifecycleContract;
@@ -55,8 +80,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 +92,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),
   }));
 }
 
@@ -238,16 +263,17 @@ function byBases<Brand>(
 
 /**
  * The framework-lifecycle detector: each member a contract lists, on each class that
- * is a component of that contract's framework, recorded where the class was found to
- * be one.
+ * is a component of that contract's framework, recorded once per place where the class
+ * was found to be one.
  */
 export function frameworkLifecycle<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
   const { project, held, targetRoot } = input;
-  if (input.ts.lifecycleContracts.length === 0) {
+  const declared = [CUSTOM_ELEMENTS, ...input.ts.lifecycle_contracts];
+  const contracts = resolveContracts(project, held, declared);
+  if (contracts.every((one) => one.components.length === 0 && one.bases.length === 0)) {
     return [];
   }
   const chains = aliasChains(project, held);
-  const contracts = resolveContracts(project, held, input.ts.lifecycleContracts);
   const components = [
     ...byComponents(project, held, chains, contracts),
     ...byBases(project, held, chains, contracts),
@@ -256,7 +282,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[] = declared.some((contract) =>
     contract.members.some((name) => name.endsWith(":static")),
   )
     ? ["instance", "static"]
@@ -264,7 +290,7 @@ export function frameworkLifecycle<Brand>(input: DetectorInput<Brand>): readonly
   const members = sides.map((side) => classMembers(project, held, ids, side));
   const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
 
-  const found: Evidence[] = [];
+  const found = new Map<string, Evidence>();
   for (const component of components) {
     const listed = new Set(component.contract.members);
     const site = renderPosition(
@@ -275,10 +301,12 @@ export function frameworkLifecycle<Brand>(input: DetectorInput<Brand>): readonly
     for (const member of members.flatMap((side) => side.get(component.id) ?? [])) {
       const symbol = byId.get(member.id);
       const spelled = symbol === undefined ? undefined : memberComponent(symbol, byId);
-      if (spelled !== undefined && listed.has(spelled)) {
-        found.push({ id: member.id, detail: component.detail, site });
+      // A configured contract may name the platform's registry too; one record answers both.
+      const key = `${member.id}\0${component.detail}\0${site.path}:${String(site.line)}:${String(site.column)}`;
+      if (spelled !== undefined && listed.has(spelled) && !found.has(key)) {
+        found.set(key, { id: member.id, detail: component.detail, site });
       }
     }
   }
-  return found;
+  return [...found.values()];
 }

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;
+}

package/src/fs/manifest.ts

@@ -0,0 +1,96 @@
+import type { Host } from "../host.ts";
+import { isRecord } from "../json-document.ts";
+import { joinPath } from "../paths.ts";
+import { message } from "../product.ts";
+
+/** 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",
+] as const;
+
+/** Whether one path passes through an installed-packages directory. */
+export function inInstalledPackages(path: string): boolean {
+  return path.split("/").includes(INSTALLED_PACKAGES);
+}
+
+/** What one JSON file reads as: its text and decoded value, text that does not parse, or a file that cannot be read, with the read's error. */
+type JSONRead =
+  | { readonly kind: "read"; readonly text: string; readonly value: unknown }
+  | { readonly kind: "malformed" }
+  | { readonly kind: "unread"; readonly reason: string };
+
+/** One JSON file, read and parsed, as {@link JSONRead} tells its states apart. */
+export function readJSONFile(host: Host, path: string): JSONRead {
+  let text: string;
+  try {
+    text = host.readFile(path);
+  } catch (error: unknown) {
+    return { kind: "unread", reason: message(error) };
+  }
+  try {
+    return { kind: "read", text, value: JSON.parse(text) as unknown };
+  } catch {
+    return { kind: "malformed" };
+  }
+}
+
+/** One JSON file's text and decoded value, or undefined where it cannot be read or parsed. */
+export function readDocument(
+  host: Host,
+  path: string,
+): { text: string; value: unknown } | undefined {
+  const read = readJSONFile(host, path);
+  return read.kind === "read" ? { text: read.text, value: read.value } : undefined;
+}
+
+/** One JSON file's decoded value, or undefined where it cannot be read or parsed. */
+export function readJSON(host: Host, path: string): unknown {
+  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: Host, dir: string): Record<string, unknown> | undefined {
+  const value = readJSON(host, joinPath(dir, MANIFEST));
+  return isRecord(value) ? value : undefined;
+}
+
+/**
+ * What one directory's manifest reads as: none, an object, a file that does not parse as one,
+ * or a file that cannot be read, with the read's error. Either of the last two still bounds
+ * the package it would declare.
+ */
+export type ManifestRead =
+  | { readonly kind: "absent" }
+  | { readonly kind: "read"; readonly manifest: Record<string, unknown> }
+  | { readonly kind: "malformed" }
+  | { readonly kind: "unread"; readonly reason: string };
+
+/** The manifest in one directory, as {@link ManifestRead} tells its states apart. */
+export function readManifestAt(host: Host, dir: string): ManifestRead {
+  if (!holdsManifest(host, dir)) {
+    return { kind: "absent" };
+  }
+  const read = readJSONFile(host, joinPath(dir, MANIFEST));
+  if (read.kind !== "read") {
+    return read;
+  }
+  return isRecord(read.value) ? { kind: "read", manifest: read.value } : { kind: "malformed" };
+}
+
+/** Whether one directory holds a manifest file. */
+export function holdsManifest(host: Host, dir: string): boolean {
+  return host.kindOf(joinPath(dir, MANIFEST)) === "file";
+}

package/src/fs/tree.ts

@@ -0,0 +1,110 @@
+import type { DirectoryEntry, Host } from "../host.ts";
+import { ancestors, joinPath, resolvePath } from "../paths.ts";
+import { LANGUAGE_ROWS } from "../contract/contract.generated.ts";
+import { LANGUAGE } from "../product.ts";
+import { bytewise } from "../text/compare.ts";
+import { globExpression } from "../text/glob.ts";
+
+/** 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: string): boolean {
+  return SKIPPED_DIRECTORIES.some((pattern) => pattern.test(name));
+}
+
+/** A git repository's working tree root, and the `info/exclude` file git reads for it. */
+interface Repository {
+  readonly root: string;
+  /** Undefined where a `.git` file names no repository directory. */
+  readonly exclude: string | undefined;
+}
+
+/** One file's text without its line ending, or undefined where it cannot be read. */
+function lineOf(host: Host, path: string): string | undefined {
+  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: Host, dir: string): Repository | undefined {
+  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: Host, dir: string): readonly DirectoryEntry[] {
+  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: Host,
+  dir: string,
+  accepts: (name: string) => boolean,
+): readonly string[] {
+  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: Host, dir: string): readonly string[] {
+  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: Host,
+  root: string,
+  accepts: (name: string) => boolean,
+): readonly string[] {
+  const found: string[] = [];
+  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);
+}