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

package/dist/src/{framework-lifecycle.js → exemptions/framework-lifecycle.js}

@@ -1,23 +1,47 @@
 /**
- * The framework-lifecycle class: a member a `ts.lifecycle_contracts` entry lists is held
- * back on each class that is the entry's component, being a class a decorator or a call
- * the entry's `components` name is attached to or passes, or one extending, directly or
- * through a chain, a class its `bases` name. A component's members are its type's, so a
- * member a base class declares answers for every subclass.
+ * The framework-lifecycle class: a member a lifecycle contract lists is held back on each
+ * class that is the contract's component, being a class a decorator or a call the
+ * contract's `components` name is attached to or passes, or one extending, directly or
+ * through a chain, a class its `bases` name. The contracts are the platform's custom
+ * elements and each `ts.lifecycle_contracts` entry. A component's members are its type's,
+ * so a member a base class declares answers for every subclass.
  */
-import { isClassDeclaration, isClassExpression, isHeritageClause, SyntaxKind, } from "@typescript/native/ast";
-import { aliasChains } from "./alias-chain.js";
-import { calleeName, callsOf, classesPassed, decoratedClasses, decoratorCallee } from "./calls.js";
-import { classMembers, memberComponent, typesAt } from "./class-members.js";
-import { entriesAt, names, namesADeclaration, resolveEntries, spelledEntry, } from "./configured-declarations.js";
-import { nodeKey } from "./inventory.js";
-import { renderPosition } from "./position.js";
-import { must } from "./query.js";
+import { isHeritageClause, SyntaxKind, } from "@typescript/native/ast";
+import { aliasChains } from "../alias-chain.js";
+import { nameOf } from "../index/values.js";
+import { classesPassed, decoratorCallee, decoratorsOf } from "./calls.js";
+import { classMembers, memberComponent, typesAt } from "../class-members.js";
+import { entriesAt, names, namesADeclaration, resolveEntries, spelledEntry, } from "../roots/configured-declarations.js";
+import { renderPosition } from "../position.js";
+import { must } from "../query.js";
+/**
+ * The platform's own contract (references-ts.38): `CustomElementRegistry.define` reads
+ * these members off the class it registers, its constructor's and its prototype's
+ * (https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-define),
+ * and calls each callback as a custom element reaction.
+ */
+const CUSTOM_ELEMENTS = {
+    components: [{ global: "CustomElementRegistry.define" }],
+    members: [
+        "observedAttributes:static",
+        "disabledFeatures:static",
+        "formAssociated:static",
+        "connectedCallback",
+        "disconnectedCallback",
+        "connectedMoveCallback",
+        "adoptedCallback",
+        "attributeChangedCallback",
+        "formAssociatedCallback",
+        "formResetCallback",
+        "formDisabledCallback",
+        "formStateRestoreCallback",
+    ],
+};
 /** Every contract's components and bases, resolved in one pass over the entries. */
 function resolveContracts(project, held, contracts) {
     const entries = contracts.flatMap((contract) => [
-        ...contract.components,
-        ...contract.bases,
+        ...(contract.components ?? []),
+        ...(contract.bases ?? []),
     ]);
     const resolved = resolveEntries(project, held, entries);
     let next = 0;
@@ -28,21 +52,25 @@ function resolveContracts(project, held, contracts) {
     };
     return contracts.map((contract) => ({
         contract,
-        components: take(contract.components.length),
-        bases: take(contract.bases.length),
+        components: take(contract.components?.length ?? 0),
+        bases: take(contract.bases?.length ?? 0),
     }));
 }
 /** The classes a decorator or a call the contracts' components name makes a component. */
