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

package/src/{workflow-steps.ts → entries/workflow-steps.ts}

@@ -6,13 +6,13 @@
  */
 
 import type { SourceFile } from "@typescript/native/ast";
-import { pathsNamed, readCommands } from "./commands/read.ts";
-import type { Host } from "./host.ts";
-import { isRecord } from "./json-document.ts";
-import { joinPath, resolvePath } from "./paths.ts";
-import type { SourceFiles } from "./source-files.ts";
-import { filesIn } from "./fs/tree.ts";
-import { yamlDocument } from "./text/yaml.ts";
+import { pathsNamed, readCommands, type CommandReading } from "../commands/read.ts";
+import type { Host } from "../host.ts";
+import { isRecord } from "../json-document.ts";
+import { joinPath, resolvePath } from "../paths.ts";
+import type { SourceFiles } from "../source-files.ts";
+import { filesIn } from "../fs/tree.ts";
+import { yamlDocument } from "../text/yaml.ts";
 
 /** One file a workflow step, git hook or recipe runs or names. */
 interface WorkflowEntry {
@@ -204,18 +204,36 @@ export function commandFileTexts(host: Host, targetRoot: string): readonly strin
   ].flatMap((path) => readText(host, path) ?? []);
 }
 
+/** What the target root's workflow steps, git hooks, hook managers and makefile run, read once per run. */
+export interface Workflows {
+  /** Each command read, its held text followed by the directory the file writes for it. */
+  readonly readings: readonly CommandReading[];
+  /** The whole text of each file a command is read from. */
+  readonly texts: readonly string[];
+}
+
+/** Reads the target root's workflow steps, git hooks, hook managers and makefile. */
+export function readWorkflows(host: Host, targetRoot: string): Workflows {
+  return {
+    readings: workflowCommands(host, targetRoot).map(({ text, dir, writtenDirectory }) => {
+      const reading = readCommands(text, dir);
+      return { ...reading, held: [reading.held, writtenDirectory ?? ""].join("\n") };
+    }),
+    texts: commandFileTexts(host, targetRoot),
+  };
+}
+
 /**
  * The own files the target root's workflow steps, git hooks and recipes run or name, as
  * `pathsNamed` reads each command.
  */
 export function workflowEntries(
-  host: Host,
-  targetRoot: string,
+  workflows: Workflows,
   files: SourceFiles,
 ): readonly WorkflowEntry[] {
   const found: WorkflowEntry[] = [];
-  for (const { text, dir } of workflowCommands(host, targetRoot)) {
-    for (const { path, written } of pathsNamed(readCommands(text, dir))) {
+  for (const reading of workflows.readings) {
+    for (const { path, written } of pathsNamed(reading)) {
       for (const file of files.named(path)) {
         found.push({ file, source: written });
       }

package/src/exempt.ts

@@ -8,6 +8,7 @@
  */
 
 import { EXEMPTION_CLASSES } from "./contract/contract.generated.ts";
+import type { GeneratedFact } from "./generated-file.ts";
 import type { ResolvedConfig } from "./config.ts";
 import {
   TS_EXEMPTION_CLASSES,
@@ -51,8 +52,8 @@ export interface DetectorInput<Brand> {
   readonly ts: ResolvedConfig["ts"];
   /** The absolute path of each declared consumer, whose modules are part of the analysis. */
   readonly consumers: readonly string[];
-  /** The project's generated files, by path below the target root, each with the detail its retentions name. */
-  readonly generated?: ReadonlyMap<string, string>;
+  /** The project's generated files, by path below the target root, each with what decided it. */
+  readonly generated?: ReadonlyMap<string, GeneratedFact>;
 }
 
 /**

package/src/extensions.ts

@@ -0,0 +1,45 @@
+/** The extension lists the analysis reads files by, each written once. */
+
+/**
+ * The extensions tried, in order, after a path written without one: a relative specifier
+ * of a configuration file (`roots.5`) and a path a command runs or loads (`roots.13`).
+ */
+export const APPENDED_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+] as const;
+
+/** The extensions of a module a tool runs or loads as its configuration (`roots.2`). */
+export const MODULE_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"] as const;
+
+/** The extensions of a file a build writes from a source file. */
+export const OUTPUT_EXTENSIONS = [
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".jsx",
+  ".d.ts",
+  ".d.mts",
+  ".d.cts",
+] as const;
+
+/** One list as a glob's brace list, its dots dropped: `{js,mjs}`. */
+export function braced(extensions: readonly string[]): string {
+  return `{${extensions.map((one) => one.slice(1)).join(",")}}`;
+}
+
+/** The extension of one list a name ends with, the longest where several do. */
+export function extensionOf(name: string, extensions: readonly string[]): string | undefined {
+  return extensions
+    .filter((one) => name.endsWith(one))
+    .reduce<string | undefined>(
+      (longest, one) => (one.length > (longest?.length ?? 0) ? one : longest),
+      undefined,
+    );
+}

package/src/facts.ts

@@ -0,0 +1,44 @@
+/**
+ * The facts document `--facts` writes, `bindings.1` and `bindings.2`: the run's generated
+ * files under the one decision the generated-file class reads. It carries no binding
+ * record, so it states `evaluated: false`.
+ */
+
+import { FACTS_VERSION } from "./contract/contract.generated.ts";
+import type { GeneratedFact } from "./generated-file.ts";
+import { LANGUAGE, PRODUCT } from "./product.ts";
+import { bytewise } from "./text/compare.ts";
+
+/** The facts document of one run, as the text written to the path `--facts` names. */
+export function factsDocument(
+  version: string,
+  generated: ReadonlyMap<string, GeneratedFact>,
+): string {
+  const document = {
+    facts_version: FACTS_VERSION,
+    analyzer: { name: PRODUCT, version },
+    language: LANGUAGE,
+    evaluated: false,
+    generated: [...generated]
+      .sort(([a], [b]) => bytewise(a, b))
+      .map(([path, fact]) => ({
+        path,
+        line: fact.line,
+        evidence: fact.evidence,
+        detail: fact.detail,
+        ...(fact.generator === undefined
+          ? {}
+          : {
+              generator: {
+                row: fact.generator.row,
+                ...(fact.generator.version === undefined
+                  ? {}
+                  : { version: fact.generator.version }),
+              },
+              schema_files: fact.generator.schemaFiles,
+            }),
+      })),
+    bindings: [],
+  };
+  return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/file-facts.ts

@@ -6,11 +6,11 @@
 
 import type { SourceFile } from "@typescript/native/ast";
 import type { Host } from "./host.ts";
-import { packageScope } from "./inventory.ts";
+import { packageScope } from "./load/package-scope.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import { renderRef } from "./ref.ts";
 import type { ProjectView } from "./session.ts";
-import type { UnseenLoad } from "./unseen-loads.ts";
+import type { UnseenLoad } from "./roots/unseen-loads.ts";
 import { filesBelow } from "./fs/tree.ts";
 
 /** A file name the compiler reads as a source file. */

package/src/findings/emitters.ts

@@ -161,18 +161,22 @@ function dialledOver(
   unmarked: readonly CompletedFinding[],
 ): Omit<DecidedFindings, "would"> {
   const would = [...unmarked, ...found];
-  const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
   const unanswered = heldKeys(input);
+  const heldIds = new Set(input.swept.heldByUnanswered);
+  const keyOf = (finding: CompletedFinding): string =>
+    declarationKey(finding.symbol.holder ?? finding.symbol.ref, finding.position.path);
+  const held = (finding: CompletedFinding): boolean =>
+    unanswered.has(keyOf(finding)) || insideSkipped(input.swept.skipped, finding.position);
+  const ledger = ledgerOf(
+    suppressed.records,
+    would,
+    dialsOver(input, found, suppressed, unmarked),
+    { withholds: held, holdsRecord: (record) => heldIds.has(record.bound) },
+  );
   const markup = markupKeys(input);
-  const candidates = found.filter((finding) => {
-    const key = declarationKey(finding.symbol.holder ?? finding.symbol.ref, finding.position.path);
-    return (
-      !ledger.withheld(finding) &&
-      !unanswered.has(key) &&
-      !markup.has(key) &&
-      !insideSkipped(input.swept.skipped, finding.position)
-    );
-  });
+  const candidates = found.filter(
+    (finding) => !ledger.withheld(finding) && !held(finding) && !markup.has(keyOf(finding)),
+  );
   const kept = reportable(input, candidates);
   const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
   return {

package/src/findings/self-check.ts

@@ -1,12 +1,12 @@
-import { CODE } from "../contract/contract.generated.ts";
+import { CODE, REMEDIES, type Subject } from "../contract/contract.generated.ts";
 import { REPOSITORY_DOCUMENT } from "../config.ts";
 import type { Finding, FindingDetails, SuppressionEntry } from "../finding.ts";
 import type { InventorySymbol } from "../inventory.ts";
 import { FIXED_SEVERITY_CODES } from "../kinds.ts";
 import type { Position } from "../position.ts";
 import {
-  isDependencyCode,
-  isUnsuppressibleCode,
+  names,
+  subjectOfCode,
   type Mechanism,
   type Refusal,
   type SuppressionRecord,
@@ -72,6 +72,43 @@ export function fileRefsOf(symbols: readonly InventorySymbol[]): FileRefs {
   return (path) => byPath.get(path);
 }
 
+/**
+ * Why a record of `mechanism` naming `codes` can match nothing, one clause per subject whose
+ * findings kinds.json's remedies table lets no record of that mechanism name, in subject order.
+ */
+function unnameable(codes: readonly string[], mechanism: Mechanism): readonly string[] {
+  return (Object.keys(REMEDIES) as Subject[]).flatMap((subject) => {
+    const named = codes.filter((code) => subjectOfCode(code) === subject);
+    if (named.length === 0 || names(subject, mechanism)) {
+      return [];
+    }
+    const { names: what, suppressions } = REMEDIES[subject];
+    const reports = `${spelled(named)} ${named.length === 1 ? "reports" : "each report"} ${what}`;
+    if (suppressions.length > 0) {
+      const records = suppressions.map((one) => articled(WRITTEN[one]));
+      return [`${reports}, which only ${spelledOr(records)} can name`];
+    }
+    const settable = named.filter((code) => !FIXED_SEVERITY_CODES.includes(code));
+    const remedy =
+      settable.length === 0
+        ? "fix what the finding names instead"
+        : `fix what the finding names or set the severity of ${spelled(settable)} instead`;
+    return [`${reports}, which no suppression can name; ${remedy}`];
+  });
+}
+
+/** A record's written name with its indefinite article. */
+function articled(name: string): string {
+  return `${/^[aeiou]/u.test(name) ? "an" : "a"} ${name}`;
+}
+
+/** A list as a sentence names alternatives. */
+function spelledOr(items: readonly string[]): string {
+  return items.length < 2
+    ? items.join("")
+    : `${items.slice(0, -1).join(", ")} or ${items.at(-1) ?? ""}`;
+}
+
 /** A list of codes as a sentence names them. */
 function spelled(codes: readonly string[]): string {
   if (codes.length < 2) {
@@ -176,26 +213,8 @@ export function staleSuppressions(
     const reports = [...new Set(records.flatMap((one) => one.reports))]
       .filter((code) => !codes.includes(code))
       .sort(bytewise);
-    const rows = codes.filter(isUnsuppressibleCode);
-    const dependencies = first.mechanism === "inline" ? codes.filter(isDependencyCode) : [];
-    const settable = rows.filter((code) => !FIXED_SEVERITY_CODES.includes(code));
-    const remedy =
-      settable.length === 0
-        ? "fix what the finding names instead"
-        : `fix what the finding names or set the severity of ${spelled(settable)} instead`;
     const declared = reports.length === 0 ? "" : `its declaration reports ${spelled(reports)}`;
-    const because = [
-      ...(rows.length > 0
-        ? [
-            `${spelled(rows)} ${rows.length === 1 ? "reports a row" : "report rows"} of a document, which no suppression can name; ${remedy}`,
-          ]
-        : []),
-      ...(dependencies.length > 0
-        ? [
-            `${spelled(dependencies)} ${dependencies.length === 1 ? "reports a dependency row" : "report dependency rows"}, which only an ignore entry or a baseline row can name`,
-          ]
-        : []),
-    ];
+    const because = unnameable(codes, first.mechanism);
     const instead =
       because.length > 0
         ? `, because ${because.join("; ")}${declared === "" ? "" : `; ${declared}`}`

package/src/findings/visibility-narrowing.ts

@@ -4,7 +4,7 @@ import { OUTSIDE, type Graph } from "../graph.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
 import { declarationKey } from "../ref.ts";
-import type { RootKind } from "../roots.ts";
+import type { RootKind } from "../roots/root-set.ts";
 import { runnerCalls } from "../sweep.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { writeOnlyDeclarations } from "./reads-and-writes.ts";

package/src/findings-pass.ts

@@ -16,13 +16,7 @@ import {
   type StaleRecord,
   type StaleSuppression,
 } from "./findings/self-check.ts";
-import {
-  isDependencySubject,
-  isRowSubject,
-  pairs,
-  suppressionCounts,
-  type Ledger,
-} from "./suppress.ts";
+import { namesKind, pairs, suppressionCounts, type Ledger } from "./suppress.ts";
 import type { Provenance, Recorded } from "./suppress-file.ts";
 import { bytewise } from "./text/compare.ts";
 import { PRODUCT } from "./product.ts";
@@ -131,15 +125,14 @@ export interface RecordableFinding {
 
 /**
  * The rows one round of a baseline write records from its findings, in their order. A
- * finding about a row of a document other than a dependency row is not recorded: no record
- * withholds one, so a row recording it would be stale on the first read back. Two findings
- * that would record the same row, two parts of one declaration under one code, record it
- * once.
+ * finding no baseline row can name is not recorded: a row recording it would be stale on
+ * the first read back. Two findings that would record the same row, two parts of one
+ * declaration under one code, record it once.
  */
 export function recordedFindings(findings: readonly RecordableFinding[]): readonly Recorded[] {
   const rows = new Map<string, Recorded>();
   for (const finding of findings) {
-    if (isRowSubject(finding.symbol.kind) && !isDependencySubject(finding.symbol.kind)) {
+    if (!namesKind(finding.symbol.kind, "baseline")) {
       continue;
     }
     const row = { code: finding.code, symbol: finding.symbol.ref, path: finding.position.path };

package/src/framework-lifecycle.ts

@@ -26,7 +26,7 @@ import {
   resolveEntries,
   spelledEntry,
   type ResolvedEntry,
-} from "./configured-declarations.ts";
+} from "./roots/configured-declarations.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { renderPosition } from "./position.ts";

package/src/fs/manifest.ts

@@ -22,24 +22,36 @@ export function inInstalledPackages(path: string): boolean {
   return path.split("/").includes(INSTALLED_PACKAGES);
 }
 
-/** One JSON file's text and decoded value, or undefined where it cannot be read or parsed. */
-export function readDocument(
-  host: Host,
-  path: string,
-): { text: string; value: unknown } | undefined {
+/** What one JSON file reads as: its text and decoded value, text that does not parse, or a file that cannot be read, with the read's error. */
+type JSONRead =
+  | { readonly kind: "read"; readonly text: string; readonly value: unknown }
+  | { readonly kind: "malformed" }
+  | { readonly kind: "unread"; readonly reason: string };
+
+/** One JSON file, read and parsed, as {@link JSONRead} tells its states apart. */
+export function readJSONFile(host: Host, path: string): JSONRead {
   let text: string;
   try {
     text = host.readFile(path);
-  } catch {
-    return undefined;
+  } catch (error: unknown) {
+    return { kind: "unread", reason: message(error) };
   }
   try {
-    return { text, value: JSON.parse(text) as unknown };
+    return { kind: "read", text, value: JSON.parse(text) as unknown };
   } catch {
-    return undefined;
+    return { kind: "malformed" };
   }
 }
 
+/** One JSON file's text and decoded value, or undefined where it cannot be read or parsed. */
+export function readDocument(
+  host: Host,
+  path: string,
+): { text: string; value: unknown } | undefined {
+  const read = readJSONFile(host, path);
+  return read.kind === "read" ? { text: read.text, value: read.value } : undefined;
+}
+
 /** One JSON file's decoded value, or undefined where it cannot be read or parsed. */
 export function readJSON(host: Host, path: string): unknown {
   return readDocument(host, path)?.value;
@@ -71,19 +83,11 @@ export function readManifestAt(host: Host, dir: string): ManifestRead {
   if (!holdsManifest(host, dir)) {
     return { kind: "absent" };
   }
-  let text: string;
-  try {
-    text = host.readFile(joinPath(dir, MANIFEST));
-  } catch (error: unknown) {
-    return { kind: "unread", reason: message(error) };
-  }
-  let value: unknown;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    return { kind: "malformed" };
+  const read = readJSONFile(host, joinPath(dir, MANIFEST));
+  if (read.kind !== "read") {
+    return read;
   }
-  return isRecord(value) ? { kind: "read", manifest: value } : { kind: "malformed" };
+  return isRecord(read.value) ? { kind: "read", manifest: read.value } : { kind: "malformed" };
 }
 
 /** Whether one directory holds a manifest file. */