@aoelite/refpact-ts 0.0.0-stage → 0.2.0

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 };
+}

package/dist/frontend/imports.d.ts

@@ -0,0 +1,149 @@
+import type { Node, SourceFile } from "./compiler.ts";
+import type { DependencyKind } from "./dependencies.ts";
+/** The reference kinds of the TypeScript front end. */
+export declare const KINDS: readonly ["import", "import-type", "dynamic-import", "require", "export-from", "export-type-from", "resolve", "global"];
+/**
+ * The kind of a place that asks where a module is and does not load it: `require.resolve("m")`,
+ * `import.meta.resolve("m")` and `new URL("./m", import.meta.url)`.
+ */
+export declare const RESOLVE_KIND: Kind;
+/**
+ * The kind of a use of a global of the host, such as `process.env` or `fetch(..)`: a name
+ * that no file of the project declares and that the ECMAScript library does not declare.
+ */
+export declare const GLOBAL_KIND: Kind;
+/**
+ * The kind of a use of a member of a class, an interface or an enum: `order.total`. Only a
+ * project that is loaded with `resolveMembers` has this kind.
+ */
+export declare const MEMBER_KIND: Kind;
+/** One of the reference kinds of the TypeScript front end. */
+export type Kind = (typeof KINDS)[number] | "member" | DependencyKind;
+/** One name taken from a module: `a` in `import { a as b } from "m"`. */
+export interface NameUse {
+    /** The name as the module exports it. `default` for a default import. */
+    readonly exported: string;
+    readonly kind: Kind;
+    /** The node that carries the position and the symbol. */
+    readonly node: Node;
+    /**
+     * True for a name in the braces of an `import` or an `export ... from`. The symbol of such
+     * a name is an alias of the export that the module has under `exported`.
+     */
+    readonly specifier?: true;
+}
+/** A local name that stands for a whole module: `ns` in `import * as ns from "m"`. */
+export interface NamespaceBinding {
+    readonly local: string;
+    readonly node: Node;
+    readonly kind: Kind;
+}
+/** One statement or expression that names a module. */
+export interface ModuleUse {
+    readonly specifier: string;
+    readonly specifierNode: Node;
+    /** The node whose position is reported for a use of the module as a whole. */
+    readonly at: Node;
+    readonly kind: Kind;
+    /** True when the construct uses the module as a whole and not only some names of it. */
+    readonly whole: boolean;
+    readonly names: readonly NameUse[];
+    readonly namespace?: NamespaceBinding;
+    /** The `require` identifier of a `require("m")` call. It may be a local name, not Node's. */
+    readonly requireNode?: Node;
+    /**
+     * How the code gives the specifier, when it is not one string in the place.
+     * - `constant`: the code computes it from strings that are known, and `specifier` is the result.
+     * - `pattern`: a part is not known. `specifier` has a `*` for each such part.
+     * - `glob`: the argument of `import.meta.glob`, which is a glob pattern.
+     * - `unknown`: nothing of it is known. `specifier` is empty.
+     */
+    readonly computed?: "constant" | "pattern" | "glob" | "unknown";
+    /**
+     * The names of constants that the specifier is computed from, each with the name of the
+     * declaration that was read. The value holds only when the compiler says that both are
+     * one variable.
+     */
+    readonly constants?: readonly {
+        readonly use: Node;
+        readonly declaration: Node;
+    }[];
+    /** True for `new URL(..)`, which may name a file that is no module, such as an image. */
+    readonly asset?: true;
+}
+/** `object.member` or `object.member` in a type, where `object` may be a namespace binding. */
+export interface MemberUse {
+    readonly object: Node;
+    readonly member: Node;
+    readonly objectName: string;
+    readonly memberName: string;
+    /**
+     * For a member of a `const` that stands for a namespace binding, `const f = ns; f.name`: the
+     * name of the declaration of the `const`, and the name of the binding in its value.
+     * `object` is then the `const` where it is used, and `objectName` is the name of the binding.
+     */
+    readonly alias?: {
+        readonly declaration: Node;
+        readonly of: Node;
+    };
+}
+/**
+ * Finds every construct of the file that names a module.
+ *
+ * `prune` lets the visit leave out nodes, see {@link Mentions}. It must be `false` for a
+ * JavaScript file: the compiler makes nodes from the types in JSDoc comments, and such a node
+ * is in the text before the node that it belongs to, not in it.
+ */
+export declare function collectModuleUses(sourceFile: SourceFile, prune: boolean): ModuleUse[];
+/** Finds `object.member` where `object` is one of the given local names. */
+export declare function collectMemberUses(sourceFile: SourceFile, locals: ReadonlySet<string>, prune: boolean): MemberUse[];
+/**
+ * The names after the dot of each `object.name` of a file, in the order of the text. What a
+ * name is a member of depends on the type of the object, which only the compiler knows.
+ * Every node of the file is visited.
+ */
+export declare function collectAccesses(sourceFile: SourceFile): Node[];
+/**
+ * A name in a file that may be a global: `fetch` in `fetch(..)`, or `process` and its member
+ * `env` in `process.env`. Through `globalThis`, `window`, `self` and `global`, the global is
+ * the name after the dot: `window.localStorage` is `localStorage`. Only the compiler can tell
+ * whether the names are globals: `node` and `through` are the nodes to ask.
+ */
+export interface GlobalUse {
+    /** The node that carries the position. */
+    readonly at: Node;
+    /** The node of the name of the global. */
+    readonly node: Node;
+    /** The name of the global. */
+    readonly name: string;
+    /** The member of the global that is used, if any: `env` in `process.env`. */
+    readonly member?: string;
+    /** `globalThis`, `window`, `self` or `global`, when the global is written as its member. */
+    readonly through?: Node;
+    /** The shorthand property that the name is, `{ fetch }`: the compiler is asked for its value apart. */
+    readonly shorthand?: Node;
+}
+/**
+ * The names in value positions that may be globals, in the order of the text. Types,
+ * the names after a dot, JSX tags and the callee of `require(..)` are left out.
+ */
+export declare function collectGlobalUses(sourceFile: SourceFile): GlobalUse[];
+/**
+ * The markers that a file can contain: a use of the global `console`, a `debugger`
+ * statement, and `unresolved-import`, an import of a relative path, a `paths` alias or a
+ * `#name` of `imports` that leads to no file.
+ */
+export declare const MARKERS: readonly ["console", "debugger", "unresolved-import", "computed-import"];
+/** One of {@link MARKERS}. */
+export type MarkerName = (typeof MARKERS)[number];
+/**
+ * A place that may be a marker. A `debugger` statement is one. `console.name` is one when
+ * `console` is the global, which only the compiler can tell: `object` is the node to ask.
+ */
+export interface MarkerUse {
+    readonly marker: MarkerName;
+    readonly at: Node;
+    readonly object?: Node;
+}
+/** The `debugger` statements of a file, and its `console.name`, in the order of the text. */
+export declare function collectMarkers(sourceFile: SourceFile, prune: boolean): MarkerUse[];