-function byComponents(project, held, chains, contracts) {
+function byComponents(project, held, sites, chains, contracts) {
     const routed = contracts.filter((one) => one.components.length > 0);
     if (routed.length === 0) {
         return [];
     }
     const contractOf = new Map(routed.flatMap((one) => one.components.map((entry) => [entry, one.contract])));
-    const calls = callsOf(project);
-    const decorated = decoratedClasses(project, held);
+    const calls = sites.calls.map((one) => one.call);
+    const invoked = (call) => nameOf(sites.invocations.of(call).callee);
+    const decorated = sites.classes.flatMap(({ id, node }) => {
+        const decorators = decoratorsOf(node);
+        return decorators.length === 0 ? [] : [{ id, decorators }];
+    });
     const named = entriesAt(project, chains, [
-        ...calls.flatMap((call) => calleeName(call.expression) ?? []),
+        ...calls.flatMap((call) => invoked(call) ?? []),
         ...decorated.flatMap((one) => one.decorators.flatMap((decorator) => decoratorCallee(decorator) ?? [])),
     ], [...contractOf.keys()]);
     const naming = (node) => (node === undefined ? [] : (named.get(node) ?? [])).flatMap((entry) => {
@@ -59,12 +87,12 @@ function byComponents(project, held, chains, contracts) {
     }
     const matched = new Map();
     for (const call of calls) {
-        const routes = naming(calleeName(call.expression));
+        const routes = naming(invoked(call));
         if (routes.length > 0) {
             matched.set(call, routes);
         }
     }
-    for (const [call, uses] of classesPassed(project, held, chains, [...matched.keys()])) {
+    for (const [call, uses] of classesPassed(project, held, chains, sites, [...matched.keys()])) {
         for (const route of matched.get(call) ?? []) {
             for (const use of uses) {
                 found.push({
@@ -78,32 +106,23 @@ function byComponents(project, held, chains, contracts) {
     }
     return found;
 }
-/** The class declarations of the target that extend another class. */
-function extendingClasses(project, held) {
-    const found = [];
-    for (const file of project.ownSourceFiles()) {
-        const visit = (node) => {
-            if ((isClassDeclaration(node) || isClassExpression(node)) && node.name !== undefined) {
-                const id = held.declarations.get(nodeKey(file, node));
-                const clause = (node.heritageClauses ?? []).find((one) => isHeritageClause(one) && one.token === SyntaxKind.ExtendsKeyword);
-                const extended = clause !== undefined && isHeritageClause(clause) ? clause.types[0] : undefined;
-                if (id !== undefined && extended !== undefined) {
-                    found.push({ id, name: node.name, extended });
-                }
-            }
-            node.forEachChild(visit);
-        };
-        file.forEachChild(visit);
-    }
-    return found;
+/** Each named class of the target that extends another, with its name and the class its `extends` names. */
+function extendingClasses(sites) {
+    return sites.classes.flatMap(({ id, node }) => {
+        const clause = (node.heritageClauses ?? []).find((one) => isHeritageClause(one) && one.token === SyntaxKind.ExtendsKeyword);
+        const extended = clause !== undefined && isHeritageClause(clause) ? clause.types[0] : undefined;
+        return node.name === undefined || extended === undefined
+            ? []
+            : [{ id, name: node.name, extended }];
+    });
 }
 /** The classes that extend, directly or through a chain, a class the contracts' bases name. */
-function byBases(project, held, chains, contracts) {
+function byBases(project, held, sites, chains, contracts) {
     const based = contracts.filter((one) => one.bases.length > 0);
     if (based.length === 0) {
         return [];
     }
-    const classes = extendingClasses(project, held);
+    const classes = extendingClasses(sites);
     if (classes.length === 0) {
         return [];
     }
@@ -155,40 +174,43 @@ function byBases(project, held, chains, contracts) {
 }
 /**
  * The framework-lifecycle detector: each member a contract lists, on each class that
- * is a component of that contract's framework, recorded where the class was found to
- * be one.
+ * is a component of that contract's framework, recorded once per place where the class
+ * was found to be one.
  */
 export function frameworkLifecycle(input) {
     const { project, held, targetRoot } = input;
-    if (input.ts.lifecycleContracts.length === 0) {
+    const declared = [CUSTOM_ELEMENTS, ...input.ts.lifecycle_contracts];
+    const contracts = resolveContracts(project, held, declared);
+    if (contracts.every((one) => one.components.length === 0 && one.bases.length === 0)) {
         return [];
     }
     const chains = aliasChains(project, held);
-    const contracts = resolveContracts(project, held, input.ts.lifecycleContracts);
     const components = [
-        ...byComponents(project, held, chains, contracts),
-        ...byBases(project, held, chains, contracts),
+        ...byComponents(project, held, input.sites, chains, contracts),
+        ...byBases(project, held, input.sites, chains, contracts),
     ];
     if (components.length === 0) {
         return [];
     }
     const ids = new Set(components.map((one) => one.id));
-    const sides = input.ts.lifecycleContracts.some((contract) => contract.members.some((name) => name.endsWith(":static")))
+    const sides = declared.some((contract) => contract.members.some((name) => name.endsWith(":static")))
         ? ["instance", "static"]
         : ["instance"];
     const members = sides.map((side) => classMembers(project, held, ids, side));
     const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
-    const found = [];
+    const found = new Map();
     for (const component of components) {
         const listed = new Set(component.contract.members);
         const site = renderPosition(component.site.getSourceFile(), targetRoot, component.site.getStart());
         for (const member of members.flatMap((side) => side.get(component.id) ?? [])) {
             const symbol = byId.get(member.id);
             const spelled = symbol === undefined ? undefined : memberComponent(symbol, byId);
-            if (spelled !== undefined && listed.has(spelled)) {
-                found.push({ id: member.id, detail: component.detail, site });
+            // A configured contract may name the platform's registry too; one record answers both.
+            const key = `${member.id}\0${component.detail}\0${site.path}:${String(site.line)}:${String(site.column)}`;
+            if (spelled !== undefined && listed.has(spelled) && !found.has(key)) {
+                found.set(key, { id: member.id, detail: component.detail, site });
             }
         }
     }
-    return found;
+    return [...found.values()];
 }

package/dist/src/exemptions/generated-file.js

@@ -0,0 +1,241 @@
+/**
+ * The generated-file class on TypeScript: every declaration in a file that marks itself
+ * 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. The same decision is each `generated` entry of the facts document.
+ */
+import { isIdentifier, isImportDeclaration, isPropertyAssignment, isStringLiteralLikeNode, isVariableStatement, NodeFlags, } from "@typescript/native/ast";
+import { GENERATORS } from "../contract/contract.generated.js";
+import { minifiedBy } from "../javascript-file.js";
+import { bytewise } from "../text/compare.js";
+import { satisfies } from "../version-range.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, each as its lines. */
+function leadingComments(text) {
+    const comments = [];
+    const lineAt = (offset) => text.slice(0, offset).split(/\r\n|[\n\r\u2028\u2029]/u).length;
+    const lines = (from, to) => {
+        const first = lineAt(from);
+        return text
+            .slice(from, to)
+            .split(/\r\n|[\n\r\u2028\u2029]/u)
+            .map((one, index) => ({ text: one, line: first + index }));
+    };
+    let at = text.startsWith("\uFEFF") ? 1 : 0;
+    if (text.startsWith("#!", at)) {
+        const end = text.indexOf("\n", at);
+        at = end === -1 ? text.length : end + 1;
+    }
+    for (;;) {
+        while (at < text.length && /\s/u.test(text.charAt(at))) {
+            at++;
+        }
+        if (text.startsWith("//", at)) {
+            const end = text.slice(at).search(/[\r\n\u2028\u2029]/u);
+            const stop = end === -1 ? text.length : at + end;
+            comments.push(lines(at, stop));
+            at = stop;
+        }
+        else if (text.startsWith("/*", at)) {
+            const end = text.indexOf("*/", at + 2);
+            if (end === -1) {
+                return comments;
+            }
+            comments.push(lines(at, end + 2));
+            at = end + 2;
+        }
+        else {
+            return comments;
+        }
+    }
+}
+/** The mark one file's leading comments make it generated by, or undefined where they mark nothing. */
+export function generatedMark(text) {
+    const lines = leadingComments(text).flat();
+    const header = lines.find((one) => HEADER_LINE.test(one.text));
+    if (header !== undefined) {
+        return { evidence: "header", line: header.line, detail: header.text };
+    }
+    const tag = lines.find((one) => GENERATED_TAG.test(one.text));
+    if (tag !== undefined) {
+        return { evidence: "tag", line: tag.line, detail: tag.text };
+    }
+    const [first] = lines;
+    if (first !== undefined && GENERATED_BY.test(first.text)) {
+        return { evidence: "notice", line: first.line, detail: first.text };
+    }
+    const notice = lines.map((one) => one.text).join("\n");
+    if (GENERATED_WORD.test(notice) && KEEP_OUT.test(notice)) {
+        const marked = lines.find((one) => GENERATED_WORD.test(one.text) || KEEP_OUT.test(one.text));
+        return marked === undefined
+            ? undefined
+            : { evidence: "notice", line: marked.line, detail: marked.text };
+    }
+    return undefined;
+}
+/** What one form's first group captures, for each line the form matches. */
+function after(lines, form) {
+    return lines.flatMap((one) => form.exec(one.text)?.[1] ?? []);
+}
+/**
+ * Where each plugin's output states its version and its schema files, as `references-ts.36`
+ * states: a plugin missing here states no version, and one with no schema form names none.
+ */
+const STATEMENTS = {
+    "protoc-gen-es": {
+        version: /^\/\/ @generated by protoc-gen-es (\S+)/u,
+        schemaFiles: /^\/\/ @generated from file (\S+)/u,
+    },
+    "protoc-gen-connect-es": {
+        version: /^\/\/ @generated by protoc-gen-connect-es (\S+)/u,
+        schemaFiles: /^\/\/ @generated from file (\S+)/u,
+    },
+    "protobuf-ts": {
+        version: /^\/\/ @generated by protobuf-ts (\S+)/u,
+        schemaFiles: /^\/\/ @generated from protobuf file "([^"]+)"/u,
+    },
+    "ts-proto": {
+        version: /^\/\/\s+protoc-gen-ts_proto\s+(\S+)$/u,
+        schemaFiles: /^\/\/ source: (.+)$/u,
+    },
+    "protoc-gen-grpc-web": {
+        version: /^\/\/\s+protoc-gen-grpc-web\s+(\S+)$/u,
+        schemaFiles: /^\/\/ source: (.+)$/u,
+    },
+    "protoc-gen-js": { schemaFiles: /^\/\/ source: (.+)$/u },
+    "ts-protoc-gen": { schemaFiles: /^\/\/ file: (.+)$/u },
+};
+/** A ts-proto service path literal: `/<package>.<service>/<method>`. */
+const SERVICE_PATH = /^\/(?:\w+\.)+\w+\/\w+$/u;
+/** Whether one ts-proto file writes a service path, as `references-ts.36` reads one. */
+function writesServicePath(file) {
+    const named = file.statements.some((statement) => isVariableStatement(statement) &&
+        (statement.declarationList.flags & NodeFlags.Const) !== 0 &&
+        statement.declarationList.declarations.some((one) => isIdentifier(one.name) &&
+            one.name.text.endsWith("ServiceName") &&
+            one.initializer !== undefined &&
+            isStringLiteralLikeNode(one.initializer)));
+    let found = named;
+    const visit = (node) => {
+        if (found) {
+            return;
+        }
+        if (isPropertyAssignment(node) &&
+            isIdentifier(node.name) &&
+            node.name.text === "path" &&
+            isStringLiteralLikeNode(node.initializer) &&
+            SERVICE_PATH.test(node.initializer.text)) {
+            found = true;
+            return;
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/** Whether one file imports a module by its specifier. */
+function imports(file, module) {
+    return file.statements.some((statement) => isImportDeclaration(statement) &&
+        isStringLiteralLikeNode(statement.moduleSpecifier) &&
+        statement.moduleSpecifier.text === module);
+}
+/** The option sets the rows of `references-ts.36` name, by row; every other row's is met by any output. */
+const OPTION_SETS = {
+    "ts-proto-2-output-schema": (file) => imports(file, "ts-proto-descriptors"),
+    "ts-proto-2": writesServicePath,
+    "ts-proto-2-types": (file) => !writesServicePath(file),
+};
+/** The first generator row one file matches, in `generators.json`'s order, as `bindings.3` reads it. */
+export function generatorOf(file) {
+    const lines = leadingComments(file.text).flat();
+    for (const row of GENERATORS) {
+        const header = new RegExp(row.header, "u");
+        if (!lines.some((one) => header.test(one.text))) {
+            continue;
+        }
+        const statements = STATEMENTS[row.plugin] ?? {};
+        const [version] = statements.version === undefined ? [] : after(lines, statements.version);
+        if ("versions" in row &&
+            (version === undefined ||
+                !satisfies(version.replace(/^v/u, ""), `>=${row.versions.min.replace(/^v/u, "")} <=${row.versions.max.replace(/^v/u, "")}`))) {
+            continue;
+        }
+        if (OPTION_SETS[row.id]?.(file) === false) {
+            continue;
+        }
+        const schemaFiles = statements.schemaFiles === undefined
+            ? []
+            : [
+                ...new Set(after(lines, statements.schemaFiles).filter((one) => one.endsWith(".proto"))),
+            ].sort(bytewise);
+        return { row: row.id, ...(version === undefined ? {} : { version }), schemaFiles };
+    }
+    return undefined;
+}
+/**
+ * Every own file of one project that is generated, by its path below the target root, with
+ * what decided it: its leading comments' mark, else the row naming its directory as
+ * generated, else its minified name or text; and the generator row it matches.
+ */
+export function generatedFilesOf(files, byRow) {
+    const found = new Map();
+    for (const [path, file] of files.byPath) {
+        const row = byRow.get(path);
+        const minified = row === undefined ? minifiedBy(file.fileName, file.text) : undefined;
+        const fact = generatedMark(file.text) ??
+            (row === undefined
+                ? minified === undefined
+                    ? undefined
+                    : { evidence: "minified", line: 1, detail: minified }
+                : { evidence: "convention", line: 1, detail: row });
+        if (fact === undefined) {
+            continue;
+        }
+        const generator = generatorOf(file);
+        found.set(path, generator === undefined ? fact : { ...fact, generator });
+    }
+    return found;
+}
+/** The detail a retention in a generated file names, from what decided the file. */
+function retentionDetail(fact) {
+    switch (fact.evidence) {
+        case "header":
+            return "generated by the header line its leading comments hold";
+        case "tag":
+            return "generated by the @generated tag its leading comments hold";
+        case "notice":
+            return "generated by the notice its leading comments hold";
+        case "convention":
+            return `generated below a directory the convention row ${fact.detail} names`;
+        case "minified":
+            return "generated as a minified JavaScript file";
+    }
+}
+/** The generated-file detector, recording each file's first line. */
+export function generatedFile(input) {
+    const generated = input.generated;
+    if (generated === undefined || generated.size === 0) {
+        return [];
+    }
+    return input.held.symbols.flatMap((symbol) => {
+        const fact = generated.get(symbol.position.path);
+        return symbol.kind === "file" || fact === undefined
+            ? []
+            : [
+                {
+                    id: symbol.id,
+                    detail: retentionDetail(fact),
+                    site: { path: symbol.position.path, line: 1, column: 1 },
+                },
+            ];
+    });
+}

package/dist/src/{injection-container.js → exemptions/injection-container.js}

@@ -6,13 +6,14 @@
  * parameter property is injected, decorated or not. A constructor is no declaration of
  * the inventory, so the class stands for it and the registration referencing it keeps it.
  */
-import { isClassDeclaration, isClassExpression, isConstructorDeclaration, isGetAccessorDeclaration, isPropertyDeclaration, isSetAccessorDeclaration, } from "@typescript/native/ast";
-import { aliasChains } from "./alias-chain.js";
-import { calleeName, callsOf, classesPassed, decoratorsOf, spelledDecorator } from "./calls.js";
-import { classMembers } from "./class-members.js";
-import { entriesAt, namesADeclaration, resolveEntries, spelledEntry, } from "./configured-declarations.js";
-import { isParameterProperty, nodeKey } from "./inventory.js";
-import { renderPosition } from "./position.js";
+import { isConstructorDeclaration, isGetAccessorDeclaration, isPropertyDeclaration, isSetAccessorDeclaration, } from "@typescript/native/ast";
+import { aliasChains } from "../alias-chain.js";
+import { nameOf } from "../index/values.js";
+import { classesPassed, decoratorsOf, spelledDecorator } from "./calls.js";
+import { classMembers } from "../class-members.js";
+import { entriesAt, namesADeclaration, resolveEntries, spelledEntry, } from "../roots/configured-declarations.js";
+import { isParameterProperty } from "../inventory.js";
+import { renderPosition } from "../position.js";
 /** Whether one member declaration is a parameter property, or a property or accessor carrying a decorator. */
 function isInjected(node) {
     return (isParameterProperty(node) ||
@@ -23,23 +24,24 @@ function isInjected(node) {
 }
 /** The classes of the target a call whose callee an entry names passes, with that call's entry. */
 function registrations(input) {
-    const { project, held } = input;
-    const resolved = resolveEntries(project, held, input.ts.injectionRegistrations);
+    const { project, held, sites } = input;
+    const resolved = resolveEntries(project, held, input.ts.injection_registrations);
     if (!resolved.some(namesADeclaration)) {
         return [];
     }
     const chains = aliasChains(project, held);
-    const calls = callsOf(project);
-    const named = entriesAt(project, chains, calls.flatMap((call) => calleeName(call.expression) ?? []), resolved);
+    const calls = sites.calls.map((one) => one.call);
+    const invoked = (call) => nameOf(sites.invocations.of(call).callee);
+    const named = entriesAt(project, chains, calls.flatMap((call) => invoked(call) ?? []), resolved);
     const matched = new Map();
     for (const call of calls) {
-        const name = calleeName(call.expression);
+        const name = invoked(call);
         const [entry] = name === undefined ? [] : (named.get(name) ?? []);
         if (entry !== undefined) {
             matched.set(call, entry);
         }
     }
-    return [...classesPassed(project, held, chains, [...matched.keys()])].flatMap(([call, uses]) => {
+    return [...classesPassed(project, held, chains, sites, [...matched.keys()])].flatMap(([call, uses]) => {
         const entry = matched.get(call);
         const detail = entry === undefined ? "" : `registered by ${spelledEntry(entry.entry, held)}`;
         return uses.map((use) => ({ id: use.id, site: use.site, detail }));
@@ -50,20 +52,12 @@ function registrations(input) {
  * with the first such decorator.
  */
 function constructedForParameters(input) {
-    const { project, held } = input;
     const found = new Map();
-    for (const file of project.ownSourceFiles()) {
-        const visit = (node) => {
-            if (isClassDeclaration(node) || isClassExpression(node)) {
-                const id = held.declarations.get(nodeKey(file, node));
-                const [asks] = node.members.flatMap((member) => isConstructorDeclaration(member) ? member.parameters.flatMap(decoratorsOf) : []);
-                if (id !== undefined && asks !== undefined) {
-                    found.set(id, asks);
-                }
-            }
-            node.forEachChild(visit);
-        };
-        file.forEachChild(visit);
+    for (const { id, node } of input.sites.classes) {
+        const [asks] = node.members.flatMap((member) => isConstructorDeclaration(member) ? member.parameters.flatMap(decoratorsOf) : []);
+        if (asks !== undefined) {
+            found.set(id, asks);
+        }
     }
     return found;
 }