workspace-conformance 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { ConfigFileOptions, LayoutConfig, RankSkipOptions, Section } from "@exadev/config";
+import { IViolation } from "dependency-cruiser";
 import { z } from "zod";
 import { CompilerOptions } from "ts-morph";
 //#region src/check.d.ts
@@ -53,6 +54,77 @@ type CheckFunction<Options> = (context: CheckContext<Options>) => Promise<readon
  */
 type LayoutCheckFunction<Options> = (context: LayoutCheckContext<Options>) => Promise<readonly Violation[]>;
 //#endregion
+//#region src/migrations/adapters.d.ts
+/**
+ * Which of several things in a deploy tool's config the generator's output belongs to.
+ */
+interface DeploySelector {
+  /**
+   * The binding of the database, when the config declares more than one.
+   */
+  readonly database?: string;
+  /**
+   * The named environment whose settings apply instead of the top-level ones.
+   */
+  readonly environment?: string;
+}
+/**
+ * What a deploy tool's config says about the directory it applies migrations from.
+ */
+type DeployDirectory = {
+  readonly directory: string;
+  readonly none?: never;
+} | {
+  readonly none: string;
+  readonly directory?: never;
+};
+/**
+ * A schema generator, for the cross-check between where it writes migrations and where the deploy tool applies them from. The data of a config file is already read; an adapter only knows where in it the directory is.
+ */
+interface GeneratorAdapter {
+  /**
+   * The names the config file may have, by precedence. The extension decides how the file is read.
+   */
+  readonly configFiles: readonly [string, ...string[]];
+  /**
+   * Matches a shell command that applies migrations with the generator itself, bypassing the deploy tool.
+   */
+  readonly applyCommand: RegExp;
+  /**
+   * The command as it is written, for messages.
+   */
+  readonly applyCommandName: string;
+  /**
+   * The directory the generator writes migrations to, as the config writes it (relative to the config file's directory) or the generator's default when the config sets none. Throws `ConformanceError` when the config is not of a shape the adapter can read.
+   */
+  readonly outputDirectory: (config: unknown, file: string) => string;
+}
+/**
+ * A deploy tool that applies migrations from a directory.
+ */
+interface DeployToolAdapter {
+  /**
+   * The names the config file may have, by precedence. The extension decides how the file is read.
+   */
+  readonly configFiles: readonly [string, ...string[]];
+  /**
+   * The directory the tool applies migrations from, as the config writes it (relative to the config file's directory) or the tool's default when the config sets none. Throws `ConformanceError` when the config is not of a shape the adapter can read or `selector` is needed and absent.
+   */
+  readonly migrationsDirectory: (config: unknown, file: string, selector: DeploySelector) => DeployDirectory;
+}
+/**
+ * The generators that have an adapter.
+ */
+declare const generatorNames: readonly ["drizzle-kit"];
+/**
+ * The deploy tools that have an adapter.
+ */
+declare const deployToolNames: readonly ["wrangler"];
+type GeneratorName = (typeof generatorNames)[number];
+type DeployToolName = (typeof deployToolNames)[number];
+export declare const generators: Readonly<Record<GeneratorName, GeneratorAdapter>>;
+export declare const deployTools: Readonly<Record<DeployToolName, DeployToolAdapter>>;
+//#endregion
 //#region src/options.d.ts
 /**
  * Options of the `aggregate-mappers` check: every aggregate type a contract exports has a mapper file in the place the template names.
@@ -177,6 +249,39 @@ interface DockerfilePackageManagerOptions {
    */
   readonly packageJson?: string;
 }
+/**
+ * Options of the `migrations-directory` check: the directory a schema generator writes migrations to is the one the deploy tool applies them from, and no script applies them with the generator.
+ */
+interface MigrationsDirectoryOptions {
+  /**
+   * The schema generator, which has an adapter that knows its config file and where in it the output directory is.
+   */
+  readonly generator: GeneratorName;
+  /**
+   * The deploy tool, which has an adapter that knows its config file and where in it the migrations directory is.
+   */
+  readonly deployTool: DeployToolName;
+  /**
+   * The generator's config file, relative to the directory the checks run in. The first of the adapter's default file names that exists when omitted.
+   */
+  readonly generatorConfig?: string;
+  /**
+   * The deploy tool's config file. The first of the adapter's default file names that exists when omitted.
+   */
+  readonly deployConfig?: string;
+  /**
+   * The binding of the database the generator writes migrations for. Needed when the deploy config declares more than one; the only one is used when omitted.
+   */
+  readonly database?: string;
+  /**
+   * The named environment of the deploy config to read instead of its top-level settings.
+   */
+  readonly environment?: string;
+  /**
+   * Globs of the `package.json` files whose scripts are searched for the generator's apply command. Every `package.json` at any depth when omitted.
+   */
+  readonly packageJsons?: readonly string[];
+}
 /**
  * The options of every check, by check name.
  */
