@cplieger/deadset-ts 3.3.0 → 3.4.0

package/README.md

@@ -8,7 +8,7 @@ deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It
 
 deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
 
-**Status: pre-release.** This version implements contract 3.0.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Four exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process; no other verb reports findings yet, so `analyze`, `explain` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
+**Status: pre-release.** This version implements contract 3.1.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Seven exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; `injection-container`, a decorated property of a class a dependency-injection container constructs, being a class passed to a call `ts.injection_registrations` names or one a parameter of whose constructor carries a decorator; `framework-lifecycle`, a member a `ts.lifecycle_contracts` entry lists, on a class that is the entry's component by a decorator or a call the entry names or by extending a class it names; `serialization-contract`, the properties of a class whose values reach `JSON.stringify` or a declaration `ts.serializers` names, and those and its `toJSON` and `toString` where a value is passed to an `unknown` or `any` parameter of a function outside the analysis; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process; no other verb reports findings yet, so `analyze`, `explain` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
 
 ## Install
 

package/dist/src/analysis.js

@@ -10,6 +10,8 @@
 import { decorator } from "./decorator.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
 import { computeExemptions, disabledClasses, exemptionsOf, retainedIn, } from "./exempt.js";
+import { frameworkLifecycle } from "./framework-lifecycle.js";
+import { injectionContainer } from "./injection-container.js";
 import { interfaceSatisfaction } from "./interface-satisfaction.js";
 import { inventory } from "./inventory.js";
 import { readManifest } from "./manifest.js";
@@ -19,6 +21,7 @@ import { byPosition } from "./position.js";
 import { reflectiveLookup } from "./reflective-lookup.js";
 import { references } from "./references.js";
 import { roots, unmatchedEverywhere, unmatchedRoots } from "./roots.js";
+import { serializationContract } from "./serialization-contract.js";
 import { diagnosticsOf, runSession } from "./session.js";
 import { readTemplates, templateField } from "./template-field.js";
 /** The setting whose source decides where a finding about a configured root sits. */
