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

package/dist/src/findings-pass.js

@@ -3,27 +3,20 @@
  * applied and the declared edges evaluated, and the stale suppressions, the totals and the
  * verdict a report carries beside them.
  */
+import { EXIT_CLEAN, EXIT_FINDINGS, EXIT_PENDING } from "./contract/contract.generated.js";
 import { fails } from "./config.js";
 import { decidedFindings } from "./findings/emitters.js";
 import { fileRefsOf, staleSuppressions, } from "./findings/self-check.js";
-import { isDependencySubject, isRowSubject, pairs, suppressionCounts, } from "./suppress.js";
-import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.js";
-/** The exit code of a report holding at least one pending finding. */
-export const EXIT_PENDING = 4;
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    return a < b ? -1 : 1;
-}
+import { namesKind, pairs, suppressionCounts } from "./suppress.js";
+import { bytewise } from "./text/compare.js";
+import { PRODUCT } from "./product.js";
 /** The canonical order: path, line, column, code, then the symbol reference. */
 function canonical(a, b) {
-    return (compare(a.position.path, b.position.path) ||
+    return (bytewise(a.position.path, b.position.path) ||
         a.position.line - b.position.line ||
         a.position.column - b.position.column ||
-        compare(a.code, b.code) ||
-        compare(a.symbol.ref, b.symbol.ref));
+        bytewise(a.code, b.code) ||
+        bytewise(a.symbol.ref, b.symbol.ref));
 }
 /**
  * The pass over one run. The emitter table decides every record against every finding the
@@ -73,20 +66,19 @@ export function verdictOf(result, config) {
     if (result.totals.staleSuppressions > 0) {
         return EXIT_FINDINGS;
     }
-    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.failOn));
+    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.fail_on));
     return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 /**
  * 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) {
     const rows = new Map();
     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 };
@@ -100,5 +92,5 @@ export function rowKey(row) {
 }
 /** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */
 export function analyzerProvenance(version) {
-    return { analyzer: "deadset-ts", version };
+    return { analyzer: PRODUCT, version };
 }

package/dist/src/fs/document.js

@@ -0,0 +1,52 @@
+/**
+ * The one read of a document the target holds at its root, which a checkout under analysis
+ * controls: the repository configuration, the ignore file, the baseline and the edges
+ * document. The read stays inside the target root, takes a regular file alone, and holds no
+ * more of it than the Contract's document bound.
+ */
+import { CONFIG_MAX_BYTES } from "../contract/config.generated.js";
+import { failureExit } from "../failure.js";
+import { joinPath, relativePath } from "../paths.js";
+import { message } from "../product.js";
+import { utf8Bytes } from "../reporters/sha256.js";
+import { UsageError } from "../usage.js";
+function unreadable(label, reason) {
+    return failureExit("unreadable-document", `${label}: ${reason}: make it a regular file inside the target root that the run can read, or remove it`);
+}
+/** Refuses a document past the Contract's bound with the usage code, naming it `label`. */
+export function refuseOverBound(label, text) {
+    if (utf8Bytes(text).length > CONFIG_MAX_BYTES) {
+        throw new UsageError(`${label}: holds more than ${String(CONFIG_MAX_BYTES)} bytes`);
+    }
+}
+/**
+ * The text of the document `name` at the absolute `targetRoot`, undefined where nothing is
+ * there. One whose name resolves outside the target root or to anything but a regular file,
+ * or whose read fails, is refused by `refuse` naming it `label`, nothing read from it. A
+ * document past the bound is read one byte past it and refused as {@link refuseOverBound} does.
+ */
+export function readTargetDocument(host, targetRoot, name, label = name, refuse = unreadable) {
+    const attempt = (read) => {
+        try {
+            return read();
+        }
+        catch (error) {
+            throw refuse(label, message(error));
+        }
+    };
+    const path = joinPath(targetRoot, name);
+    const kind = attempt(() => host.kindOf(path));
+    if (kind === "absent") {
+        return undefined;
+    }
+    const real = attempt(() => host.realPath(path));
+    if (relativePath(attempt(() => host.realPath(targetRoot)), real) === undefined) {
+        throw refuse(label, `resolves to ${real}, outside the target root`);
+    }
+    if (kind !== "file") {
+        throw refuse(label, "is not a regular file");
+    }
+    const text = attempt(() => host.readFile(real, CONFIG_MAX_BYTES + 1));
+    refuseOverBound(label, text);
+    return text;
+}

