@cplieger/deadset-ts 8.0.0-dev.15 → 8.0.0-dev.16

package/src/roots/unseen-loads.ts

@@ -0,0 +1,307 @@
+/**
+ * The loads by a computed path: those whose files the analysis resolves, and those it
+ * cannot, whose files are roots the analysis does not see, so the configuration's roots
+ * are never complete.
+ */
+
+import {
+  isBinaryExpression,
+  isCallExpression,
+  isIdentifier,
+  isMetaProperty,
+  isNoSubstitutionTemplateLiteral,
+  isPropertyAccessExpression,
+  isStringLiteral,
+  isTemplateExpression,
+  SyntaxKind,
+  type CallExpression,
+  type Identifier,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/ast";
+import { membersNamed, textsOf, writtenValue, type Value } from "../entries/static-module.ts";
+import { writtenName } from "../platform-calls.ts";
+import { dirnamePath, relativePath, resolvePath } from "../paths.ts";
+import type { Position } from "../position.ts";
+import { unwrapped } from "../unwrap.ts";
+import { globExpression } from "../text/glob.ts";
+
+/** One load the analysis cannot resolve, in the configuration whose production file writes it. */
+export interface UnseenLoad {
+  readonly configuration: string;
+  /** The position of the call. */
+  readonly position: Position;
+}
+
+/** The literal text a computed path starts with: a template's head, or a concatenation's first literal. */
+function leadingLiteral(node: Node): string | undefined {
+  const at = unwrapped(node);
+  if (isTemplateExpression(at)) {
+    return at.head.text;
+  }
+  if (isBinaryExpression(at) && at.operatorToken.kind === SyntaxKind.PlusToken) {
+    const left = unwrapped(at.left);
+    return isStringLiteral(left) || isNoSubstitutionTemplateLiteral(left)
+      ? left.text
+      : leadingLiteral(at.left);
+  }
+  return undefined;
+}
+
+/**
+ * The directory below `dir` a computed load's leading literal names, every file of which
+ * the load reaches, or none where it names a package, `dir` itself or a directory holding
+ * it, each of which would name every sibling.
+ */
+function computedLoadDirectory(dir: string, prefix: string): string | undefined {
+  if (!(prefix.startsWith("./") || prefix.startsWith("../")) || !prefix.endsWith("/")) {
+    return undefined;
+  }
+  const target = resolvePath(dir, prefix);
+  return target === dir || relativePath(target, dir) !== undefined ? undefined : target;
+}
+
+/** One `import()`, `require()` or `import.meta.glob()` call, and the declaration whose code writes it. */
+export interface LoadCall {
+  readonly call: CallExpression;
+  readonly from: string;
+}
+
+/** One file a computed load may load, by its id. */
+interface Loadable {
+  readonly file: SourceFile;
+  readonly fileId: string;
+}
+
+/** One load by a computed path whose files the analysis resolves. */
+interface ComputedLoad {
+  readonly call: CallExpression;
+  readonly from: string;
+  /** The name a `require()` call is written with; {@link callsPlatform} owns which one loads. */
+  readonly require: Identifier | undefined;
+  readonly files: readonly Loadable[];
+  /** Whether the load reads each file as text or as a URL, which references no declaration of it. */
+  readonly asset: boolean;
+  /**
+   * Whether the analysis names every file the load may load. An unresolved load names none,
+   * and leaves the configuration's roots incomplete (confidence.26).
+   */
+  readonly resolved: boolean;
+  /**
+   * Whether the load is an eager glob, which Vite turns into static imports at the top of
+   * the calling module (https://vite.dev/guide/features.html#glob-import), so the file
+   * evaluates what it loads wherever the call is written.
+   */
+  readonly eager: boolean;
+}
+
+/** Whether one node is a call that may load a module by a computed path. */
+export function isLoadCall(node: Node): node is CallExpression {
+  if (!isCallExpression(node)) {
+    return false;
+  }
+  return (
+    node.expression.kind === SyntaxKind.ImportKeyword ||
+    writtenName(node.expression) !== undefined ||
+    isMetaGlob(node)
+  );
+}
+
+/**
+ * The files one `import.meta.glob` call loads, as Vite's `toAbsoluteGlob` reads its globs
+ * (https://vite.dev/guide/features.html#glob-import): `/` against the project root, `./`
+ * and `../` against a literal `base` (read against the root where it starts with `/`) or the
+ * calling file's directory, `**` as written, and `!` removing what it matches. Undefined
+ * where Vite reads a glob through an alias, the root is unknown, or a glob or base is computed.
+ */
+function globbed(
+  file: SourceFile,
+  first: Node,
+  options: Node | undefined,
+  others: readonly Loadable[],
+  rootOf: (fileName: string) => string | undefined,
+): readonly Loadable[] | undefined {
+  const patterns = textsOf(writtenValue(first), true);
+  const bases = globOption(options, "base");
+  const [written, ...more] = bases ?? [];
+  const base = written === undefined ? undefined : textsOf(written, false);
+  if (
+    patterns === undefined ||
+    bases === undefined ||
+    more.length > 0 ||
+    (written !== undefined && base === undefined)
+  ) {
+    return undefined;
+  }
+  const dir = dirnamePath(file.fileName);
+  const root = (): string | undefined => rootOf(file.fileName);
+  const against = (at: string): string | undefined => {
+    if (!at.startsWith("/")) {
+      return resolvePath(dir, at);
+    }
+    const top = root();
+    return top === undefined ? undefined : resolvePath(top, `.${at}`);
+  };
+  const from = base?.[0] === undefined ? dir : against(base[0]);
+  const keep: RegExp[] = [];
+  const drop: RegExp[] = [];
+  for (const written of patterns) {
+    const negated = written.startsWith("!");
+    const pattern = negated ? written.slice(1) : written;
+    let path: string | undefined;
+    if (pattern.startsWith("/")) {
+      path = against(pattern);
+    } else if (pattern.startsWith("./") || pattern.startsWith("../")) {
+      path = from === undefined ? undefined : resolvePath(from, pattern);
+    } else if (pattern.startsWith("**")) {
+      path = pattern;
+    }
+    if (path === undefined) {
+      return undefined;
+    }
+    (negated ? drop : keep).push(globExpression(path));
+  }
+  return others.filter(
+    (candidate) =>
+      keep.some((glob) => glob.test(candidate.file.fileName)) &&
+      !drop.some((glob) => glob.test(candidate.file.fileName)),
+  );
+}
+
+/**
+ * The computed loads among one file's load calls, each loading the `candidates` but the
+ * file itself: an `import()` or `require()` whose path starts with a relative literal naming
+ * a directory below the file's loads every candidate below it, as a bundler's context module
+ * reads it, and an `import.meta.glob` every candidate its globs match ({@link globbed}). A
+ * call of a computed path that names no such directory and no package is an unresolved load.
+ */
+export function computedLoadsOf(
+  file: SourceFile,
+  calls: readonly LoadCall[],
+  candidates: readonly Loadable[],
+  rootOf: (fileName: string) => string | undefined,
+): readonly ComputedLoad[] {
+  const dir = dirnamePath(file.fileName);
+  const others = candidates.filter((candidate) => candidate.file !== file);
+  return calls.flatMap(({ call, from }): ComputedLoad[] => {
+    const [first, options] = call.arguments;
+    if (first === undefined) {
+      return [];
+    }
+    if (isMetaGlob(call)) {
+      const files = globbed(file, first, options, others, rootOf);
+      const asset = readsAsAsset(options);
+      return [
+        {
+          call,
+          from,
+          require: undefined,
+          files: files ?? [],
+          resolved: files !== undefined,
+          asset,
+          eager: isEager(options),
+        },
+      ];
+    }
+    const argument = unwrapped(first);
+    const require =
+      call.expression.kind === SyntaxKind.ImportKeyword ? undefined : writtenName(call.expression);
+    if (!mayNamePath(argument)) {
+      return [];
+    }
+    const prefix = leadingLiteral(argument);
+    if (namesPackage(prefix)) {
+      return [];
+    }
+    const target = prefix === undefined ? undefined : computedLoadDirectory(dir, prefix);
+    const files =
+      target === undefined
+        ? []
+        : others.filter((candidate) => relativePath(target, candidate.file.fileName) !== undefined);
+    return [
+      { call, from, require, files, resolved: target !== undefined, asset: false, eager: false },
+    ];
+  });
+}
+
+/**
+ * Whether a computed argument may be a module path: anything but a string, which names its
+ * module, and a value no path is, a number, a boolean, `null`, an object, an array, a
+ * function or a class.
+ */
+function mayNamePath(argument: Node): boolean {
+  return !NO_PATH.has(argument.kind);
+}
+
+const NO_PATH: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.StringLiteral,
+  SyntaxKind.NoSubstitutionTemplateLiteral,
+  SyntaxKind.NumericLiteral,
+  SyntaxKind.BigIntLiteral,
+  SyntaxKind.TrueKeyword,
+  SyntaxKind.FalseKeyword,
+  SyntaxKind.NullKeyword,
+  SyntaxKind.ObjectLiteralExpression,
+  SyntaxKind.ArrayLiteralExpression,
+  SyntaxKind.ArrowFunction,
+  SyntaxKind.FunctionExpression,
+  SyntaxKind.ClassExpression,
+  SyntaxKind.RegularExpressionLiteral,
+]);
+
+/** Whether one call is `import.meta.glob(...)`. */
+function isMetaGlob(node: CallExpression): boolean {
+  if (!isPropertyAccessExpression(node.expression)) {
+    return false;
+  }
+  const { expression, name } = node.expression;
+  return (
+    isIdentifier(name) &&
+    name.text === "glob" &&
+    isMetaProperty(expression) &&
+    expression.keywordToken === SyntaxKind.ImportKeyword
+  );
+}
+
+/** The values the options of an `import.meta.glob` write for one key, undefined where a spread may hide one. */
+function globOption(options: Node | undefined, key: string): readonly Value[] | undefined {
+  return options === undefined ? [] : membersNamed(writtenValue(options), key);
+}
+
+/** Whether the options of an `import.meta.glob` set `eager` to `true`. */
+function isEager(options: Node | undefined): boolean {
+  return (
+    globOption(options, "eager")?.some((value) => value.kind === "boolean" && value.value) === true
+  );
+}
+
+/** The query parameters that make Vite load a file as its text or its URL, each written bare. */
+const ASSET_QUERY = /(?:^\?|&)(?:raw|url|inline)(?:&|$)/u;
+
+/**
+ * Whether the options of an `import.meta.glob` read each file as text or as a URL: a
+ * `query` string holding a bare `raw`, `url` or `inline`, or an `as` of `raw` or `url`,
+ * which Vite reads as that query (https://vite.dev/guide/features.html#glob-import). Any
+ * other query is read as loading the module, which keeps more than it may.
+ */
+function readsAsAsset(options: Node | undefined): boolean {
+  const texts = (key: string): readonly string[] =>
+    (globOption(options, key) ?? []).flatMap((value) =>
+      value.kind === "text" ? [value.text] : [],
+    );
+  return (
+    texts("as").some((text) => text === "raw" || text === "url") ||
+    texts("query").some((text) => ASSET_QUERY.test(text.startsWith("?") ? text : `?${text}`))
+  );
+}
+
+/** Whether a computed path's leading literal names a package, whose files are none of the target's. */
+function namesPackage(prefix: string | undefined): boolean {
+  return (
+    prefix !== undefined &&
+    prefix !== "" &&
+    !prefix.startsWith(".") &&
+    !prefix.startsWith("/") &&
+    !/^[A-Za-z][A-Za-z\d+.-]*:/u.test(prefix)
+  );
+}

