@aoelite/refpact-ts 0.0.0-stage → 0.2.0

package/dist/core/wasm.js

@@ -0,0 +1,67 @@
+/**
+ * The core of refpact, the Rust crate `refpact-core`, as WebAssembly (SPEC section 8).
+ *
+ * The module is `wasm/refpact_core.wasm` beside `src` and `dist`, built by `cargo xtask wasm`.
+ * It is compiled once, on the first call, and speaks JSON requests. This is the only file of
+ * the core that reads a file.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The version of the wire format that this package speaks. */
+const VERSION = 1;
+let core;
+/** Counts the instances. A handle of a fact set is valid only in the instance that made it. */
+let generation = 0;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function instance() {
+    if (core !== undefined) {
+        return core;
+    }
+    const url = new URL("../../wasm/refpact_core.wasm", import.meta.url);
+    let bytes;
+    try {
+        bytes = readFileSync(url);
+    }
+    catch (cause) {
+        throw new Error(`refpact: the core is missing at ${fileURLToPath(url)}. Build it with \`cargo xtask wasm\`.`, { cause });
+    }
+    const made = new WebAssembly.Instance(new WebAssembly.Module(bytes), {}).exports;
+    core = made;
+    generation += 1;
+    const { version } = JSON.parse(call('{"op":"version"}'));
+    if (version !== VERSION) {
+        core = undefined;
+        throw new Error(`refpact: the core speaks version ${version} of the wire format, not ${VERSION}. Build it again with \`cargo xtask wasm\`.`);
+    }
+    return made;
+}
+/** The instance that the handles of fact sets belong to. */
+export function currentGeneration() {
+    instance();
+    return generation;
+}
+/**
+ * Sends one request and returns the answer as JSON text. Throws when the core finds the
+ * request not valid, which is a bug of this package and not of the rule.
+ */
+export function call(request) {
+    const exports = instance();
+    const bytes = encoder.encode(request);
+    const address = exports.refpact_alloc(bytes.length);
+    new Uint8Array(exports.memory.buffer, address, bytes.length).set(bytes);
+    let status;
+    try {
+        status = exports.refpact_call(address, bytes.length);
+    }
+    catch (error) {
+        // A trap leaves the instance in an unknown state. The next call starts a new one.
+        core = undefined;
+        throw error;
+    }
+    const answer = decoder.decode(new Uint8Array(exports.memory.buffer, exports.refpact_answer(), exports.refpact_answer_len()));
+    if (status !== 0) {
+        throw new Error(`refpact: the core rejected a request: ${answer}`);
+    }
+    return answer;
+}

package/dist/custom.d.ts

