@cplieger/deadset-ts 3.13.0 → 4.0.0

package/src/value-reach.ts

@@ -17,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. */
@@ -46,11 +47,11 @@ 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];
     }),
   );
 }
@@ -60,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,
@@ -74,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()) {
@@ -95,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;
     }
@@ -110,13 +109,13 @@ 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),
     ];
   };
 
@@ -135,13 +134,11 @@ export function valueReach<Brand>(project: ProjectView<Brand>, held: Inventory):
 
   /** The data members and conversion methods of one written object type. */
   const carried = (type: Type): readonly TSSymbol[] =>
-    checker
-      .getPropertiesOfType(type)
-      .filter(
-        (property) =>
-          (property.flags & SymbolFlags.Property) !== 0 ||
-          ((property.flags & SymbolFlags.Method) !== 0 && CONVERSION_NAMES.has(property.name)),
-      );
+    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[] => {
@@ -151,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 =
@@ -161,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);

package/src/verbs/analyze.ts

@@ -5,12 +5,15 @@ import { moduleIdentity } from "../consumers.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";
@@ -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[],
@@ -203,6 +219,7 @@ 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 mode = { production: true };
@@ -225,6 +242,7 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
       recorded = write.rows;
     }
     const { result, run } = analysis;
+    partial = partialNotes({ notBuilt: run.notBuilt, unanswered: run.unanswered });
     const built = buildReport({
       contractVersion: CONTRACT_VERSION,
       version,
@@ -232,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),
@@ -251,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)),
@@ -260,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/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;
 };