@@ -192,6 +297,7 @@ interface CheckOptionsByName {
   readonly "single-storybook": SingleStorybookOptions;
   readonly "commit-types": CommitTypesOptions;
   readonly "dockerfile-package-manager": DockerfilePackageManagerOptions;
+  readonly "migrations-directory": MigrationsDirectoryOptions;
 }
 /**
  * The name of a check.
@@ -238,6 +344,116 @@ export declare const commitTypes: CheckFunction<CommitTypesOptions>;
  */
 export declare const dockerfilePackageManager: CheckFunction<DockerfilePackageManagerOptions>;
 //#endregion
+//#region src/workspace/packages.d.ts
+/**
+ * A package directory found under the workspace root, before the layout classifies it.
+ */
+interface DiscoveredPackage {
+  /**
+   * Relative to the workspace root, with `/` separators.
+   */
+  readonly dir: string;
+  /**
+   * The manifest's `name`; a manifest may omit it.
+   */
+  readonly name: string | undefined;
+}
+/**
+ * A workspace package as the layout sees it.
+ */
+interface WorkspacePackage extends DiscoveredPackage {
+  /**
+   * The name of the group whose root is the longest prefix of the package directory.
+   */
+  readonly group: string;
+  /**
+   * The rank from `nameRanks`, else the group's rank, else `defaultRank`; `undefined` when none of them applies.
+   */
+  readonly rank: number | undefined;
+  /**
+   * The slice the group's `slice` rule derives; `undefined` for a group without one and for a package that yields none.
+   */
+  readonly slice: string | undefined;
+}
+/**
+ * Classify discovered packages by the layout: group, rank and slice. Pure.
+ *
+ * A package no group owns is a configuration error, because every check would otherwise skip it without saying so. Nested package directories are one too: the checks attribute a file to the package whose directory is its prefix, which is ambiguous for a package inside another. A `namePrefix` slice takes the longest slice value that a `segment` group produced and that prefixes the package's unscoped name; a package without a name has no such slice.
+ */
+export declare function classifyPackages(discovered: readonly DiscoveredPackage[], layout: LayoutConfig): readonly WorkspacePackage[];
+//#endregion
+//#region src/workspace/rules.d.ts
+/**
+ * A forbidden-dependency rule in the shape dependency-cruiser takes: a dependency from a file matching `from` to a file matching `to` is a violation.
+ */
+interface ImportRule {
+  readonly name: string;
+  readonly severity: "error";
+  readonly comment: string;
+  readonly from: {
+    readonly path?: string;
+  };
+  readonly to: {
+    readonly path?: string;
+    readonly circular?: boolean;
+    readonly couldNotResolve?: boolean;
+  };
+}
+/**
+ * A regular expression, as source text, matching every file inside any of the packages. The trailing `/` keeps `packages/a` from matching `packages/ab`.
+ */
+export declare function packagesPattern(packages: readonly WorkspacePackage[]): string;
+/**
+ * One rule per rank that has a higher rank above it: files of a package at that rank may not import a package at a strictly higher rank. A rule compares no numbers, so the ordering is expanded into path alternations here. Each rule comes with a `-by-name` rule for imports that do not resolve to a file.
+ */
+export declare function uphillRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
+/**
+ * One rule per rank with a package more than `rankSkip.maxDistance` ranks below it that is not an exempt rank.
+ */
+export declare function rankSkipRules(packages: readonly WorkspacePackage[], rankSkip: RankSkipOptions): readonly ImportRule[];
+/**
+ * One rule per slice: a package in it may not import a package that has a different slice. A package without a slice is in none and is never restricted.
+ */
+export declare function crossSliceRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
+/**
+ * Two rules per isolated pair, one for each direction.
+ */
+export declare function isolatedGroupRules(packages: readonly WorkspacePackage[], isolatedGroups: NonNullable<LayoutConfig["isolatedGroups"]>): readonly ImportRule[];
+/**
+ * The rule that forbids any import cycle among the packages' files.
+ */
+export declare function cycleRule(): ImportRule;
+//#endregion
+//#region src/checks/import-graph.d.ts
+/**
+ * What a check's report may need to know about the workspace the graph was cruised over.
+ */
+interface ImportScope {
+  readonly cwd: string;
+  /**
+   * The workspace root; finding paths are relative to it.
+   */
+  readonly root: string;
+  readonly packages: readonly WorkspacePackage[];
+}
+/**
+ * How an import check takes part in a shared cruise: the rules it adds and how it reads its own findings. Findings are routed to a check by the names of the rules it generated, so those names must differ from every other check's.
+ */
+interface ImportCheckSpec {
+  /**
+   * The check's name; the violation code is `<name>/<reason>`.
+   */
+  readonly name: string;
+  /**
+   * The forbidden rules for the workspace's packages. Throws `ConformanceError` when the layout does not configure what the check needs.
+   */
+  readonly rules: (packages: readonly WorkspacePackage[], layout: LayoutConfig) => readonly ImportRule[];
+  /**
+   * The violations for the findings of this check's rules, in a stable order.
+   */
+  readonly report: (findings: readonly IViolation[], scope: ImportScope) => readonly Violation[];
+}
+//#endregion
 //#region src/checks/import-cross-slice.d.ts
 /**
  * A package imports a package in a different slice.
@@ -276,6 +492,14 @@ export declare const importUphill: LayoutCheckFunction<ImportGraphOptions>;
  */
 export declare const instructionSymlinks: CheckFunction<InstructionSymlinksOptions>;
 //#endregion
