@aoelite/refpact-ts 0.0.0-stage → 0.2.0

package/dist/layers.js

@@ -0,0 +1,215 @@
+/** Layers: rules about which layers of an architecture may import which. */
+import { addFilters } from "./filters.js";
+import { RuleSet } from "./group.js";
+import { filePattern } from "./patterns.js";
+import { all, AnyOf, anyOf, ArchitectureError, Files, rule } from "./rules.js";
+export class Layers extends RuleSet {
+    settings;
+    /** @internal */
+    constructor(settings) {
+        super();
+        this.settings = settings;
+    }
+    /** The name of the layers. */
+    get name() {
+        return this.settings.name;
+    }
+    /** Adds a layer below the layers that are there. */
+    layer(name, ...files) {
+        return this.with({ list: [...this.settings.list, { name, files }] });
+    }
+    /** @internal The layers with one more filter. */
+    filtered(filter) {
+        return this.with({ filters: [...this.settings.filters, filter] });
+    }
+    /** Makes the layers strict: a layer may import only the layer right below it, not the layers further down. */
+    strict() {
+        return this.with({ strict: true });
+    }
+    /**
+     * The layer may import only these layers. Each of them must be below it, and right below
+     * it when the layers are {@link Layers.strict | strict}. No layers forbids the layer to
+     * import any other layer.
+     */
+    mayOnlyImport(layer, ...layers) {
+        return this.with({ mayOnlyImport: [...this.settings.mayOnlyImport, [layer, layers]] });
+    }
+    /**
+     * Only these layers may import the layer. Each of them must be above it, and right above
+     * it when the layers are {@link Layers.strict | strict}. No layers forbids every other layer
+     * to import it.
+     *
+     * This is about the layers only. To keep every other file away as well, add a rule with
+     * {@link ScopedRule.mustOnlyBeImportedBy}.
+     */
+    mayOnlyBeImportedBy(layer, ...layers) {
+        return this.with({ mayOnlyBeImportedBy: [...this.settings.mayOnlyBeImportedBy, [layer, layers]] });
+    }
+    /**
+     * Each of these files must be in a layer. A new file then cannot stay out of the
+     * architecture unseen. Leave out the files that belong to no layer, such as the entry
+     * point: `allExcept("src/main.ts")`.
+     */
+    everyFileInALayer(files) {
+        return this.with({ covered: files });
+    }
+    /**
+     * The rules of the layers: one `mustNotImport` rule for each layer that must not import
+     * some other layers, and the rule of {@link Layers.everyFileInALayer} when it is given.
+     *
+     * The rule of a layer has the name of the layers and the name of the layer. It is
+     * `<layers>: <layer> does not import the layers above it` when only the order of the
+     * layers applies to the layer, and `<layers>: <layer> imports only the layers it may
+     * import` when more applies.
+     *
+     * Throws an {@link ArchitectureError} of type `malformed` when the layers cannot fail as
+     * written or name a layer that does not exist.
+     */
+    rules() {
+        const settings = this.settings;
+        const allowed = this.allowed();
+        if (!Array.isArray(allowed)) {
+            throw new ArchitectureError(allowed);
+        }
+        const made = [];
+        settings.list.forEach((layer, from) => {
+            const forbidden = forbiddenFor(allowed, from);
+            if (forbidden.length === 0) {
+                return;
+            }
+            const onlyAbove = forbidden.length === from && forbidden.every((to, index) => to === index);
+            const name = onlyAbove
+                ? `${settings.name}: ${layer.name} does not import the layers above it`
+                : `${settings.name}: ${layer.name} imports only the layers it may import`;
+            const targets = forbidden.flatMap((to) => settings.list[to]?.files ?? []);
+            const one = rule(name)
+                .files(anyOf(...layer.files))
+                .mustNotImport(anyOf(...targets));
+            made.push(this.withFilters(one, true));
+        });
+        if (settings.covered !== undefined) {
+            const places = settings.list.flatMap((layer) => layer.files);
+            const covered = rule(`${settings.name}: every file is in a layer`).files(settings.covered).mustBeIn(places);
+            made.push(this.withFilters(covered, false));
+        }
+        return made;
+    }
+    /** The rule with the filters of the layers. A rule that looks at no import gets only the filters that are not about imports. */
+    withFilters(made, seesImports) {
+        const filters = this.settings.filters.filter((filter) => seesImports || !filter.aboutImports);
+        return filters.reduce((one, filter) => one.filtered(filter), made);
+    }
+    /**
+     * A diagram of the layers, in Mermaid (the default) or DOT, from the top to the bottom. Each
+     * layer is a node, and an edge is an import between two layers. An import that the layers
+     * forbid is red. A file is in the first layer that matches it, and a file in no layer is
+     * not drawn. The files of {@link Layers.everyFileInALayer} are not checked.
+     *
+     * Throws an {@link ArchitectureError}: `malformed` as {@link Layers.rules} does, or
+     * `invalid` when a pattern of a layer matches no file.
+     *
+     * ```ts
+     * const text = layers("the layers").layer("ui", "src/ui/**").layer("db", "src/db/**").diagram(app);
+     * writeFileSync("docs/layers.md", `\`\`\`mermaid\n${text}\`\`\`\n`);
+     * ```
+     */
+    diagram(project, format = "mermaid") {
+        const settings = this.settings;
+        const allowed = this.allowed();
+        if (!Array.isArray(allowed)) {
+            throw new ArchitectureError(allowed);
+        }
+        const list = settings.list.map((layer, from) => ({
+            name: layer.name,
+            units: layer.files.map(filePattern),
+            mustNotUse: forbiddenFor(allowed, from),
+        }));
+        const drawn = rule(settings.name).files(all()).mustBeImported();
+        return this.withFilters(drawn, true).draw(project, { layers: list }, format);
+    }
+    /** For each layer, by position from the top, the layers it may import; or every problem of the layers. */
+    allowed() {
+        const { name, list, strict } = this.settings;
+        const malformed = (problems) => ({
+            type: "malformed",
+            rule: name,
+            message: `rule \`${name}\` cannot be checked:\n  ${problems.join("\n  ")}`,
+        });
+        const count = list.length;
+        if (count < 2) {
+            return malformed(["fewer than two layers are given, so no layer can import a layer above it"]);
+        }
+        const problems = [];
+        list.forEach((layer, position) => {
+            if (list.slice(0, position).some((other) => other.name === layer.name)) {
+                problems.push(`two layers have the name \`${layer.name}\``);
+            }
+        });
+        // What the order allows: the layers below, or only the next one when strict.
+        const ordered = (from, to) => to > from && (!strict || to === from + 1);
+        const allowed = list.map((_, from) => list.map((__, to) => ordered(from, to)));
+        const position = (layer) => {
+            const found = list.findIndex((entry) => entry.name === layer);
+            if (found === -1) {
+                problems.push(`\`${layer}\` is not a layer`);
+                return undefined;
+            }
+            return found;
+        };
+        const restrict = (lists, twice, forbidden, edge) => {
+            const seen = new Set();
+            for (const [layer, others] of lists) {
+                const at = position(layer);
+                if (at === undefined) {
+                    continue;
+                }
+                if (seen.has(at)) {
+                    problems.push(twice(layer));
+                }
+                seen.add(at);
+                const keep = list.map(() => false);
+                for (const other of others) {
+                    const otherAt = position(other);
+                    if (otherAt === undefined) {
+                        continue;
+                    }
+                    const [from, to] = edge(at, otherAt);
+                    if (ordered(from, to)) {
+                        keep[otherAt] = true;
+                    }
+                    else {
+                        problems.push(forbidden(layer, other));
+                    }
+                }
+                keep.forEach((kept, otherAt) => {
+                    const [from, to] = edge(at, otherAt);
+                    const row = allowed[from];
+                    row[to] = row[to] === true && kept;
+                });
+            }
+        };
+        restrict(this.settings.mayOnlyImport, (layer) => `\`${layer}\` has two lists of the layers it may import`, (layer, other) => `\`${layer}\` may only import \`${other}\`, which the order of the layers forbids`, (layer, other) => [layer, other]);
+        restrict(this.settings.mayOnlyBeImportedBy, (layer) => `\`${layer}\` has two lists of the layers that may import it`, (layer, other) => `\`${layer}\` may only be imported by \`${other}\`, which the order of the layers forbids`, (layer, other) => [other, layer]);
+        return problems.length === 0 ? allowed : malformed(problems);
+    }
+    with(change) {
+        return new Layers({ ...this.settings, ...change });
+    }
+}
+/** The layers that a layer must not import, by position from the top, from what each layer may import. */
+function forbiddenFor(allowed, from) {
+    return allowed.map((_, to) => to).filter((to) => to !== from && allowed[from]?.[to] !== true);
+}
+/** Starts a set of layers. Add the layers from the top to the bottom. */
+export function layers(name) {
+    return new Layers({
+        name,
+        list: [],
+        filters: [],
+        strict: false,
+        mayOnlyImport: [],
+        mayOnlyBeImportedBy: [],
+        covered: undefined,
+    });
+}
+addFilters(Layers);

