@aoelite/refpact-ts 0.0.0-stage → 0.1.2

package/dist/frontend/declarations.js

@@ -0,0 +1,158 @@
+/** The named items that a file declares at its top level, for the rules about items. */
+import { SyntaxKind } from "./compiler.js";
+/** The kinds of item a declaration can have. */
+export const ITEM_KINDS = ["function", "class", "interface", "type", "enum", "variable", "namespace"];
+/** The visibilities a declaration can have. */
+export const VISIBILITIES = ["exported", "local"];
+/**
+ * The relations that the syntax of a declaration gives: `extends` and `implements` of a class
+ * or an interface, the decorators of a class, and the types that a function takes and
+ * returns and that a variable has.
+ */
+export const TIES = ["extends", "implements", "decorator", "returns", "takes", "has-type"];
+/** The modifiers a declaration can have, in the order of their description. */
+export const MODIFIERS = ["async", "abstract", "declare", "const", "default", "documented"];
+/** All relations of a declaration: the ties, and the types that it extends or implements at any depth. */
+export const RELATIONS = [...TIES, "assignable-to"];
+const K = SyntaxKind;
+const KINDS = new Map([
+    [K.FunctionDeclaration, "function"],
+    [K.ClassDeclaration, "class"],
+    [K.InterfaceDeclaration, "interface"],
+    [K.TypeAliasDeclaration, "type"],
+    [K.EnumDeclaration, "enum"],
+    [K.ModuleDeclaration, "namespace"],
+]);
+function identifier(node) {
+    return node !== undefined && node.kind === K.Identifier ? (node.text ?? node.escapedText) : undefined;
+}
+/** The node that names what a decorator or a heritage type refers to: `a` in `@a()`, `a.B` in `extends a.B`. */
+function named(node) {
+    let current = node;
+    while (current !== undefined && current.kind === K.CallExpression) {
+        current = current.expression;
+    }
+    return current;
+}
+/**
+ * The nodes that name a type in a type, at any depth: `Order` and `Error` in
+ * `Result<Order, Error>`, `x` in `typeof x`, and `Order` in `import("./order").Order`.
+ */
+function typeNames(type, found) {
+    if (type === undefined) {
+        return;
+    }
+    const name = type.kind === K.TypeReference ? type.typeName : type.kind === K.TypeQuery ? type.exprName : type.kind === K.ImportType ? type.qualifier : undefined;
+    if (name !== undefined) {
+        found.push(name);
+    }
+    type.forEachChild((child) => typeNames(child, found));
+}
+/** The ties of a signature: the types of its parameters, without `this`, and its return type. */
+function signatureTies(signature, ties) {
+    for (const parameter of signature.parameters ?? []) {
+        if (identifier(parameter.name) === "this") {
+            continue;
+        }
+        const names = [];
+        typeNames(parameter.type, names);
+        ties.push(...names.map((node) => ({ relation: "takes", node })));
+    }
+    const names = [];
+    typeNames(signature.type, names);
+    ties.push(...names.map((node) => ({ relation: "returns", node })));
+}
+const KEYWORDS = new Map([
+    [K.AsyncKeyword, "async"],
+    [K.AbstractKeyword, "abstract"],
+    [K.DeclareKeyword, "declare"],
+    [K.ConstKeyword, "const"],
+    [K.DefaultKeyword, "default"],
+]);
+/**
+ * The modifiers of a statement, from its keywords and from the comments before it. `more`
+ * are modifiers that the caller found elsewhere, such as the `async` of an arrow function.
+ */
+function modifiersOf(statement, sourceFile, more) {
+    const found = new Set(more);
+    for (const modifier of statement.modifiers ?? []) {
+        const known = KEYWORDS.get(modifier.kind);
+        if (known !== undefined) {
+            found.add(known);
+        }
+    }
+    // The text between the end of the node before and the first token of this one holds its
+    // comments.
+    if (sourceFile.text.slice(statement.pos, statement.getStart(sourceFile)).includes("/**")) {
+        found.add("documented");
+    }
+    return MODIFIERS.filter((modifier) => found.has(modifier));
+}
+/** The top-level declarations of a file, in the order of the text. */
+export function collectDeclarations(sourceFile) {
+    const found = [];
+    sourceFile.forEachChild((child) => {
+        const node = child;
+        const modifiers = node.modifiers ?? [];
+        const exported = modifiers.some((modifier) => modifier.kind === K.ExportKeyword);
+        if (node.kind === K.VariableStatement) {
+            for (const declaration of node.declarationList?.declarations ?? []) {
+                const name = identifier(declaration.name);
+                if (name !== undefined && declaration.name !== undefined) {
+                    const ties = [];
+                    const names = [];
+                    typeNames(declaration.type, names);
+                    ties.push(...names.map((node) => ({ relation: "has-type", node })));
+                    // `const make = (order: Order): Total => ..` takes and returns as a function does.
+                    const value = declaration.initializer;
+                    const more = [];
+                    if (value !== undefined && (value.kind === K.ArrowFunction || value.kind === K.FunctionExpression)) {
+                        signatureTies(value, ties);
+                        if ((value.modifiers ?? []).some((modifier) => modifier.kind === K.AsyncKeyword)) {
+                            more.push("async");
+                        }
+                    }
+                    const list = node.declarationList;
+                    if (list !== undefined && /^const\b/.test(sourceFile.text.slice(list.getStart(sourceFile)))) {
+                        more.push("const");
+                    }
+                    found.push({ name, kind: "variable", at: declaration.name, whole: declaration, exported, ties, modifiers: modifiersOf(node, sourceFile, more) });
+                }
+            }
+            return;
+        }
+        const kind = KINDS.get(node.kind);
+        if (kind === undefined) {
+            return;
+        }
+        const name = identifier(node.name);
+        const isDefault = modifiers.some((modifier) => modifier.kind === K.DefaultKeyword);
+        if (name === undefined && !(isDefault && kind === "class") && !(isDefault && kind === "function")) {
+            return;
+        }
+        const ties = [];
+        for (const modifier of modifiers) {
+            const target = modifier.kind === K.Decorator ? named(modifier.expression) : undefined;
+            if (target !== undefined) {
+                ties.push({ relation: "decorator", node: target });
+            }
+        }
+        for (const clause of node.heritageClauses ?? []) {
+            const relation = clause.token === K.ImplementsKeyword ? "implements" : clause.token === K.ExtendsKeyword ? "extends" : undefined;
+            for (const type of clause.types ?? []) {
+                // TypeScript 7.0 gives each type of a heritage clause its `expression`. TypeScript 7.1
+                // gives a type that is only a type, as in `implements` and in the `extends` of an
+                // interface, as a type reference, which names its target in `typeName`.
+                const target = named(type.expression ?? type.typeName);
+                if (relation !== undefined && target !== undefined) {
+                    ties.push({ relation, node: target });
+                }
+            }
+        }
+        if (kind === "function") {
+            signatureTies(node, ties);
+        }
+        found.push({ name: name ?? "default", kind, at: node.name ?? node, whole: node, exported, ties, modifiers: modifiersOf(node, sourceFile, []) });
+    });
+    return found;
+}

