@cplieger/deadset-ts 3.3.1 → 3.4.0

package/dist/src/framework-lifecycle.js

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ */
+import { isClassDeclaration, isClassExpression, isHeritageClause, SyntaxKind, } from "@typescript/native/unstable/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";
+/** 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,
+    ]);
+    const resolved = resolveEntries(project, held, entries);
+    let next = 0;
+    const take = (count) => {
+        const taken = resolved.slice(next, next + count).filter(namesADeclaration);
+        next += count;
+        return taken;
+    };
+    return contracts.map((contract) => ({
+        contract,
+        components: take(contract.components.length),
+        bases: take(contract.bases.length),
+    }));
+}
+/** The classes a decorator or a call the contracts' components name makes a component. */
+function byComponents(project, held, 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 named = entriesAt(project, chains, [
+        ...calls.flatMap((call) => calleeName(call.expression) ?? []),
+        ...decorated.flatMap((one) => one.decorators.flatMap((decorator) => decoratorCallee(decorator) ?? [])),
+    ], [...contractOf.keys()]);
+    const naming = (node) => (node === undefined ? [] : (named.get(node) ?? [])).flatMap((entry) => {
+        const contract = contractOf.get(entry);
+        return contract === undefined ? [] : [{ contract, detail: spelledEntry(entry.entry, held) }];
+    });
+    const found = [];
+    for (const one of decorated) {
+        for (const decorator of one.decorators) {
+            for (const { contract, detail } of naming(decoratorCallee(decorator))) {
+                found.push({ contract, id: one.id, site: decorator, detail: `decorated by @${detail}` });
+            }
+        }
+    }
+    const matched = new Map();
+    for (const call of calls) {
+        const routes = naming(calleeName(call.expression));
+        if (routes.length > 0) {
+            matched.set(call, routes);
+        }
+    }
+    for (const [call, uses] of classesPassed(project, held, chains, [...matched.keys()])) {
+        for (const route of matched.get(call) ?? []) {
+            for (const use of uses) {
+                found.push({
+                    contract: route.contract,
+                    id: use.id,
+                    site: use.site,
+                    detail: `registered by ${route.detail}`,
+                });
+            }
+        }
+    }
+    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;
+}
+/** The classes that extend, directly or through a chain, a class the contracts' bases name. */
+function byBases(project, held, chains, contracts) {
+    const based = contracts.filter((one) => one.bases.length > 0);
+    if (based.length === 0) {
+        return [];
+    }
+    const classes = extendingClasses(project, held);
+    if (classes.length === 0) {
+        return [];
+    }
+    const checker = project.checker;
+    const ancestry = new Map();
+    const ancestorsOf = (type, seen) => {
+        const known = ancestry.get(type.id);
+        if (known !== undefined) {
+            return known;
+        }
+        const declared = type.isClassOrInterface()
+            ? type
+            : type.isTypeReference()
+                ? type.getTarget()
+                : undefined;
+        if (declared === undefined || !declared.isClassOrInterface() || seen.has(declared.id)) {
+            return [];
+        }
+        seen.add(declared.id);
+        const found = checker
+            .getBaseTypes(declared)
+            .flatMap((base) => [base, ...ancestorsOf(base, seen)]);
+        ancestry.set(type.id, found);
+        return found;
+    };
+    const types = typesAt(project, classes.map((one) => one.name));
+    const found = [];
+    classes.forEach((one, index) => {
+        const type = types[index];
+        if (type === undefined) {
+            return;
+        }
+        const ancestors = ancestorsOf(type, new Set()).flatMap((base) => base.getSymbol() ?? []);
+        for (const contract of based) {
+            for (const entry of contract.bases) {
+                if (ancestors.some((symbol) => names(entry, symbol, chains))) {
+                    found.push({
+                        contract: contract.contract,
+                        id: one.id,
+                        site: one.extended,
+                        detail: `extends ${spelledEntry(entry.entry, held)}`,
+                    });
+                }
+            }
+        }
+    });
+    return found;
+}
+/**
+ * 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.
+ */
+export function frameworkLifecycle(input) {
+    const { project, held, targetRoot } = input;
+    if (input.ts.lifecycleContracts.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),
+    ];
+    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")))
+        ? ["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 = [];
+    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 });
+            }
+        }
+    }
+    return found;
+}

package/dist/src/injection-container.js