package/dist/src/fs/manifest.js

@@ -0,0 +1,67 @@
+import { isRecord } from "../json-document.js";
+import { joinPath } from "../paths.js";
+import { message } from "../product.js";
+/** The file a package's manifest is read from. */
+export const MANIFEST = "package.json";
+/** The directory a package manager installs packages into, whose files are no project's own. */
+export const INSTALLED_PACKAGES = "node_modules";
+/** The manifest members a package declares the packages it depends on under. */
+export const DEPENDENCY_SECTIONS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
+/** Whether one path passes through an installed-packages directory. */
+export function inInstalledPackages(path) {
+    return path.split("/").includes(INSTALLED_PACKAGES);
+}
+/** One JSON file, read and parsed, as {@link JSONRead} tells its states apart. */
+export function readJSONFile(host, path) {
+    let text;
+    try {
+        text = host.readFile(path);
+    }
+    catch (error) {
+        return { kind: "unread", reason: message(error) };
+    }
+    try {
+        return { kind: "read", text, value: JSON.parse(text) };
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+}
+/** One JSON file's text and decoded value, or undefined where it cannot be read or parsed. */
+export function readDocument(host, path) {
+    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, path) {
+    return readDocument(host, path)?.value;
+}
+/**
+ * The manifest in one directory, decoded, or undefined where none reads as an object. A
+ * manifest this program cannot read declares nothing, the same answer as an absent one:
+ * the package manager owns the refusal of a manifest it rejects.
+ */
+export function manifestAt(host, dir) {
+    const value = readJSON(host, joinPath(dir, MANIFEST));
+    return isRecord(value) ? value : undefined;
+}
+/** The manifest in one directory, as {@link ManifestRead} tells its states apart. */
+export function readManifestAt(host, dir) {
+    if (!holdsManifest(host, dir)) {
+        return { kind: "absent" };
+    }
+    const read = readJSONFile(host, joinPath(dir, MANIFEST));
+    if (read.kind !== "read") {
+        return read;
+    }
+    return isRecord(read.value) ? { kind: "read", manifest: read.value } : { kind: "malformed" };
+}
+/** Whether one directory holds a manifest file. */
+export function holdsManifest(host, dir) {
+    return host.kindOf(joinPath(dir, MANIFEST)) === "file";
+}

package/dist/src/fs/tree.js

@@ -0,0 +1,88 @@
+import { ancestors, joinPath, resolvePath } from "../paths.js";
+import { LANGUAGE_ROWS } from "../contract/contract.generated.js";
+import { LANGUAGE } from "../product.js";
+import { bytewise } from "../text/compare.js";
+import { globExpression } from "../text/glob.js";
+/** The directories no walk of the tree enters, by the patterns the language's row names. */
+const SKIPPED_DIRECTORIES = LANGUAGE_ROWS[LANGUAGE].skippedDirectories.map(globExpression);
+function skipped(name) {
+    return SKIPPED_DIRECTORIES.some((pattern) => pattern.test(name));
+}
+/** One file's text without its line ending, or undefined where it cannot be read. */
+function lineOf(host, path) {
+    try {
+        return host.readFile(path).replace(/\r?\n$/u, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The repository whose working tree holds `dir`: the nearest directory at or above it with a
+ * `.git`. A `.git` file, which a linked worktree or a submodule holds, names the repository's
+ * directory on its `gitdir:` line; that directory's `commondir` file, where it has one, names
+ * the directory shared with the main worktree, which holds `info/exclude`:
+ * https://git-scm.com/docs/gitrepository-layout
+ */
+export function repositoryOf(host, dir) {
+    for (const root of ancestors(dir)) {
+        const dotGit = joinPath(root, ".git");
+        const kind = host.kindOf(dotGit);
+        if (kind === "directory") {
+            return { root, exclude: joinPath(dotGit, "info/exclude") };
+        }
+        if (kind === "file") {
+            const named = /^gitdir: (.+)$/u.exec(lineOf(host, dotGit) ?? "")?.[1];
+            const gitDir = named === undefined ? undefined : resolvePath(root, named);
+            const common = gitDir === undefined ? undefined : lineOf(host, joinPath(gitDir, "commondir"));
+            const shared = gitDir === undefined || common === undefined ? gitDir : resolvePath(gitDir, common);
+            return { root, exclude: shared === undefined ? undefined : joinPath(shared, "info/exclude") };
+        }
+    }
+    return undefined;
+}
+/** The entries of one directory, none where it cannot be read. */
+export function entriesOf(host, dir) {
+    try {
+        return host.readDirectory(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** The names of the files directly in `dir` whose name `accepts`, in bytewise order. */
+export function filesIn(host, dir, accepts) {
+    return entriesOf(host, dir)
+        .filter((entry) => !entry.directory && accepts(entry.name))
+        .map((entry) => entry.name)
+        .sort(bytewise);
+}
+/** The names of the directories directly in `dir` a walk enters, in bytewise order. */
+export function directoriesIn(host, dir) {
+    return entriesOf(host, dir)
+        .filter((entry) => entry.directory && !skipped(entry.name))
+        .map((entry) => entry.name)
+        .sort(bytewise);
+}
+/**
+ * Every file below `root` whose name `accepts`, by its path relative to `root` in bytewise
+ * order, read in no skipped directory.
+ */
+export function filesBelow(host, root, accepts) {
+    const found = [];
+    const pending = [""];
+    for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
+        for (const entry of entriesOf(host, joinPath(root, dir))) {
+            const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+            if (!entry.directory) {
+                if (accepts(entry.name)) {
+                    found.push(path);
+                }
+            }
+            else if (!skipped(entry.name)) {
+                pending.push(path);
+            }
+        }
+    }
+    return found.sort(bytewise);
+}

package/dist/src/git-ignore.js

@@ -1,10 +1,12 @@
 /**
- * Which files the `.gitignore` files of a tree ignore, read as git reads them:
+ * Which files git ignores below a tree's root, read as git reads its ignore files:
  * https://git-scm.com/docs/gitignore#_pattern_format
  */
-import { globExpression } from "./glob.js";
-import { dirnamePath, joinPath, relativePath } from "./paths.js";
-/** The rules one `.gitignore` text writes, in order. */
+import { ancestors, dirnamePath, joinPath, relativePath } from "./paths.js";
+import { message } from "./product.js";
+import { gitignoreExpression } from "./text/glob.js";
+import { repositoryOf } from "./fs/tree.js";
+/** The rules one ignore file's text writes, in order. */
 function rulesOf(text) {
     const rules = [];
     for (const raw of text.split(/\r?\n/u)) {
@@ -13,7 +15,7 @@ function rulesOf(text) {
             continue;
         }
         const negated = line.startsWith("!");
-        line = negated || line.startsWith("\\") ? line.slice(1) : line;
+        line = negated ? line.slice(1) : line;
         const directoryOnly = line.endsWith("/");
         line = line.replace(/\/+$/u, "");
         if (line === "") {
@@ -26,43 +28,54 @@ function rulesOf(text) {
         rules.push({
             negated,
             directoryOnly,
-            expression: globExpression(anchored ? pattern : `**/${pattern}`),
+            expression: gitignoreExpression(anchored ? pattern : `**/${pattern}`),
         });
     }
     return rules;
 }
+function rulesIn(host, path, unread) {
+    try {
+        return rulesOf(host.readFile(path));
+    }
+    catch (error) {
+        if (host.kindOf(path) !== "absent") {
+            unread(path, message(error));
+        }
+        return [];
+    }
+}
 /**
- * Whether the `.gitignore` files at and below `root` ignore one absolute path. A path
- * outside `root` is not ignored, and a file below an ignored directory stays ignored
- * whatever a later pattern says, as git cannot re-include it.
+ * Whether git ignores one absolute path below `root`: by the repository's `info/exclude`, then
+ * the `.gitignore` files from its root down to the path's directory, a later pattern overriding
+ * an earlier one, though a file below an ignored directory stays ignored, as git cannot re-include
+ * it. A path outside `root` is not ignored. With no repository, the files at and below `root` are
+ * read; with one, the directories above `root` give patterns but are not tested. An unreadable
+ * ignore file ignores nothing, and `unread` is told it.
  */
-export function gitIgnored(host, root) {
+export function gitIgnored(host, root, unread = () => undefined) {
+    const found = repositoryOf(host, root);
+    const repository = found?.root;
+    const above = repository === undefined ? [] : [...ancestors(dirnamePath(root), repository)].reverse();
+    const excluded = found?.exclude === undefined ? [] : rulesIn(host, found.exclude, unread);
     const read = new Map();
     const rulesAt = (dir) => {
         let rules = read.get(dir);
         if (rules === undefined) {
-            try {
-                rules = rulesOf(host.readFile(joinPath(dir, ".gitignore")));
-            }
-            catch {
-                rules = [];
-            }
+            rules = rulesIn(host, joinPath(dir, ".gitignore"), unread);
             read.set(dir, rules);
         }
         return rules;
     };
-    /** Whether the rules of `root` and of each directory down to one path's own decide it ignored. */
     const decided = (path, directory) => {
-        const dirs = [];
-        for (let at = dirnamePath(path); relativePath(root, at) !== undefined; at = dirnamePath(at)) {
-            dirs.unshift(at);
-        }
-        dirs.unshift(root);
+        const sources = [
+            ...(repository === undefined ? [] : [[repository, excluded]]),
+            ...[...above, ...[...ancestors(dirnamePath(path), root)].reverse()].map((dir) => [dir, rulesAt(dir)]),
+        ];
         let ignored = false;
-        for (const dir of dirs) {
-            const below = relativePath(dir, path);
-            for (const rule of below === undefined ? [] : rulesAt(dir)) {
-                if ((directory || !rule.directoryOnly) && rule.expression.test(below ?? "")) {
+        for (const [dir, rules] of sources) {
+            const below = relativePath(dir, path) ?? "";
+            for (const rule of rules) {
+                if ((directory || !rule.directoryOnly) && rule.expression.test(below)) {
                     ignored = !rule.negated;
                 }
             }

package/dist/src/import-bindings.js

@@ -2,7 +2,7 @@
  * The import bindings of one file: the names its import declarations bind, which only
  * the file itself can read.
  */
-import { isExportSpecifier, isExternalModuleReference, isIdentifier, isImportDeclaration, isImportEqualsDeclaration, isJsxElement, isJsxFragment, isJsxSelfClosingElement, isNamespaceImport, SyntaxKind, } from "@typescript/native/ast";
+import { isExportDeclaration, isExportSpecifier, isExternalModuleReference, isImportDeclaration, isImportEqualsDeclaration, isJsxElement, isJsxFragment, isJsxSelfClosingElement, isNamedExports, isNamespaceImport, SyntaxKind, } from "@typescript/native/ast";
 /** The extensions of the files whose import bindings are judged: no markup can read them. */
 const JUDGED = /\.(?:[mc]?ts|tsx|[mc]?js|jsx)$/u;
 /** The compiler's `jsx` settings whose emit calls no factory the file must hold. */
@@ -13,41 +13,86 @@ const DOC_COMMENT = /\/\*\*[\s\S]*?\*\//gu;
 const DOC_REFERENCE = /\{[^{}]*\}|@see\s+[A-Za-z_$][\w$.]*/gu;
 /** The factory a pragma comment names: `@jsx h` or `@jsxFrag Fragment`. */
 const PRAGMA = /@jsx(?:Frag)?\s+([A-Za-z_$][\w$]*)/gu;
+const bindingsCache = new WeakMap();
 /**
- * The names one file's import declarations bind: the default, named and namespace names of
- * an `import` declaration, and the name of an `import x = require()` declaration that is
- * not exported. None is judged in a declaration file or a component file.
+ * Every name one import declaration binds, in source order: the default, named and
+ * namespace names of an `import` declaration and the name of an `import x = …` declaration.
+ * A namespace import and an import assignment bind a whole module.
  */
-export function importBindings(file) {
-    if (file.isDeclarationFile || !JUDGED.test(file.fileName)) {
-        return [];
+export function declarationBindings(declaration) {
+    if (isImportEqualsDeclaration(declaration)) {
+        return [
+            {
+                name: declaration.name,
+                equals: {
+                    exported: (declaration.modifiers ?? []).some((modifier) => modifier.kind === SyntaxKind.ExportKeyword),
+                    external: isExternalModuleReference(declaration.moduleReference),
+                },
+            },
+        ];
     }
+    const clause = declaration.importClause;
     const found = [];
-    for (const statement of file.statements) {
-        if (isImportDeclaration(statement)) {
-            const clause = statement.importClause;
-            if (clause?.name !== undefined) {
-                found.push(clause.name);
-            }
-            const named = clause?.namedBindings;
-            if (named !== undefined && isNamespaceImport(named)) {
-                found.push(named.name);
-            }
-            else if (named !== undefined) {
-                for (const element of named.elements) {
-                    found.push(element.name);
-                }
-            }
-        }
-        else if (isImportEqualsDeclaration(statement) &&
-            isExternalModuleReference(statement.moduleReference) &&
-            isIdentifier(statement.name) &&
-            !(statement.modifiers ?? []).some((modifier) => modifier.kind === SyntaxKind.ExportKeyword)) {
-            found.push(statement.name);
+    if (clause?.name !== undefined) {
+        found.push({ name: clause.name, imported: "default" });
+    }
+    const named = clause?.namedBindings;
+    if (named !== undefined && isNamespaceImport(named)) {
+        found.push({ name: named.name });
+    }
+    else if (named !== undefined) {
+        for (const element of named.elements) {
+            found.push({ name: element.name, imported: element.propertyName?.text ?? element.name.text });
         }
     }
     return found;
 }
+/** Every name one file's top-level import declarations bind, in source order. */
+export function bindingsOf(file) {
+    const known = bindingsCache.get(file);
+    if (known !== undefined) {
+        return known;
+    }
+    const found = file.statements.flatMap((statement) => isImportDeclaration(statement) || isImportEqualsDeclaration(statement)
+        ? declarationBindings(statement)
+        : []);
+    bindingsCache.set(file, found);
+    return found;
+}
+/**
+ * The export names an import or a re-export declaration reads from the module it names,
+ * `undefined` standing for the whole module where a namespace or a star reads it; none for
+ * any other node.
+ */
+export function importedNames(node) {
+    if (isImportDeclaration(node)) {
+        return declarationBindings(node).map((binding) => binding.imported);
+    }
+    if (!isExportDeclaration(node)) {
+        return [];
+    }
+    const clause = node.exportClause;
+    return clause === undefined || !isNamedExports(clause)
+        ? [undefined]
+        : clause.elements.map((one) => (one.propertyName ?? one.name).text);
+}
+/** The export names {@link importedNames} gives one node, without the whole module. */
+export function namesImported(node) {
+    return importedNames(node).flatMap((name) => name ?? []);
+}
+/**
+ * The bindings of one file that are judged as imports: those of {@link bindingsOf} but an
+ * `import x = …` that is exported or names no external module. None is judged in a
+ * declaration file or a component file.
+ */
+export function importBindings(file) {
+    if (file.isDeclarationFile || !JUDGED.test(file.fileName)) {
+        return [];
+    }
+    return bindingsOf(file).flatMap((binding) => binding.equals !== undefined && (binding.equals.exported || !binding.equals.external)
+        ? []
+        : [binding.name]);
+}
 /** Whether one identifier names a binding in a local export, which reads it whatever it resolves to. */
 export function exportsLocally(use) {
     return isExportSpecifier(use.parent);