package/dist/frontend/dependencies.d.ts

@@ -0,0 +1,53 @@
+import type { Declaration, Fact, Path } from "../core/index.ts";
+/**
+ * The kinds of the references that a `package.json` gives. Only a project that is loaded
+ * with `readDependencies` has them.
+ *
+ * - `dependency`, `dev-dependency`, `peer-dependency` and `optional-dependency`: a package
+ *   that `dependencies`, `devDependencies`, `peerDependencies` or `optionalDependencies` names.
+ * - `transitive-dependency`: a package that the file does not name so, and that one of its
+ *   `dependencies`, `peerDependencies` or `optionalDependencies` needs.
+ * - `transitive-dev-dependency`: a package that only its `devDependencies` need.
+ *
+ * Each of these references has the properties of its package, when the package is
+ * installed: its version and its licence.
+ */
+export declare const DEPENDENCY_KINDS: readonly ["dependency", "dev-dependency", "peer-dependency", "optional-dependency", "transitive-dependency", "transitive-dev-dependency"];
+/** One of {@link DEPENDENCY_KINDS}. */
+export type DependencyKind = (typeof DEPENDENCY_KINDS)[number];
+/** The kinds of the dependencies that a `package.json` names itself. */
+export declare const NAMED_DEPENDENCY_KINDS: readonly string[];
+/**
+ * The properties of a reference to an installed package, from its own `package.json`:
+ *
+ * - `version`: its version, such as `4.17.21`.
+ * - `license`: its licence as the file writes it, such as `MIT` or `(MIT OR Apache-2.0)`. A
+ *   package that names no licence has none.
+ *
+ * A package that is not installed has neither. Two versions of one package are two
+ * references.
+ */
+export declare const PACKAGE_PROPERTIES: readonly ["version", "license"];
+/** The kind of the item that a `package.json` with a name declares: its package. */
+export declare const PACKAGE_ITEM_KIND = "package";
+/** What the `package.json` files of a project give. */
+export interface DependencyFacts {
+    /** Each `package.json` as a unit, with the number of its lines. */
+    readonly units: readonly {
+        readonly path: Path;
+        readonly lines: number;
+    }[];
+    readonly facts: readonly Fact[];
+    /** The package that each `package.json` with a name declares. */
+    readonly declarations: readonly Declaration[];
+}
+/**
+ * The dependencies of the `package.json` files that the files of a project belong to. Each
+ * `package.json` is a unit under its path from the root, and each dependency is a reference
+ * from it to the package, at the line of its key.
+ *
+ * A package that another `package.json` of the project declares is also a reference to that
+ * file. A package that a dependency needs is found in the `node_modules` directories, as
+ * Node finds it; one that is not installed is not followed.
+ */
+export declare function dependencyFacts(root: string, files: readonly string[]): DependencyFacts;