@@ -0,0 +1,101 @@
+/**
+ * The injection-container class: a container constructs a class passed to a call
+ * `ts.injection_registrations` names, or one a parameter of whose constructor carries a
+ * decorator, and populates each of its properties and accessors that carries one, a base
+ * class's included. A constructor and its parameters are no declarations of the
+ * inventory, so the class stands for them and the registration referencing it keeps it.
+ */
+import { isClassDeclaration, isClassExpression, isConstructorDeclaration, isGetAccessorDeclaration, isPropertyDeclaration, isSetAccessorDeclaration, } from "@typescript/native/unstable/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 { nodeKey } from "./inventory.js";
+import { renderPosition } from "./position.js";
+/** Whether one member declaration is a property or an accessor carrying a decorator. */
+function isInjected(node) {
+    return ((isPropertyDeclaration(node) ||
+        isGetAccessorDeclaration(node) ||
+        isSetAccessorDeclaration(node)) &&
+        decoratorsOf(node).length > 0);
+}
+/** 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);
+    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 matched = new Map();
+    for (const call of calls) {
+        const name = calleeName(call.expression);
+        const [entry] = name === undefined ? [] : (named.get(name) ?? []);
+        if (entry !== undefined) {
+            matched.set(call, entry);
+        }
+    }
+    return [...classesPassed(project, held, chains, [...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 }));
+    });
+}
+/** The classes of the target a parameter of whose constructor carries a decorator. */
+function constructedForParameters(input) {
+    const { project, held } = input;
+    const found = new Set();
+    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.some((member) => isConstructorDeclaration(member) &&
+                    member.parameters.some((parameter) => decoratorsOf(parameter).length > 0));
+                if (id !== undefined && asks) {
+                    found.add(id);
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return found;
+}
+/**
+ * The injection-container detector: each decorated property or accessor of a class a
+ * container constructs, recorded at the registration that names the class, or, for a
+ * class whose constructor asks for its parameters, at the member's own decorator.
+ */
+export function injectionContainer(input) {
+    const { project, held, targetRoot } = input;
+    const registered = registrations(input);
+    const constructed = constructedForParameters(input);
+    const classes = new Set([...registered.map((one) => one.id), ...constructed]);
+    if (classes.size === 0) {
+        return [];
+    }
+    const members = classMembers(project, held, classes, "instance");
+    const injected = (id) => (members.get(id) ?? []).filter((member) => isInjected(member.node));
+    const at = (node) => renderPosition(node.getSourceFile(), targetRoot, node.getStart());
+    const found = [];
+    for (const registration of registered) {
+        for (const member of injected(registration.id)) {
+            found.push({ id: member.id, detail: registration.detail, site: at(registration.site) });
+        }
+    }
+    for (const id of constructed) {
+        for (const member of injected(id)) {
+            const [decorator] = decoratorsOf(member.node);
+            if (decorator !== undefined) {
+                found.push({
+                    id: member.id,
+                    detail: `injected by ${spelledDecorator(decorator)}`,
+                    site: at(decorator),
+                });
+            }
+        }
+    }
+    return found;
+}

package/dist/src/print.js

@@ -1,4 +1,15 @@
 import { renderOrigin } from "./config.js";
+/** One declaration entry as a document writes it: the members of its shape alone. */
+function declarationOf(entry) {
+    switch (entry.shape) {
+        case "symbol":
+            return { symbol: entry.symbol };
+        case "module":
+            return { module: entry.module, name: entry.name };
+        case "global":
+            return { global: entry.global };
+    }
+}
 /**
  * The resolved configuration and its provenance as one JSON object, indented,
  * ending in a newline.
@@ -44,6 +55,13 @@ export function printConfig(config, provenance) {
         ts: {
             test_files: config.ts.testFiles,
             entry_files: config.ts.entryFiles,
+            injection_registrations: config.ts.injectionRegistrations.map(declarationOf),
+            lifecycle_contracts: config.ts.lifecycleContracts.map((entry) => ({
+                components: entry.components.map(declarationOf),
+                bases: entry.bases.map(declarationOf),
+                members: entry.members,
+            })),
+            serializers: config.ts.serializers.map(declarationOf),
         },
         provenance: Object.fromEntries([...provenance]
             .sort(([a], [b]) => (a < b ? -1 : 1))

package/dist/src/resolve.js

@@ -292,6 +292,98 @@ function readExemptions(document, label) {
     }
     return disabled;
 }
+/** The members that name a declaration, each belonging to exactly one shape. */
+const SHAPE_MEMBERS = ["symbol", "module", "name", "global"];
+/** The prefix of a stable symbol reference in the TypeScript form. */
+const SYMBOL_PREFIX = "ts://";
+/**
+ * A bare specifier: neither relative nor absolute, and not one the package's own
+ * imports field maps, each of which names a file of the analyzed program.
+ */
+const BARE_SPECIFIER = /^[^./#]/u;
+/**
+ * One declaration entry, read as the one shape its members name. An entry carrying
+ * members of two shapes, or of none, is refused at the entry, as is a module named
+ * without the declaration's path or a path without its module.
+ */
+function readDeclaration(entry, at, label) {
+    if (!isRecord(entry)) {
+        throw malformed(label, at, "is not an object");
+    }
+    const named = SHAPE_MEMBERS.filter((name) => Object.hasOwn(entry, name));
+    if (named.length === 1 && named[0] === "symbol") {
+        const symbol = requireMember(readString(entry, "symbol", `${at}.symbol`, label), `${at}.symbol`, label);
+        if (!symbol.startsWith(SYMBOL_PREFIX)) {
+            throw malformed(label, `${at}.symbol`, `${JSON.stringify(symbol)} is not a ts:// reference`);
+        }
+        return { shape: "symbol", symbol };
+    }
+    if (named.length === 1 && named[0] === "global") {
+        const path = `${at}.global`;
+        return {
+            shape: "global",
+            global: requireMember(readString(entry, "global", path, label), path, label),
+        };
+    }
+    if (named.length === 2 && named.includes("module") && named.includes("name")) {
+        const module = requireMember(readString(entry, "module", `${at}.module`, label), `${at}.module`, label);
+        if (!BARE_SPECIFIER.test(module)) {
+            throw malformed(label, `${at}.module`, `${JSON.stringify(module)} is not a bare specifier: a file of the analyzed program is named by its symbol`);
+        }
+        const path = `${at}.name`;
+        return {
+            shape: "module",
+            module,
+            name: requireMember(readString(entry, "name", path, label), path, label),
+        };
+    }
+    throw malformed(label, at, named.length === 0
+        ? 'names no declaration: an entry carries "symbol", "module" with "name", or "global"'
+        : `carries ${spell(named)}, which is not one of "symbol", "module" with "name", or "global"`);
+}
+/** One array of declaration entries, absent where the document does not write it. */
+function readDeclarations(parent, name, path, label) {
+    const value = member(parent, name);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw malformed(label, path, "is not an array");
+    }
+    return value.map((entry, index) => readDeclaration(entry, `${path}[${String(index)}]`, label));
+}
+/**
+ * One lifecycle contract. The member names are required, and the entry names at least
+ * one component declaration or one base class, because a contract naming neither
+ * makes no class a component and so retains nothing.
+ */
+function readLifecycleContract(entry, at, label) {
+    if (!isRecord(entry)) {
+        throw malformed(label, at, "is not an object");
+    }
+    const components = readDeclarations(entry, "components", `${at}.components`, label) ?? [];
+    const bases = readDeclarations(entry, "bases", `${at}.bases`, label) ?? [];
+    const members = readStrings(entry, "members", `${at}.members`, label, 1);
+    if (members === undefined) {
+        throw malformed(label, `${at}.members`, "is required and names nothing");
+    }
+    if (components.length === 0 && bases.length === 0) {
+        throw malformed(label, at, 'names no declaration in "components" and no class in "bases", so it makes no class a component');
+    }
+    return { components, bases, members };
+}
+/** The lifecycle contracts, one per framework the project declares. */
+function readLifecycleContracts(ts, label) {
+    const path = "ts.lifecycle_contracts";
+    const value = member(ts, "lifecycle_contracts");
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw malformed(label, path, "is not an array");
+    }
+    return value.map((entry, index) => readLifecycleContract(entry, `${path}[${String(index)}]`, label));
+}
 /**
  * Reads one already-parsed configuration document as the settings it supplies,
  * refusing every constraint the closed key list declares that a parse cannot
@@ -337,6 +429,9 @@ function readDoc(value, label) {
         failOn: readEnum(reporters, "fail_on", "reporters.fail_on", label, SEVERITIES),
         testFiles: readStrings(ts, "test_files", "ts.test_files", label, 1),
         entryFiles: readStrings(ts, "entry_files", "ts.entry_files", label, 0),
+        injectionRegistrations: readDeclarations(ts, "injection_registrations", "ts.injection_registrations", label),
+        lifecycleContracts: readLifecycleContracts(ts, label),
+        serializers: readDeclarations(ts, "serializers", "ts.serializers", label),
     };
 }
 /** Parses one document's text and walks it against the closed key list. */
