@aoelite/refpact-ts 0.0.0-stage → 0.2.0

package/dist/rules.d.ts

@@ -0,0 +1,408 @@
+import type { Baseline } from "./baseline.ts";
+import type { DiagramFormat, DiagramNodes } from "./core/index.ts";
+import type { EvaluateResult, RawPattern, Rule as CoreRule, RuleError, StaleEntry, Violation } from "./core/index.ts";
+import { Scope } from "./custom.ts";
+import type { Filter, Filters } from "./filters.ts";
+import type { ListNames } from "./custom.ts";
+import { KINDS, MARKERS } from "./frontend/imports.ts";
+import { ItemSelection } from "./items.ts";
+import type { Kind, MarkerName as Marker } from "./frontend/imports.ts";
+import type { Project } from "./frontend/project.ts";
+/** A package, a subpath of a package, or one export of it, as a target of a rule. */
+export declare class PackageTarget {
+    /** @internal */
+    readonly segments: RawPattern;
+    /** @internal */
+    constructor(segments: RawPattern);
+    /** One export of the package: `pkg("lodash").export("debounce")`. Use `default` for the default export. */
+    export(name: string): PackageTarget;
+}
+/**
+ * A package as a target: `pkg("lodash")`, `pkg("@scope/name")`, `pkg("lodash/fp")` for a
+ * subpath, `pkg("node:fs")` or `pkg("fs")` for a module of Node. The target covers all
+ * subpaths and all exports of the package. `*` matches a part of the name: `pkg("@aws-sdk/*")`.
+ */
+export declare function pkg(specifier: string): PackageTarget;
+/**
+ * A global of the host as a target: `globalApi("fetch")`, `globalApi("process")`, or one member
+ * of it, `globalApi("process.env")`. The target of a global covers its members. A use of a
+ * global counts as an import of it, of the kind `global`: see {@link KINDS}. `*` matches a
+ * part of the name: `globalApi("*Storage")`.
+ *
+ * A global is a name that no file of the project declares and that the ECMAScript library
+ * does not declare: the globals of Node, of the browser and of other hosts, such as
+ * `process`, `fetch`, `window`, `document` and `localStorage`. `Math`, `Date`, `JSON` and
+ * `Promise` are part of the language and are no globals here.
+ */
+export declare function globalApi(name: string): PackageTarget;
+/** A file pattern, a package or a global. */
+export type Target = string | PackageTarget;
+/** A selection of files. */
+export declare class Files {
+    /** @internal */
+    readonly include: readonly string[] | undefined;
+    /** @internal */
+    readonly excluded: readonly string[] | undefined;
+    /** @internal */
+    constructor(include: readonly string[] | undefined, excluded: readonly string[] | undefined);
+}
+/** A set of forbidden targets. */
+export declare class Targets {
+    /** @internal */
+    readonly anyOf: readonly Target[];
+    /** @internal */
+    readonly unverified: readonly Target[];
+    /** @internal */
+    constructor(anyOf: readonly Target[], unverified: readonly Target[]);
+}
+/** A list of patterns that form a union. */
+export declare class AnyOf<T extends Target = Target> {
+    /** @internal */
+    readonly patterns: readonly T[];
+    /** @internal */
+    constructor(patterns: readonly T[]);
+    /** Removes the files that match one of `patterns` from the selection. */
+    except(this: AnyOf<string>, ...patterns: string[]): Files;
+    /** Adds targets that are not checked for existence. See {@link unverified}. */
+    andUnverified(...patterns: Target[]): Targets;
+}
+/** The union of some patterns: files for `files(..)`, targets for `mustNotImport(..)`. */
+export declare function anyOf(...patterns: string[]): AnyOf<string>;
+export declare function anyOf(...patterns: Target[]): AnyOf<Target>;
+/** All files of the project. */
+export declare function all(): Files;
+/** All files of the project except those that match one of the patterns. */
+export declare function allExcept(...patterns: string[]): Files;
+/**
+ * Targets that are not checked for existence. Use this only for files of the project that
+ * the compiler does not load, such as generated files that are not there yet.
+ */
+export declare function unverified(...patterns: Target[]): Targets;
+/** Starts a rule. The name is printed with every violation. */
+export declare function rule(name: string): NamedRule;
+/** A rule with a name. Say which files it applies to. */
+export declare class NamedRule {
+    private readonly name;
+    /** @internal */
+    constructor(name: string);
+    /** The files that the rule constrains: `anyOf(..)`, `all()`, `allExcept(..)` or `anyOf(..).except(..)`. */
+    files(files: AnyOf<string> | Files): ScopedRule;
+    /**
+     * The items that these files declare at their top level: functions, classes, interfaces,
+     * types, enums, variables and namespaces. Narrow them with the filters of
+     * {@link ItemSelection}, then say what they must meet, for example with
+     * {@link ItemSelection.mustResideIn}.
+     */
+    items(files: AnyOf<string> | Files): ItemSelection;
+}
+/**
+ * A rule with a name and files. Say what the files must or must not do, for example with
+ * `mustNotImport`, `mustOnlyImport` or `mustBeAcyclic`.
+ */
+export declare class ScopedRule {
+    private readonly name;
+    private readonly selection;
+    /** @internal */
+    constructor(name: string, selection: Files);
+    /**
+     * The files must not import any of the targets, in any form: `import`, `import type`,
+     * `import()`, `require`, or `export .. from`. An import through a barrel file counts as
+     * an import of the file that declares the name.
+     */
+    mustNotImport(targets: AnyOf | Targets): ImportRule;
+    /**
+     * Every import of the files must lead to one of the targets. An import is allowed when the
+     * module in the code is allowed, or when the file that declares the name is.
+     *
+     * The list must name everything the files import, also packages and modules of Node:
+     * `pkg("*")` is every package, and `pkg("node:*")` is every module of Node.
+     */
+    mustOnlyImport(targets: AnyOf | Targets): ImportRule;
+    /**
+     * The files must not form a cycle: no file may reach itself through the imports between
+     * them. Each tangle of files is reported once, with one of its cycles.
+     */
+    mustBeAcyclic(): ImportRule;
+    /**
+     * Like {@link ScopedRule.mustBeAcyclic}, between slices. The slice of a file is the
+     * shortest start of its path that matches one of the patterns: with `src/features/*`, the
+     * file `src/features/cart/view/list.ts` is in the slice `src/features/cart`. Imports inside
+     * a slice do not count, and a file without a slice is left out.
+     */
+    mustBeAcyclicBetween(slices: AnyOf<string>): ImportRule;
+    /**
+     * No file of one slice may import a file of another slice. Slices are as in
+     * {@link ScopedRule.mustBeAcyclicBetween}: with `src/features/*`, no feature may import
+     * another feature.
+     *
+     * A file that the rule does not select is in no slice. Leave a shared part out with
+     * `allExcept("src/features/shared/**")`.
+     */
+    mustBeIndependentBetween(slices: AnyOf<string>): ImportRule;
+    /**
+     * The files must not contain any of the markers: `console`, a use of the global
+     * `console`, `debugger`, 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. A local
+     * variable named `console` is no marker. An import of a package is never an `unresolved-import`:
+     * refpact does not check that a package is installed.
+     *
+     * ```ts
+     * rule("every import resolves").files(all()).mustNotContain("unresolved-import").check(app);
+     * ```
+     */
+    mustNotContain(...markers: Marker[]): ImportRule;
+    /**
+     * Each file must have at most this number of lines. The blank lines and the comments
+     * count.
+     *
+     * ```ts
+     * rule("no file is longer than 400 lines").files(anyOf("src/**")).mustNotExceedLines(400).check(app);
+     * ```
+     */
+    mustNotExceedLines(lines: number): ImportRule;
+    /**
+     * Each file must be imported by another file. Leave the entry points out of the files:
+     * `allExcept("src/main.ts")`.
+     */
+    mustBeImported(): ImportRule;
+    /**
+     * No chain of imports may lead from the files to one of the targets: not the files
+     * themselves, and not a file that they import, at any distance. The report shows the
+     * shortest chain.
+     */
+    mustNotReach(targets: AnyOf | Targets): ImportRule;
+    /** A chain of imports must lead from one of the root files to each file. Give the entry points as roots. */
+    mustBeReachableFrom(roots: AnyOf<string>): ImportRule;
+    /**
+     * Only the importers, and the files of the rule themselves, may import the files of the
+     * rule. Every other file that imports one of them breaks the rule, also through a barrel
+     * file. Importers match files as the files of a rule do.
+     */
+    mustOnlyBeImportedBy(importers: AnyOf<string>): ImportRule;
+    /**
+     * Each file must be one that a place matches. The layers use it for `everyFileInALayer`.
+     *
+     * @internal
+     */
+    mustBeIn(places: readonly string[]): ImportRule;
+    /**
+     * Every package that the files import must be in the `package.json` that the file belongs
+     * to: the nearest one above it. Any of `dependencies`, `devDependencies`,
+     * `peerDependencies` and `optionalDependencies` counts. A type import of `name` is also
+     * declared by `@types/name`. A package may import itself by its own name.
+     *
+     * The project must be loaded with `readDependencies`: the rule reads the references that
+     * the `package.json` files give, as a check of your own can.
+     */
+    mustOnlyImportDeclaredPackages(): ImportRule;
+    /**
+     * The files must not import a package that their `package.json` has only in
+     * `devDependencies`. Select the files that are shipped: `allExcept("**\/*.test.ts")`.
+     * The project must be loaded with `readDependencies`.
+     */
+    mustNotImportDevDependencies(): ImportRule;
+    /**
+     * The files must pass a check of your own: a function that gets the {@link Scope} of the
+     * rule and returns the violations. The rule selects the files, applies its filters and its
+     * exemptions, and reports and baselines the violations, as for the rules above.
+     *
+     * A function cannot match a pattern, so the check names the lists of patterns that it
+     * needs, and the rule matches them: see {@link CheckPatterns}. A pattern that matches
+     * nothing is an error, as it is for `mustNotImport`.
+     *
+     * ```ts
+     * rule("a file imports at most ten files")
+     *   .files(anyOf("src/**"))
+     *   .mustSatisfy((scope) =>
+     *     scope.subjects
+     *       .filter((file) => scope.imports.filter((seen) => seen.file === file).length > 10)
+     *       .map((file) => scope.violationOfFile(file, "imports more than ten files")),
+     *   )
+     *   .check(app);
+     * ```
+     */
+    mustSatisfy(check: (scope: Scope) => readonly Violation[], patterns?: CheckPatterns): ImportRule;
+    private targets;
+    private rule;
+    private custom;
+}
+/**
+ * The lists of patterns that a check of the user needs. The rule matches them, and the
+ * {@link Scope} of the check gives the result by the name of each list.
+ *
+ * ```ts
+ * rule("the database is imported with its types only")
+ *   .files(anyOf("src/**"))
+ *   .mustSatisfy(
+ *     (scope) =>
+ *       scope.imports
+ *         .filter((seen) => seen.subject && seen.hits["db"] !== undefined && seen.reference.kind !== "import-type")
+ *         .map((seen) => scope.violationAt(seen.fact, "imports a value of the database")),
+ *     { targets: { db: anyOf("src/db/**") } },
+ *   )
+ *   .check(app);
+ * ```
+ */
+export interface CheckPatterns {
+    /**
+     * Lists of targets, as in `mustNotImport`. Each import in the scope has the first of its
+     * paths that a list matches in {@link SeenImport.hits}, by the name of the list.
+     */
+    readonly targets?: Readonly<Record<string, AnyOf | Targets>>;
+    /**
+     * Lists of file patterns, which match as the files of a rule do. {@link Scope.matched}
+     * gives the files that a list matches, by the name of the list.
+     */
+    readonly files?: Readonly<Record<string, AnyOf<string>>>;
+}
+/** The check of a rule with a custom check: what finds the violations in what the rule sees. @internal */
+export interface Finder {
+    readonly names: ListNames;
+    readonly find: (scope: Scope, project: Project) => readonly Violation[];
+}
+/**
+ * Why a rule did not pass.
+ *
+ * - `violated`: the code breaks the rule.
+ * - `invalid`: the rule cannot fail as written, for example because a pattern matches nothing.
+ * - `stale-baseline`: the baseline accepts violations that the code no longer has.
+ * - `baseline`: the baseline file cannot be read or written.
+ * - `malformed`: a rule or a group of rules cannot fail as written, for example layers with one layer only.
+ * - `several`: several rules of one group did not pass.
+ */
+export type Failure = {
+    readonly type: "violated";
+    /** The name of the rule. */
+    readonly rule: string;
+    /** Why the rule exists, when it says so. See {@link ImportRule.because}. */
+    readonly reason?: string;
+    /** The violations that no baseline accepts. */
+    readonly violations: readonly Violation[];
+    /** The report. */
+    readonly message: string;
+} | {
+    readonly type: "invalid";
+    /** The name of the rule. */
+    readonly rule: string;
+    /** Every reason, in the order of the specification. */
+    readonly errors: readonly RuleError[];
+    /** The report. */
+    readonly message: string;
+} | {
+    readonly type: "stale-baseline";
+    /** The name of the rule. */
+    readonly rule: string;
+    /** The baseline file. */
+    readonly file: string;
+    /** The entries that accept too much. */
+    readonly entries: readonly StaleEntry[];
+    /** The report. */
+    readonly message: string;
+} | {
+    readonly type: "baseline";
+    /** What went wrong. */
+    readonly message: string;
+} | {
+    readonly type: "malformed";
+    /** The name of the rule or of the group. */
+    readonly rule: string;
+    /** What is wrong with it. */
+    readonly message: string;
+} | {
+    readonly type: "several";
+    /** The failures of the rules, in the order of the rules. */
+    readonly failures: readonly Failure[];
+    /** The reports of all failures. */
+    readonly message: string;
+};
+/** The error that `check` throws. Its message is the report. */
+export declare class ArchitectureError extends Error {
+    /** Why the rule did not pass. */
+    readonly failure: Failure;
+    constructor(failure: Failure);
+}
+/**
+ * A complete rule: a plain value that can be checked against a project. Its filters are
+ * those of {@link Filters}, such as `because`, `asWarning` and `ignoringKinds`.
+ */
+export interface ImportRule extends Filters<ImportRule> {
+}
+export declare class ImportRule {
+    private readonly rule;
+    /** The check of a rule with a custom check. */
+    private readonly finder;
+    /** @internal */
+    constructor(rule: CoreRule, finder?: Finder);
+    /** The name of the rule. */
+    get name(): string;
+    /** @internal The rule with one more filter. */
+    filtered(filter: Filter): ImportRule;
+    /**
+     * Names the properties of imports that a check of your own reads, such as `license`. A
+     * name that the load does not produce is then an error, as a kind that it does not produce
+     * is: a check that reads `licence` for `license`, or the properties of a load without
+     * `readDependencies`, cannot pass because it finds nothing.
+     */
+    readingProperties(...names: string[]): ImportRule;
+    /**
+     * Evaluates the rule and returns the violations, which may be none, or the errors of the
+     * rule. A rule about `package.json` throws an {@link ArchitectureError} when no
+     * `package.json` can make it fail.
+     */
+    evaluate(project: Project): EvaluateResult;
+    /**
+     * Evaluates the rule and returns the failure, or `undefined` when the rule passes. The
+     * violations of a warning are reported with `console.warn` and are no failure: see
+     * {@link ImportRule.asWarning}.
+     */
+    verify(project: Project): Failure | undefined;
+    /** The violations, or the reason why the rule cannot be evaluated. */
+    private found;
+    /**
+     * A diagram of what the rule sees, in Mermaid (the default) or DOT. The nodes are the files
+     * of the rule, or its slices when the rule is about slices, such as
+     * {@link ScopedRule.mustBeAcyclicBetween}. An edge is an import between two nodes that the
+     * filters and the exemptions of the rule let pass. The files and imports of a cycle are
+     * red. The constraint of the rule is not evaluated, so a rule of any kind draws its files.
+     * Throws an {@link ArchitectureError} when the rule cannot be evaluated.
+     *
+     * A Markdown viewer that knows Mermaid, such as GitHub's, draws the text in a block
+     * ` ```mermaid `.
+     *
+     * ```ts
+     * const text = rule("the features").files(all()).mustBeAcyclicBetween(anyOf("src/features/*")).diagram(app);
+     * writeFileSync("docs/features.md", `\`\`\`mermaid\n${text}\`\`\`\n`);
+     * ```
+     */
+    diagram(project: Project, format?: DiagramFormat): string;
+    /** @internal The diagram of the rule with these nodes. */
+    draw(project: Project, nodes: DiagramNodes, format: DiagramFormat): string;
+    /** Throws an {@link ArchitectureError} when the rule is violated or cannot be evaluated. */
+    check(project: Project): void;
+    /**
+     * Like {@link ImportRule.verify}, but violations that the baseline file accepts do not fail.
+     *
+     * A baseline is used only through this method and {@link ImportRule.checkWithBaseline}. It
+     * can only shrink: an entry that accepts more violations than the code has is a failure.
+     * When the environment variable `REFPACT_BASELINE` is `update`, this writes the violations
+     * of the rule to the file and passes.
+     */
+    verifyWithBaseline(project: Project, baseline: Baseline): Failure | undefined;
+    /**
+     * Throws an {@link ArchitectureError} when the rule has violations that the baseline file
+     * does not accept, when the baseline has stale entries, or when the rule cannot be evaluated.
+     */
+    checkWithBaseline(project: Project, baseline: Baseline): void;
+    /**
+     * Writes the current violations of this rule to the baseline file. Entries of other rules
+     * in the file are kept. Returns the failure, or `undefined` when the file is written.
+     */
+    writeBaseline(project: Project, baseline: Baseline): Failure | undefined;
+    /** The failure of the violations. A warning reports them and fails not. */
+    private violated;
+    private violationsForBaseline;
+    /** The rule as the core sees it. */
+    toCore(): CoreRule;
+}
+export { KINDS, MARKERS };
+export type { Kind, Marker };