@@ -0,0 +1,166 @@
+/** Checks of the user: what a rule sees, and how its violations are made (SPEC 4.15). */
+import type { Declaration, Detail, Fact, FactSet, Path, Reference, GraphResult, SelectResult, Step, TanglesResult, Violation } from "./core/index.ts";
+/** An import that the rule sees: the filters and the exemptions of the rule let it pass. */
+export interface SeenImport {
+    /** The fact of the import. */
+    readonly fact: Fact;
+    /** The reference of the fact. */
+    readonly reference: Reference;
+    /** The file that imports. */
+    readonly file: Path;
+    /** Whether the rule selects the file that imports. */
+    readonly subject: boolean;
+    /** The paths of the import, `[target, ...aliases]`. */
+    readonly paths: readonly Path[];
+    /** For each path, the file that has it, or `undefined` for a package or a module of Node. */
+    readonly owners: readonly (Path | undefined)[];
+    /**
+     * For each list of targets that the check names: the first path of the import that the
+     * list matches. A list that matches no path of the import has no entry.
+     */
+    readonly hits: Readonly<Record<string, Path>>;
+}
+/** A marker of a selected file that the rule sees. */
+export interface SeenMarker {
+    /** The fact of the marker. */
+    readonly fact: Fact;
+    /** The file. */
+    readonly file: Path;
+    /** The marker. */
+    readonly marker: string;
+}
+/** An edge of the graph of files, with the first import that makes it. */
+export interface ImportEdge {
+    /** The file that the edge leads to. */
+    readonly to: Path;
+    /** The fact of the import. */
+    readonly fact: Fact;
+    /** The path of the import that leads to the file. */
+    readonly target: Path;
+}
+/** Files that all reach each other by imports, with one of their cycles: see {@link Graph.tangles}. */
+export interface Tangle {
+    /** The files of the tangle, in the order of the files of the project. */
+    readonly members: readonly Path[];
+    /** A shortest cycle through the first member. The last step leads back to it. */
+    readonly cycle: readonly Step[];
+}
+/** The names of the lists of patterns of a check, in the order of the lists in the request. @internal */
+export interface ListNames {
+    readonly targets: readonly string[];
+    readonly files: readonly string[];
+}
+type Selection = Extract<SelectResult, {
+    ok: true;
+}>;
+/** A graph of the core. With `subjects`, it is the graph of the selected files. @internal */
+export type CoreGraph = Extract<GraphResult, {
+    ok: true;
+}>;
+type CoreTangles = Extract<TanglesResult, {
+    ok: true;
+}>["tangles"];
+/** Asks the core for a graph or for its tangles. The core makes each only for a check that uses it. @internal */
+export interface CoreGraphs {
+    readonly graph: (subjects: boolean) => CoreGraph;
+    readonly tangles: (subjects: boolean) => CoreTangles;
+}
+/**
+ * What a check of the user gets: the files that the rule selects and what the rule sees. The
+ * rule has applied its filters and its exemptions.
+ */
+export declare class Scope {
+    /** The name of the rule. */
+    readonly ruleName: string;
+    /** The facts of the project. */
+    readonly facts: FactSet;
+    /** The files that the rule selects, in order. */
+    readonly subjects: readonly Path[];
+    /** The imports that the rule sees, of all files, in the order of the facts. */
+    readonly imports: readonly SeenImport[];
+    /** The markers of the selected files that the rule sees. */
+    readonly markers: readonly SeenMarker[];
+    /** The declarations of the selected files that the rule sees. */
+    readonly declarations: readonly Declaration[];
+    /** @internal */
+    protected readonly selection: Selection;
+    private readonly selected;
+    private readonly lists;
+    private firstFiles;
+    private readonly core;
+    private readonly made;
+    /** @internal */
+    constructor(ruleName: string, facts: FactSet, selection: Selection, names: ListNames, core: CoreGraphs);
+    /** Whether the rule selects the file. */
+    selects(file: Path): boolean;
+    /**
+     * The files that a list of file patterns of the check matches, by the name of the list.
+     * The files match as the files of a rule do. Throws when the check names no such list.
+     */
+    matched(list: string): readonly Path[];
+    /**
+     * The graph of all files, selected or not, from the imports that the rule sees. An import
+     * leads to the file of each of its paths, so an import through a barrel file leads to the
+     * barrel and to the file that declares the name. An import of the own file is no edge.
+     */
+    graph(): Graph;
+    /**
+     * The graph of the selected files only, from the imports that the rule sees: the graph
+     * whose tangles `mustBeAcyclic` reports. An import of a file that the rule does not select
+     * is no edge, so a cycle through such a file is no tangle.
+     */
+    subjectGraph(): Graph;
+    /**
+     * A violation at the place of a fact, with its note. A message gives a `custom` detail,
+     * which a baseline counts by `key`, or by the message when there is no key.
+     */
+    violationAt(fact: Fact, detail: string | Detail, key?: string): Violation;
+    /** A violation at the place of a declaration. */
+    violationOfItem(declaration: Declaration, detail: string | Detail, baselineKey?: string): Violation;
+    /** A violation about a file as a whole, with no line. */
+    violationOfFile(file: Path, detail: string | Detail, baselineKey?: string): Violation;
+}
+/**
+ * What a check of items gets: the {@link Scope} of the rule, and the items that the filters
+ * of the rule select.
+ */
+export declare class ItemScope extends Scope {
+    /** The items that the rule selects, in order. */
+    readonly items: readonly Declaration[];
+    /**
+     * The imports that the rule sees inside the selected items. A front end that does not say
+     * which item holds an import gives none: the TypeScript front end is one.
+     */
+    readonly itemImports: readonly SeenImport[];
+    /** @internal */
+    constructor(ruleName: string, facts: FactSet, selection: Selection, names: ListNames, core: CoreGraphs);
+}
+/** A graph of files: see {@link Scope.graph} and {@link Scope.subjectGraph}. */
+export declare class Graph {
+    /** The file of each node. */
+    private readonly units;
+    private readonly numbers;
+    /** For each file, by its number: the edges, each with the number of the file that it leads to. */
+    private readonly edges;
+    /** Asks the core for the tangles, on the first use of them. */
+    private readonly coreTangles;
+    private found;
+    /** @internal */
+    constructor(facts: FactSet, graph: CoreGraph, coreTangles: () => CoreTangles);
+    /** The edges of a file, in the order of their first imports. A path that is no file of the graph has none. */
+    edgesOf(file: Path): readonly ImportEdge[];
+    /**
+     * The tangles: each group of two or more files that all reach each other, once, in the
+     * order of their first files.
+     */
+    tangles(): Tangle[];
+    /** An edge as the step of a report. */
+    private step;
+    /**
+     * A shortest chain of imports from a file to a file that is an end, as the steps of a
+     * report. No steps: the file itself is an end. `undefined`: no chain leads to an end. The
+     * search is breadth-first with the edges of each file in their order.
+     */
+    chain(from: Path, isEnd: (file: Path) => boolean): Step[] | undefined;
+}
+export {};