package/dist/onion.d.ts

@@ -0,0 +1,78 @@
+import type { Filter, Filters } from "./filters.ts";
+import { RuleSet } from "./group.ts";
+import { Layers } from "./layers.ts";
+import type { DiagramFormat } from "./core/index.ts";
+import type { Project } from "./frontend/project.ts";
+import type { AnyOf, Files, ImportRule } from "./rules.ts";
+interface Parts {
+    readonly name: string;
+    readonly domainModels: readonly string[] | undefined;
+    readonly domainServices: readonly string[] | undefined;
+    readonly applicationServices: readonly string[] | undefined;
+    readonly adapters: readonly {
+        readonly name: string;
+        readonly files: readonly string[];
+    }[];
+    /** The filters of every rule of the architecture. */
+    readonly filters: readonly Filter[];
+    readonly covered: AnyOf<string> | Files | undefined;
+}
+/**
+ * The parts of an onion architecture. From the inside out:
+ *
+ * - the **domain models**, which import no other part;
+ * - the **domain services**, which may import the domain models;
+ * - the **application services**, which may import the domain;
+ * - the **adapters**, such as a web interface or a database, which may import the
+ *   application services and the domain, but not each other.
+ *
+ * Give the parts that the code has; at least two of them. The rules are those of
+ * {@link layers}, one layer for each part, and each adapter a layer of its own.
+ *
+ * ```ts
+ * onionArchitecture("the shop")
+ *   .domainModels("src/domain/model/**")
+ *   .domainServices("src/domain/service/**")
+ *   .applicationServices("src/application/**")
+ *   .adapter("web", "src/adapter/web/**")
+ *   .adapter("database", "src/adapter/db/**")
+ *   .check(app);
+ * ```
+ *
+ * The filters of a rule ({@link Filters}), such as `ignoringTypeImports()`, apply to every
+ * part.
+ */
+export interface Onion extends Filters<Onion> {
+}
+export declare class Onion extends RuleSet {
+    private readonly parts;
+    /** @internal */
+    constructor(parts: Parts);
+    /** The name of the architecture. */
+    get name(): string;
+    /** The files of the domain models: the centre, which imports no other part. */
+    domainModels(...files: string[]): Onion;
+    /** The files of the domain services, which may import the domain models. */
+    domainServices(...files: string[]): Onion;
+    /** The files of the application services, which may import the domain. */
+    applicationServices(...files: string[]): Onion;
+    /**
+     * Adds an adapter. It may import the application services and the domain, and no other
+     * adapter may import it. Its layer is named `adapter <name>`.
+     */
+    adapter(name: string, ...files: string[]): Onion;
+    /** @internal The architecture with one more filter. */
+    filtered(filter: Filter): Onion;
+    /** Each of these files must be in a part. See {@link Layers.everyFileInALayer}. */
+    everyFileInALayer(files: AnyOf<string> | Files): Onion;
+    /** The parts as layers, from the outside in. */
+    asLayers(): Layers;
+    /** A diagram of the parts as layers. See {@link Layers.diagram}. */
+    diagram(project: Project, format?: DiagramFormat): string;
+    /** The rules of the architecture. See {@link Layers.rules}. */
+    rules(): ImportRule[];
+    private with;
+}
+/** Starts an onion architecture. See {@link Onion}. */
+export declare function onionArchitecture(name: string): Onion;
+export {};