@@ -538,6 +633,9 @@ function settleAll(inputs) {
         ts: {
             testFiles: at("ts.test_files", defaults.ts.testFiles, (doc) => doc.testFiles),
             entryFiles: at("ts.entry_files", defaults.ts.entryFiles, (doc) => doc.entryFiles),
+            injectionRegistrations: at("ts.injection_registrations", defaults.ts.injectionRegistrations, (doc) => doc.injectionRegistrations),
+            lifecycleContracts: at("ts.lifecycle_contracts", defaults.ts.lifecycleContracts, (doc) => doc.lifecycleContracts),
+            serializers: at("ts.serializers", defaults.ts.serializers, (doc) => doc.serializers),
         },
     };
     return { config, provenance };

package/dist/src/schema.js

@@ -1,5 +1,10 @@
 import { ConfigError } from "./config.js";
 const leaf = { kind: "leaf" };
+/** A list of declarations, each entry in one of the three shapes the `ts` section states. */
+const declarations = {
+    kind: "list",
+    members: { symbol: leaf, module: leaf, name: leaf, global: leaf },
+};
 /**
  * The closed key list the Contract's configuration schema declares, derived from
  * that schema key by key. A test pins the two equal, so a Contract change that
@@ -44,7 +49,19 @@ export const SCHEMA_ROOT = {
             },
         },
         go: { kind: "section", members: {} },
-        ts: { kind: "section", members: { test_files: leaf, entry_files: leaf } },
+        ts: {
+            kind: "section",
+            members: {
+                test_files: leaf,
+                entry_files: leaf,
+                injection_registrations: declarations,
+                lifecycle_contracts: {
+                    kind: "list",
+                    members: { components: declarations, bases: declarations, members: leaf },
+                },
+                serializers: declarations,
+            },
+        },
         provenance: { kind: "map" },
     },
 };