package/dist/custom.js

@@ -0,0 +1,239 @@
+/**
+ * What a check of the user gets: the files that the rule selects and what the rule sees. The
+ * rule has applied its filters and its exemptions.
+ */
+export class Scope {
+    /** The name of the rule. */
+    ruleName;
+    /** The facts of the project. */
+    facts;
+    /** The files that the rule selects, in order. */
+    subjects;
+    /** The imports that the rule sees, of all files, in the order of the facts. */
+    imports;
+    /** The markers of the selected files that the rule sees. */
+    markers;
+    /** The declarations of the selected files that the rule sees. */
+    declarations;
+    /** @internal */
+    selection;
+    selected;
+    lists;
+    firstFiles;
+    core;
+    made = {};
+    /** @internal */
+    constructor(ruleName, facts, selection, names, core) {
+        this.ruleName = ruleName;
+        this.facts = facts;
+        this.selection = selection;
+        this.core = core;
+        const units = facts.units;
+        this.subjects = selection.subjects.map((unit) => units[unit]);
+        this.selected = new Set(this.subjects.map(key));
+        this.lists = new Map(names.files.map((name, list) => [name, (selection.units[list] ?? []).map((unit) => units[unit])]));
+        const subjectSet = new Set(selection.subjects);
+        this.imports = selection.references.map((seen) => {
+            const fact = facts.facts[seen.fact];
+            const reference = fact.what;
+            const paths = [reference.target, ...reference.aliases];
+            const hits = {};
+            seen.hits?.forEach((hit, list) => {
+                if (hit !== null) {
+                    hits[names.targets[list]] = paths[hit];
+                }
+            });
+            return {
+                fact,
+                reference,
+                file: units[seen.unit],
+                subject: subjectSet.has(seen.unit),
+                paths,
+                owners: seen.owners.map((owner) => (owner === null ? undefined : units[owner])),
+                hits,
+            };
+        });
+        this.markers = selection.markers.map((position) => {
+            const fact = facts.facts[position];
+            return { fact, file: fact.unit, marker: fact.what.marker };
+        });
+        const declarations = facts.declarations ?? [];
+        this.declarations = selection.declarations.map((position) => declarations[position]);
+    }
+    /** Whether the rule selects the file. */
+    selects(file) {
+        return this.selected.has(key(file));
+    }
+    /**
+     * The files that a list of file patterns of the check matches, by the name of the list.
+     * The files match as the files of a rule do. Throws when the check names no such list.
+     */
+    matched(list) {
+        const files = this.lists.get(list);
+        if (files === undefined) {
+            throw new TypeError(`refpact: rule \`${this.ruleName}\`: the check names no list of files \`${list}\``);
+        }
+        return files;
+    }
+    /**
+     * The graph of all files, selected or not, from the imports that the rule sees. An import
+     * leads to the file of each of its paths, so an import through a barrel file leads to the
+     * barrel and to the file that declares the name. An import of the own file is no edge.
+     */
+    graph() {
+        this.made.all ??= new Graph(this.facts, this.core.graph(false), () => this.core.tangles(false));
+        return this.made.all;
+    }
+    /**
+     * The graph of the selected files only, from the imports that the rule sees: the graph
+     * whose tangles `mustBeAcyclic` reports. An import of a file that the rule does not select
+     * is no edge, so a cycle through such a file is no tangle.
+     */
+    subjectGraph() {
+        this.made.subjects ??= new Graph(this.facts, this.core.graph(true), () => this.core.tangles(true));
+        return this.made.subjects;
+    }
+    /**
+     * A violation at the place of a fact, with its note. A message gives a `custom` detail,
+     * which a baseline counts by `key`, or by the message when there is no key.
+     */
+    violationAt(fact, detail, key) {
+        return {
+            rule: this.ruleName,
+            unit: fact.unit,
+            file: fact.file,
+            line: fact.line,
+            column: fact.column,
+            ...(fact.note !== undefined ? { note: fact.note } : {}),
+            detail: custom(detail, key),
+        };
+    }
+    /** A violation at the place of a declaration. */
+    violationOfItem(declaration, detail, baselineKey) {
+        const { unit, file, line, column } = declaration;
+        return { rule: this.ruleName, unit, file, line, column, detail: custom(detail, baselineKey) };
+    }
+    /** A violation about a file as a whole, with no line. */
+    violationOfFile(file, detail, baselineKey) {
+        if (this.firstFiles === undefined) {
+            this.firstFiles = new Map();
+            for (const fact of this.facts.facts) {
+                const unit = key(fact.unit);
+                if (!this.firstFiles.has(unit)) {
+                    this.firstFiles.set(unit, fact.file);
+                }
+            }
+        }
+        return { rule: this.ruleName, unit: file, file: this.firstFiles.get(key(file)) ?? "", line: 0, column: 0, detail: custom(detail, baselineKey) };
+    }
+}
+/**
+ * What a check of items gets: the {@link Scope} of the rule, and the items that the filters
+ * of the rule select.
+ */
+export class ItemScope extends Scope {
+    /** The items that the rule selects, in order. */
+    items;
+    /**
+     * The imports that the rule sees inside the selected items. A front end that does not say
+     * which item holds an import gives none: the TypeScript front end is one.
+     */
+    itemImports;
+    /** @internal */
+    constructor(ruleName, facts, selection, names, core) {
+        super(ruleName, facts, selection, names, core);
+        const declarations = facts.declarations ?? [];
+        this.items = (selection.items ?? []).map((position) => declarations[position]);
+        this.itemImports = this.imports.filter((_, index) => selection.references[index]?.inside === true);
+    }
+}
+/** A graph of files: see {@link Scope.graph} and {@link Scope.subjectGraph}. */
+export class Graph {
+    /** The file of each node. */
+    units;
+    numbers;
+    /** For each file, by its number: the edges, each with the number of the file that it leads to. */
+    edges;
+    /** Asks the core for the tangles, on the first use of them. */
+    coreTangles;
+    found;
+    /** @internal */
+    constructor(facts, graph, coreTangles) {
+        this.coreTangles = coreTangles;
+        this.units = graph.nodes?.map((unit) => facts.units[unit]) ?? facts.units;
+        this.numbers = new Map();
+        this.units.forEach((unit, number) => {
+            if (!this.numbers.has(key(unit))) {
+                this.numbers.set(key(unit), number);
+            }
+        });
+        // The core makes the edges, as it does for the built-in rules.
+        this.edges = graph.edges.map((edges) => edges.map(([to, position, path]) => {
+            const fact = facts.facts[position];
+            const reference = fact.what;
+            return { to: this.units[to], node: to, fact, target: [reference.target, ...reference.aliases][path] };
+        }));
+    }
+    /** The edges of a file, in the order of their first imports. A path that is no file of the graph has none. */
+    edgesOf(file) {
+        const node = this.numbers.get(key(file));
+        return node === undefined ? [] : this.edges[node];
+    }
+    /**
+     * The tangles: each group of two or more files that all reach each other, once, in the
+     * order of their first files.
+     */
+    tangles() {
+        this.found ??= this.coreTangles();
+        return this.found.map(({ members, cycle }) => ({
+            members: members.map((node) => this.units[node]),
+            cycle: cycle.map(([node, edge]) => this.step(node, this.edges[node][edge])),
+        }));
+    }
+    /** An edge as the step of a report. */
+    step(from, edge) {
+        const { fact, target } = edge;
+        const kind = fact.what.kind;
+        return { from: this.units[from], to: this.units[edge.node], file: fact.file, line: fact.line, column: fact.column, target, kind };
+    }
+    /**
+     * A shortest chain of imports from a file to a file that is an end, as the steps of a
+     * report. No steps: the file itself is an end. `undefined`: no chain leads to an end. The
+     * search is breadth-first with the edges of each file in their order.
+     */
+    chain(from, isEnd) {
+        const start = this.numbers.get(key(from));
+        if (start === undefined) {
+            return undefined;
+        }
+        // For each file that the search found: the file and the edge that led to it.
+        const foundBy = new Map();
+        const queue = [start];
+        for (let next = 0; next < queue.length; next++) {
+            const node = queue[next];
+            if (isEnd(this.units[node])) {
+                const steps = [];
+                for (let current = node, found = foundBy.get(current); found !== undefined; current = found.from, found = foundBy.get(current)) {
+                    steps.push(this.step(found.from, found.edge));
+                }
+                return steps.reverse();
+            }
+            for (const edge of this.edges[node] ?? []) {
+                if (edge.node !== start && !foundBy.has(edge.node)) {
+                    foundBy.set(edge.node, { from: node, edge });
+                    queue.push(edge.node);
+                }
+            }
+        }
+        return undefined;
+    }
+}
+function key(path) {
+    return path.join("\u0000");
+}
+function custom(detail, key) {
+    if (typeof detail !== "string") {
+        return detail;
+    }
+    return { type: "custom", message: detail, ...(key !== undefined ? { key } : {}) };
+}

