@cplieger/deadset-ts 1.1.0 → 2.0.0

package/dist/src/inventory.js

@@ -0,0 +1,676 @@
+import { isClassDeclaration, isComputedPropertyName, isEnumDeclaration, isEnumMember, isExportAssignment, isExportDeclaration, isFunctionDeclaration, isGetAccessorDeclaration, isIdentifier, isInterfaceDeclaration, isIntersectionTypeNode, isMethodDeclaration, isMethodSignatureDeclaration, isModuleBlock, isModuleDeclaration, isNamespaceExport, isPrivateIdentifier, isPropertyDeclaration, isPropertySignatureDeclaration, isSetAccessorDeclaration, isTypeAliasDeclaration, isTypeLiteralNode, isUnionTypeNode, isVariableStatement, ModifierFlags, } from "@typescript/native/unstable/ast";
+import { dirnamePath, joinPath, relativePath } from "./paths.js";
+import { byPosition, positionKey, renderPosition } from "./position.js";
+import { computedComponent, nameComponent, renderRef } from "./ref.js";
+const MANIFEST = "package.json";
+/**
+ * Resolves each file's package scope: the name of the nearest manifest at or above
+ * its directory up to the target root, and the file's path below that manifest.
+ * Where no manifest up to the root carries a name, the package is a single dot and
+ * the path is read from the root, which cannot collide, because a package name never
+ * starts with a dot.
+ *
+ * One directory is read at most once, because a package holds many files and a
+ * manifest read is a filesystem call.
+ */
+function packages(host, root) {
+    const named = new Map();
+    const manifestName = (dir) => {
+        let text;
+        try {
+            text = host.readFile(joinPath(root, dir, MANIFEST));
+        }
+        catch {
+            return undefined;
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            // A manifest this program cannot read names no package, which is the same
+            // answer as an absent one: the file is then scoped by the target root.
+            return undefined;
+        }
+        if (typeof value !== "object" || value === null) {
+            return undefined;
+        }
+        const name = value["name"];
+        return typeof name === "string" && name !== "" ? name : undefined;
+    };
+    const nearest = (dir) => {
+        if (named.has(dir)) {
+            return named.get(dir);
+        }
+        const name = manifestName(dir);
+        const found = name !== undefined ? { name, at: dir } : dir === "" ? undefined : nearest(parentOf(dir));
+        named.set(dir, found);
+        return found;
+    };
+    return (path) => {
+        const found = nearest(parentOf(path));
+        if (found === undefined) {
+            return { package: ".", path };
+        }
+        return { package: found.name, path: found.at === "" ? path : path.slice(found.at.length + 1) };
+    };
+}
+/** The directory one path below the root sits in, and the root itself as the empty path. */
+function parentOf(path) {
+    const dir = dirnamePath(path);
+    return dir === "." ? "" : dir;
+}
+/** The modifier flags one node carries, and zero for a node that carries none. */
+function modifiersOf(node) {
+    return node.modifierFlags ?? 0;
+}
+/** The type parameters one node declares, and none for a node that declares none. */
+function typeParametersOf(node) {
+    if (isFunctionDeclaration(node) ||
+        isMethodDeclaration(node) ||
+        isMethodSignatureDeclaration(node)) {
+        return node.typeParameters ?? [];
+    }
+    return [];
+}
+/**
+ * The reference component one declaration name node spells, and undefined for a
+ * name the grammar does not represent: a binding pattern, and a computed key whose
+ * source text carries a closing bracket.
+ */
+function componentOf(name) {
+    if (name === undefined) {
+        return undefined;
+    }
+    if (isComputedPropertyName(name)) {
+        const text = name.expression.getText();
+        return text.includes("]") ? undefined : { text, computed: true };
+    }
+    if (isIdentifier(name) || isPrivateIdentifier(name)) {
+        return { text: name.getText(), computed: false };
+    }
+    if (isStringOrNumericName(name)) {
+        // A string or numeric key's own text carries its quotes and its numeric
+        // spelling; the reference carries the value, which the component then quotes.
+        return { text: literalTextOf(name), computed: false };
+    }
+    return undefined;
+}
+function isStringOrNumericName(name) {
+    const text = name.getText();
+    return (text.startsWith('"') || text.startsWith("'") || text.startsWith("`") || /^[0-9]/u.test(text));
+}
+/** One member's identity inside its container: its component, and its side of a class. */
+function memberKey(component, isStatic) {
+    return `${component.computed ? "[" : ""}${component.text}${isStatic ? ":static" : ""}`;
+}
+/**
+ * The members one type alias declares: the members of the object type it writes, and
+ * of every object type that is a direct constituent of a union or an intersection it
+ * writes. A constituent naming another type declares nothing here, because that
+ * declaration carries its own members.
+ *
+ * A name two constituents both declare is left out of all of them. The alias stands
+ * for such a member, because the two declarations are one member of the type and
+ * neither of them is the one a reference to it would name.
+ */
+function aliasMembers(type) {
+    const literals = isTypeLiteralNode(type)
+        ? [type]
+        : isUnionTypeNode(type) || isIntersectionTypeNode(type)
+            ? type.types.filter(isTypeLiteralNode)
+            : [];
+    if (literals.length < 2) {
+        return literals[0]?.members ?? [];
+    }
+    const declaring = new Map();
+    for (const literal of literals) {
+        for (const key of new Set(literal.members.map(keyOf))) {
+            if (key !== undefined) {
+                declaring.set(key, (declaring.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    return literals.flatMap((literal) => literal.members.filter((member) => {
+        const key = keyOf(member);
+        return key !== undefined && declaring.get(key) === 1;
+    }));
+}
+/** One type member's identity, and undefined for a member the grammar cannot name. */
+function keyOf(member) {
+    const component = componentOf(nameNodeOf(member));
+    return component === undefined ? undefined : memberKey(component, false);
+}
+/** The value one string or numeric key denotes, which is what the reference names. */
+function literalTextOf(name) {
+    const text = name.getText();
+    if (text.startsWith('"') || text.startsWith("'") || text.startsWith("`")) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+/**
+ * The component one declaration's reference carries, and its declared name where the
+ * two differ.
+ *
+ * A declaration its module exports as the default is named `default`, because that is
+ * its export name and a module has at most one, so the spelling is unambiguous and it
+ * holds for an anonymous declaration too. Its declared name is a fact about the source
+ * rather than about the export, so it travels beside the component as the display name.
+ */
+function exportedAs(node, name) {
+    const declared = componentOf(name);
+    if ((modifiersOf(node) & ModifierFlags.Default) === 0) {
+        return { component: declared, localName: undefined };
+    }
+    return { component: { text: "default", computed: false }, localName: declared?.text };
+}
+/** The visibility one member declaration's modifiers and name give it. */
+function visibilityOf(node, name) {
+    if (name !== undefined && isPrivateIdentifier(name)) {
+        return "private-name";
+    }
+    const flags = modifiersOf(node);
+    if ((flags & ModifierFlags.Private) !== 0) {
+        return "private";
+    }
+    if ((flags & ModifierFlags.Protected) !== 0) {
+        return "protected";
+    }
+    return "public";
+}
+/** The name node of one declaration, for the kinds that carry one. */
+function nameNodeOf(node) {
+    return node.name;
+}
+/**
+ * One node's identity inside one program, which is how two readings of that program
+ * name one declaration.
+ *
+ * The two mechanisms behind the member set resolve a member separately and meet here;
+ * so does the reference pass, which starts from a resolved symbol's declaration and
+ * needs the declaration this enumeration made for it.
+ */
+export function nodeKey(file, node) {
+    return `${file.fileName}:${String(node.pos)}:${String(node.end)}`;
+}
+/** The kind a class element takes: a method, or a property or accessor. */
+function classMemberKind(node) {
+    return isMethodDeclaration(node) ? "method" : "class-member";
+}
+/** The kind a type element takes: a method of an interface, or any other member. */
+function typeMemberKind(node, inInterface) {
+    return inInterface && isMethodSignatureDeclaration(node) ? "interface-method" : "type-member";
+}
+/**
+ * Every declaration one project's own files hold.
+ *
+ * `targetRoot` is the absolute path every position is rendered against; a file the
+ * program holds that is not below it ends the enumeration rather than being passed
+ * over. `host` is the filesystem the manifests that name each file's package are
+ * read through, and nothing else is read from it.
+ *
+ * The order is by rendered position, so two enumerations of one project return the
+ * same list whatever order the program reported its files in.
+ */
+export function inventory(project, host, targetRoot) {
+    const files = project.ownSourceFiles();
+    const ownFiles = new Set(files.map((file) => file.fileName));
+    const moduleOf = packages(host, targetRoot);
+    const building = [];
+    const byNode = new Map();
+    const exportScopes = [];
+    const containers = [];
+    const starReExports = [];
+    let outsideOwnFiles = 0;
+    const keep = (record) => {
+        building.push(record);
+        byNode.set(nodeKey(record.file, record.node), record);
+        return record;
+    };
+    for (const file of files) {
+        const path = relativePath(targetRoot, file.fileName);
+        if (path === undefined) {
+            // renderPosition states the refusal, with the root it was rendered against.
+            renderPosition(file, targetRoot, 0);
+            continue;
+        }
+        const module = moduleOf(path);
+        const fileRecord = keep({
+            file,
+            node: file,
+            module,
+            position: renderPosition(file, targetRoot, 0),
+            endLine: renderPosition(file, targetRoot, Math.max(file.end - 1, 0)).line,
+            kind: "file",
+            parentChain: [],
+            // A file's reference names its module, so no component of it is ever spelled;
+            // the path is what a text line renders for it.
+            component: { text: path, computed: false },
+            localName: path,
+            parent: undefined,
+            visibility: "public",
+            static: false,
+            exported: false,
+            typeParameter: undefined,
+        });
+        exportScopes.push({ owner: fileRecord, nameNode: file });
+        walkStatements(file.statements, fileRecord);
+    }
+    /** One declaration of a module, a namespace or a container body. */
+    function walkStatements(statements, owner) {
+        for (const statement of statements) {
+            walkStatement(statement, owner);
+        }
+    }
+    function declare(node, owner, kind, name, named) {
+        const at = name ?? node;
+        const record = keep({
+            file: owner.file,
+            node,
+            module: owner.module,
+            position: renderPosition(owner.file, targetRoot, at.getStart()),
+            endLine: renderPosition(owner.file, targetRoot, Math.max(node.end - 1, 0)).line,
+            kind,
+            parentChain: owner.kind === "file" ? [] : chainOf(owner),
+            component: named.component,
+            localName: named.localName,
+            parent: owner,
+            visibility: visibilityOf(node, name),
+            static: (modifiersOf(node) & ModifierFlags.Static) !== 0,
+            exported: false,
+            typeParameter: undefined,
+        });
+        declareTypeParameters(node, record);
+        return record;
+    }
+    function declareTypeParameters(node, owner) {
+        for (const parameter of typeParametersOf(node)) {
+            const name = nameNodeOf(parameter);
+            if (name === undefined) {
+                continue;
+            }
+            keep({
+                file: owner.file,
+                node: parameter,
+                module: owner.module,
+                position: renderPosition(owner.file, targetRoot, name.getStart()),
+                endLine: renderPosition(owner.file, targetRoot, Math.max(parameter.end - 1, 0)).line,
+                kind: "type-parameter",
+                parentChain: owner.parentChain,
+                component: owner.component,
+                localName: undefined,
+                parent: owner,
+                visibility: "public",
+                static: owner.static,
+                exported: false,
+                typeParameter: name.getText(),
+            });
+        }
+    }
+    function walkStatement(node, owner) {
+        if (isFunctionDeclaration(node)) {
+            const named = exportedAs(node, node.name);
+            if (named.component !== undefined) {
+                declare(node, owner, "function", node.name, { ...named, component: named.component });
+            }
+            return;
+        }
+        if (isClassDeclaration(node)) {
+            const named = exportedAs(node, node.name);
+            if (named.component === undefined) {
+                return;
+            }
+            const record = declare(node, owner, "class", node.name, {
+                ...named,
+                component: named.component,
+            });
+            containers.push({
+                owner: record,
+                nameNode: node.name,
+                members: node.members,
+                memberKind: "class-member",
+                isClass: true,
+                membersAreExports: false,
+            });
+            return;
+        }
+        if (isInterfaceDeclaration(node)) {
+            const named = exportedAs(node, node.name);
+            if (named.component === undefined) {
+                return;
+            }
+            const record = declare(node, owner, "interface", node.name, {
+                ...named,
+                component: named.component,
+            });
+            containers.push({
+                owner: record,
+                nameNode: node.name,
+                members: node.members,
+                memberKind: "interface-method",
+                isClass: false,
+                membersAreExports: false,
+            });
+            return;
+        }
+        if (isTypeAliasDeclaration(node)) {
+            const named = exportedAs(node, node.name);
+            if (named.component === undefined) {
+                return;
+            }
+            const record = declare(node, owner, "type", node.name, {
+                ...named,
+                component: named.component,
+            });
+            // A type alias keeps no member table of its own: the members belong to the
+            // object types its declaration writes, so the declaration is what carries them.
+            const members = aliasMembers(node.type);
+            if (members.length > 0) {
+                containers.push({
+                    owner: record,
+                    nameNode: undefined,
+                    members,
+                    memberKind: "type-member",
+                    isClass: false,
+                    membersAreExports: false,
+                });
+            }
+            return;
+        }
+        if (isEnumDeclaration(node)) {
+            const named = exportedAs(node, node.name);
+            if (named.component === undefined) {
+                return;
+            }
+            const record = declare(node, owner, "enum", node.name, {
+                ...named,
+                component: named.component,
+            });
+            containers.push({
+                owner: record,
+                nameNode: node.name,
+                members: node.members,
+                memberKind: "enum-member",
+                isClass: false,
+                membersAreExports: true,
+            });
+            return;
+        }
+        if (isModuleDeclaration(node)) {
+            const component = componentOf(node.name);
+            if (component === undefined) {
+                return;
+            }
+            const record = declare(node, owner, "namespace", node.name, {
+                component,
+                localName: undefined,
+            });
+            exportScopes.push({ owner: record, nameNode: node.name });
+            const body = node.body;
+            if (body === undefined) {
+                return;
+            }
+            if (isModuleBlock(body)) {
+                walkStatements(body.statements, record);
+                return;
+            }
+            walkStatement(body, record);
+            return;
+        }
+        if (isVariableStatement(node)) {
+            for (const declaration of node.declarationList.declarations) {
+                const component = componentOf(declaration.name);
+                if (component === undefined) {
+                    // A destructuring pattern declares binding elements, which the reference
+                    // grammar does not represent; the statement stands for them.
+                    continue;
+                }
+                declare(declaration, owner, "variable", declaration.name, {
+                    component,
+                    localName: undefined,
+                });
+            }
+            return;
+        }
+        if (isExportDeclaration(node)) {
+            walkExportDeclaration(node, owner);
+            return;
+        }
+        if (isExportAssignment(node) && !node.isExportEquals) {
+            declare(node, owner, "export-alias", undefined, {
+                component: { text: "default", computed: false },
+                localName: undefined,
+            });
+        }
+    }
+    function walkExportDeclaration(node, owner) {
+        const clause = node.exportClause;
+        if (clause === undefined) {
+            const specifier = node.moduleSpecifier;
+            starReExports.push(specifier === undefined ? "" : literalTextOf(specifier));
+            return;
+        }
+        if (isNamespaceExport(clause)) {
+            const component = componentOf(clause.name);
+            if (component !== undefined) {
+                declare(clause, owner, "export-alias", clause.name, { component, localName: undefined });
+            }
+            return;
+        }
+        for (const element of clause.elements ?? []) {
+            const name = nameNodeOf(element);
+            const component = componentOf(name);
+            if (component !== undefined) {
+                declare(element, owner, "export-alias", name, { component, localName: undefined });
+            }
+        }
+    }
+    // One batch for every module and every container the walk found, because a
+    // checker accessor with an array overload costs one round trip for the batch and
+    // one per node without it.
+    const batched = [
+        ...exportScopes.map((scope) => scope.nameNode),
+        ...containers.map((container) => container.nameNode).filter((node) => node !== undefined),
+    ];
+    const handles = batched.map((node) => project.handle(node));
+    const resolved = project.symbolsAt(handles);
+    const symbolOf = new Map();
+    batched.forEach((node, index) => {
+        const symbol = resolved[index];
+        if (symbol !== undefined) {
+            symbolOf.set(node, symbol);
+        }
+    });
+    let exportTables = 0;
+    for (const scope of exportScopes) {
+        const symbol = symbolOf.get(scope.nameNode);
+        if (symbol === undefined) {
+            continue;
+        }
+        exportTables += 1;
+        for (const [, exported] of symbol.getExports()) {
+            for (const declaration of exported.declarations) {
+                const held = project.declarationAt(declaration);
+                if (held === undefined) {
+                    continue;
+                }
+                const record = byNode.get(nodeKey(held.node.getSourceFile(), held.node));
+                if (record === undefined) {
+                    continue;
+                }
+                record.exported = true;
+            }
+        }
+    }
+    let memberTables = 0;
+    for (const container of containers) {
+        const symbol = container.nameNode === undefined ? undefined : symbolOf.get(container.nameNode);
+        const seen = new Map();
+        if (symbol !== undefined) {
+            if (!container.membersAreExports) {
+                memberTables += 1;
+                outsideOwnFiles += readTable(container, symbol.getMembers(), seen, false);
+            }
+            if (container.membersAreExports || container.isClass) {
+                memberTables += 1;
+                outsideOwnFiles += readTable(container, symbol.getExports(), seen, container.isClass);
+            }
+        }
+        completeFromTree(container, seen);
+    }
+    /**
+     * One container's members as its symbol table holds them, each positioned at the
+     * declaration the table names. A member with no declaration is the language's own
+     * (a class's `prototype`), and a member declared outside the target's own files
+     * belongs to another program; neither is a declaration of the target.
+     */
+    function readTable(container, table, seen, areStatic) {
+        let outside = 0;
+        for (const [, member] of table) {
+            const declarations = member.declarations
+                .map((handle) => project.declarationAt(handle))
+                .filter((held) => held !== undefined);
+            if (declarations.length === 0) {
+                continue;
+            }
+            const own = declarations.filter((held) => ownFiles.has(held.node.getSourceFile().fileName));
+            if (own.length === 0) {
+                outside += declarations.length;
+                continue;
+            }
+            for (const held of own) {
+                keepMember(container, held.node, seen, areStatic);
+            }
+        }
+        return outside;
+    }
+    /**
+     * One container's members as its own declaration writes them, for the members its
+     * symbol table does not hold: a member whose key is computed is bound to the
+     * container's type later than the table is built.
+     */
+    function completeFromTree(container, seen) {
+        for (const member of container.members) {
+            keepMember(container, member, seen, (modifiersOf(member) & ModifierFlags.Static) !== 0);
+        }
+    }
+    function keepMember(container, node, seen, areStatic) {
+        const kind = memberKindOf(container, node);
+        if (kind === undefined) {
+            return;
+        }
+        const name = nameNodeOf(node);
+        const component = componentOf(name);
+        if (component === undefined) {
+            return;
+        }
+        const file = node.getSourceFile();
+        const key = memberKey(component, areStatic);
+        const held = seen.get(key);
+        const endLine = renderPosition(file, targetRoot, Math.max(node.end - 1, 0)).line;
+        if (held !== undefined) {
+            // A getter and a setter of one name are one symbol and one reference, so the
+            // second declaration widens the first record rather than making a second. Both
+            // nodes name that record, so a reading that starts from either one finds it.
+            held.endLine = Math.max(held.endLine, endLine);
+            byNode.set(nodeKey(file, node), held);
+            return;
+        }
+        const at = name ?? node;
+        const record = keep({
+            file,
+            node,
+            module: container.owner.module,
+            position: renderPosition(file, targetRoot, at.getStart()),
+            endLine,
+            kind,
+            parentChain: chainOf(container.owner),
+            component,
+            localName: undefined,
+            parent: container.owner,
+            visibility: visibilityOf(node, name),
+            static: areStatic,
+            exported: false,
+            typeParameter: undefined,
+        });
+        seen.set(key, record);
+        declareTypeParameters(node, record);
+    }
+    function memberKindOf(container, node) {
+        if (container.isClass) {
+            if (isPropertyDeclaration(node) ||
+                isMethodDeclaration(node) ||
+                isGetAccessorDeclaration(node) ||
+                isSetAccessorDeclaration(node)) {
+                return classMemberKind(node);
+            }
+            return undefined;
+        }
+        if (container.memberKind === "enum-member") {
+            return isEnumMember(node) ? "enum-member" : undefined;
+        }
+        if (isPropertySignatureDeclaration(node) || isMethodSignatureDeclaration(node)) {
+            return typeMemberKind(node, container.memberKind === "interface-method");
+        }
+        if (isGetAccessorDeclaration(node) || isSetAccessorDeclaration(node)) {
+            return "type-member";
+        }
+        return undefined;
+    }
+    const symbols = building
+        .map(render)
+        .sort((a, b) => byPosition(a.position, b.position) || (a.ref < b.ref ? -1 : 1));
+    return {
+        configFile: project.configFile,
+        symbols,
+        declarations: new Map([...byNode].map(([key, record]) => [key, positionKey(record.position)])),
+        cost: { batches: 1, exportTables, memberTables },
+        starReExports,
+        outsideOwnFiles,
+    };
+}
+/** The chain of components that names one declaration, read from the module inward. */
+function chainOf(record) {
+    return [...record.parentChain, record.component];
+}
+/**
+ * One declaration as the inventory reports it. The display name is the chain in the
+ * spelling a reference gives it, except where the declaration carries a name of its
+ * own the reference does not: a file, whose reference names its module, and a default
+ * export, whose reference carries its export name.
+ */
+function render(record) {
+    const chain = chainOf(record);
+    const spelled = chain
+        .map((component) => component.computed ? computedComponent(component.text) : nameComponent(component.text))
+        .join(".");
+    const name = record.localName ??
+        (record.typeParameter === undefined ? spelled : `${spelled}<${record.typeParameter}>`);
+    return {
+        id: positionKey(record.position),
+        ref: refOf(record, chain),
+        name,
+        kind: record.kind,
+        position: record.position,
+        endLine: record.endLine,
+        parent: record.parent === undefined ? "" : positionKey(record.parent.position),
+        exported: record.exported,
+        visibility: record.visibility,
+        static: record.static,
+    };
+}
+function refOf(record, chain) {
+    if (record.kind === "file") {
+        return renderRef(record.module, { of: "module" });
+    }
+    if (record.kind === "export-alias") {
+        return renderRef(record.module, { of: "alias", name: record.component.text });
+    }
+    return renderRef(record.module, {
+        of: "declaration",
+        chain,
+        static: record.static,
+        ...(record.typeParameter === undefined ? {} : { typeParameter: record.typeParameter }),
+    });
+}

package/dist/src/kinds.js

@@ -0,0 +1,12 @@
+/**
+ * The issue-kind codes whose severity the Contract fixes. A severity key naming
+ * one, or a family prefix whose range holds one, is an unimplemented key rather
+ * than a setting.
+ *
+ * The codes are written out rather than read from the Contract at run time: the
+ * Contract is data a reader outside this program consults, and a product that
+ * read it while running would need it installed beside itself. A test compares
+ * this list against the Contract release the analyzer is written against, so a
+ * code the Contract fixes arrives here as a failing test.
+ */
+export const FIXED_SEVERITY_CODES = ["DS1703", "DS1704"];