package/dist/onion.js

@@ -0,0 +1,96 @@
+/**
+ * The onion architecture, also called the hexagonal architecture or ports and adapters:
+ * layers with the domain at the centre and the adapters outside.
+ */
+import { addFilters } from "./filters.js";
+import { RuleSet } from "./group.js";
+import { layers, Layers } from "./layers.js";
+export class Onion extends RuleSet {
+    parts;
+    /** @internal */
+    constructor(parts) {
+        super();
+        this.parts = parts;
+    }
+    /** The name of the architecture. */
+    get name() {
+        return this.parts.name;
+    }
+    /** The files of the domain models: the centre, which imports no other part. */
+    domainModels(...files) {
+        return this.with({ domainModels: files });
+    }
+    /** The files of the domain services, which may import the domain models. */
+    domainServices(...files) {
+        return this.with({ domainServices: files });
+    }
+    /** The files of the application services, which may import the domain. */
+    applicationServices(...files) {
+        return this.with({ applicationServices: files });
+    }
+    /**
+     * Adds an adapter. It may import the application services and the domain, and no other
+     * adapter may import it. Its layer is named `adapter <name>`.
+     */
+    adapter(name, ...files) {
+        return this.with({ adapters: [...this.parts.adapters, { name, files }] });
+    }
+    /** @internal The architecture with one more filter. */
+    filtered(filter) {
+        return this.with({ filters: [...this.parts.filters, filter] });
+    }
+    /** Each of these files must be in a part. See {@link Layers.everyFileInALayer}. */
+    everyFileInALayer(files) {
+        return this.with({ covered: files });
+    }
+    /** The parts as layers, from the outside in. */
+    asLayers() {
+        const parts = this.parts;
+        const adapter = (name) => `adapter ${name}`;
+        let made = layers(parts.name);
+        for (const { name, files } of parts.adapters) {
+            made = made.layer(adapter(name), ...files);
+        }
+        const inner = [
+            ["application services", parts.applicationServices],
+            ["domain services", parts.domainServices],
+            ["domain models", parts.domainModels],
+        ].flatMap(([name, files]) => (files !== undefined ? [{ name, files }] : []));
+        for (const { name, files } of inner) {
+            made = made.layer(name, ...files);
+        }
+        // An adapter is above the adapters that follow it, but may not import them.
+        for (const { name } of parts.adapters) {
+            made = made.mayOnlyImport(adapter(name), ...inner.map((part) => part.name));
+        }
+        made = parts.filters.reduce((layers, filter) => layers.filtered(filter), made);
+        if (parts.covered !== undefined) {
+            made = made.everyFileInALayer(parts.covered);
+        }
+        return made;
+    }
+    /** A diagram of the parts as layers. See {@link Layers.diagram}. */
+    diagram(project, format = "mermaid") {
+        return this.asLayers().diagram(project, format);
+    }
+    /** The rules of the architecture. See {@link Layers.rules}. */
+    rules() {
+        return this.asLayers().rules();
+    }
+    with(change) {
+        return new Onion({ ...this.parts, ...change });
+    }
+}
+/** Starts an onion architecture. See {@link Onion}. */
+export function onionArchitecture(name) {
+    return new Onion({
+        name,
+        domainModels: undefined,
+        domainServices: undefined,
+        applicationServices: undefined,
+        adapters: [],
+        filters: [],
+        covered: undefined,
+    });
+}
+addFilters(Onion);