package/dist/frontend/dependencies.js

@@ -0,0 +1,337 @@
+/**
+ * The dependencies that the `package.json` files of a project name: each is a reference
+ * from the `package.json` to a package, so that a rule can say which package may depend on
+ * which. This is the one place that reads `package.json` files.
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { exportSegment, packageSegment } from "./paths.js";
+/**
+ * The kinds of the references that a `package.json` gives. Only a project that is loaded
+ * with `readDependencies` has them.
+ *
+ * - `dependency`, `dev-dependency`, `peer-dependency` and `optional-dependency`: a package
+ *   that `dependencies`, `devDependencies`, `peerDependencies` or `optionalDependencies` names.
+ * - `transitive-dependency`: a package that the file does not name so, and that one of its
+ *   `dependencies`, `peerDependencies` or `optionalDependencies` needs.
+ * - `transitive-dev-dependency`: a package that only its `devDependencies` need.
+ *
+ * Each of these references has the properties of its package, when the package is
+ * installed: its version and its licence.
+ */
+export const DEPENDENCY_KINDS = [
+    "dependency",
+    "dev-dependency",
+    "peer-dependency",
+    "optional-dependency",
+    "transitive-dependency",
+    "transitive-dev-dependency",
+];
+/** The kinds of the dependencies that a `package.json` names itself. */
+export const NAMED_DEPENDENCY_KINDS = ["dependency", "dev-dependency", "peer-dependency", "optional-dependency"];
+/**
+ * The properties of a reference to an installed package, from its own `package.json`:
+ *
+ * - `version`: its version, such as `4.17.21`.
+ * - `license`: its licence as the file writes it, such as `MIT` or `(MIT OR Apache-2.0)`. A
+ *   package that names no licence has none.
+ *
+ * A package that is not installed has neither. Two versions of one package are two
+ * references.
+ */
+export const PACKAGE_PROPERTIES = ["version", "license"];
+/** The kind of the item that a `package.json` with a name declares: its package. */
+export const PACKAGE_ITEM_KIND = "package";
+/** The keys of a `package.json` that name dependencies, with the kind of each. */
+const SECTIONS = [
+    ["dependencies", "dependency"],
+    ["devDependencies", "dev-dependency"],
+    ["peerDependencies", "peer-dependency"],
+    ["optionalDependencies", "optional-dependency"],
+];
+/** The keys whose packages are needed where the package is installed. */
+const INSTALLED = ["dependencies", "peerDependencies", "optionalDependencies"];
+/**
+ * The places of the keys of a JSON text: for each key at the top that has an object, the
+ * keys of that object. The key `""` has the keys at the top themselves.
+ */
+function keyPlaces(text) {
+    const found = new Map();
+    const record = (section, key, place) => {
+        const keys = found.get(section) ?? new Map();
+        found.set(section, keys);
+        if (!keys.has(key)) {
+            keys.set(key, place);
+        }
+    };
+    let depth = 0;
+    let section;
+    let line = 1;
+    let lineStart = 0;
+    for (let at = 0; at < text.length; at++) {
+        const char = text[at];
+        if (char === "\n") {
+            line += 1;
+            lineStart = at + 1;
+        }
+        else if (char === "{" || char === "[") {
+            depth += 1;
+        }
+        else if (char === "}" || char === "]") {
+            depth -= 1;
+        }
+        else if (char === '"') {
+            let end = at + 1;
+            while (end < text.length && text[end] !== '"') {
+                end += text[end] === "\\" ? 2 : 1;
+            }
+            let after = end + 1;
+            while (after < text.length && /\s/.test(text[after])) {
+                after += 1;
+            }
+            if (text[after] === ":" && depth <= 2) {
+                const key = JSON.parse(text.slice(at, end + 1));
+                const place = { line, column: at - lineStart + 1 };
+                if (depth === 1) {
+                    section = key;
+                    record("", key, place);
+                }
+                else if (section !== undefined) {
+                    record(section, key, place);
+                }
+            }
+            at = end;
+        }
+    }
+    return found;
+}
+function read(file) {
+    if (!existsSync(file)) {
+        return undefined;
+    }
+    const text = readFileSync(file, "utf8");
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`refpact: cannot read ${file}: ${error.message}`);
+    }
+    const places = keyPlaces(text);
+    const name = typeof json["name"] === "string" ? json["name"] : undefined;
+    // A `package.json` that has no name and no dependencies, such as one that only sets `"type"`, describes no package.
+    if (name === undefined && SECTIONS.every(([section]) => (places.get(section)?.size ?? 0) === 0)) {
+        return undefined;
+    }
+    return { file, name, lines: text.split("\n").length - (text.endsWith("\n") ? 1 : 0), places, namePlace: places.get("")?.get("name") };
+}
+/** Finds the `package.json` that a file belongs to. */
+class Manifests {
+    byDirectory = new Map();
+    /** The nearest `package.json` that describes a package, in the directory of the file or above it. */
+    of(file) {
+        return this.inDirectory(path.dirname(file));
+    }
+    inDirectory(directory) {
+        if (this.byDirectory.has(directory)) {
+            return this.byDirectory.get(directory);
+        }
+        const parent = path.dirname(directory);
+        const found = read(path.join(directory, "package.json")) ?? (parent === directory ? undefined : this.inDirectory(parent));
+        this.byDirectory.set(directory, found);
+        return found;
+    }
+}
+/** The packages that are installed, as `node_modules` directories have them. */
+class Installed {
+    found = new Map();
+    read = new Map();
+    /** The directory of the package that code in `from` gets for a name, without links; `undefined` when it is not installed. */
+    resolve(from, name) {
+        const key = `${from}\u0000${name}`;
+        if (this.found.has(key)) {
+            return this.found.get(key);
+        }
+        let found;
+        for (let directory = from;; directory = path.dirname(directory)) {
+            const candidate = path.join(directory, "node_modules", name);
+            if (existsSync(path.join(candidate, "package.json"))) {
+                found = realpathSync(candidate);
+                break;
+            }
+            if (path.dirname(directory) === directory) {
+                break;
+            }
+        }
+        this.found.set(key, found);
+        return found;
+    }
+    /** What the `package.json` of the package in a directory says. */
+    package(directory) {
+        let found = this.read.get(directory);
+        if (found === undefined) {
+            let json = {};
+            try {
+                json = JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8"));
+            }
+            catch {
+                // A package that cannot be read needs nothing that can be followed, and says nothing.
+            }
+            const needs = INSTALLED.flatMap((key) => {
+                const value = json[key];
+                return typeof value === "object" && value !== null ? Object.keys(value) : [];
+            });
+            // An old form of the licence is an object with the name as its `type`.
+            const license = json["license"];
+            const named = typeof license === "object" && license !== null ? license["type"] : license;
+            const properties = {};
+            for (const name of PACKAGE_PROPERTIES) {
+                const value = name === "license" ? named : json[name];
+                if (typeof value === "string") {
+                    properties[name] = value;
+                }
+            }
+            found = { needs, properties };
+            this.read.set(directory, found);
+        }
+        return found;
+    }
+}
+/**
+ * The dependencies of the `package.json` files that the files of a project belong to. Each
+ * `package.json` is a unit under its path from the root, and each dependency is a reference
+ * from it to the package, at the line of its key.
+ *
+ * A package that another `package.json` of the project declares is also a reference to that
+ * file. A package that a dependency needs is found in the `node_modules` directories, as
+ * Node finds it; one that is not installed is not followed.
+ */
+export function dependencyFacts(root, files) {
+    const manifests = new Manifests();
+    const found = new Map();
+    for (const file of files) {
+        const manifest = manifests.of(file);
+        if (manifest !== undefined) {
+            found.set(manifest.file, manifest);
+        }
+    }
+    const unitOf = (manifest) => path.relative(root, manifest.file).split(path.sep);
+    const ordered = [...found.values()].sort((a, b) => {
+        const [left, right] = [unitOf(a).join("/"), unitOf(b).join("/")];
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+    const byName = new Map();
+    for (const manifest of ordered) {
+        if (manifest.name !== undefined && !byName.has(manifest.name)) {
+            byName.set(manifest.name, unitOf(manifest));
+        }
+    }
+    const installed = new Installed();
+    const facts = [];
+    const declarations = [];
+    for (const manifest of ordered) {
+        const unit = unitOf(manifest);
+        const file = unit.join("/");
+        // `at` is the directory of the package, when it is installed.
+        const add = (kind, name, place, at, note) => {
+            const sibling = byName.get(name);
+            const properties = at !== undefined ? installed.package(at).properties : {};
+            facts.push({
+                unit,
+                file,
+                line: place.line,
+                column: place.column,
+                tags: [],
+                ...(note !== undefined ? { note } : {}),
+                what: {
+                    type: "reference",
+                    target: [packageSegment(name)],
+                    aliases: sibling !== undefined && sibling !== unit ? [sibling] : [],
+                    kind,
+                    certainty: "exact",
+                    ...(Object.keys(properties).length > 0 ? { properties } : {}),
+                },
+            });
+        };
+        if (manifest.name !== undefined && manifest.namePlace !== undefined) {
+            declarations.push({
+                path: [...unit, exportSegment(manifest.name)],
+                name: manifest.name,
+                unit,
+                file,
+                line: manifest.namePlace.line,
+                column: manifest.namePlace.column,
+                tags: [],
+                kind: PACKAGE_ITEM_KIND,
+                visibility: "exported",
+                relations: [],
+                modifiers: [],
+            });
+        }
+        const named = [];
+        for (const [section, kind] of SECTIONS) {
+            for (const [name, place] of manifest.places.get(section) ?? []) {
+                named.push({ kind, name, place });
+            }
+        }
+        named.sort((a, b) => a.place.line - b.place.line || a.place.column - b.place.column);
+        const directory = path.dirname(manifest.file);
+        for (const { kind, name, place } of named) {
+            add(kind, name, place, installed.resolve(directory, name));
+        }
+        // What the dependencies need, on the shortest way first. A package is found on the way
+        // that says most: first through what is installed with the package, then through what
+        // only its development needs.
+        // A package is known by its name and its version: another version of a package that
+        // the file names is another package. One that is not installed has no version, and
+        // then the name stands for all of them, as the name of the own package does.
+        const known = new Set();
+        const know = (name, at) => {
+            known.add(at !== undefined ? `${name}@${installed.package(at).properties["version"] ?? ""}` : name);
+        };
+        const isKnown = (name, at) => known.has(name) || known.has(`${name}@${installed.package(at).properties["version"] ?? ""}`);
+        for (const { kind, name } of named) {
+            if (kind !== "dev-dependency") {
+                know(name, installed.resolve(directory, name));
+            }
+        }
+        if (manifest.name !== undefined) {
+            known.add(manifest.name);
+        }
+        const walk = (development) => {
+            const kind = development ? "transitive-dev-dependency" : "transitive-dependency";
+            const seen = new Set([realpathSync(directory)]);
+            const queue = [];
+            for (const { kind: of, name, place } of named) {
+                const at = (of === "dev-dependency") === development ? installed.resolve(directory, name) : undefined;
+                if (at !== undefined && !seen.has(at)) {
+                    seen.add(at);
+                    queue.push({ at, place, through: [name] });
+                }
+            }
+            for (let next = 0; next < queue.length; next++) {
+                const { at, place, through } = queue[next];
+                for (const name of installed.package(at).needs) {
+                    const needed = installed.resolve(at, name);
+                    if (needed === undefined || seen.has(needed)) {
+                        continue;
+                    }
+                    seen.add(needed);
+                    if (!isKnown(name, needed)) {
+                        know(name, needed);
+                        add(kind, name, place, needed, `through ${through.map((one) => `\`${one}\``).join(", ")}`);
+                    }
+                    queue.push({ at: needed, place, through: [...through, name] });
+                }
+            }
+        };
+        walk(false);
+        for (const { kind, name } of named) {
+            if (kind === "dev-dependency") {
+                know(name, installed.resolve(directory, name));
+            }
+        }
+        walk(true);
+    }
+    return { units: ordered.map((manifest) => ({ path: unitOf(manifest), lines: manifest.lines })), facts, declarations };
+}