@@ -128,6 +131,9 @@ const DETECTORS = new Map([
     ["template-field", templateField],
     ["reflective-lookup", reflectiveLookup],
     ["decorator", decorator],
+    ["injection-container", injectionContainer],
+    ["framework-lifecycle", frameworkLifecycle],
+    ["serialization-contract", serializationContract],
 ]);
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
@@ -145,6 +151,7 @@ export function runSweep(engine, host, scope, config, input, detectors = DETECTO
     const templates = disabled.has("template-field")
         ? { delimiters: config.analysis.templateDelimiters, files: [] }
         : readTemplates(host, targetRoot, config.analysis);
+    const consumers = scope.consumers.map((consumer) => consumer.path);
     const read = readProjects(engine, host, scope, config, (project, projectRead) => {
         const resolved = references(project, projectRead.held, targetRoot, {
             testFiles: config.ts.testFiles,
@@ -156,7 +163,7 @@ export function runSweep(engine, host, scope, config, input, detectors = DETECTO
             roots: projectRead.rooted.liveUnderReachability,
             testFiles: resolved.testFilePaths,
         };
-        const exempt = computeExemptions({ project, held: projectRead.held, targetRoot, templates }, detectors, {
+        const exempt = computeExemptions({ project, held: projectRead.held, targetRoot, templates, ts: config.ts, consumers }, detectors, {
             disabled,
             mode: input.mode,
             testFiles: new Set(resolved.testFilePaths),

package/dist/src/calls.js

@@ -0,0 +1,154 @@
+/**
+ * The calls and decorators of one project that the configured classes read: what each
+ * callee resolves to, and which of the target's classes a call passes or a decorator
+ * is attached to. A class is passed as an argument, or as an element of an array
+ * literal or a property value of an object literal written as one, at any depth, and a
+ * decorator written as a call is a call.
+ */
+import { isArrayLiteralExpression, isCallExpression, isClassDeclaration, isDecorator, isIdentifier, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadElement, } from "@typescript/native/unstable/ast";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { nodeKey } from "./inventory.js";
+import { DEFAULT_BATCH_CAP } from "./references.js";
+/** The name node a callee or a decorator expression resolves through, where it has one. */
+export function calleeName(expression) {
+    if (isParenthesizedExpression(expression)) {
+        return calleeName(expression.expression);
+    }
+    if (isPropertyAccessExpression(expression)) {
+        return expression.name;
+    }
+    return isIdentifier(expression) ? expression : undefined;
+}
+/** The callee one decorator names: its expression, or the callee of the call it writes. */
+export function decoratorCallee(decorator) {
+    const expression = decorator.expression;
+    return calleeName(isCallExpression(expression) ? expression.expression : expression);
+}
+/** How one decorator is spelled in a record: its expression, without a call's arguments. */
+export function spelledDecorator(decorator) {
+    const expression = decorator.expression;
+    const named = isCallExpression(expression) ? expression.expression : expression;
+    return `@${named.getText().replace(/\s+/gu, "")}`;
+}
+/** The decorators written on one declaration. */
+export function decoratorsOf(node) {
+    return (node.modifiers ?? []).filter(isDecorator);
+}
+/**
+ * What each of a batch of nodes resolves to, every alias followed to the declaration
+ * it stands for. A node the checker resolves to nothing, and an alias that resolves
+ * to nothing, are absent from the answer. Each alias is followed once.
+ */
+export function resolvedTargets(project, nodes) {
+    const followed = new Map();
+    const targets = new Map();
+    for (let from = 0; from < nodes.length; from += DEFAULT_BATCH_CAP) {
+        const run = nodes.slice(from, from + DEFAULT_BATCH_CAP);
+        project.symbolsAt(run.map((node) => project.handle(node))).forEach((symbol, index) => {
+            const node = run[index];
+            if (symbol === undefined || node === undefined) {
+                return;
+            }
+            let target = symbol;
+            if ((symbol.flags & SymbolFlags.Alias) !== 0) {
+                if (!followed.has(symbol.id)) {
+                    const aliased = project.checker.getAliasedSymbol(symbol);
+                    followed.set(symbol.id, aliased.declarations.length === 0 ? undefined : aliased);
+                }
+                target = followed.get(symbol.id);
+            }
+            if (target !== undefined) {
+                targets.set(node, target);
+            }
+        });
+    }
+    return targets;
+}
+/** The values one expression passes: itself, or what an array or object literal holds. */
+function passedIn(expression, found) {
+    if (isParenthesizedExpression(expression)) {
+        passedIn(expression.expression, found);
+        return;
+    }
+    if (isArrayLiteralExpression(expression)) {
+        for (const element of expression.elements) {
+            passedIn(isSpreadElement(element) ? element.expression : element, found);
+        }
+        return;
+    }
+    if (isObjectLiteralExpression(expression)) {
+        for (const property of expression.properties) {
+            if (isPropertyAssignment(property)) {
+                passedIn(property.initializer, found);
+            }
+            else if (isShorthandPropertyAssignment(property)) {
+                found.push({ site: property.name, name: property, shorthand: true });
+            }
+        }
+        return;
+    }
+    const name = calleeName(expression);
+    if (name !== undefined) {
+        found.push({ site: expression, name, shorthand: false });
+    }
+}
+/** The values one argument passes, a spread argument's included. */
+export function valuesPassed(argument) {
+    const found = [];
+    passedIn(isSpreadElement(argument) ? argument.expression : argument, found);
+    return found;
+}
+/**
+ * The classes of the target each call passes, by the call. A value that names no
+ * class of the target, a class of another program included, passes nothing here.
+ */
+export function classesPassed(project, held, chains, calls) {
+    const passed = new Map(calls.map((call) => [call, call.arguments.flatMap((argument) => valuesPassed(argument))]));
+    const all = [...passed.values()].flat();
+    const targets = resolvedTargets(project, all.filter((value) => !value.shorthand).map((value) => value.name));
+    const classes = new Set(held.symbols.filter((symbol) => symbol.kind === "class").map((symbol) => symbol.id));
+    const classesOf = (value) => {
+        const symbol = value.shorthand
+            ? project.shorthandValueAt(project.handle(value.name))
+            : targets.get(value.name);
+        return symbol === undefined
+            ? []
+            : chains.declarationsOf(symbol).filter((id) => classes.has(id));
+    };
+    return new Map([...passed].map(([call, values]) => [
+        call,
+        values.flatMap((value) => classesOf(value).map((id) => ({ id, site: value.site }))),
+    ]));
+}
+/** Every class declaration of the target that carries a decorator. */
+export function decoratedClasses(project, held) {
+    const found = [];
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node) => {
+            if (isClassDeclaration(node)) {
+                const id = held.declarations.get(nodeKey(file, node));
+                const decorators = decoratorsOf(node);
+                if (id !== undefined && decorators.length > 0) {
+                    found.push({ id, decorators });
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return found;
+}
+/** Every call expression of the project's own files, decorators written as calls included. */
+export function callsOf(project) {
+    const found = [];
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node) => {
+            if (isCallExpression(node)) {
+                found.push(node);
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return found;
+}

package/dist/src/class-members.js

@@ -0,0 +1,92 @@
+/**
+ * The members a value of one of the target's classes carries, as the checker answers
+ * for the class's type, so a member a base class declares is a member of every class
+ * that extends it and a member a subclass overrides is the subclass's own.
+ */
+import { isClassDeclaration, isClassExpression } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { DEFAULT_BATCH_CAP } from "./references.js";
+/** The name node of each class declaration of the target, by the class's identifier. */
+export function classNames(project, held) {
+    const names = new Map();
+    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));
+                if (id !== undefined) {
+                    names.set(id, node.name);
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return names;
+}
+/** The types of a batch of nodes, asked in capped batches. */
+export function typesAt(project, nodes) {
+    const types = [];
+    for (let from = 0; from < nodes.length; from += DEFAULT_BATCH_CAP) {
+        types.push(...project.checker.getTypeAtLocation(nodes.slice(from, from + DEFAULT_BATCH_CAP)));
+    }
+    return types;
+}
+/**
+ * The type one side of each class is: the instance type at the class's name, or the
+ * type of the class's own symbol, which is its constructor's.
+ */
+function sideTypes(project, nodes, side) {
+    if (side === "instance") {
+        return typesAt(project, nodes);
+    }
+    const symbols = project.symbolsAt(nodes.map((node) => project.handle(node)));
+    const present = symbols.filter((symbol) => symbol !== undefined);
+    const types = present.length === 0 ? [] : project.checker.getTypeOfSymbol(present);
+    let next = 0;
+    return symbols.map((symbol) => (symbol === undefined ? undefined : types[next++]));
+}
+/**
+ * The members one side of each class carries that the target declares, by the class.
+ * A member declared in a file outside the project's own, and the `prototype` a class
+ * carries on its static side, are not declarations of the target and are left out.
+ */
+export function classMembers(project, held, classIds, side) {
+    const named = [...classNames(project, held)].filter(([id]) => classIds.has(id));
+    const own = new Set(project.ownSourceFiles().map((file) => file.fileName));
+    const types = sideTypes(project, named.map(([, node]) => node), side);
+    const members = new Map();
+    named.forEach(([id], index) => {
+        const type = types[index];
+        if (type === undefined) {
+            return;
+        }
+        const found = [];
+        for (const property of project.checker.getPropertiesOfType(type)) {
+            for (const handle of property.declarations) {
+                if (!own.has(handle.path)) {
+                    continue;
+                }
+                const node = project.declarationAt(handle)?.node;
+                const declared = node === undefined
+                    ? undefined
+                    : held.declarations.get(nodeKey(node.getSourceFile(), node));
+                if (node !== undefined && declared !== undefined) {
+                    found.push({ id: declared, node, flags: property.flags });
+                }
+            }
+        }
+        members.set(id, found);
+    });
+    return members;
+}
+/**
+ * The last component of one member's stable reference, `:static` included, which is
+ * how a configuration names a member; undefined for a declaration that is no member.
+ */
+export function memberComponent(symbol, byId) {
+    const parent = byId.get(symbol.parent);
+    if (parent === undefined || !symbol.ref.startsWith(`${parent.ref}.`)) {
+        return undefined;
+    }
+    return symbol.ref.slice(parent.ref.length + 1);
+}

package/dist/src/config.js

@@ -37,6 +37,9 @@ export function defaultConfig() {
         ts: {
             testFiles: ["**/*.test.{ts,tsx,mts,cts}"],
             entryFiles: [],
+            injectionRegistrations: [],
+            lifecycleContracts: [],
+            serializers: [],
         },
     };
 }

package/dist/src/configured-declarations.js

@@ -0,0 +1,232 @@
+/**
+ * The declarations the configuration's entries name, resolved in one project, and
+ * which of them a symbol is. Declarations are compared rather than symbols, because a
+ * member read through an instantiation of a generic type is a symbol of its own that
+ * keeps the declarations of the member it instantiates.
+ */
+import { isCallExpression, isExportDeclaration, isExternalModuleReference, isImportDeclaration, isImportEqualsDeclaration, isNoSubstitutionTemplateLiteral, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { SymbolFlags, } from "@typescript/native/unstable/sync";
+import { resolvedTargets } from "./calls.js";
+import { nameComponent } from "./ref.js";
+/** The meanings a name of the global scope is looked up under: any of them. */
+const ANY_MEANING = SymbolFlags.Value | SymbolFlags.Type | SymbolFlags.Namespace;
+/** The suffix that marks a static member at the end of a path. */
+const STATIC = ":static";
+/** The key one declaration handle is compared by: its file and its index in that file. */
+function handleKey(handle) {
+    return `${handle.path}:${String(handle.index)}`;
+}
+/**
+ * The components of one declaration path and whether its last one is a static member.
+ * A path is split at the dots outside a quoted or a bracketed component, and each
+ * component keeps the spelling a reference gives it.
+ */
+function componentsOf(path) {
+    const isStatic = path.endsWith(STATIC);
+    const body = isStatic ? path.slice(0, -STATIC.length) : path;
+    const components = [];
+    let current = "";
+    let closing = "";
+    for (let at = 0; at < body.length; at += 1) {
+        const ch = body.charAt(at);
+        if (closing === "'" && ch === "\\") {
+            current += ch + body.charAt(at + 1);
+            at += 1;
+            continue;
+        }
+        if (closing !== "") {
+            closing = ch === closing ? "" : closing;
+        }
+        else if (ch === "'" || ch === "[") {
+            closing = ch === "'" ? "'" : "]";
+        }
+        else if (ch === ".") {
+            components.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    components.push(current);
+    return { components, static: isStatic };
+}
+/** What a symbol is once every alias it stands for is followed. */
+function unaliased(project, symbol) {
+    if ((symbol.flags & SymbolFlags.Alias) === 0) {
+        return symbol;
+    }
+    const target = project.checker.getAliasedSymbol(symbol);
+    return target.declarations.length === 0 ? undefined : target;
+}
+/** Whether one symbol is a member a class declares: a property, a method or an accessor. */
+function isClassMember(symbol) {
+    return (symbol.flags & SymbolFlags.ClassMember) !== 0;
+}
+/**
+ * The members of one container a path component may name. A class keeps its static
+ * members among its exports beside what a merged namespace exports, so a component
+ * with the static suffix names one of the first and a component without it names an
+ * instance member or one of the second.
+ */
+function candidatesOf(container, isStatic) {
+    const exported = [...container.getExports().values()];
+    if (isStatic) {
+        return exported.filter(isClassMember);
+    }
+    const isClass = (container.flags & SymbolFlags.Class) !== 0;
+    return [
+        ...container.getMembers().values(),
+        ...exported.filter((member) => !isClass || !isClassMember(member)),
+    ];
+}
+/** The member of one container a path component spells, followed through any alias. */
+function memberOf(project, container, component, isStatic) {
+    const member = candidatesOf(container, isStatic).find((candidate) => nameComponent(candidate.name) === component);
+    return member === undefined ? undefined : unaliased(project, member);
+}
+/** The declaration a path names from one starting symbol, component by component. */
+function walkPath(project, start, rest, isStatic) {
+    let at = start;
+    rest.forEach((component, index) => {
+        if (at !== undefined) {
+            at = memberOf(project, at, component, isStatic && index === rest.length - 1);
+        }
+    });
+    return at;
+}
+/** Whether one node is literal text: a string literal or a template with no substitution. */
+function isLiteralText(node) {
+    return node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node));
+}
+/** The module specifier one node writes, for each form that imports or re-exports a module. */
+function specifierOf(node) {
+    if (isImportDeclaration(node) || isExportDeclaration(node)) {
+        return node.moduleSpecifier;
+    }
+    if (isImportEqualsDeclaration(node) && isExternalModuleReference(node.moduleReference)) {
+        return node.moduleReference.expression;
+    }
+    if (isCallExpression(node) && node.expression.kind === SyntaxKind.ImportKeyword) {
+        return node.arguments[0];
+    }
+    return undefined;
+}
+/**
+ * The module each specifier the entries name resolves to in one project, read from a
+ * specifier the project's own files write, so the module is the one the target's own
+ * import resolves. A specifier no file writes resolves to no module.
+ */
+function modulesNamed(project, specifiers) {
+    const written = new Map();
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node) => {
+            const specifier = specifierOf(node);
+            if (isLiteralText(specifier) &&
+                specifiers.has(specifier.text) &&
+                !written.has(specifier.text)) {
+                written.set(specifier.text, specifier);
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    const specified = [...written];
+    const symbols = project.symbolsAt(specified.map(([, node]) => project.handle(node)));
+    const modules = new Map();
+    specified.forEach(([name], index) => {
+        const symbol = symbols[index];
+        if (symbol !== undefined) {
+            modules.set(name, symbol);
+        }
+    });
+    return modules;
+}
+/**
+ * The declaration each entry names in one project. A symbol entry names the
+ * inventory's declaration whose reference it spells exactly; a module entry names the
+ * declaration its path reaches from the exports of the module its specifier resolves
+ * to; a global entry names the declaration its path reaches from the global scope.
+ * Every alias along a path is followed to the declaration it stands for.
+ */
+export function resolveEntries(project, held, entries) {
+    if (entries.length === 0) {
+        return [];
+    }
+    const byRef = new Map(held.symbols.map((symbol) => [symbol.ref, symbol.id]));
+    const modules = modulesNamed(project, new Set(entries.flatMap((entry) => (entry.shape === "module" ? [entry.module] : []))));
+    return entries.map((entry) => {
+        if (entry.shape === "symbol") {
+            const id = byRef.get(entry.symbol);
+            return { entry, handles: new Set(), ids: new Set(id === undefined ? [] : [id]) };
+        }
+        const { components, static: isStatic } = componentsOf(entry.shape === "module" ? entry.name : entry.global);
+        const [first = "", ...rest] = components;
+        let start;
+        if (isStatic && rest.length === 0) {
+            // Only a member is static, and a path of one component names no member.
+            start = undefined;
+        }
+        else if (entry.shape === "module") {
+            const module = modules.get(entry.module);
+            start = module === undefined ? undefined : memberOf(project, module, first, false);
+        }
+        else if (nameComponent(first) === first) {
+            const global = project.checker.resolveName(first, ANY_MEANING, undefined, false);
+            start = global === undefined ? undefined : unaliased(project, global);
+        }
+        const declared = walkPath(project, start, rest, isStatic);
+        return {
+            entry,
+            handles: new Set(declared?.declarations.map(handleKey) ?? []),
+            ids: new Set(),
+        };
+    });
+}
+/**
+ * Whether one symbol is the declaration a resolved entry names: it shares one of the
+ * entry's declarations, or, for an entry naming a declaration of the program, it is
+ * declared there. `chains` reads the symbol's declarations against the inventory the
+ * entries were resolved with.
+ */
+export function names(resolved, symbol, chains) {
+    if (symbol.declarations.some((handle) => resolved.handles.has(handleKey(handle)))) {
+        return true;
+    }
+    return resolved.ids.size > 0 && chains.declarationsOf(symbol).some((id) => resolved.ids.has(id));
+}
+/** Whether a resolved entry names a declaration, so that some symbol can be it. */
+export function namesADeclaration(resolved) {
+    return resolved.handles.size > 0 || resolved.ids.size > 0;
+}
+/**
+ * The entries each of a batch of name nodes is: what the node resolves to, every alias
+ * followed, is the declaration each of them names. A node that is none is absent.
+ */
+export function entriesAt(project, chains, nodes, resolved) {
+    const naming = resolved.filter(namesADeclaration);
+    const found = new Map();
+    if (naming.length === 0) {
+        return found;
+    }
+    for (const [node, target] of resolvedTargets(project, nodes)) {
+        const entries = naming.filter((entry) => names(entry, target, chains));
+        if (entries.length > 0) {
+            found.set(node, entries);
+        }
+    }
+    return found;
+}
+/**
+ * How one entry is spelled in a record's detail: its path, or for a declaration of the
+ * program the display name the inventory gives it.
+ */
+export function spelledEntry(entry, held) {
+    switch (entry.shape) {
+        case "symbol":
+            return held.symbols.find((symbol) => symbol.ref === entry.symbol)?.name ?? entry.symbol;
+        case "module":
+            return entry.name;
+        case "global":
+            return entry.global;
+    }
+}

package/dist/src/decorator.js

@@ -10,17 +10,11 @@
  * declaration is held back, and the member set of a decorated class is every member
  * the inventory holds for the class, static members included.
  */
-import { isCallExpression, isDecorator, } from "@typescript/native/unstable/ast";
+import { decoratorsOf, spelledDecorator } from "./calls.js";
 import { nodeKey } from "./inventory.js";
 import { renderPosition } from "./position.js";
 /** The kinds of declaration a decorator is attached to and holds back. */
 const DECORATED = new Set(["class", "method", "class-member"]);
-/** How one decorator is spelled in a record: its expression, without a call's arguments. */
-function spelled(decorator) {
-    const expression = decorator.expression;
-    const named = isCallExpression(expression) ? expression.expression : expression;
-    return `@${named.getText().replace(/\s+/gu, "")}`;
-}
 /**
  * The decorator detector: each decorated member, and each member of a decorated
  * class, recorded at the decorator.
@@ -46,9 +40,8 @@ export function decorator(input) {
             const id = held.declarations.get(nodeKey(file, node));
             const symbol = id === undefined ? undefined : byId.get(id);
             if (symbol !== undefined && DECORATED.has(symbol.kind)) {
-                const modifiers = node.modifiers ?? [];
-                for (const attached of modifiers.filter(isDecorator)) {
-                    const detail = `decorated by ${spelled(attached)}`;
+                for (const attached of decoratorsOf(node)) {
+                    const detail = `decorated by ${spelledDecorator(attached)}`;
                     const site = renderPosition(file, targetRoot, attached.getStart());
                     const reached = symbol.kind === "class" ? (membersOf.get(symbol.id) ?? []) : [symbol];
                     for (const member of reached) {

package/dist/src/findings/dependencies-and-module-machinery.js

@@ -0,0 +1,2 @@
+/** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
+export const dependenciesAndModuleMachinery = () => [];

package/dist/src/findings/emitter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/findings/emitters.js

@@ -0,0 +1,19 @@
+import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.js";
+import { interfaces } from "./interfaces.js";
+import { intraFunction } from "./intra-function.js";
+import { nonCodeArtifacts } from "./non-code-artifacts.js";
+import { readsAndWrites } from "./reads-and-writes.js";
+import { selfCheck } from "./self-check.js";
+import { unusedDeclarations } from "./unused-declarations.js";
+import { visibilityNarrowing } from "./visibility-narrowing.js";
+/** Every kind family this analyzer reports, each by its emitter, in code order. */
+export const EMITTERS = new Map([
+    ["unused-declarations", unusedDeclarations],
+    ["visibility-narrowing", visibilityNarrowing],
+    ["interfaces", interfaces],
+    ["reads-and-writes", readsAndWrites],
+    ["non-code-artifacts", nonCodeArtifacts],
+    ["dependencies-and-module-machinery", dependenciesAndModuleMachinery],
+    ["self-check", selfCheck],
+    ["intra-function", intraFunction],
+]);

package/dist/src/findings/interfaces.js

@@ -0,0 +1,2 @@
+/** The findings of the interfaces family, `DS1200` to `DS1299`. */
+export const interfaces = () => [];

package/dist/src/findings/intra-function.js

@@ -0,0 +1,2 @@
+/** The findings of the intra-function family, `DS1800` to `DS1899`. */
+export const intraFunction = () => [];

package/dist/src/findings/non-code-artifacts.js

@@ -0,0 +1,2 @@
+/** The findings of the non-code-artifacts family, `DS1500` to `DS1599`. */
+export const nonCodeArtifacts = () => [];

package/dist/src/findings/reads-and-writes.js

@@ -0,0 +1,2 @@
+/** The findings of the reads-and-writes family, `DS1300` to `DS1399`. */
+export const readsAndWrites = () => [];

package/dist/src/findings/self-check.js

@@ -0,0 +1,2 @@
+/** The findings of the self-check family, `DS1700` to `DS1799`. */
+export const selfCheck = () => [];

package/dist/src/findings/unused-declarations.js

@@ -0,0 +1,2 @@
+/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+export const unusedDeclarations = () => [];

package/dist/src/findings/visibility-narrowing.js

@@ -0,0 +1,2 @@
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing = () => [];