@cplieger/deadset-ts 3.10.0 → 3.12.0

package/src/analysis.ts

@@ -10,6 +10,12 @@
 
 import type { Diagnostic } from "@typescript/native/unstable/sync";
 import type { Config, Provenance } from "./config.ts";
+import {
+  consumerLoads,
+  consumerReferences,
+  moduleIdentity,
+  type LoadedConsumer,
+} from "./consumers.ts";
 import { decorator } from "./decorator.ts";
 import { dependenciesOf, projectNeeds } from "./dependencies.ts";
 import { deprecatedDeclarations } from "./deprecation.ts";
@@ -41,11 +47,18 @@ import { injectionContainer } from "./injection-container.ts";
 import { interfaceSatisfaction } from "./interface-satisfaction.ts";
 import { inventory, type Inventory } from "./inventory.ts";
 import { readManifest } from "./manifest.ts";
-import { matrixOf, sweepMatrix, type Configured, type Matrix, type SweepResult } from "./matrix.ts";
+import {
+  matrixOf,
+  referenceKey,
+  sweepMatrix,
+  type Configured,
+  type Matrix,
+  type SweepResult,
+} from "./matrix.ts";
 import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition, type Position } from "./position.ts";
 import { reflectiveLookup } from "./reflective-lookup.ts";
