@cplieger/deadset-ts 3.12.1 → 4.0.0

package/src/value-reach.ts

@@ -1,9 +1,11 @@
 /**
- * The classes of the target a value of one type carries, as a serializer walking the
- * value reaches them: through union and intersection constituents, array and tuple
- * elements, and the data members of the target's classes and of object types the
- * target writes. The walk stops at `any`, `unknown`, a type parameter, a function and
- * an interface or class of another program, so an instance held only there is missed.
+ * The classes of the target a value of one type carries, and the members of the other
+ * object types the target writes that it carries, as a serializer walking the value
+ * reaches them: through union and intersection constituents, array and tuple elements,
+ * and the data members and index signatures of the target's classes and of the
+ * interfaces and object types the target writes. The walk stops at `any`, `unknown`, a
+ * type parameter, a function and an interface or class of another program, so an
+ * instance held only there is missed.
  */
 
 import {
@@ -15,6 +17,7 @@ import {
 } from "@typescript/native/unstable/sync";
 import { classNames, typesAt } from "./class-members.ts";
 import type { Inventory } from "./inventory.ts";
+import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 
 /** The object types whose members the walk reads whatever declares them. */
@@ -23,19 +26,32 @@ const WRITTEN = ObjectFlags.ObjectLiteral | ObjectFlags.Mapped;
 /** The symbols of an anonymous object type the target writes as a type. */
 const LITERAL_SYMBOLS = SymbolFlags.TypeLiteral | SymbolFlags.ObjectLiteral;
 
-/** The classes a type's values carry, each asked of the checker once. */
+/** What a value of one type carries that the target declares. */
+export interface Reached {
+  /** The identifiers of the target's classes. */
+  readonly classes: ReadonlySet<string>;
+  /**
+   * The members of the interfaces and object types the target writes, other than its
+   * classes: each data member, and each method named `toJSON` or `toString`.
+   */
+  readonly members: readonly TSSymbol[];
+}
+
+/** What each type's values carry, each type asked of the checker once. */
 export interface ValueReach {
-  /** The identifiers of the target's classes a value of `type` carries. */
-  classesOf(type: Type): ReadonlySet<string>;
+  reachedFrom(type: Type): Reached;
 }
 
+/** The two conversion methods a serializer or a formatter resolves on a value's own shape. */
+const CONVERSION_NAMES: ReadonlySet<string> = new Set(["toJSON", "toString"]);
+
 /** The global array types, whose element type is what an array value carries. */
 function arrayTargets<Brand>(project: ProjectView<Brand>): ReadonlySet<number> {
-  const checker = project.checker;
+  const queries = project.queries;
   return new Set(
     ["Array", "ReadonlyArray"].flatMap((name) => {
-      const symbol = checker.resolveName(name, SymbolFlags.Type, undefined, false);
-      return symbol === undefined ? [] : [checker.getDeclaredTypeOfSymbol(symbol).id];
+      const symbol = must(queries.resolveName(name, SymbolFlags.Type, undefined, false));
+      return symbol === undefined ? [] : [must(queries.declaredTypeOf(symbol)).id];
     }),
   );
 }
@@ -45,7 +61,7 @@ function arrayTargets<Brand>(project: ProjectView<Brand>): ReadonlySet<number> {
  * project's inventory.
  */
 export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory): ValueReach {
-  const checker = project.checker;
+  const queries = project.queries;
   const names = [...classNames(project, held)];
   const declared = typesAt(
     project,
@@ -59,14 +75,12 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
     }
   });
   const arrays = arrayTargets(project);
-  const own = new Set(project.ownSourceFiles().map((file) => file.fileName));
+  const own = project.ownPaths();
   const children = new Map<number, readonly Type[]>();
 
   /** The generic target of a type reference, and the type itself otherwise. */
   const targetOf = (type: ObjectType): Type =>