package/dist/filters.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The filters of a rule: what it leaves out, why it exists and how much it weighs.
+ *
+ * A rule, layers and an onion architecture have the same filters. Each filter is written
+ * once, here: {@link addFilters} gives its method to all of them, so a new filter cannot be
+ * missing from one.
+ */
+import type { Rule as CoreRule } from "./core/index.ts";
+import type { Kind } from "./frontend/imports.ts";
+import type { AnyOf } from "./rules.ts";
+/** One filter, as a value that a set of rules keeps until its rules are made. @internal */
+export interface Filter {
+    /**
+     * Whether the filter says which imports a rule sees. A rule that looks at no import, such
+     * as "every file is in a layer", does not get such a filter: there, an exemption that lets
+     * nothing pass would be an error.
+     */
+    readonly aboutImports: boolean;
+    /** The rule of the core with the filter. */
+    readonly apply: (rule: CoreRule) => CoreRule;
+}
+/** What has filters: it gives itself again with one more filter. @internal */
+export interface Filtered<Self> {
+    /** @internal */
+    filtered(filter: Filter): Self;
+}
+/** The filters of a rule, of layers and of an onion architecture. */
+export interface Filters<Self> {
+    /**
+     * Says why this exists. The report of a violation prints the reason below the name of the
+     * rule, so whoever breaks the rule learns what it protects.
+     */
+    because(reason: string): Self;
+    /**
+     * Makes this a warning: the violations are reported with `console.warn`, and the check
+     * passes. A rule that cannot fail as written is still an error, and so is a stale
+     * baseline. {@link ImportRule.evaluate} gives the violations of a warning as of any rule.
+     *
+     * ```ts
+     * rule("new code does not print").files(all()).mustNotContain("console").asWarning().check(app);
+     * ```
+     */
+    asWarning(): Self;
+    /** Counts only these kinds of import. */
+    onlyKinds(...kinds: Kind[]): Self;
+    /** Counts all kinds of import except these. */
+    ignoringKinds(...kinds: Kind[]): Self;
+    /**
+     * Leaves out the imports that the analysis could not prove: the files that a computed
+     * specifier such as `` import(`./locales/${name}.ts`) `` can name.
+     */
+    ignoringCandidates(): Self;
+    /** Leaves out `import type`, type-only names, `import("m")` in types, and `export type .. from`. */
+    ignoringTypeImports(): Self;
+    /**
+     * The imports from these files of these targets are not seen: one known import that is
+     * allowed. Files match as the files of a rule do; targets as in `mustNotImport`. For a
+     * cycle or a chain, the import is no edge.
+     *
+     * An exemption that lets no import pass is an error, so it goes when the code that it
+     * allows goes. Call this again for more exemptions.
+     */
+    ignoringImport(from: AnyOf<string>, to: AnyOf): Self;
+}
+/**
+ * Gives a class the methods of {@link Filters}. The class says that it has them with
+ * `interface Name extends Filters<Name> {}`.
+ *
+ * @internal
+ */
+export declare function addFilters(target: {
+    readonly prototype: Filtered<unknown>;
+}): void;