package/dist/patterns.d.ts

@@ -0,0 +1,14 @@
+/** Patterns of rules as the core sees them: lists of segments. */
+import type { RawPattern } from "./core/index.ts";
+/** What a target of a rule that is no file pattern has: its segments. */
+interface Segmented {
+    readonly segments: RawPattern;
+}
+/**
+ * A file pattern as segments. `src/db/**` selects by path, `src/db/client.ts#query` names
+ * one export of a file, and `src/domain/order.ts#Order#total` one member of an export.
+ */
+export declare function filePattern(pattern: string): RawPattern;
+/** A target as segments: a file pattern, or a package or a global. */
+export declare function targetPattern(target: string | Segmented): RawPattern;
+export {};

package/dist/patterns.js

@@ -0,0 +1,15 @@
+/**
+ * A file pattern as segments. `src/db/**` selects by path, `src/db/client.ts#query` names
+ * one export of a file, and `src/domain/order.ts#Order#total` one member of an export.
+ */
+export function filePattern(pattern) {
+    const hash = pattern.indexOf("#");
+    const file = (hash === -1 ? pattern : pattern.slice(0, hash)).replace(/^\.\//, "");
+    const segments = file.split("/");
+    const names = hash === -1 ? [] : pattern.slice(hash + 1).split("#");
+    return [...segments, ...names.map((name) => `#${name}`)];
+}
+/** A target as segments: a file pattern, or a package or a global. */
+export function targetPattern(target) {
+    return typeof target === "string" ? filePattern(target) : target.segments;
+}