@aoelite/refpact-ts 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AoElite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# refpact
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Architecture tests for TypeScript 6 and 7: rules about what files may import, checked as
+ordinary tests under Vitest or `node --test`. The compiler of your project resolves each
+import.
+
+```sh
+pnpm add --save-dev @aoelite/refpact-ts
+```
+
+```ts
+import { test } from "vitest";
+import { anyOf, loadProject, pkg, rule } from "@aoelite/refpact-ts";
+
+const app = loadProject("tsconfig.json");
+
+test("the user interface does not import the database", () => {
+  rule("the user interface does not import the database")
+    .files(anyOf("src/ui/**"))
+    .mustNotImport(anyOf("src/db/**", pkg("pg")))
+    .check(app);
+});
+```
+
+`check` throws an error, and the message of the error is the report:
+
+```text
+rule `the user interface does not import the database` is violated in 1 place(s):
+  src/ui/view.ts:3:10: [the user interface does not import the database] src/ui/view.ts uses src/db/client.ts#query (import, written as src/db/index.ts#query)
+```
+
+- [The TypeScript guide](https://github.com/AoElite/RefPact/blob/main/docs/typescript.md):
+  how to install the package, every rule, and the limits of the analysis.
+- [All that you can check](https://github.com/AoElite/RefPact#what-you-can-check), also in
+  Rust.
+
+## License
+
+MIT

package/dist/baseline.d.ts

@@ -0,0 +1,26 @@
+import type { BaselineEntry, PathFormat, Violation } from "./core/index.ts";
+import type { Failure } from "./rules.ts";
+/**
+ * A file of violations that the project accepts for now.
+ *
+ * A rule uses a baseline only when it is checked with `checkWithBaseline`. Plain `check`
+ * never reads one.
+ *
+ * The file is text, one accepted violation per line, without line numbers of the source.
+ * Commit it. To write it, run the tests once with `REFPACT_BASELINE=update`.
+ */
+export declare class Baseline {
+    /** The absolute path of the file. */
+    readonly file: string;
+    /** @internal */
+    constructor(file: string);
+    /** @internal The entries, or the reason why the file cannot be read. A file that is not there is empty. */
+    read(): readonly BaselineEntry[] | Failure;
+    /** @internal Replaces the entries of one rule with its current violations. */
+    write(rule: string, violations: readonly Violation[], format: PathFormat): Failure | undefined;
+}
+/**
+ * The baseline in the file at `file`. A relative path is relative to the working directory;
+ * in a test, give a path from `import.meta.dirname`.
+ */
+export declare function baseline(file: string): Baseline;

package/dist/baseline.js

@@ -0,0 +1,65 @@
+/** The baseline file. */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { baselineEntries, formatBaseline, parseBaseline } from "./core/index.js";
+/**
+ * A file of violations that the project accepts for now.
+ *
+ * A rule uses a baseline only when it is checked with `checkWithBaseline`. Plain `check`
+ * never reads one.
+ *
+ * The file is text, one accepted violation per line, without line numbers of the source.
+ * Commit it. To write it, run the tests once with `REFPACT_BASELINE=update`.
+ */
+export class Baseline {
+    /** The absolute path of the file. */
+    file;
+    /** @internal */
+    constructor(file) {
+        this.file = path.resolve(file);
+    }
+    /** @internal The entries, or the reason why the file cannot be read. A file that is not there is empty. */
+    read() {
+        if (!existsSync(this.file)) {
+            return [];
+        }
+        let text;
+        try {
+            text = readFileSync(this.file, "utf8");
+        }
+        catch (error) {
+            return { type: "baseline", message: `refpact: cannot read ${this.file}: ${error.message}` };
+        }
+        const parsed = parseBaseline(text);
+        if (!parsed.ok) {
+            return { type: "baseline", message: `${this.file}:${parsed.line}: this line of the baseline is not valid` };
+        }
+        return parsed.entries;
+    }
+    /** @internal Replaces the entries of one rule with its current violations. */
+    write(rule, violations, format) {
+        const entries = this.read();
+        if (!Array.isArray(entries)) {
+            return entries;
+        }
+        const kept = entries.filter((entry) => entry.rule !== rule);
+        try {
+            mkdirSync(path.dirname(this.file), { recursive: true });
+            // Written beside the file and moved, so that a reader never sees half a file.
+            const partial = `${this.file}.partial`;
+            writeFileSync(partial, formatBaseline([...kept, ...baselineEntries(violations, format)]));
+            renameSync(partial, this.file);
+        }
+        catch (error) {
+            return { type: "baseline", message: `refpact: cannot write ${this.file}: ${error.message}` };
+        }
+        return undefined;
+    }
+}
+/**
+ * The baseline in the file at `file`. A relative path is relative to the working directory;
+ * in a test, give a path from `import.meta.dirname`.
+ */
+export function baseline(file) {
+    return new Baseline(file);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The language-neutral core: rules evaluated over facts, reports and baselines.
+ *
+ * The core is the Rust crate `refpact-core`, run as WebAssembly. This module turns its JSON
+ * requests (SPEC section 8) into functions. A fact set crosses into the core once, on its
+ * first evaluation, and stays there while the object lives, so each further rule sends only
+ * the rule.
+ */
+import type { FactSet, Path, RawPattern, Rule, Severity } from "./model.ts";
+import type { Applied, BaselineEntry, BaselineKey, EvaluateResult, GraphResult, ParsedBaseline, PathFormat, RuleError, SelectResult, StaleEntry, TanglesResult, Violation } from "./results.ts";
+export type * from "./model.ts";
+export type * from "./results.ts";
+/** Evaluates one rule against one fact set (SPEC section 4). */
+export declare function evaluate(rule: Rule, facts: FactSet): EvaluateResult;
+/**
+ * Applies the subjects, the filters and the exemptions of a rule with a custom check, and
+ * answers what the rule sees (SPEC section 8), so that the caller finds the violations. The
+ * check is the constraint of the rule, or the demand of a rule about items.
+ */
+export declare function select(rule: Rule, facts: FactSet): SelectResult;
+/**
+ * The edges of a graph of what a rule sees, as the core makes them (SPEC section 8): the unit
+ * graph, or with `subjects` the graph of the subjects.
+ */
+export declare function graph(rule: Rule, facts: FactSet, subjects: boolean): GraphResult;
+/** The tangles of the graph that {@link graph} gives. The core searches them only for this request. */
+export declare function tangles(rule: Rule, facts: FactSet, subjects: boolean): TanglesResult;
+/** The text form of a diagram: a Mermaid flowchart, or a Graphviz graph in DOT. */
+export type DiagramFormat = "mermaid" | "dot";
+/** The diagram of a rule, or the reasons why the rule cannot be evaluated. */
+export type DiagramResult = {
+    /** The rule can be evaluated. */
+    readonly ok: true;
+    /** The diagram. */
+    readonly text: string;
+} | {
+    /** The rule cannot be evaluated. */
+    readonly ok: false;
+    /** The reasons, in the order of the specification. */
+    readonly errors: readonly RuleError[];
+};
+/** A layer of a diagram of layers (SPEC 4.17). */
+export interface DiagramLayer {
+    /** The name of the layer, which is the label of its node. */
+    readonly name: string;
+    /** The units of the layer: unit patterns, which match units exactly. */
+    readonly units: readonly RawPattern[];
+    /** The layers that the layer must not use, by their position in the list of layers. */
+    readonly mustNotUse: readonly number[];
+}
+/**
+ * The nodes of a diagram: the subjects of the rule when this is `undefined`, the slices of
+ * the subjects, or the layers from the top to the bottom.
+ */
+export type DiagramNodes = {
+    /** The slice patterns, as for `must-be-acyclic` with slices. */
+    readonly slices: readonly RawPattern[];
+} | {
+    /** The layers, from the top to the bottom. */
+    readonly layers: readonly DiagramLayer[];
+} | undefined;
+/**
+ * The diagram of what a rule sees (SPEC 4.17): its subjects, the slices or the layers, and the
+ * references between them. The constraint of the rule is not evaluated.
+ */
+export declare function diagram(rule: Rule, facts: FactSet, nodes: DiagramNodes, format?: DiagramFormat): DiagramResult;
+/** Prints a path as reports print it. */
+export declare function printPath(path: Path, format: PathFormat): string;
+/** One line for one violation: file, line, column, rule name, unit and offending path. */
+export declare function renderViolation(violation: Violation, format: PathFormat): string;
+/** All violations of one rule, one per line, with a heading, and the reason of the rule when it has one. */
+export declare function renderViolations(rule: string, violations: readonly Violation[], format: PathFormat, reason?: string, severity?: Severity): string;
+/** One sentence for one error. */
+export declare function renderError(error: RuleError): string;
+/** All errors of one rule, one per line, with a heading. */
+export declare function renderErrors(rule: string, errors: readonly RuleError[]): string;
+/** The report of the stale entries of one rule in a baseline file. */
+export declare function renderStale(rule: string, file: string, entries: readonly StaleEntry[]): string;
+/** The `unit` and `what` of the key of a violation (SPEC 7.1). */
+export declare function baselineKey(violation: Violation, format: PathFormat): BaselineKey;
+/** One entry for each key of the violations, with the number of violations that have it. */
+export declare function baselineEntries(violations: readonly Violation[], format: PathFormat): BaselineEntry[];
+/** Removes the violations of one rule that the baseline accepts (SPEC 7.3). */
+export declare function applyBaseline(rule: string, violations: readonly Violation[], baseline: readonly BaselineEntry[], format: PathFormat): Applied;
+/** Writes the text form of a baseline, sorted, so that a change shows as a small difference. */
+export declare function formatBaseline(entries: readonly BaselineEntry[]): string;
+/** Reads the text form of a baseline (SPEC 7.2). */
+export declare function parseBaseline(text: string): ParsedBaseline;

package/dist/core/index.js

@@ -0,0 +1,105 @@
+import { call, currentGeneration } from "./wasm.js";
+const loaded = new WeakMap();
+const unload = new FinalizationRegistry(({ handle, generation }) => {
+    if (generation === currentGeneration()) {
+        call(JSON.stringify({ op: "drop-facts", handle }));
+    }
+});
+/** The handle of a fact set in the core, after loading it when it is not loaded. */
+function handleOf(facts) {
+    const generation = currentGeneration();
+    const known = loaded.get(facts);
+    if (known !== undefined && known.generation === generation) {
+        return known.handle;
+    }
+    const { handle } = JSON.parse(call(`{"op":"load-facts","facts":${JSON.stringify(facts)}}`));
+    const entry = { handle, generation };
+    loaded.set(facts, entry);
+    unload.register(facts, entry);
+    return handle;
+}
+/** Only the fields of a path format, so that a fact set given as the format does not cross whole. */
+function formatOf(format) {
+    return {
+        separator: format.separator,
+        ...(format.attachedPrefixes !== undefined && { attachedPrefixes: format.attachedPrefixes }),
+        ...(format.hiddenPrefixes !== undefined && { hiddenPrefixes: format.hiddenPrefixes }),
+    };
+}
+function request(op, body) {
+    return JSON.parse(call(JSON.stringify({ op, ...body })));
+}
+/** Evaluates one rule against one fact set (SPEC section 4). */
+export function evaluate(rule, facts) {
+    return request("evaluate", { handle: handleOf(facts), rule });
+}
+/**
+ * Applies the subjects, the filters and the exemptions of a rule with a custom check, and
+ * answers what the rule sees (SPEC section 8), so that the caller finds the violations. The
+ * check is the constraint of the rule, or the demand of a rule about items.
+ */
+export function select(rule, facts) {
+    return request("select", { handle: handleOf(facts), rule });
+}
+/**
+ * The edges of a graph of what a rule sees, as the core makes them (SPEC section 8): the unit
+ * graph, or with `subjects` the graph of the subjects.
+ */
+export function graph(rule, facts, subjects) {
+    return request("graph", { handle: handleOf(facts), rule, subjects });
+}
+/** The tangles of the graph that {@link graph} gives. The core searches them only for this request. */
+export function tangles(rule, facts, subjects) {
+    return request("graph", { handle: handleOf(facts), rule, subjects, tangles: true });
+}
+/**
+ * The diagram of what a rule sees (SPEC 4.17): its subjects, the slices or the layers, and the
+ * references between them. The constraint of the rule is not evaluated.
+ */
+export function diagram(rule, facts, nodes, format = "mermaid") {
+    return request("diagram", { handle: handleOf(facts), rule, ...nodes, format });
+}
+/** Prints a path as reports print it. */
+export function printPath(path, format) {
+    return request("print-path", { path, format: formatOf(format) }).text;
+}
+/** One line for one violation: file, line, column, rule name, unit and offending path. */
+export function renderViolation(violation, format) {
+    return request("render-violation", { violation, format: formatOf(format) }).text;
+}
+/** All violations of one rule, one per line, with a heading, and the reason of the rule when it has one. */
+export function renderViolations(rule, violations, format, reason, severity = "error") {
+    return request("render-violations", { rule, reason, severity, violations, format: formatOf(format) }).text;
+}
+/** One sentence for one error. */
+export function renderError(error) {
+    return request("render-error", { error }).text;
+}
+/** All errors of one rule, one per line, with a heading. */
+export function renderErrors(rule, errors) {
+    return request("render-errors", { rule, errors }).text;
+}
+/** The report of the stale entries of one rule in a baseline file. */
+export function renderStale(rule, file, entries) {
+    return request("render-stale", { rule, file, entries }).text;
+}
+/** The `unit` and `what` of the key of a violation (SPEC 7.1). */
+export function baselineKey(violation, format) {
+    return request("baseline-key", { violation, format: formatOf(format) });
+}
+/** One entry for each key of the violations, with the number of violations that have it. */
+export function baselineEntries(violations, format) {
+    return request("baseline-entries", { violations, format: formatOf(format) }).entries;
+}
+/** Removes the violations of one rule that the baseline accepts (SPEC 7.3). */
+export function applyBaseline(rule, violations, baseline, format) {
+    return request("apply-baseline", { rule, violations, entries: baseline, format: formatOf(format) });
+}
+/** Writes the text form of a baseline, sorted, so that a change shows as a small difference. */
+export function formatBaseline(entries) {
+    return request("format-baseline", { entries }).text;
+}
+/** Reads the text form of a baseline (SPEC 7.2). */
+export function parseBaseline(text) {
+    return request("parse-baseline", { text });
+}