package/dist/filters.js

@@ -0,0 +1,39 @@
+import { filePattern, targetPattern } from "./patterns.js";
+const about = (apply) => ({ aboutImports: true, apply });
+/** The methods of {@link Filters}, written once for every class that has them. */
+const methods = {
+    because(reason) {
+        return this.filtered({ aboutImports: false, apply: (rule) => ({ ...rule, reason }) });
+    },
+    asWarning() {
+        return this.filtered({ aboutImports: false, apply: (rule) => ({ ...rule, severity: "warning" }) });
+    },
+    onlyKinds(...kinds) {
+        return this.filtered(about((rule) => ({ ...rule, kinds: { type: "only", kinds } })));
+    },
+    ignoringKinds(...kinds) {
+        return this.filtered(about((rule) => ({ ...rule, kinds: { type: "except", kinds } })));
+    },
+    ignoringCandidates() {
+        return this.filtered(about((rule) => ({ ...rule, candidates: "ignore" })));
+    },
+    ignoringTypeImports() {
+        return this.filtered(about((rule) => ({ ...rule, kinds: { type: "except", kinds: ["import-type", "export-type-from"] } })));
+    },
+    ignoringImport(from, to) {
+        const exemption = { from: from.patterns.map(filePattern), to: to.patterns.map(targetPattern) };
+        return this.filtered(about((rule) => ({ ...rule, exemptions: [...(rule.exemptions ?? []), exemption] })));
+    },
+};
+/**
+ * Gives a class the methods of {@link Filters}. The class says that it has them with
+ * `interface Name extends Filters<Name> {}`.
+ *
+ * @internal
+ */
+export function addFilters(target) {
+    Object.defineProperties(target.prototype, Object.getOwnPropertyDescriptors(methods));
+    for (const name of Object.keys(methods)) {
+        Object.defineProperty(target.prototype, name, { enumerable: false });
+    }
+}

