@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.4

package/dist/src/yaml-document.js

@@ -0,0 +1,355 @@
+/**
+ * The value of a YAML configuration document in the subset tool configurations write:
+ * block mappings and sequences, flow mappings and sequences, and plain, single-quoted and
+ * double-quoted scalars, with comments. A document using anything else, an anchor, an
+ * alias, a tag, a block scalar, a complex key or a second document, has no value here,
+ * as a JSON document that does not parse has none.
+ */
+/** A failure to read the document within the subset; it ends the whole reading. */
+class Unsupported extends Error {
+}
+/** The characters after which a quote opens a quoted scalar rather than standing in a plain one. */
+const SCALAR_START = new Set(["", ":", "-", "[", "{", ","]);
+/** The plain scalars YAML's core schema reads as something other than a string. */
+const CORE = new Map([
+    ["true", true],
+    ["True", true],
+    ["TRUE", true],
+    ["false", false],
+    ["False", false],
+    ["FALSE", false],
+    ["null", null],
+    ["Null", null],
+    ["NULL", null],
+    ["~", null],
+    ["", null],
+]);
+const NUMBER = /^[-+]?(?:\d+|\d*\.\d+|\d+\.\d*)(?:[eE][-+]?\d+)?$/u;
+/** The text of one line before its comment: a `#` at the line's start or after a blank, outside quotes. */
+function withoutComment(line) {
+    let quote;
+    let previous = "";
+    for (let at = 0; at < line.length; at += 1) {
+        const char = line.charAt(at);
+        if (quote !== undefined) {
+            if (quote === '"' && char === "\\") {
+                at += 1;
+            }
+            else if (char === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if ((char === "'" || char === '"') && SCALAR_START.has(previous)) {
+            quote = char;
+        }
+        else if (char === "#" && (at === 0 || /\s/u.test(line.charAt(at - 1)))) {
+            return line.slice(0, at);
+        }
+        if (!/\s/u.test(char)) {
+            previous = char;
+        }
+    }
+    return line;
+}
+/** The value one scalar's text denotes, quoted or plain. */
+function scalar(text) {
+    const value = text.trim();
+    if (value.startsWith("'")) {
+        if (!value.endsWith("'") || value.length < 2) {
+            throw new Unsupported();
+        }
+        return value.slice(1, -1).replaceAll("''", "'");
+    }
+    if (value.startsWith('"')) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            throw new Unsupported();
+        }
+    }
+    if (/^[&*!|>%@`?]/u.test(value) || value === "---" || value === "...") {
+        throw new Unsupported();
+    }
+    if (/:(?:\s|$)/u.test(value)) {
+        throw new Unsupported();
+    }
+    if (CORE.has(value)) {
+        return CORE.get(value);
+    }
+    return NUMBER.test(value) ? Number(value) : value;
+}
+/** Reads one flow collection or flow scalar from `text` at `at`, answering the value and where it ends. */
+function flow(text, start) {
+    let at = start;
+    const skip = () => {
+        while (at < text.length && /\s/u.test(text.charAt(at))) {
+            at += 1;
+        }
+    };
+    skip();
+    const open = text.charAt(at);
+    if (open === "[" || open === "{") {
+        const close = open === "[" ? "]" : "}";
+        const items = [];
+        const object = {};
+        at += 1;
+        for (;;) {
+            skip();
+            if (text.charAt(at) === close) {
+                return { value: open === "[" ? items : object, end: at + 1 };
+            }
+            const item = flow(text, at);
+            at = item.end;
+            skip();
+            if (open === "{") {
+                if (text.charAt(at) !== ":" || typeof item.value !== "string") {
+                    throw new Unsupported();
+                }
+                const held = flow(text, at + 1);
+                object[item.value] = held.value;
+                at = held.end;
+                skip();
+            }
+            else {
+                items.push(item.value);
+            }
+            if (text.charAt(at) === ",") {
+                at += 1;
+            }
+            else if (text.charAt(at) !== close) {
+                throw new Unsupported();
+            }
+        }
+    }
+    if (open === "'" || open === '"') {
+        let end = at + 1;
+        for (; end < text.length; end += 1) {
+            const char = text.charAt(end);
+            if (open === '"' && char === "\\") {
+                end += 1;
+            }
+            else if (char === open && !(open === "'" && text.charAt(end + 1) === "'")) {
+                break;
+            }
+            else if (char === open) {
+                end += 1;
+            }
+        }
+        if (end >= text.length) {
+            throw new Unsupported();
+        }
+        return { value: scalar(text.slice(at, end + 1)), end: end + 1 };
+    }
+    let end = at;
+    while (end < text.length && !",]}".includes(text.charAt(end))) {
+        if (text.charAt(end) === ":" && /[\s,\]}]/u.test(text.charAt(end + 1) || " ")) {
+            break;
+        }
+        end += 1;
+    }
+    return { value: scalar(text.slice(at, end)), end };
+}
+/** A value written on one or more lines of a block, read whole: a flow node, else one plain scalar. */
+function flowValue(text) {
+    if (!/^["'[{]/u.test(text)) {
+        return scalar(text);
+    }
+    const read = flow(text, 0);
+    if (text.slice(read.end).trim() !== "") {
+        throw new Unsupported();
+    }
+    return read.value;
+}
+/** The position of a mapping key's `:` in one line's content, or -1 where the content is no mapping entry. */
+function keyEnd(text) {
+    let quote;
+    for (let at = 0; at < text.length; at += 1) {
+        const char = text.charAt(at);
+        if (quote !== undefined) {
+            if (quote === '"' && char === "\\") {
+                at += 1;
+            }
+            else if (char === quote) {
+                quote = undefined;
+            }
+        }
+        else if (at === 0 && (char === "'" || char === '"')) {
+            quote = char;
+        }
+        else if (char === "[" || char === "{") {
+            return -1;
+        }
+        else if (char === ":" && (at + 1 === text.length || /\s/u.test(text.charAt(at + 1)))) {
+            return at;
+        }
+    }
+    return -1;
+}
+/** How many flow collections one text opens and leaves unclosed, quotes read through. */
+function openCollections(text) {
+    let depth = 0;
+    let quote;
+    for (let at = 0; at < text.length; at += 1) {
+        const char = text.charAt(at);
+        if (quote !== undefined) {
+            if (quote === '"' && char === "\\") {
+                at += 1;
+            }
+            else if (char === quote) {
+                quote = undefined;
+            }
+        }
+        else if ((char === "'" || char === '"') &&
+            SCALAR_START.has(text.slice(0, at).trim().slice(-1))) {
+            quote = char;
+        }
+        else if (char === "[" || char === "{") {
+            depth += 1;
+        }
+        else if (char === "]" || char === "}") {
+            depth -= 1;
+        }
+    }
+    return depth;
+}
+/** Whether one line's content is a block sequence item. */
+function isItem(text) {
+    return text === "-" || text.startsWith("- ");
+}
+/** Reads the document's lines as one value. */
+class Reader {
+    at = 0;
+    lines;
+    constructor(lines) {
+        this.lines = lines;
+    }
+    /** The whole document's value. */
+    document() {
+        const first = this.lines[0];
+        if (first === undefined) {
+            return null;
+        }
+        const value = this.block(first.indent);
+        if (this.at < this.lines.length) {
+            throw new Unsupported();
+        }
+        return value;
+    }
+    /** The block node whose first line is the next one, at `indent`. */
+    block(indent) {
+        const line = this.lines[this.at];
+        if (line === undefined) {
+            return null;
+        }
+        if (isItem(line.text)) {
+            return this.sequence(indent);
+        }
+        if (keyEnd(line.text) >= 0) {
+            return this.mapping(indent);
+        }
+        return this.multiline(indent);
+    }
+    /** A scalar or a flow collection whose text runs over the next lines indented deeper than `indent`. */
+    multiline(indent) {
+        const parts = [];
+        for (let line = this.lines[this.at]; line !== undefined && (parts.length === 0 || line.indent > indent); line = this.lines[this.at]) {
+            parts.push(line.text);
+            this.at += 1;
+        }
+        return flowValue(parts.join(" "));
+    }
+    /** The value after a key or an item marker: inline text, else the deeper block below it. */
+    valueAfter(inline, indent, sequenceAtIndent) {
+        if (inline !== "") {
+            const parts = [inline];
+            // A flow collection's closing bracket may stand at the key's own column.
+            for (let line = this.lines[this.at]; line !== undefined && (line.indent > indent || openCollections(parts.join(" ")) > 0); line = this.lines[this.at]) {
+                parts.push(line.text);
+                this.at += 1;
+            }
+            return flowValue(parts.join(" "));
+        }
+        const next = this.lines[this.at];
+        if (next === undefined) {
+            return null;
+        }
+        if (next.indent > indent || (sequenceAtIndent && next.indent === indent && isItem(next.text))) {
+            return this.block(next.indent);
+        }
+        return null;
+    }
+    mapping(indent) {
+        const object = {};
+        for (let line = this.lines[this.at]; line?.indent === indent; line = this.lines[this.at]) {
+            const end = keyEnd(line.text);
+            if (end < 0) {
+                throw new Unsupported();
+            }
+            const key = scalar(line.text.slice(0, end));
+            if (typeof key === "object" && key !== null) {
+                throw new Unsupported();
+            }
+            this.at += 1;
+            object[String(key)] = this.valueAfter(line.text.slice(end + 1).trim(), indent, true);
+        }
+        const left = this.lines[this.at];
+        if (left !== undefined && left.indent > indent) {
+            throw new Unsupported();
+        }
+        return object;
+    }
+    sequence(indent) {
+        const items = [];
+        for (let line = this.lines[this.at]; line?.indent === indent && isItem(line.text); line = this.lines[this.at]) {
+            const content = line.text.slice(1);
+            const inline = content.trimStart();
+            if (inline !== "" && (isItem(inline) || keyEnd(inline) >= 0)) {
+                // A node on the item's own line continues at its own column: read it as a block there.
+                const moved = { indent: indent + 1 + content.length - inline.length, text: inline };
+                this.lines[this.at] = moved;
+                items.push(this.block(moved.indent));
+            }
+            else {
+                this.at += 1;
+                items.push(this.valueAfter(inline, indent, false));
+            }
+        }
+        const left = this.lines[this.at];
+        if (left !== undefined && left.indent > indent) {
+            throw new Unsupported();
+        }
+        return items;
+    }
+}
+/** The JSON value one YAML document's text denotes, or undefined where it lies outside the subset. */
+export function yamlDocument(text) {
+    const lines = [];
+    for (const raw of text.replace(/^\uFEFF/u, "").split(/\r?\n/u)) {
+        if (/^ *\t/u.test(raw)) {
+            return undefined;
+        }
+        const content = withoutComment(raw).trimEnd();
+        const trimmed = content.trimStart();
+        if (trimmed === "") {
+            continue;
+        }
+        if (trimmed === "---" && lines.length === 0) {
+            continue;
+        }
+        if (trimmed.startsWith("%") || trimmed === "---" || trimmed === "...") {
+            return undefined;
+        }
+        lines.push({ indent: content.length - trimmed.length, text: trimmed });
+    }
+    try {
+        return new Reader(lines).document();
+    }
+    catch (error) {
+        if (error instanceof Unsupported) {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.2",
+  "version": "8.0.0-dev.4",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "8.0.0-dev.2",
+  "version": "8.0.0-dev.4",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
@@ -30,7 +30,7 @@
     "lint:fix": "eslint . --fix && prettier --write ."
   },
   "dependencies": {
-    "@typescript/native": "npm:typescript@7.1.0-dev.20261010.1"
+    "@typescript/native": "npm:typescript@7.1.0-dev.20261014.1"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/analysis.ts

@@ -6,7 +6,7 @@
  * another project's checker, which holds only for views the session hands out.
  */
 
-import { isStringLiteralLikeNode } from "@typescript/native/ast";
+import { isStringLiteralLikeNode, type SourceFile } from "@typescript/native/ast";
 import { lineOf, readComponent } from "./component-files.ts";
 import { kindOf, type Config, type Provenance } from "./config.ts";
 import {
@@ -56,6 +56,7 @@ import {
   holdingWhile,
   isUnansweredRecord,
   retainedIn,
+  writtenRecords,
   type Detector,
   type Detectors,
 } from "./exempt.ts";
@@ -107,14 +108,18 @@ import { references, testFileRulesOf, type Reference, type TestFileRule } from "
 import {
   roots,
   unmatchedEverywhere,
+  type Root,
   type RootKind,
   type RootOptions,
   type Roots,
 } from "./roots.ts";
 import type { Scope } from "./scope.ts";
-import { serializationContract } from "./serialization-contract.ts";
+import { decodedMembers, serializationContract, type Decoded } from "./serialization-contract.ts";
 import { outsideTestReferences, testFilesAt, type OutsideTest } from "./outside-tests.ts";
+import { mergedGlobalInterfaces } from "./augmentations.ts";
+import { unseenLoadsOf, type UnseenLoad } from "./unseen-loads.ts";
 import { joinedTestFiles, withJoinedTests } from "./test-joins.ts";
+import { GLOBALS_RUNNER, namesTestGlobals, withTestGlobals } from "./test-globals.ts";
 import { supportReferences, testSupportFiles, type TestEvidence } from "./test-support.ts";
 import {
   diagnosticsOf,
@@ -428,11 +433,17 @@ function readProjects<Answer>(
   const joins = discovered.derived
     ? joinedTestFiles(engine, host, absoluteRoot, discovered.configFiles, testPatterns)
     : new Map<string, readonly string[]>();
-  const programs = withBaseUrlPaths(
+  const programs = withTestGlobals(
     engine,
     host,
-    [...discovered.configFiles, ...consumerOf.keys()],
-    workspace?.programs ?? new Map(),
+    parse,
+    discovered.configFiles,
+    withBaseUrlPaths(
+      engine,
+      host,
+      [...discovered.configFiles, ...consumerOf.keys()],
+      workspace?.programs ?? new Map(),
+    ),
   );
   const session = runSession(
     engine,
@@ -784,6 +795,8 @@ interface SweptProject<Extra> {
   readonly exempt: readonly Exemption[];
   /** The declarations of the project an unanswered question could have kept live. */
   readonly unanswered: readonly string[];
+  /** The data members a generic declared outside the analysis fills, which it may read. */
+  readonly filledOutside: readonly string[];
   readonly typeErrorSkips: readonly TypeErrorSkip[];
   readonly skipped: readonly SkippedUnit[];
   /** The component files the project holds of its own, by path below the target root. */
@@ -804,6 +817,10 @@ interface ReadProject<Extra> {
   readonly componentWarnings: readonly ComponentWarning[];
   /** Per own file below the target root, the module specifiers its imports write. */
   readonly imports: ReadonlyMap<string, readonly string[]>;
+  /** The global augmentations a declaration outside the project names. */
+  readonly augmented: readonly Root[];
+  /** The data members its production code decodes into. */
+  readonly decoded: Decoded;
   readonly extra: Extra;
 }
 
@@ -940,6 +957,9 @@ function readRun<Extra>(
       disabled,
     );
     const components = project.ownSourceFiles().filter(isComponentFile);
+    const injected = project.program
+      .getSourceFileNames()
+      .some((name) => name.endsWith(`/node_modules/${GLOBALS_RUNNER}/globals.d.ts`));
     const pathOf = (file: (typeof components)[number]): string =>
       relativePath(targetRoot, file.fileName) ?? file.fileName;
     return {
@@ -948,12 +968,27 @@ function readRun<Extra>(
       testFiles: resolved.testFilePaths,
       evidence,
       componentFiles: components.map(pathOf),
+      augmented: mergedGlobalInterfaces(
+        project,
+        projectRead.held,
+        sourceFilesOf(project, targetRoot),
+      ).map((id): Root => ({ id, kind: "global-augmentation", source: "" })),
       imports: new Map(
         project.ownSourceFiles().flatMap((file) => {
           const path = relativePath(targetRoot, file.fileName);
-          return path === undefined
-            ? []
-            : [[path, file.imports.filter(isStringLiteralLikeNode).map((one) => one.text)]];
+          if (path === undefined) {
+            return [];
+          }
+          const specifiers = file.imports.filter(isStringLiteralLikeNode).map((one) => one.text);
+          // A file calling the globals a program declares is written for their runner.
+          return [
+            [
+              path,
+              injected && namesTestGlobals(project, file)
+                ? [...specifiers, GLOBALS_RUNNER]
+                : specifiers,
+            ],
+          ];
         }),
       ),
       componentWarnings: components.flatMap((file) =>
@@ -963,6 +998,12 @@ function readRun<Extra>(
           reason: warning.reason,
         })),
       ),
+      decoded: decodedMembers(
+        project,
+        projectRead.held,
+        productionFiles(project, targetRoot, resolved.testFilePaths),
+        consumers,
+      ),
       extra: extra(project, projectRead, resolved.references, resolved.testFilePaths),
     };
   });
@@ -984,14 +1025,31 @@ function readRun<Extra>(
     withOutside.flatMap((one) => one.testFiles),
     testEvidence(host, targetRoot, withOutside),
   );
+  // A member a decode fills or a copy carries is written: a value decoded and sent again carries it on.
+  const written = new Set([
+    ...countedWrites(
+      [...withOutside.flatMap((one) => one.references), ...read.consumers.references],
+      support,
+      mode,
+    ),
+    ...withOutside.flatMap((one) => [
+      ...one.decoded.filled,
+      ...one.decoded.parsed,
+      ...one.decoded.copied,
+    ]),
+  ]);
+  const evidence = withOutside.map((one) => writtenRecords(one.evidence, written));
   const settled = settledSatisfaction(
-    withOutside.map((one) => ({ evidence: one.evidence, held: one.projectRead.held })),
+    withOutside.map((one, index) => ({
+      evidence: evidence[index] ?? [],
+      held: one.projectRead.held,
+    })),
     [...withOutside.flatMap((one) => one.references), ...read.consumers.references],
   );
   const answers = withOutside.map((one, index): SweptProject<Extra> => {
     const { projectRead } = one;
     const satisfied = settled[index];
-    const detected = heldRecords(satisfied?.evidence ?? one.evidence, {
+    const detected = heldRecords(satisfied?.evidence ?? evidence[index] ?? [], {
       mode,
       testFiles: new Set([...one.testFiles, ...support]),
     });
@@ -1004,7 +1062,9 @@ function readRun<Extra>(
       configuration: projectRead.configuration,
       symbols: projectRead.held.symbols,
       references: [...made, ...evidenceReferences(projectRead.held.symbols, detected.inTestFiles)],
-      roots: projectRead.rooted.liveUnderReachability,
+      // The augmentations are rooted after test support is read: an outside declaration
+      // naming one calls nothing of its file.
+      roots: [...projectRead.rooted.liveUnderReachability, ...one.augmented],
       testFiles: [...one.testFiles, ...supportFiles],
       ...(supportFiles.length === 0 ? {} : { supportFiles }),
       ...(testUsedFiles.length === 0 ? {} : { testUsedFiles }),
@@ -1027,7 +1087,9 @@ function readRun<Extra>(
           .filter((reference) => reference.resolution === "by-name")
           .map((reference) => reference.to),
         ...exempt.filter(isUnansweredRecord).map((record) => record.id),
+        ...one.decoded.unanswered,
       ],
+      filledOutside: one.decoded.filled,
       typeErrorSkips: projectRead.typeErrorSkips,
       unmappedEntries: projectRead.rooted.unmappedEntries,
       skipped: projectRead.skipped,
@@ -1130,6 +1192,22 @@ function evidenceReferences(
   });
 }
 
+/**
+ * The declarations a write the mode counts stores into, a write a test-support file
+ * makes being a test's.
+ */
+function countedWrites(
+  references: readonly Reference[],
+  support: ReadonlySet<string>,
+  mode: Mode,
+): ReadonlySet<string> {
+  return new Set(
+    supportReferences(references, support).flatMap((reference) =>
+      reference.use === "write" && !(mode.production && reference.test) ? [reference.to] : [],
+    ),
+  );
+}
+
 /**
  * The declarations every reference the mode counts stores into, a loaded consumer's
  * reference counting as a read: what the write-only kind would report but for a record.
@@ -1246,6 +1324,19 @@ interface EmitterExtra {
   readonly directives: readonly InlineDirective[];
   readonly declarationsNamed: readonly boolean[];
   readonly parts: ProjectParts;
+  readonly unseenLoads: readonly UnseenLoad[];
+}
+
+/** The project's own files below the target root that are no test file. */
+function productionFiles<Brand>(
+  project: ProjectView<Brand>,
+  targetRoot: string,
+  testFiles: readonly string[],
+): readonly SourceFile[] {
+  const tests = new Set(testFiles);
+  return [...sourceFilesOf(project, targetRoot).byPath].flatMap(([path, file]) =>
+    tests.has(path) ? [] : [file],
+  );
 }
 
 /** Reads a run's projects with every per-project fact an emitter reads. */
@@ -1281,9 +1372,10 @@ export function readEmitterRun(
       ),
       declarationsNamed: declarationsNamed(project, read.held, configuredDeclarations(config)),
       parts: projectParts(project, read.held, references, targetRoot),
+      unseenLoads: unseenLoadsOf(project, read.configuration, targetRoot, testFiles),
     }),
   );
-  // Whether a declaration carries the marker decides its code, so one whose marker went
+  // Whether a declaration carries the marker decides its code, so one whose answer went
   // unread is reported by nothing.
   const unread = run.projects.flatMap((one) => one.extra.deprecation.unanswered);
   return unread.length === 0
@@ -1386,6 +1478,7 @@ export function emitterInputOver(
       heldByInclusion: new Set(projects.flatMap((one) => one.extra.heldByInclusion)),
       generated: new Set(projects.flatMap((one) => one.extra.generated)),
       inOperands: new Set(projects.flatMap((one) => one.extra.inOperands)),
+      unseenLoads: projects.flatMap((one) => one.extra.unseenLoads),
     },
     boundary: {
       consumers: {
@@ -1394,6 +1487,7 @@ export function emitterInputOver(
       },
       encapsulated: readManifest(host, targetRoot).declaresExports,
       edges: readEdgeSides(host, targetRoot),
+      filledOutside: new Set(projects.flatMap((one) => one.filledOutside)),
     },
     selfCheck,
     intraFunction: intraFunctionFacts(
@@ -1476,6 +1570,7 @@ function readAnalysis(
       librariesUnfound: read.librariesUnfound,
       conventionsApplied: read.conventionsApplied,
       unmappedEntries: unmappedEverywhere(read.projects),
+      unseenLoads: read.projects.flatMap((one) => one.extra.unseenLoads),
     },
     configured: read.projects.map((one) => one.configured),
     symbols,
@@ -1574,6 +1669,8 @@ interface RunFacts {
   readonly conventionsApplied: readonly AppliedConvention[];
   /** The manifest entries no project of the run reads back to a file, each once. */
   readonly unmappedEntries: readonly ManifestEntry[];
+  /** The loads of production files whose target the run cannot resolve, per configuration. */
+  readonly unseenLoads: readonly UnseenLoad[];
 }
 
 /** One configuration whose component files a run cannot read. */