-    (type.objectFlags & ObjectFlags.Reference) !== 0 && type.isTypeReference()
-      ? type.getTarget()
-      : type;
+    (type.objectFlags & ObjectFlags.Reference) !== 0 ? must(queries.targetOf(type)) : type;
 
   const classOf = (type: Type): string | undefined => {
     if (!type.isObjectType()) {
@@ -80,7 +94,7 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
     if ((type.objectFlags & WRITTEN) !== 0) {
       return true;
     }
-    const symbol: TSSymbol | undefined = type.getSymbol();
+    const symbol: TSSymbol | undefined = must(queries.symbolOfType(type));
     if (symbol === undefined) {
       return false;
     }
@@ -95,16 +109,37 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
 
   /** The types a value of one object type holds in its data members. */
   const memberTypes = (type: Type): readonly Type[] => {
-    const properties = checker
-      .getPropertiesOfType(type)
-      .filter((property) => (property.flags & SymbolFlags.Property) !== 0);
-    const types = properties.length === 0 ? [] : checker.getTypeOfSymbol(properties);
+    const properties = must(queries.propertiesOf(type)).filter(
+      (property) => (property.flags & SymbolFlags.Property) !== 0,
+    );
+    const types = queries.typesOfSymbols(properties).map(must);
     return [
       ...types.filter((held): held is Type => held !== undefined),
-      ...checker.getIndexInfosOfType(type).map((info) => info.valueType),
+      ...must(queries.indexInfosOf(type)).map((info) => info.valueType),
     ];
   };
 
+  /** Whether the walk reads one type's members because the target writes the type, not as a class. */
+  const writtenObject = (type: Type): boolean => {
+    if (!type.isObjectType() || classOf(type) !== undefined) {
+      return false;
+    }
+    const target = targetOf(type);
+    const isList =
+      type.isTypeReference() &&
+      (arrays.has(target.id) ||
+        (target.isObjectType() && (target.objectFlags & ObjectFlags.Tuple) !== 0));
+    return !isList && isWritten(type);
+  };
+
+  /** The data members and conversion methods of one written object type. */
+  const carried = (type: Type): readonly TSSymbol[] =>
+    must(queries.propertiesOf(type)).filter(
+      (property) =>
+        (property.flags & SymbolFlags.Property) !== 0 ||
+        ((property.flags & SymbolFlags.Method) !== 0 && CONVERSION_NAMES.has(property.name)),
+    );
+
   /** The types a value of one type holds, read once per type. */
   const childrenOf = (type: Type): readonly Type[] => {
     const known = children.get(type.id);
@@ -113,7 +148,7 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
     }
     let found: readonly Type[] = [];
     if (type.isUnionType() || type.isIntersectionType()) {
-      found = type.getTypes();
+      found = must(queries.constituents(type));
     } else if (type.isObjectType()) {
       const target = targetOf(type);
       const isList =
@@ -123,7 +158,7 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
       if (classOf(type) !== undefined || (!isList && isWritten(type))) {
         found = memberTypes(type);
       } else if (isList && type.isTypeReference()) {
-        found = checker.getTypeArguments(type);
+        found = must(queries.typeArguments(type));
       }
     }
     children.set(type.id, found);
@@ -131,8 +166,9 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
   };
 
   return {
-    classesOf: (type) => {
-      const found = new Set<string>();
+    reachedFrom: (type) => {
+      const classes = new Set<string>();
+      const members: TSSymbol[] = [];
       const seen = new Set<number>();
       const pending: Type[] = [type];
       for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
@@ -142,11 +178,13 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
         seen.add(next.id);
         const owner = classOf(next);
         if (owner !== undefined) {
-          found.add(owner);
+          classes.add(owner);
+        } else if (writtenObject(next)) {
+          members.push(...carried(next));
         }
         pending.push(...childrenOf(next));
       }
-      return found;
+      return { classes, members };
     },
   };
 }

package/src/verbs/analyze.ts

@@ -1,22 +1,25 @@
-import { runAnalysis, type RunProject } from "../analysis.ts";
+import { runAnalysis, runBaselineWrite, type RunAnalysis, type RunProject } from "../analysis.ts";
 import { ConfigError, type Format } from "../config.ts";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
 import { moduleIdentity } from "../consumers.ts";
