@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/dist/src/generated-file.js

@@ -1,13 +1,20 @@
 /**
  * The generated-file class on TypeScript: every declaration in a file that marks itself
- * generated, or below a directory an applied convention row names as generated, is
- * retained, because a generator owns the file and a deletion there is undone at the next
+ * generated, below a directory an applied convention row names as generated, or minified,
+ * is retained, because a generator owns the file and a deletion there is undone at the next
  * generation.
  */
+import { minified } from "./javascript-file.js";
 /** The generated-code header, matched against each line of a leading comment. */
 const HEADER_LINE = /^\/\/ Code generated .* DO NOT EDIT\.$/u;
 /** The documentation tag `@generated` as a word of a comment. */
 const GENERATED_TAG = /(?<![\w@$])@generated(?![\w$-])/u;
+/** A first comment naming the tool that wrote the file. */
+const GENERATED_BY = /^\/\/ Generated by \S/u;
+/** The word a generator's notice holds, beside one of {@link KEEP_OUT}. */
+const GENERATED_WORD = /\bgenerated\b/iu;
+/** The phrases a generator's notice asks a reader not to edit the file by. */
+const KEEP_OUT = /\b(?:do not edit|will be overwritten|should not make any changes)\b/iu;
 /** The comments before a text's first token, a leading hashbang line skipped. */
 function leadingComments(text) {
     const comments = [];
@@ -48,12 +55,17 @@ export function generatedByComment(text) {
     if (comments.some((one) => GENERATED_TAG.test(one))) {
         return "generated by the @generated tag its leading comments hold";
     }
+    const notice = comments.join("\n");
+    if (GENERATED_BY.test(comments[0] ?? "") ||
+        (GENERATED_WORD.test(notice) && KEEP_OUT.test(notice))) {
+        return "generated by the notice its leading comments hold";
+    }
     return undefined;
 }
 /**
  * Every own file of one project that is generated, by its path below the target root,
  * with the detail a retention in it names: its leading comments' mark, else the row
- * naming its directory as generated.
+ * naming its directory as generated, else its minified text.
  */
 export function generatedFilesOf(files, byRow) {
     const found = new Map();
@@ -61,7 +73,9 @@ export function generatedFilesOf(files, byRow) {
         const row = byRow.get(path);
         const detail = generatedByComment(file.text) ??
             (row === undefined
-                ? undefined
+                ? minified(file.fileName, file.text)
+                    ? "generated as a minified JavaScript file"
+                    : undefined
                 : `generated below a directory the convention row ${row} names`);
         if (detail !== undefined) {
             found.set(path, detail);

package/dist/src/git-ignore.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { 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)) {
+        let line = raw.replace(/(?<!\\)\s+$/u, "");
+        if (line === "" || line.startsWith("#")) {
+            continue;
+        }
+        const negated = line.startsWith("!");
+        line = negated ? line.slice(1) : line;
+        const directoryOnly = line.endsWith("/");
+        line = line.replace(/\/+$/u, "");
+        if (line === "") {
+            continue;
+        }
+        // A separator at the start or in the middle anchors the pattern to the file's
+        // directory; with none, the pattern matches at any depth below it.
+        const anchored = line.includes("/");
+        const pattern = line.replace(/^\//u, "");
+        rules.push({
+            negated,
+            directoryOnly,
+            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 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, 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) {
+            rules = rulesIn(host, joinPath(dir, ".gitignore"), unread);
+            read.set(dir, rules);
+        }
+        return rules;
+    };
+    const decided = (path, directory) => {
+        const sources = [
+            ...(repository === undefined ? [] : [[repository, excluded]]),
+            ...[...above, ...[...ancestors(dirnamePath(path), root)].reverse()].map((dir) => [dir, rulesAt(dir)]),
+        ];
+        let ignored = false;
+        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;
+                }
+            }
+        }
+        return ignored;
+    };
+    return (path) => {
+        const below = relativePath(root, path);
+        if (below === undefined) {
+            return false;
+        }
+        const parts = below.split("/");
+        for (let count = 1; count <= parts.length; count += 1) {
+            const at = joinPath(root, parts.slice(0, count).join("/"));
+            if (decided(at, count < parts.length)) {
+                return true;
+            }
+        }
+        return false;
+    };
+}

package/dist/src/graph.js

@@ -34,9 +34,9 @@ const SWEPT = {
  * Whether a root of each kind names a caller, which holds it live under both relations: a
  * tool reads what it loads and what its strings name, a runtime runs a test, setup or
  * worker file, a page's module script, a command, a script or a workflow step, the manifest
- * names what enters the package, an alias global stands for its export, and an entry file,
- * a configured root and a pattern assert a caller. A library's published API only supposes
- * an unseen consumer, so it is live under reachability alone.
+ * names what enters the package, an alias global stands for its export, an outside
+ * declaration names a global interface merging into it, and an entry file, a configured root
+ * and a pattern assert a caller. A published API supposes a consumer: reachability alone.
  */
 const NAMES_A_CALLER = {
     "entry-file": true,
@@ -49,13 +49,17 @@ const NAMES_A_CALLER = {
     pattern: true,
     "type-error": true,
     "type-query-alias": true,
+    "global-augmentation": true,
     "configuration-file": true,
     "configuration-string": true,
+    "bundler-entry": true,
     "test-runner": true,
     "browser-tests": true,
     worker: true,
     "html-entry": true,
     "workflow-step": true,
+    "computed-import": true,
+    "document-import": true,
 };
 /** Whether the sweep judges a declaration of one kind. */
 export function swept(kind) {
@@ -72,7 +76,7 @@ export function namesACaller(kind) {
  * from such a declaration still counts toward its target, because reference counting
  * asks whether any declaration names the target. A root naming nothing is dropped.
  */
-export function graphOf(symbols, references, roots, testFiles, supportFiles = []) {
+export function graphOf(symbols, references, roots, testFiles, supportFiles = [], ambient = new Set()) {
     const supports = new Set(supportFiles);
     const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
     const at = (id) => index.get(id) ?? OUTSIDE;
@@ -123,6 +127,7 @@ export function graphOf(symbols, references, roots, testFiles, supportFiles = []
         parent,
         test: symbols.map((symbol) => tests.has(symbol.position.path)),
         support: symbols.map((symbol) => supports.has(symbol.position.path)),
+        ambient: symbols.map((symbol) => ambient.has(symbol.id)),
         subject: symbols.map((symbol) => swept(symbol.kind)),
         exportsOf,
         rooted,

package/dist/src/html-entries.js

@@ -5,9 +5,9 @@
  */
 import { isExportDeclaration, isImportDeclaration, isStringLiteral, } from "@typescript/native/ast";
 import { resolveRelativeSpecifier } from "./configuration-files.js";
-import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
-/** The directory no HTML file is read below. */
-const SKIPPED = "node_modules";
+import { ancestors, dirnamePath, joinPath, resolvePath } from "./paths.js";
+import { filesBelow } from "./fs/tree.js";
+import { holdsManifest } from "./fs/manifest.js";
 /** A `<script` start tag, its attribute text captured. */
 const SCRIPT_TAG = /<script(?=[\s>/])([^>]*)>/giu;
 /** The end tag an inline module script's content runs to. */
@@ -20,29 +20,6 @@ const ELSEWHERE = /^(?:\/\/|[A-Za-z][A-Za-z\d+.-]*:)/u;
 const CLASSIC_TYPES = new Set(["text/javascript", "application/javascript"]);
 /** The prefixes an inline script's specifier names a file of the target with. */
 const FILE_PREFIXES = ["/", "./", "../"];
-/** Every HTML file below `dir`, outside every `node_modules` directory, by absolute path. */
-function htmlFiles(host, dir) {
-    let entries;
-    try {
-        entries = host.readDirectory(dir);
-    }
-    catch {
-        return [];
-    }
-    const found = [];
-    for (const entry of entries) {
-        const path = joinPath(dir, entry.name);
-        if (entry.directory) {
-            if (entry.name !== SKIPPED) {
-                found.push(...htmlFiles(host, path));
-            }
-        }
-        else if (entry.name.endsWith(".html")) {
-            found.push(path);
-        }
-    }
-    return found.sort();
-}
 /** Each attribute of one start tag's attribute text, by its lowercase name. */
 function attributes(text) {
     const found = new Map();
@@ -98,12 +75,7 @@ function scriptValues(parse, path, text) {
 }
 /** The directory of the nearest `package.json` at or above `dir`, inside `root`, else `root`. */
 function manifestDirectory(host, root, dir) {
-    for (let at = dir; relativePath(root, at) !== undefined; at = dirnamePath(at)) {
-        if (host.kindOf(joinPath(at, "package.json")) === "file") {
-            return at;
-        }
-    }
-    return root;
+    return ancestors(dir, root).find((at) => holdsManifest(host, at)) ?? root;
 }
 /**
  * The own files the scripts of every HTML file below the target root load. A value
@@ -115,7 +87,8 @@ function manifestDirectory(host, root, dir) {
 export function htmlEntries(host, targetRoot, files, parse) {
     const root = resolvePath(host.workingDirectory(), targetRoot);
     const found = [];
-    for (const path of htmlFiles(host, root)) {
+    for (const below of filesBelow(host, root, (name) => name.endsWith(".html"))) {
+        const path = joinPath(root, below);
         let text;
         try {
             text = host.readFile(path);

package/dist/src/import-bindings.js

@@ -0,0 +1,97 @@
+/**
+ * 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";
+/** 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. */
+const AUTOMATIC_RUNTIME = new Set([4, 5, "react-jsx", "react-jsxdev"]);
+/** A doc comment, where a JavaScript file names the types it imports. */
+const DOC_COMMENT = /\/\*\*[\s\S]*?\*\//gu;
+/** The parts of a doc comment the compiler resolves names in: a `{…}` type or link, a `@see` target. */
+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;
+/**
+ * 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.
+ */
+export function importBindings(file) {
+    if (file.isDeclarationFile || !JUDGED.test(file.fileName)) {
+        return [];
+    }
+    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);
+        }
+    }
+    return found;
+}
+/** 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);
+}
+/**
+ * The names a file reads without an identifier the program resolves: each name a type, a
+ * link or a `@see` tag of its doc comments spells, and, where it writes JSX the compiler
+ * turns into factory calls, the factories the configuration or a pragma names.
+ */
+export function implicitReads(file, options) {
+    const names = new Set();
+    for (const comment of file.text.match(DOC_COMMENT) ?? []) {
+        for (const reference of comment.match(DOC_REFERENCE) ?? []) {
+            for (const word of reference.match(/[A-Za-z_$][\w$]*/gu) ?? []) {
+                names.add(word);
+            }
+        }
+    }
+    if (AUTOMATIC_RUNTIME.has(options.jsx) || !writesJsx(file)) {
+        return names;
+    }
+    for (const factory of [options.jsxFactory, options.jsxFragmentFactory]) {
+        names.add(typeof factory === "string" ? (factory.split(".")[0] ?? factory) : "React");
+    }
+    for (const match of file.text.matchAll(PRAGMA)) {
+        if (match[1] !== undefined) {
+            names.add(match[1]);
+        }
+    }
+    return names;
+}
+/** Whether a file holds a JSX element or fragment. */
+function writesJsx(file) {
+    let found = false;
+    const visit = (node) => {
+        if (found) {
+            return;
+        }
+        if (isJsxElement(node) || isJsxSelfClosingElement(node) || isJsxFragment(node)) {
+            found = true;
+            return;
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}

package/dist/src/in-operands.js

@@ -5,6 +5,7 @@
  */
 import { isBinaryExpression, isNoSubstitutionTemplateLiteral, isStringLiteral, SyntaxKind, } from "@typescript/native/ast";
 import { sourceFilesOf } from "./source-files.js";
+import { bytewise } from "./text/compare.js";
 /**
  * The text of each string literal, or template literal with no substitution, written as
  * the left operand of an `in` expression in a file of the project that is no test file.
@@ -26,5 +27,5 @@ export function inOperandNames(project, targetRoot, testFiles) {
             file.forEachChild(visit);
         }
     }
-    return [...found].sort();
+    return [...found].sort(bytewise);
 }

package/dist/src/index.js

@@ -2,4 +2,4 @@ export { run, SETTING_OPTIONS } from "./run.js";
 export { DECLINED_CONVENTIONS } from "./entry-point-gaps.js";
 export { byPosition, positionKey, PositionError, renderPosition, } from "./position.js";
 export { computedComponent, isRef, nameComponent, REF_EXPRESSIONS, renderRef, } from "./ref.js";
-export { CONTRACT_VERSION } from "./version.js";
+export { CONTRACT_VERSION } from "./contract/contract.generated.js";