package/src/serialization-contract.ts

@@ -72,7 +72,7 @@ import {
   namesADeclaration,
   resolveEntries,
   spelledEntry,
-} 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, type Position } from "./position.ts";

package/src/source-files.ts

@@ -8,6 +8,7 @@ import type { SourceFile } from "@typescript/native/ast";
 import { commonDirectory, emittedFrom } from "./load/emit-map.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { ProjectView } from "./session.ts";
+import { OUTPUT_EXTENSIONS } from "./extensions.ts";
 
 /** The one character a subpath pattern of a manifest's `exports` holds. */
 const SUBPATH_WILDCARD = "*";
@@ -15,9 +16,6 @@ const SUBPATH_WILDCARD = "*";
 /** The extension a source file's name drops when the project writes it out. */
 const SOURCE_EXTENSION = /\.[cm]?[jt]sx?$/u;
 
-/** The extensions the project may write a source file's output under. */
-const OUTPUT_EXTENSIONS = [".js", ".mjs", ".cjs", ".jsx", ".d.ts", ".d.mts", ".d.cts"] as const;
-
 /**
  * Whether one path is what a subpath pattern stands for: the text before the
  * wildcard, any run of characters including the solidus, then the text after it.
@@ -90,13 +88,10 @@ function layoutOf<Brand>(
 }
 
 /**
- * The lookups over one project's own files.
- *
- * A path that names an emitted file is read back to the source the project would
- * emit it from through the project's own emit mapping and nothing else: the
- * extension is one the compiler emits from a source extension, and a path below the
- * output directory is read below the directory the compiler emits from, which the
- * configuration declares or which is the directory every input file shares.
+ * The lookups over one project's own files. A path naming an emitted file is read back to its
+ * source through the project's own emit mapping alone: the extension is one the compiler emits
+ * from a source extension, and a path below the output directory is read below the directory
+ * the compiler emits from, which the configuration declares or every input file shares.
  */
 export function sourceFilesOf<Brand>(project: ProjectView<Brand>, targetRoot: string): SourceFiles {
   const byName = new Map<string, SourceFile>();

package/src/suppress.ts

@@ -4,12 +4,13 @@
  * ignore entry or a baseline row. A bound record marks its declaration live before the
  * sweep, unless its code reports a part or a dependency row, and is in effect when it
  * withholds a finding its code would have produced there, dormant when the configuration
- * withholds every such finding anyway, and stale otherwise.
+ * or a hold withholds every such finding anyway, and stale otherwise.
  */
 
 import {
   type CODE,
   KIND_ROWS,
+  REMEDIES,
   SYMBOL_SUBJECTS,
   type Subject,
 } from "./contract/contract.generated.ts";
@@ -147,6 +148,20 @@ export interface Dials<F extends Finding = Finding> {
   readonly withholds: (finding: F) => boolean;
 }
 
+/**
+ * What the analysis holds because it cannot decide it, as the ledger reads it: a hold is a
+ * gap, not evidence that the code changed, so a record it touches is dormant.
+ */
+export interface Holds<F extends Finding = Finding> {
+  /** Whether a hold withholds one finding: a type error's skip, or a hold of its declaration. */
+  readonly withholds: (finding: F) => boolean;
+  /** Whether a hold keeps the declaration one record is bound to live, so no finding about it is computed. */
+  readonly holdsRecord: (record: SuppressionRecord) => boolean;
+}
+
+/** No hold. */
+const NO_HOLDS: Holds = { withholds: () => false, holdsRecord: () => false };
+
 /** What every record did, and the findings the records withhold. */
 export interface Ledger {
   /** One verdict per record, in reading order. */
@@ -172,36 +187,30 @@ function rowOf(subject: Subject | undefined): boolean {
   return subject === "file" || subject === "dependency" || subject === "record";
 }
 
-/**
- * Whether a finding's subject is a row of a document rather than a declaration. Apart
- * from a dependency row, nothing withholds a finding about one.
- */
+/** Whether a finding's subject is a row of a document rather than a declaration. */
 export function isRowSubject(kind: string): boolean {
   return rowOf(subjectOf(kind));
 }
 
-/** Whether a code reports a row of a document. */
-export function isRowCode(code: string): boolean {
-  return rowOf(SUBJECT_OF_CODE.get(code));
+/** The subject a code reports, which kinds.json's remedies table answers for. */
+export function subjectOfCode(code: string): Subject | undefined {
+  return SUBJECT_OF_CODE.get(code);
 }
 
 /**
- * Whether a finding's subject is a dependency row. An ignore entry or a baseline row
- * naming the row's reference and file withholds its finding and marks nothing, and an
- * inline directive never binds one.
+ * Whether a record of `mechanism` can name a finding about `subject`, as kinds.json's
+ * remedies table lists the suppressions of each subject. A subject the table does not
+ * know is a declaration's.
  */
-export function isDependencySubject(kind: string): boolean {
-  return subjectOf(kind) === "dependency";
-}
-
-/** Whether a code reports a dependency row, which only an ignore entry or a baseline row names. */
-export function isDependencyCode(code: string): boolean {
-  return SUBJECT_OF_CODE.get(code) === "dependency";
+export function names(subject: Subject | undefined, mechanism: Mechanism): boolean {
+  return (REMEDIES[subject ?? "declaration"].suppressions as readonly Mechanism[]).includes(
+    mechanism,
+  );
 }
 
-/** Whether a code reports a row of a document that no record of any mechanism can name. */
-export function isUnsuppressibleCode(code: string): boolean {
-  return isRowCode(code) && !isDependencyCode(code);
+/** Whether a finding about a symbol of `kind` is one a record of `mechanism` can name. */
+export function namesKind(kind: string, mechanism: Mechanism): boolean {
+  return names(subjectOf(kind), mechanism);
 }
 
 /**
@@ -238,16 +247,13 @@ export function pairs(record: SuppressionRecord, finding: Finding): boolean {
   if (record.code !== finding.code) {
     return false;
   }
-  if (isDependencySubject(finding.symbol.kind)) {
-    return (
-      record.mechanism !== "inline" &&
-      record.symbol === finding.symbol.ref &&
-      record.path === finding.position.path
-    );
-  }
-  if (isRowSubject(finding.symbol.kind)) {
+  const subject = subjectOf(finding.symbol.kind);
+  if (!names(subject, record.mechanism)) {
     return false;
   }
+  if (subject === "dependency") {
+    return record.symbol === finding.symbol.ref && record.path === finding.position.path;
+  }
   if (record.bound !== "" && record.bound === positionKey(finding.position)) {
     return true;
   }
@@ -262,13 +268,14 @@ export function pairs(record: SuppressionRecord, finding: Finding): boolean {
  * there: swept with no mark for a liveness kind, and as swept otherwise. The first record
  * in reading order claims a finding, so a second naming it is stale; a part-kind record
  * claims every finding of its code about a part of its declaration. A record is dormant
- * when the dials withhold every finding it claims, read from those findings alone, or when
- * it claims none and its code's severity is `allow`.
+ * when the dials or `holds` withhold every finding it claims, or when it claims none and
+ * its code is at `allow` or a hold keeps its declaration live.
  */
 export function ledgerOf<F extends Finding>(
   records: readonly SuppressionRecord[],
   would: readonly F[],
   dials: Dials<F>,
+  holds: Holds<F> = NO_HOLDS,
 ): Ledger {
   const taken = new Set<string>();
   const verdicts: Verdict[] = [];
@@ -278,13 +285,21 @@ export function ledgerOf<F extends Finding>(
     const claimed =
       first === undefined ? [] : isPartKind(record.code) ? would.filter(open) : [first];
     if (claimed.length === 0) {
-      verdicts.push(record.bound !== "" && dials.allows(record.code) ? "dormant" : "stale");
+      verdicts.push(
+        record.bound !== "" && (dials.allows(record.code) || holds.holdsRecord(record))
+          ? "dormant"
+          : "stale",
+      );
       continue;
     }
     for (const finding of claimed) {
       taken.add(claimKey(finding));
     }
-    verdicts.push(claimed.every((finding) => dials.withholds(finding)) ? "dormant" : "in-effect");
+    verdicts.push(
+      claimed.every((finding) => dials.withholds(finding) || holds.withholds(finding))
+        ? "dormant"
+        : "in-effect",
+    );
   }
   return {
     verdicts,

package/src/test-support.ts

@@ -6,11 +6,11 @@
  * test code.
  */
 
-import { CONVENTION_ROWS, TEST_LIBRARIES, TEST_LIBRARY_SCOPES } from "./convention-rows.ts";
+import { CONVENTION_ROWS, TEST_LIBRARIES, TEST_LIBRARY_SCOPES } from "./entries/convention-rows.ts";
 import { packageOfSpecifier } from "./dependencies.ts";
 import type { InventorySymbol } from "./inventory.ts";
 import type { Reference } from "./references.ts";
-import type { Root } from "./roots.ts";
+import type { Root } from "./roots/root-set.ts";
 
 /** The root kind that never takes a file out of test-support code: the skip only withholds. */
 const SKIP_ROOT = "type-error";
@@ -20,7 +20,12 @@ const SKIP_ROOT = "type-error";
  * convention row reads test files for, and the convention table's test libraries.
  */
 const TEST_PACKAGES: ReadonlySet<string> = new Set([
-  ...CONVENTION_ROWS.filter((row) => row.testFiles !== undefined).map((row) => row.package),
+  ...CONVENTION_ROWS.filter(
+    (row) =>
+      row.testFiles !== undefined ||
+      row.testDirectories !== undefined ||
+      row.testRunner !== undefined,
+  ).map((row) => row.package),
   ...TEST_LIBRARIES,
 ]);
 

package/src/verbs/analyze.ts

@@ -9,10 +9,11 @@ import {
 import { kindOf } from "../config.ts";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
 import { analyzerProvenance, verdictOf } from "../findings-pass.ts";
+import { factsDocument } from "../facts.ts";
 import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
 import type { Host } from "../host.ts";
-import type { ManifestEntry } from "../manifest.ts";
-import type { HeldScripts } from "../roots.ts";
+import type { ManifestEntry } from "../roots/manifest.ts";
+import type { HeldScripts } from "../roots/root-set.ts";
 import { moduleIdentity, type NotBuilt } from "../load/discover.ts";
 import { partialNotes } from "../partial.ts";
 import {
@@ -29,7 +30,7 @@ import { RENDERINGS } from "../reporters/reporters.ts";
 import { parseTemplate, TemplateError, type Template } from "../reporters/template.ts";
 import { resolve } from "../resolve.ts";
 import { otherSchemeRows, rowReason, writeBaseline, type Recorded } from "../suppress-file.ts";
-import type { UnseenLoad } from "../unseen-loads.ts";
+import type { UnseenLoad } from "../roots/unseen-loads.ts";
 import type { UnreadInput } from "../load/plan.ts";
 import type { UnresolvedSpecifier } from "../load/specifiers.ts";
 
@@ -42,7 +43,7 @@ import { ownVersion } from "./version.ts";
 
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS: VerbOptions = {
-  plain: ["report", "baseline-write", "exit-code", "template"],
+  plain: ["report", "facts", "baseline-write", "exit-code", "template"],
   repeatable: ["format"],
 };
 
@@ -258,6 +259,7 @@ function templateOf(
 /** Every document one invocation asked for: the report, each rendering beside it, a baseline. */
 interface Documents {
   readonly report: string;
+  readonly facts: string | undefined;
   readonly formats: readonly Format[];
   readonly baseline: string | undefined;
 }
@@ -286,8 +288,13 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
   const { config, provenance } = resolve(inputs());
   const invoked = host.workingDirectory();
   const baseline = option("baseline-write");
+  const facts = option("facts");
+  if (facts === "") {
+    throw new UsageError("--facts names the path the facts document is written to, and named none");
+  }
   const documents: Documents = {
     report: resolvePath(invoked, reportPath),
+    facts: facts === undefined ? undefined : resolvePath(invoked, facts),
     formats: formatsOf(repeated("format"), config.reporters.formats),
     baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
   };
@@ -378,6 +385,12 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
     );
   }
   writeDocument(host, documents.report, "name a path the run can write", () => json(report));
+  const factsPath = documents.facts;
+  if (factsPath !== undefined) {
+    writeDocument(host, factsPath, "name a path the run can write", () => [
+      factsDocument(version, run.generated),
+    ]);
+  }
   const options = {
     readSource: (path: string) => host.readFile(joinPath(targetRoot, path)),
     template,

package/src/verbs/describe.ts

@@ -2,6 +2,7 @@ import {
   CONTRACT_VERSION,
   EXIT_CLEAN,
   EXIT_USAGE,
+  FACTS_VERSION,
   SCHEMA_VERSIONS,
 } from "../contract/contract.generated.ts";
 import { CONFORMANCE, type Conformance } from "../conformance.ts";
@@ -11,8 +12,9 @@ import { ownVersion } from "./version.ts";
 
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
- * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, a member the document omits where no run is recorded.
+ * report schema versions it reads, the languages it claims, the facts version it writes,
+ * and its recorded result over the conformance corpus, a member the document omits where
+ * no run is recorded.
  */
 export function describeDocument(version: string, recorded: Conformance | undefined): string {
   const document = {
@@ -21,6 +23,7 @@ export function describeDocument(version: string, recorded: Conformance | undefi
     contract_version: CONTRACT_VERSION,
     schema_versions_accepted: SCHEMA_VERSIONS,
     languages: [LANGUAGE],
+    facts_version_written: FACTS_VERSION,
     ...(recorded === undefined
       ? {}
       : {

package/src/verbs/explain.ts

@@ -11,7 +11,7 @@ import { resolvePath } from "../paths.ts";
 import { positionKey } from "../position.ts";
 import type { Reference } from "../references.ts";
 import { resolve } from "../resolve.ts";
-import type { Root } from "../roots.ts";
+import type { Root } from "../roots/root-set.ts";
 import { type Verb, type VerbOptions } from "./verb.ts";
 import { UsageError } from "../usage.ts";
 import { bytewise } from "../text/compare.ts";