+//#region src/checks/migrations-directory.d.ts
+/**
+ * The directory a schema generator writes migrations to is the one the deploy tool applies them from, and no script applies them with the generator instead of the deploy tool. The generator and the deploy tool are named in the options and each has an adapter that knows its config file names and where in them the directory is; both directories are resolved against the directory of the file that sets them.
+ *
+ * The config files are read as data: JSON, JSONC and TOML are parsed, and a module (a generator's TypeScript config) is evaluated, so it must be trusted.
+ */
+export declare const migrationsDirectory: CheckFunction<MigrationsDirectoryOptions>;
+//#endregion
 //#region src/checks/single-storybook.d.ts
 /**
  * At most one Storybook exists, in the permitted directory (the workspace root unless the options say otherwise), and none in a package such as a UI package. A Storybook is a `.storybook` directory.
@@ -321,9 +545,9 @@ interface RunInput {
   readonly configFiles: ConfigFileOptions | undefined;
 }
 /**
- * A check bound to its place in the `checks` map.
+ * What every registered check has, whichever way it runs.
  */
-interface RegisteredCheck<Name extends CheckName> {
+interface RegisteredCheckBase<Name extends CheckName> {
   readonly name: Name;
   readonly description: string;
   /**
@@ -334,8 +558,26 @@ interface RegisteredCheck<Name extends CheckName> {
    * Whether the `checks` map turns this check on.
    */
   readonly isEnabled: (checks: ChecksConfig) => boolean;
+}
+/**
+ * A check that runs on its own.
+ */
+interface StandaloneCheck<Name extends CheckName> extends RegisteredCheckBase<Name> {
   readonly run: (input: RunInput) => Promise<readonly Violation[]>;
 }
+/**
+ * An import check. It has no `run` of its own: it always joins a cruise shared with the other import checks of the run, so there is one path from the registry to dependency-cruiser.
+ */
+interface ImportGraphCheck<Name extends CheckName> extends RegisteredCheckBase<Name> {
+  readonly importGraph: {
+    readonly spec: ImportCheckSpec;
+    readonly optionsOf: (checks: ChecksConfig) => ImportGraphOptions | undefined;
+  };
+}
+/**
+ * A check bound to its place in the `checks` map.
+ */
+type RegisteredCheck<Name extends CheckName> = StandaloneCheck<Name> | ImportGraphCheck<Name>;
 /**
  * Every check, by name, in the order they run. The key is the name used in the `checks` map, on the command line and in violation codes.
  */
@@ -478,84 +720,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-//#region src/workspace/packages.d.ts
-/**
- * A package directory found under the workspace root, before the layout classifies it.
- */
-interface DiscoveredPackage {
-  /**
-   * Relative to the workspace root, with `/` separators.
-   */
-  readonly dir: string;
-  /**
-   * The manifest's `name`; a manifest may omit it.
-   */
-  readonly name: string | undefined;
-}
-/**
- * A workspace package as the layout sees it.
- */
-interface WorkspacePackage extends DiscoveredPackage {
-  /**
-   * The name of the group whose root is the longest prefix of the package directory.
-   */
-  readonly group: string;
-  /**
-   * The rank from `nameRanks`, else the group's rank, else `defaultRank`; `undefined` when none of them applies.
-   */
-  readonly rank: number | undefined;
-  /**
-   * The slice the group's `slice` rule derives; `undefined` for a group without one and for a package that yields none.
-   */
-  readonly slice: string | undefined;
-}
-/**
- * Classify discovered packages by the layout: group, rank and slice. Pure.
- *
- * A package no group owns is a configuration error, because every check would otherwise skip it without saying so. Nested package directories are one too: the checks attribute a file to the package whose directory is its prefix, which is ambiguous for a package inside another. A `namePrefix` slice takes the longest slice value that a `segment` group produced and that prefixes the package's unscoped name; a package without a name has no such slice.
- */
-export declare function classifyPackages(discovered: readonly DiscoveredPackage[], layout: LayoutConfig): readonly WorkspacePackage[];
-//#endregion
-//#region src/workspace/rules.d.ts
-/**
- * A forbidden-dependency rule in the shape dependency-cruiser takes: a dependency from a file matching `from` to a file matching `to` is a violation.
- */
-interface ImportRule {
-  readonly name: string;
-  readonly severity: "error";
-  readonly comment: string;
-  readonly from: {
-    readonly path?: string;
-  };
-  readonly to: {
-    readonly path?: string;
-    readonly circular?: boolean;
-    readonly couldNotResolve?: boolean;
-  };
-}
-/**
- * A regular expression, as source text, matching every file inside any of the packages. The trailing `/` keeps `packages/a` from matching `packages/ab`.
- */
-export declare function packagesPattern(packages: readonly WorkspacePackage[]): string;
-/**
- * One rule per rank that has a higher rank above it: files of a package at that rank may not import a package at a strictly higher rank. A rule compares no numbers, so the ordering is expanded into path alternations here. Each rule comes with a `-by-name` rule for imports that do not resolve to a file.
- */
-export declare function uphillRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
-/**
- * One rule per rank with a package more than `rankSkip.maxDistance` ranks below it that is not an exempt rank.
- */
-export declare function rankSkipRules(packages: readonly WorkspacePackage[], rankSkip: RankSkipOptions): readonly ImportRule[];
-/**
- * One rule per slice: a package in it may not import a package that has a different slice. A package without a slice is in none and is never restricted.
- */
-export declare function crossSliceRules(packages: readonly WorkspacePackage[]): readonly ImportRule[];
-/**
- * Two rules per isolated pair, one for each direction.
- */
-export declare function isolatedGroupRules(packages: readonly WorkspacePackage[], isolatedGroups: NonNullable<LayoutConfig["isolatedGroups"]>): readonly ImportRule[];
-/**
- * The rule that forbids any import cycle among the packages' files.
- */
-export declare function cycleRule(): ImportRule;
-//#endregion
-export type { AggregateMappersOptions, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DiscoveredPackage, DockerfilePackageManagerOptions, ExhaustivenessProof, ImportGraphOptions, InstructionSymlinksOptions, LayoutCheckContext, LayoutCheckFunction, RegisteredCheck, RunChecksOptions, RunResult, SingleStorybookOptions, SourceLocation, TypeErrorReport, Violation, WorkspacePackage };
+export type { AggregateMappersOptions, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DiscoveredPackage, DockerfilePackageManagerOptions, ExhaustivenessProof, GeneratorAdapter, GeneratorName, ImportGraphOptions, InstructionSymlinksOptions, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, RegisteredCheck, RunChecksOptions, RunResult, SingleStorybookOptions, SourceLocation, TypeErrorReport, Violation, WorkspacePackage };