-import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.ts";
+import { analyzerProvenance, verdictOf } from "../findings-pass.ts";
 import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
 import type { Host } from "../host.ts";
+import type { NotBuilt } from "../discover.ts";
+import { partialNotes } from "../partial.ts";
 import {
   buildReport,
   capFindings,
   sortFindings,
   type Report,
   type ReportConfiguration,
+  type ReportNotBuilt,
 } from "../report.ts";
 import { json } from "../reporters/json.ts";
 import { RENDERINGS } from "../reporters/reporters.ts";
 import { parseTemplate, TemplateError, type Template } from "../reporters/template.ts";
 import { resolve } from "../resolve.ts";
-import { writeBaseline, type Recorded } from "../suppress-file.ts";
+import { rowReason, writeBaseline, type Recorded } from "../suppress-file.ts";
 import { CONTRACT_VERSION } from "../version.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, type Verb, type VerbOptions } from "./verb.ts";
 
@@ -81,6 +84,19 @@ function runRelative(invoked: string, path: string): string {
   return below;
 }
 
+/** Each project the run dropped as a report names it, by its configuration file below the target. */
+function notBuiltOf(dropped: readonly NotBuilt[], targetRoot: string): readonly ReportNotBuilt[] {
+  return dropped.map((one) => {
+    const project = relativePath(targetRoot, one.configFile);
+    if (project === undefined) {
+      throw new ReportPathError(
+        `the project ${one.id} would be opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it`,
+      );
+    }
+    return { id: one.id, project, error: one.error };
+  });
+}
+
 /** Each project of the run as a report names it, by its configuration file below the target. */
 function configurationsOf(
   projects: readonly RunProject[],
@@ -153,8 +169,9 @@ interface Documents {
 /**
  * Analyzes the scope under the configuration and writes the JSON report to the path
  * `--report` names, each rendering `--format` names beside it at the report's path with the
- * format's suffix appended, and a baseline of every finding where `--baseline-write` names a
- * path. The template format renders the template `--template` names. Nothing is written to
+ * format's suffix appended, and where `--baseline-write` names a path the baseline a fixpoint
+ * over the analysis records, the report then being its first round, which reads no
+ * baseline. The template format renders the template `--template` names. Nothing is written to
  * the output stream; diagnostics go to the error stream and the verdict is the exit code, or 0
  * under `--exit-code=off`, and a rendering that cannot be written ends the run with 3.
  */
@@ -202,11 +219,30 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
   let report: Report;
   let recorded: readonly Recorded[];
   let verdict: number;
+  let partial: readonly string[];
   try {
     const root = runRelative(invoked, targetRoot);
-    const { result, run } = runAnalysis(openClient(false), host, scoped, config, provenance, {
-      production: true,
-    });
+    const mode = { production: true };
+    let analysis: RunAnalysis;
+    if (documents.baseline === undefined) {
+      analysis = runAnalysis(openClient(false), host, scoped, config, provenance, mode);
+      recorded = [];
+    } else {
+      const reason = rowReason(analyzerProvenance(version));
+      const write = runBaselineWrite(
+        openClient(false),
+        host,
+        scoped,
+        config,
+        provenance,
+        mode,
+        reason,
+      );
+      analysis = write.first;
+      recorded = write.rows;
+    }
+    const { result, run } = analysis;
+    partial = partialNotes({ notBuilt: run.notBuilt, unanswered: run.unanswered });
     const built = buildReport({
       contractVersion: CONTRACT_VERSION,
       version,
@@ -214,6 +250,7 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
       declaredGaps: DECLARED_GAPS,
       target: { kind, root, identity: moduleIdentity(host, scoped.target) },
       configurations: configurationsOf(run.projects, targetRoot),
+      notBuilt: notBuiltOf(run.notBuilt, targetRoot),
       loaded: run.consumers.map((consumer) => ({
         id: consumer.id,
         path: runRelative(invoked, consumer.path),
@@ -222,9 +259,6 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
       result,
       testFileRules: run.testFileRules,
     });
-    // The baseline records every finding, so its rows are taken before the cap bounds what
-    // a rendering prints: a baseline missing a reported finding fails the next run on it.
-    recorded = recordedFindings(result);
     report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
     verdict = verdictOf(result, config);
   } catch (error: unknown) {
@@ -236,7 +270,7 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
   }
 
   try {
-    host.writeFile(documents.report, json(report));
+    host.writeDocument(documents.report, json(report));
     const options = {
       failOn: config.reporters.failOn,
       readSource: (path: string) => host.readFile(joinPath(targetRoot, path)),
@@ -245,17 +279,20 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
     for (const format of documents.formats) {
       const rendering = RENDERINGS.get(format);
       if (rendering !== undefined) {
-        host.writeFile(documents.report + rendering.suffix, rendering.render(report, options));
+        host.writeDocument(documents.report + rendering.suffix, rendering.render(report, options));
       }
     }
     if (documents.baseline !== undefined) {
-      host.writeFile(documents.baseline, writeBaseline(recorded, analyzerProvenance(version)));
+      host.writeDocument(documents.baseline, writeBaseline(recorded, analyzerProvenance(version)));
     }
   } catch (error: unknown) {
     err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
     return EXIT_FAILURE;
   }
 
+  for (const note of partial) {
+    err.write(`deadset-ts: ${note}\n`);
+  }
   if (report.totals.pending > 0) {
     err.write(
       `deadset-ts: ${counted(report.totals.pending, "pending finding")}: the report names a declared cross-language edge, and no merge has resolved it\n`,

package/src/verbs/describe.ts

@@ -1,25 +1,29 @@
 import { CONFORMANCE, type Conformance } from "../conformance.ts";
-import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.ts";
+import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSIONS_ACCEPTED } from "../report.ts";
 import { CONTRACT_VERSION } from "../version.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.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.
+ * the conformance corpus, a member the document omits where no run is recorded.
  */
-export function describeDocument(version: string, recorded: Conformance): string {
+export function describeDocument(version: string, recorded: Conformance | undefined): string {
   const document = {
     name: ANALYZER_NAME,
     version,
     contract_version: CONTRACT_VERSION,
-    schema_versions_accepted: [SCHEMA_VERSION],
+    schema_versions_accepted: SCHEMA_VERSIONS_ACCEPTED,
     languages: [LANGUAGE],
-    conformance: {
-      corpus_version: recorded.corpusVersion,
-      result: recorded.result,
-      digest: recorded.digest,
-    },
+    ...(recorded === undefined
+      ? {}
+      : {
+          conformance: {
+            corpus_version: recorded.corpusVersion,
+            result: recorded.result,
+            digest: recorded.digest,
+          },
+        }),
   };
   return `${JSON.stringify(document, null, 2)}\n`;
 }

package/src/verbs/explain.ts

@@ -6,6 +6,7 @@ import type { CompletedFinding } from "../finding.ts";
 import { OUTSIDE, swept as judged } from "../graph.ts";
 import type { InventorySymbol } from "../inventory.ts";
 import { referenceKey, type Configured } from "../matrix.ts";
+import { partialNotes } from "../partial.ts";
 import { positionKey } from "../position.ts";
 import type { Reference } from "../references.ts";
 import { resolve } from "../resolve.ts";
@@ -344,6 +345,9 @@ function explanation(analysis: RunAnalysis, subject: InventorySymbol, cascade: C
     for (const one of retained) {
       text += `  class: ${one.class}\t${positionKey(one.site)}\t${one.detail}\n`;
     }
+  } else if (analysis.swept.heldByUnanswered.includes(subject.id)) {
+    text +=
+      "answer: held\n  held by: a question the checker did not answer, which could have kept it live, so no finding names it\n";
   } else {
     text += liveness(analysis, subject, cascade);
   }
@@ -351,12 +355,12 @@ function explanation(analysis: RunAnalysis, subject: InventorySymbol, cascade: C
 }
 
 /**
- * Explains one symbol from the analysis the report is built from, so an explanation cannot
- * disagree with a finding: why a reported symbol is reported, which exemption classes held a
- * retained one back, and for any other declaration the relations that hold it live and the
- * shortest path of references from a root or a loaded consumer, or the references it has where
- * no path reaches it. A request naming no one declaration exits with the usage code and names
- * what partially matches it.
+ * Explains one symbol from the analysis the report is built from: why a reported symbol is
+ * reported, which exemption classes held a retained one back, that an unanswered question held
+ * a held one, and for any other declaration the relations that hold it live and the shortest
+ * path from a root or a loaded consumer, or the references it has where no path reaches it. A
+ * request naming no one declaration exits with the usage code and names what partially
+ * matches it. Where the analysis was partial, the error stream says so.
  */
 export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, option }) => {
   const named = namedSymbol(option);
@@ -365,6 +369,10 @@ export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, o
     production: true,
   });
   const { subject, candidates } = subjectOf(analysis.swept.matrix.union.symbols, named);
+  const notes = partialNotes({
+    notBuilt: analysis.run.notBuilt,
+    unanswered: analysis.run.unanswered,
+  });
   if (subject === undefined) {
     err.write(`deadset-ts: ${JSON.stringify(named)} names no one symbol of the target\n`);
     for (const candidate of candidates) {
@@ -373,8 +381,11 @@ export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, o
     if (candidates.length === 0) {
       err.write("  no symbol of the target partially matches it either\n");
     }
-    return EXIT_USAGE;
+  } else {
+    out.write(explanation(analysis, subject, config.reporters.cascade));
+  }
+  for (const note of notes) {
+    err.write(`deadset-ts: ${note}\n`);
   }
-  out.write(explanation(analysis, subject, config.reporters.cascade));
-  return EXIT_CLEAN;
+  return subject === undefined ? EXIT_USAGE : EXIT_CLEAN;
 };

package/src/verbs/print-projects.ts

@@ -1,4 +1,14 @@
-import { diagnosticErrors, discoverProjects, renderDiagnostic } from "../discover.ts";
+import {
+  discoverProjects,
+  DiscoveryError,
+  isGuess,
+  projectErrors,
+  renderDiagnostic,
+  targetRelative,
+  type NotBuilt,
+} from "../discover.ts";
+import { partialNotes } from "../partial.ts";
+import { relativePath, resolvePath } from "../paths.ts";
 import { resolveMatrix } from "../resolve.ts";
 import { diagnosticsOf, runSession } from "../session.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, type Verb } from "./verb.ts";
@@ -7,7 +17,8 @@ import { EXIT_CLEAN, EXIT_FAILURE, type Verb } from "./verb.ts";
  * Writes the name of every project one run analyzes, one per line, having read each
  * project's diagnostics first: the identifier the build matrix declares for it, or,
  * where discovery derived the project, its configuration file's path below the
- * target root.
+ * target root. A derived project that does not load is not one the run analyzes, so it
+ * is named on the error stream instead, as the analysis drops it.
  */
 export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
   const matrix = resolveMatrix(inputs());
@@ -15,12 +26,36 @@ export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openCli
   const engine = openClient(false);
   const discovered = discoverProjects(engine, host, scoped, matrix);
   const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+  const root = resolvePath(host.workingDirectory(), scoped.target.path);
+  const notBuilt: NotBuilt[] = [...discovered.notBuilt];
   const failures: string[] = [];
-  const { projects } = runSession(engine, discovered.configFiles, (project) => {
-    const errors = diagnosticErrors(diagnosticsOf(project));
-    failures.push(...errors.map(renderDiagnostic));
-    return ids.get(project.configFile) ?? project.configFile;
-  });
+  const session = runSession(
+    engine,
+    discovered.configFiles,
+    (project) => {
+      const id = ids.get(project.configFile) ?? project.configFile;
+      const errors = projectErrors(diagnosticsOf(project));
+      const [unloaded] = errors.load;
+      if (unloaded !== undefined && isGuess(discovered, project.configFile)) {
+        const error = renderDiagnostic(unloaded, (path) => relativePath(root, path) ?? path);
+        notBuilt.push({ id, configFile: project.configFile, error: targetRelative(error, root) });
+        return undefined;
+      }
+      failures.push(...[...errors.load, ...errors.check].map((one) => renderDiagnostic(one)));
+      return id;
+    },
+    discovered.derived ? "record" : "refuse",
+  );
+  for (const configFile of session.unopened) {
+    if (!isGuess(discovered, configFile)) {
+      throw new DiscoveryError(`${configFile} opened no project`, []);
+    }
+    notBuilt.push({
+      id: ids.get(configFile) ?? configFile,
+      configFile,
+      error: "the compiler opened no project for the configuration",
+    });
+  }
   if (failures.length > 0) {
     for (const line of failures) {
       err.write(`${line}\n`);
@@ -28,8 +63,19 @@ export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openCli
     err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
     return EXIT_FAILURE;
   }
+  const projects = session.projects.filter((id): id is string => id !== undefined);
+  if (projects.length === 0 && notBuilt.length > 0) {
+    for (const note of partialNotes({ notBuilt, unanswered: [] })) {
+      err.write(`deadset-ts: ${note}\n`);
+    }
+    err.write("deadset-ts: no configuration discovery derived could be built\n");
+    return EXIT_FAILURE;
+  }
   for (const id of projects) {
     out.write(`${id}\n`);
   }
+  for (const note of partialNotes({ notBuilt, unanswered: [] })) {
+    err.write(`deadset-ts: ${note}\n`);
+  }
   return EXIT_CLEAN;
 };

package/src/verbs/print-retained.ts

@@ -1,5 +1,6 @@
 import { runSweep } from "../analysis.ts";
 import { retainedLines } from "../exempt.ts";
+import { partialNotes } from "../partial.ts";
 import { resolve } from "../resolve.ts";
 import { EXIT_CLEAN, type Verb } from "./verb.ts";
 
@@ -8,9 +9,9 @@ import { EXIT_CLEAN, type Verb } from "./verb.ts";
  * built from, one per line, and nothing where no exemption held one back. One fact
  * several configurations found is one record, so the line names no configuration. The
  * line shape is this command's own rather than a Contract format, so that sort and cut
- * read it.
+ * read it. Where the analysis was partial, the error stream says so.
  */
-export const printRetainedVerb: Verb = ({ out, host, inputs, scope, openClient }) => {
+export const printRetainedVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
   const { config } = resolve(inputs());
   const scoped = scope();
   const swept = runSweep(openClient(false), host, scoped, config, {
@@ -20,5 +21,8 @@ export const printRetainedVerb: Verb = ({ out, host, inputs, scope, openClient }
   for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
     out.write(`${line}\n`);
   }
+  for (const note of partialNotes({ notBuilt: swept.notBuilt, unanswered: swept.unanswered })) {
+    err.write(`deadset-ts: ${note}\n`);
+  }
   return EXIT_CLEAN;
 };

package/src/verbs/print-roots.ts

@@ -1,4 +1,5 @@
 import { runRoots, type RunRoot } from "../analysis.ts";
+import { partialNotes } from "../partial.ts";
 import { resolve } from "../resolve.ts";
 import { EXIT_CLEAN, EXIT_FINDINGS, type Verb } from "./verb.ts";
 
@@ -20,7 +21,7 @@ function rootLine(root: RunRoot, several: boolean): string {
 /**
  * Writes the root set of the run, one root per line, and then names on the error
  * stream, by its issue kind, every configured root or pattern that named nothing;
- * one such string fails the run. The line shape is this command's own rather than a
+ * one such string fails the run, and then where the analysis was partial. The line shape is this command's own rather than a
  * Contract format, so that sort and cut read it.
  */
 export const printRootsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
@@ -34,5 +35,8 @@ export const printRootsVerb: Verb = ({ out, err, host, inputs, scope, openClient
   for (const finding of answer.findings) {
     err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
   }
+  for (const note of partialNotes({ notBuilt: answer.notBuilt, unanswered: answer.unanswered })) {
+    err.write(`deadset-ts: ${note}\n`);
+  }
   return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
 };

package/src/version.ts

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "3.2.0";
+export const CONTRACT_VERSION = "4.0.0";