package/dist/frontend/checks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Switches for the tests of this package. Each one makes a short way of the front end also
+ * take the long way, and a difference between the two is an error.
+ *
+ * - `aliases`: the first step of an alias is read from the exports of the module. With the
+ *   switch, it is compared with the answer of the compiler for that name.
+ * - `walk`: a node whose text has no word that can name a module is not visited. With the
+ *   switch, all nodes are also visited, and the two visits must find the same.
+ *
+ * @internal
+ */
+export declare const checks: {
+    aliases: boolean;
+    walk: boolean;
+};

package/dist/frontend/checks.js

@@ -0,0 +1,12 @@
+/**
+ * Switches for the tests of this package. Each one makes a short way of the front end also
+ * take the long way, and a difference between the two is an error.
+ *
+ * - `aliases`: the first step of an alias is read from the exports of the module. With the
+ *   switch, it is compared with the answer of the compiler for that name.
+ * - `walk`: a node whose text has no word that can name a module is not visited. With the
+ *   switch, all nodes are also visited, and the two visits must find the same.
+ *
+ * @internal
+ */
+export const checks = { aliases: false, walk: false };

package/dist/frontend/classic.d.ts

@@ -0,0 +1,3 @@
+import type { Backend, Installed } from "./compiler.ts";
+/** Loads the compiler of the installed TypeScript 6. */
+export declare function loadClassic(installed: Installed): Promise<Backend>;