-import { references, testFileRulesOf, type TestFileRule } from "./references.ts";
+import { references, testFileRulesOf, type Reference, type TestFileRule } from "./references.ts";
 import { roots, unmatchedEverywhere, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { serializationContract } from "./serialization-contract.ts";
@@ -125,11 +138,27 @@ interface ProjectRead {
   readonly rooted: Roots;
 }
 
+/** What a run read of the consumers its scope declares. */
+interface ConsumerReads {
+  /** Every declared consumer, each loaded, in the scope's order. */
+  readonly loaded: readonly LoadedConsumer[];
+  /** Every reference a consumer makes to a declaration of the target, each once. */
+  readonly references: readonly Reference[];
+}
+
+/** What a run read of its projects: each target project's answer, and its consumers. */
+interface ReadProjects<Answer> {
+  readonly answers: readonly Answer[];
+  readonly consumers: ConsumerReads;
+}
+
 /**
- * Reads every project the scope discovers, in one snapshot: each is checked for errors
- * first, then enumerated, then rooted, and `stage` reads the rest of what it needs from
- * the project while its view is open. A project carrying an error fails the run with no
- * answer, as every verb that reads declarations does.
+ * Reads every project the scope discovers, and every project of every consumer it
+ * declares, in one snapshot. Each is checked for errors first. A target project is then
+ * enumerated and rooted, and `stage` reads the rest of what it needs from the project
+ * while its view is open; a consumer project is read for its references to the target's
+ * declarations. A project carrying an error fails the run with no answer, as every verb
+ * that reads declarations does, and so does a declared consumer that cannot be loaded.
  */
 function readProjects<Answer>(
   engine: Engine,
@@ -137,10 +166,16 @@ function readProjects<Answer>(
   scope: Scope,
   config: Config,
   stage: <Brand>(project: ProjectView<Brand>, read: ProjectRead) => Answer,
-): readonly Answer[] {
+): ReadProjects<Answer> {
   const targetRoot = scope.target.path;
   const discovered = discoverProjects(engine, host, scope, config.analysis.configurations);
   const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+  const loads = consumerLoads(engine, host, scope, discovered.configFiles);
+  const consumerOf = new Map(
+    loads.flatMap((load) =>
+      load.configFiles.map((configFile) => [configFile, load.consumer] as const),
+    ),
+  );
   const options = {
     manifest: readManifest(host, targetRoot),
     patterns: config.rootPatterns,
@@ -149,24 +184,51 @@ function readProjects<Answer>(
     publishedAPI: config.targetKind === "library",
   };
   const failures: Diagnostic[] = [];
-  const { projects } = runSession(engine, discovered.configFiles, (project) => {
-    const errors = diagnosticErrors(diagnosticsOf(project));
-    if (errors.length > 0) {
-      failures.push(...errors);
-      return undefined;
-    }
-    const held = inventory(project, host, targetRoot);
-    const rooted = roots(project, held, targetRoot, options);
-    const configuration = ids.get(project.configFile) ?? project.configFile;
-    return stage(project, { configuration, configFile: project.configFile, held, rooted });
-  });
+  const consumed = new Map<string, Reference>();
+  const { projects } = runSession(
+    engine,
+    [...discovered.configFiles, ...consumerOf.keys()],
+    (project) => {
+      const errors = diagnosticErrors(diagnosticsOf(project));
+      if (errors.length > 0) {
+        failures.push(...errors);
+        return undefined;
+      }
+      const consumer = consumerOf.get(project.configFile);
+      if (consumer !== undefined) {
+        for (const reference of consumerReferences(
+          project,
+          host,
+          targetRoot,
+          {
+            id: consumer.id,
+            root: consumer.path,
+          },
+          config,
+        )) {
+          consumed.set(referenceKey(reference), reference);
+        }
+        return undefined;
+      }
+      const held = inventory(project, host, targetRoot);
+      const rooted = roots(project, held, targetRoot, options);
+      const configuration = ids.get(project.configFile) ?? project.configFile;
+      return stage(project, { configuration, configFile: project.configFile, held, rooted });
+    },
+  );
   if (failures.length > 0) {
     throw new DiscoveryError(
       `${String(failures.length)} error(s); no answer was produced`,
       failures,
     );
   }
-  return projects.filter((answer): answer is Answer => answer !== undefined);
+  return {
+    answers: projects.filter((answer): answer is Answer => answer !== undefined),
+    consumers: {
+      loaded: loads.map((load) => load.consumer),
+      references: [...consumed.values()],
+    },
+  };
 }
 
 /**
@@ -183,7 +245,7 @@ export function runRoots(
   provenance: Provenance,
 ): RunRoots {
   const targetRoot = scope.target.path;
-  const projects = readProjects(engine, host, scope, config, (_project, read) => read);
+  const projects = readProjects(engine, host, scope, config, (_project, read) => read).answers;
 
   const configurations: string[] = [];
   const merged = new Map<string, Omit<RunRoot, "configurations"> & { configurations: string[] }>();
@@ -266,12 +328,15 @@ interface ReadRun<Extra> {
   readonly matrix: Matrix;
   readonly exempt: readonly Exemption[];
   readonly projects: readonly SweptProject<Extra>[];
+  /** Every declared consumer, each loaded, in the scope's order. */
+  readonly consumers: readonly LoadedConsumer[];
 }
 
 /**
  * Reads every project of the run, its references and exemptions, and `extra`'s answer,
  * while the project's view is open, and merges the projects into one matrix in the run's
- * order.
+ * order. Every configuration holds every consumer's references beside its own, because a
+ * consumer calls the target whichever configuration the target is built under.
  */
 function readRun<Extra>(
   engine: Engine,
@@ -288,7 +353,7 @@ function readRun<Extra>(
     ? { delimiters: config.analysis.templateDelimiters, files: [] }
     : readTemplates(host, targetRoot, config.analysis);
   const consumers = scope.consumers.map((consumer) => consumer.path);
-  const projects = readProjects(engine, host, scope, config, (project, projectRead) => {
+  const read = readProjects(engine, host, scope, config, (project, projectRead) => {
     const resolved = references(project, projectRead.held, targetRoot, {
       testFiles: config.ts.testFiles,
     });
@@ -315,10 +380,23 @@ function readRun<Extra>(
       extra: extra(project, projectRead),
     };
   });
+  const consumed = read.consumers.references;
+  const projects = read.answers.map((one) =>
+    consumed.length === 0
+      ? one
+      : {
+          ...one,
+          configured: {
+            ...one.configured,
+            references: [...one.configured.references, ...consumed],
+          },
+        },
+  );
   return {
     matrix: matrixOf(projects.map((one) => one.configured)),
     exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
     projects,
+    consumers: read.consumers.loaded,
   };
 }
 
@@ -430,7 +508,10 @@ function emitterInputOver(
       heldByInclusion: new Set(projects.flatMap((one) => one.extra.heldByInclusion)),
     },
     boundary: {
-      consumers: { declared: scope.consumers.map((consumer) => consumer.id), loaded: [] },
+      consumers: {
+        declared: scope.consumers.map((consumer) => moduleIdentity(host, consumer)),
+        loaded: read.consumers.map((consumer) => consumer.id),
+      },
       encapsulated: readManifest(host, targetRoot).declaresExports,
       edges: readEdgeSides(host, targetRoot),
     },
@@ -442,8 +523,8 @@ function emitterInputOver(
  * What every emitter reads of the run the scope and the configuration describe, swept
  * under the caller's marks: the run's sweep, the facts beside it each kind family reads,
  * and the sides of the target's declared cross-language edges that name a symbol of this
- * language. The run loads no consumer, and it reads no suppression document, so the
- * self-check family has nothing to report.
+ * language. The run reads no suppression document, so the self-check family has nothing
+ * to report.
  */
 export function runEmitterInput(
   engine: Engine,
@@ -483,7 +564,11 @@ function runAnalysisInputs(
   provenance: Provenance,
   mode: Mode,
   detectors: Detectors,
-): { readonly inputs: AnalysisInputs; readonly run: RunFacts } {
+): {
+  readonly inputs: AnalysisInputs;
+  readonly run: RunFacts;
+  readonly configured: readonly Configured[];
+} {
   const targetRoot = scope.target.path;
   const read = readEmitterRun(engine, host, scope, config, mode, detectors);
   const symbols = read.matrix.union.symbols;
@@ -522,7 +607,9 @@ function runAnalysisInputs(
         config.ts.testFiles,
         read.projects.flatMap((one) => one.configured.testFiles),
       ),
+      consumers: read.consumers,
     },
+    configured: read.projects.map((one) => one.configured),
   };
 }
 
@@ -539,18 +626,25 @@ export interface RunFacts {
   readonly projects: readonly RunProject[];
   /** The rules that classified files as test files, each counted over every project at once. */
   readonly testFileRules: readonly TestFileRule[];
+  /** Every consumer the run loaded beside the target, in the scope's order. */
+  readonly consumers: readonly LoadedConsumer[];
 }
 
 /** The findings of one run, beside what a report states about the run itself. */
 export interface RunAnalysis {
   readonly result: PassResult;
   readonly run: RunFacts;
+  /** The sweep the findings were decided over, under the mark of every bound record. */
+  readonly swept: RunSweep;
+  /** What each project answered, in the run's order, which the sweep was built from. */
+  readonly configured: readonly Configured[];
 }
 
 /**
  * The analysis of the run the scope and the configuration describe: the run read with its
  * suppressions bound, every family's findings with the suppressions applied and the
- * declared edges evaluated, and the projects and test-file rules the report names.
+ * declared edges evaluated, the projects and test-file rules the report names, and the sweep
+ * an explanation reads.
  */
 export function runAnalysis(
   engine: Engine,
@@ -561,7 +655,7 @@ export function runAnalysis(
   mode: Mode,
   detectors: Detectors = DETECTORS,
 ): RunAnalysis {
-  const { inputs, run } = runAnalysisInputs(
+  const { inputs, run, configured } = runAnalysisInputs(
     engine,
     host,
     scope,
@@ -570,5 +664,5 @@ export function runAnalysis(
     mode,
     detectors,
   );
-  return { result: findingsPass(inputs), run };
+  return { result: findingsPass(inputs), run, swept: inputs.marked.swept, configured };
 }

package/src/config.ts

@@ -28,6 +28,14 @@ export type Language = "go" | "ts";
 /** What a finding of one issue kind does to a run. */
 export type Severity = "allow" | "warn" | "deny";
 
+/** The severities ranked, the strongest highest. */
+const SEVERITY_RANK: Readonly<Record<Severity, number>> = { allow: 0, warn: 1, deny: 2 };
+
+/** Whether a finding at one severity fails a run under the failing severity. */
+export function fails(severity: Severity, failOn: Severity): boolean {
+  return SEVERITY_RANK[severity] >= SEVERITY_RANK[failOn];
+}
+
 /** One rendering of the finding list. */
 export type Format = "text" | "json" | "github" | "sarif" | "template";
 

package/src/conformance-record.ts

@@ -3,8 +3,8 @@
 export const RECORD = {
   conformance: {
     corpusVersion: "1.9.0",
-    result: "fail",
-    digest: "sha256:8c29f19fc189f4f5d9ea210d556b62d12c3701c221eb7a8adde499b7060bec0d",
+    result: "pass",
+    digest: "sha256:3e9e40876551faa2c196311bf06d47d220ab5127a9fb8921969aae552c42e824",
   },
   gaps: [
     {
@@ -13,17 +13,5 @@ export const RECORD = {
       reason:
         "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
     },
-    {
-      fixture: "redundant-export-keyword",
-      capability: "DS1104",
-      reason:
-        "No consumer is loaded beside the target, so the published surface is unknown and no export is narrowed; review an export only the target uses by hand.",
-    },
-    {
-      fixture: "unused-exported-consumer",
-      capability: "DS1001",
-      reason:
-        "No consumer is loaded beside the target, so an export nothing in the target references is reported at the possible class rather than the certain one.",
-    },
   ],
 } as const;

package/src/consumers.ts

@@ -0,0 +1,86 @@
+/**
+ * The consumers a scope declares, loaded beside the target: each a directory on the
+ * local filesystem whose compiler configurations open as projects of the run's one
+ * snapshot, and whose references to the target's declarations count against them.
+ */
+
+import type { Config } from "./config.ts";
+import { consumerProjects } from "./discover.ts";
+import type { Host } from "./host.ts";
+import { inventory, packageScope } from "./inventory.ts";
+import { relativePath } from "./paths.ts";
+import { references, type ConsumerSide, type Reference } from "./references.ts";
+import type { Module, Scope } from "./scope.ts";
+import { narrowedTo, type Engine, type ProjectView } from "./session.ts";
+
+/** One consumer the run loaded. */
+export interface LoadedConsumer {
+  /** The name the consumer publishes itself under, which every finding names it by. */
+  readonly id: string;
+  /** The consumer's directory, absolute. */
+  readonly path: string;
+}
+
+/** One declared consumer and the compiler configurations it opens as. */
+interface ConsumerLoad {
+  readonly consumer: LoadedConsumer;
+  /** The configuration files, absolute, in discovery order, none a target project's. */
+  readonly configFiles: readonly string[];
+}
+
+/** The name one module publishes itself under: the scope's, else its manifest's. */
+export function moduleIdentity(host: Host, module: Module): string {
+  return module.id === "" ? packageScope(host, module.path)("index.ts").package : module.id;
+}
+
+/**
+ * Every consumer the scope declares, in its order, with the projects it opens as. A
+ * configuration that is also one of the target's projects, or an earlier consumer's, is
+ * that project's alone. A consumer whose directory is absent, is no directory or holds
+ * no configuration ends the run naming it, before any project opens.
+ */
+export function consumerLoads(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  targetConfigFiles: readonly string[],
+): readonly ConsumerLoad[] {
+  const opened = new Set(targetConfigFiles);
+  return scope.consumers.map((module) => {
+    const configFiles = consumerProjects(engine, host, module.path).filter((configFile) => {
+      const fresh = !opened.has(configFile);
+      opened.add(configFile);
+      return fresh;
+    });
+    return { consumer: { id: moduleIdentity(host, module), path: module.path }, configFiles };
+  });
+}
+
+/**
+ * Every reference one consumer project's own files make to a declaration of the target.
+ * The target's declarations are enumerated over the target's files the consumer's
+ * program holds, against the target root, so each carries the identifier the target's
+ * own projects give it. A reference from a consumer's test file is a test reference
+ * unless the configuration counts it as a production one.
+ */
+export function consumerReferences<Brand>(
+  project: ProjectView<Brand>,
+  host: Host,
+  targetRoot: string,
+  consumer: ConsumerSide,
+  config: Config,
+): readonly Reference[] {
+  const held = inventory(
+    narrowedTo(project, (file) => relativePath(targetRoot, file.fileName) !== undefined),
+    host,
+    targetRoot,
+  );
+  const found = references(project, held, targetRoot, {
+    testFiles: config.ts.testFiles,
+    consumer,
+  }).references;
+  if (config.analysis.consumerTests !== "production") {
+    return found;
+  }
+  return found.map((reference) => (reference.test ? { ...reference, test: false } : reference));
+}

package/src/discover.ts

@@ -160,17 +160,70 @@ function referencesOf(host: Host, configFile: string): string[] {
 }
 
 /**
- * The configuration files the scope names directly: one per module the scope
- * declares whose path names a configuration file rather than a directory. A module
- * naming a directory is reached by the walk over that directory instead.
+ * The configuration file the scope names for the target directly, where its path
+ * names one rather than a directory. A target naming a directory is reached by the
+ * walk over that directory instead. A consumer's projects are a consumer's, never the
+ * target's, so no consumer path is read here.
  */
 function scopeConfigFiles(host: Host, scope: Scope): string[] {
-  return [scope.target, ...scope.consumers]
-    .map((module) => module.path)
+  return [scope.target.path]
     .filter((path) => path.endsWith(".json"))
     .map((path) => resolvePath(host.workingDirectory(), path));
 }
 
+/**
+ * Every configuration file reached from `pending`, in the order discovery reads them:
+ * each once, each followed by the configurations it references, transitively. A
+ * configuration the compiler cannot read ends the run naming it.
+ */
+function derivedFrom(engine: Engine, host: Host, pending: string[]): string[] {
+  const seen = new Set<string>();
+  const found: string[] = [];
+  while (pending.length > 0) {
+    const configFile = pending.shift();
+    if (configFile === undefined) {
+      break;
+    }
+    const path = resolvePath(host.workingDirectory(), configFile);
+    if (seen.has(path)) {
+      continue;
+    }
+    seen.add(path);
+    parseOrRefuse(engine, path, path);
+    found.push(path);
+    pending.push(...referencesOf(host, path));
+  }
+  return found;
+}
+
+/**
+ * The compiler configurations one consumer is loaded through: every one under its
+ * root that is not inside an ignored directory, and the configurations each of those
+ * references, transitively, in that order. A root that is absent, that is no
+ * directory, or that holds no configuration ends the run naming it, because a
+ * finding computed without a declared consumer would claim a reference set the run
+ * never read.
+ */
+export function consumerProjects(engine: Engine, host: Host, root: string): readonly string[] {
+  const kind = host.kindOf(root);
+  if (kind !== "directory") {
+    throw new DiscoveryError(
+      kind === "absent"
+        ? `the consumer ${root} does not exist`
+        : `the consumer ${root} is not a directory`,
+      [],
+    );
+  }
+  const found = derivedFrom(engine, host, configFilesUnder(host, root));
+  if (found.length === 0) {
+    throw new DiscoveryError(
+      `the consumer ${root} holds no compiler configuration, so none of its references can be read`,
+      [],
+    );
+  }
+  return found;
+}
+
 /**
  * The name a derived project carries: its configuration file's path below the target
  * root, or the absolute path of a file outside it.
@@ -257,24 +310,15 @@ function declaredProjects(
  */
 function derivedProjects(engine: Engine, host: Host, scope: Scope): Discovery {
   const fromScope = scopeConfigFiles(host, scope);
-  const seen = new Set<string>();
-  const projects: DiscoveredProject[] = [];
-  const pending = [...fromScope, ...configFilesUnder(host, scope.target.path)];
-  while (pending.length > 0) {
-    const configFile = pending.shift();
-    if (configFile === undefined) {
-      break;
-    }
-    const path = resolvePath(host.workingDirectory(), configFile);
-    if (seen.has(path)) {
-      continue;
-    }
-    seen.add(path);
-    parseOrRefuse(engine, path, path);
-    projects.push({ id: derivedId(scope.target.path, path), configFile: path });
-    pending.push(...referencesOf(host, path));
-  }
-  return { projects, configFiles: projects.map((project) => project.configFile), fromScope };
+  const configFiles = derivedFrom(engine, host, [
+    ...fromScope,
+    ...configFilesUnder(host, scope.target.path),
+  ]);
+  const projects = configFiles.map((configFile) => ({
+    id: derivedId(scope.target.path, configFile),
+    configFile,
+  }));
+  return { projects, configFiles, fromScope };
 }
 
 /**