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

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";