okmodel 0.3.0 → 0.4.0

package/dist/tooling/migrate/estimate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Row estimates for `okm migrate plan` (D194).
+ *
+ * The numbers come from `pg_class.reltuples` on a selected target. They are
+ * printed next to the lock and then discarded. The linter never reads them,
+ * and `okm generate` never asks for them.
+ */
+import type { PlanStep } from "./plan.js";
+/**
+ * Estimated rows above which an `ACCESS EXCLUSIVE` lock prints a note.
+ *
+ * The note is text on the lock line. It is not a lint finding.
+ */
+export declare const LARGE_TABLE_ROWS = 1000000;
+/** What `pg_class` said about one table. */
+export type RowEstimate = {
+    readonly kind: "rows";
+    readonly reltuples: number;
+} | {
+    readonly kind: "unknown";
+};
+/**
+ * Reads `reltuples` for the named tables.
+ *
+ * The statements run in one read-only transaction. A table that is absent
+ * from the result is not entered in the map: the printer treats that as
+ * `new table`. `reltuples` of `-1` is {@link RowEstimate} `unknown`. This
+ * never scans a table.
+ *
+ * @param url - Target URL
+ * @param schema - Schema the plan qualifies, usually `public`
+ * @param tables - Table names the plan steps name
+ * @returns One entry per relation `pg_class` returned
+ */
+export declare function readRowEstimates(url: string, schema: string, tables: readonly string[]): Promise<ReadonlyMap<string, RowEstimate>>;
+/**
+ * Lock line with estimates, the safe-rewrite label, and the large-table note.
+ *
+ * @param step - One plan step
+ * @param estimates - `reltuples` for tables that exist on the target
+ * @returns The text after `-- lock: `
+ */
+export declare function annotateLock(step: PlanStep, estimates: ReadonlyMap<string, RowEstimate>): string;
+/**
+ * Compact phrase for one estimate.
+ *
+ * @param count - Rounded `reltuples`
+ * @returns `about 4.2M rows` and the same shape for thousands and billions
+ */
+export declare function aboutRows(count: number): string;

package/dist/tooling/migrate/extensions.d.ts

@@ -8,9 +8,11 @@
  */
 import type { CatalogObject } from "../../contracts/catalog/types.js";
 import type { DriverConnection } from "../../contracts/driver.js";
+import { type StepKind } from "./classify.js";
 /** One extension alter. The planner stores it as a plan step. */
 export type ExtensionStep = {
     readonly sql: string;
+    readonly kind: StepKind;
     readonly class: "expand" | "contract";
     readonly action: "ddl";
     readonly lock: string;

package/dist/tooling/migrate/files.d.ts

@@ -1,6 +1,7 @@
 /**
  * Migration files on disk: SQL from {@link formatPlan} plus the catalog hash.
  */
+import { parseCatalog } from "../../contracts/catalog/document.js";
 import { type PlanStep } from "./plan.js";
 /** One migration the applier can run and resume. */
 export type StoredMigration = {
@@ -17,3 +18,14 @@ export type StoredMigration = {
  * @returns Migrations in apply order
  */
 export declare function loadMigrations(directory: string): readonly StoredMigration[];
+/**
+ * Loads the last migration's catalog, which is the head snapshot.
+ *
+ * @param directory - Migrations directory
+ * @returns The last file, or `undefined` when there are none
+ */
+export declare function loadHeadSnapshot(directory: string): {
+    readonly id: string;
+    readonly catalogHash: string;
+    readonly catalog: ReturnType<typeof parseCatalog>;
+} | undefined;

package/dist/tooling/migrate/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * Public entry for `okmodel/migrate`.
  *
- * `defineConfig` and its types. The CLI imports planning and apply helpers
- * from their modules, so those names are not exported.
+ * `defineConfig`, its types, and `provision` for one configured target.
+ * The CLI imports planning and apply helpers from their modules.
  */
 export { defineConfig, type MigrateConfig, type TargetInput } from "./config.js";
+export { provision } from "./provision.js";

package/dist/tooling/migrate/index.js

@@ -1,7 +1,73 @@
+import"../../shared/wqem4jed.js";
+import"../../shared/8jb4ymh2.js";
+import"../../shared/n442h54c.js";
+import {
+  applyTarget2,
+  backfillTiming2
+} from "../../shared/s4mb6a4b.js";
+import {
+  loadMigrations,
+  loadHeadSnapshot,
+  readReference
+} from "../../shared/7nk68fj8.js";
+import {
+  assertTargetPolicy,
+  selectTarget,
+  loadBuiltSchema,
+  loadConfig
+} from "../../shared/q6zsyh31.js";
+import"../../shared/n5y9zyj1.js";
+import"../../shared/41kv2xdm.js";
+import {
+  OkmError2
+} from "../../shared/52szzakm.js";
+
 // src/tooling/migrate/config.ts
 function defineConfig(config) {
   return config;
 }
+// src/tooling/migrate/provision.ts
+import { join } from "node:path";
+async function provision(target, cwd = process.cwd()) {
+  const config = await loadConfig(cwd);
+  const selected = selectTarget(config, target);
+  assertTargetPolicy(selected, "provision");
+  const directory = join(cwd, config.migrations ?? "migrations");
+  const migrations = loadMigrations(directory);
+  const head = loadHeadSnapshot(directory);
+  if (head === undefined) {
+    throw new OkmError2("invalid", "There is no head snapshot to provision.", {
+      fix: { summary: "Run okm generate before provision." }
+    });
+  }
+  const built = await loadBuiltSchema(cwd, config);
+  const report = await applyTarget2({
+    url: selected.url,
+    target: selected.name,
+    protected: selected.protected,
+    allowPooler: config.allowPooler === true,
+    ...backfillTiming2(config.backfill),
+    migrations,
+    snapshot: {
+      catalog: head.catalog,
+      migrationId: head.id,
+      catalogHash: head.catalogHash,
+      reference: readReference(built.tables, built.casing, head.catalog),
+      only: true
+    },
+    ...config.roles !== undefined ? { migrationRole: config.roles.migration } : {},
+    lintDirectory: directory
+  });
+  if (report.applied.length === 0)
+    return `target ${report.target}
+nothing to apply
+`;
+  return `target ${report.target}
+${report.applied.map((id) => `applied ${id}`).join(`
+`)}
+`;
+}
 export {
-  defineConfig
+  defineConfig,
+  provision
 };

package/dist/tooling/migrate/lint-rules.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Lint rules for one plan step or one catalog column.
+ *
+ * A rule reads the statement and the catalogs. It does not connect.
+ */
+import type { Catalog, ColumnObject } from "../../contracts/catalog/types.js";
+import type { PlanStep } from "./plan.js";
+/** Destructive, compatibility, data, locking, or a schema type preference. */
+export type LintCategory = "destructive" | "backward-incompatible" | "data-dependent" | "locking" | "type-preference";
+/** An error blocks plan, check, and apply. A warning is printed and does not. */
+export type LintSeverity = "error" | "warning";
+/** What a step rule can see. Catalogs are the plan's before and after. */
+export type StepInput = {
+    readonly step: PlanStep;
+    readonly before: Catalog;
+    readonly after: Catalog;
+    readonly existingTables: ReadonlySet<string>;
+    /** Steps before this one. A safe `SET NOT NULL` is recognised from them. */
+    readonly earlier: readonly PlanStep[];
+    /** Steps after this one. A unique index built for a constraint is recognised from them. */
+    readonly later: readonly PlanStep[];
+};
+/** One step rule. `check` returns a reason for each hit, or nothing. */
+export type StepRule = {
+    readonly code: string;
+    readonly category: Exclude<LintCategory, "type-preference">;
+    readonly severity: LintSeverity;
+    /** One line for the codes table. */
+    readonly doc: string;
+    readonly check: (input: StepInput) => readonly string[];
+};
+/** One schema rule. `okm check` runs these on the author catalog. */
+export type ColumnRule = {
+    readonly code: string;
+    readonly category: "type-preference";
+    readonly severity: "warning";
+    /** One line for the codes table. */
+    readonly doc: string;
+    readonly check: (column: ColumnObject) => string | undefined;
+};
+/**
+ * Step rules, lowest free code in each category.
+ *
+ * OKM1534 to OKM1537 are errors when the statement is not the safe form.
+ * OKM1538 stays a warning: a rewriting type change has no safe form here.
+ */
+export declare const STEP_RULES: readonly StepRule[];
+/**
+ * Type preferences. Warnings, read from the schema catalog by `okm check`.
+ */
+export declare const COLUMN_RULES: readonly ColumnRule[];

package/dist/tooling/migrate/lint.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Runs the migration linter.
+ *
+ * The linter reads a plan and the two catalogs. It does not connect.
+ * An override is a `-- okm-allow` line on the statement. It silences only
+ * the code it names, and only with a reason.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { OkmError } from "../../contracts/error.js";
+import { type LintSeverity } from "./lint-rules.js";
+import { type MigrationPlan } from "./plan.js";
+/** One finding. `place` is `step N` or `table.column`, optionally prefixed with the file. */
+export type Finding = {
+    readonly severity: LintSeverity;
+    readonly code: string;
+    readonly place: string;
+    readonly reason: string;
+    readonly fix: string;
+};
+/**
+ * Lints every step. Type preferences are {@link lintCatalog}, not here.
+ *
+ * @param plan - Parsed or planned steps, including `-- okm-allow` lines
+ * @param before - Catalog the statements start from
+ * @param after - Catalog the statements end on
+ * @returns Findings in step order, then code order
+ */
+export declare function lintPlan(plan: MigrationPlan, before: Catalog, after: Catalog): readonly Finding[];
+/**
+ * Lints type preferences on the author catalog.
+ *
+ * @param source - Schema catalog `okm check` loaded
+ * @returns One warning per column that prefers another type
+ */
+export declare function lintCatalog(source: Catalog): readonly Finding[];
+/**
+ * Lints each SQL file against the previous file's catalog.
+ *
+ * The walk starts at the first file, against an empty catalog, so a later
+ * file sees the catalog the file before it left. The sibling `.catalog.json`
+ * is the catalog after that file. When `pending` is passed, only those
+ * migration ids contribute findings. The earlier files are still read.
+ *
+ * @param directory - Migrations directory. Missing means there are none
+ * @param pending - Migration ids still to run. Omit to lint every file
+ * @returns Findings, each place prefixed with the migration id
+ */
+export declare function lintMigrationDirectory(directory: string, pending?: ReadonlySet<string>): readonly Finding[];
+/**
+ * Prints findings one per line, in a form CI can grep.
+ *
+ * @param findings - Findings from {@link lintPlan} or {@link lintCatalog}
+ * @returns The text, or `""` when there are none. A non-empty result ends in a newline
+ */
+export declare function formatFindings(findings: readonly Finding[]): string;
+/**
+ * Reports whether any finding is an error.
+ *
+ * @param findings - Findings to scan
+ * @returns `true` when plan, check, or apply must fail
+ */
+export declare function hasError(findings: readonly Finding[]): boolean;
+/**
+ * OKM1510 for an unresolved error finding.
+ *
+ * The message is the finding lines, so the failure text stays greppable.
+ *
+ * @param findings - Findings that include at least one error
+ * @returns The error apply, plan, and check throw before continuing
+ */
+export declare function lintRefusal(findings: readonly Finding[]): OkmError;

package/dist/tooling/migrate/managed.d.ts

@@ -1,5 +1,5 @@
 /**
- * Tables OKModel owns: `okm_meta` and `okm_history`.
+ * Tables OKModel owns: `okm_meta`, `okm_history`, and `okm_backfill`.
  *
  * Apply creates them. They are not part of the author schema. Plan, push,
  * check, and doctor omit them on both sides, so a diff neither drops them

package/dist/tooling/migrate/plan.d.ts

@@ -6,26 +6,56 @@
  * OKM1530. The planner never prompts.
  *
  * Picklist and enum removals are expand `UPDATE`s plus a contract swap
- * (D131). Those data steps are plain statements here. Batching them is P52.
+ * (D131). Each data step is a backfill: one idempotent `UPDATE` per batch,
+ * with `-- backfill` naming the primary key (D195).
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import type { DeclaredRename } from "../../dialects/pg/declarations.js";
+import { type BackfillSpec } from "./backfill.js";
+import { type MigrationClass, type StepKind } from "./classify.js";
 import { type Replacement } from "./values.js";
-/** Expand, contract, or a step that is neither. */
-export type MigrationClass = "expand" | "contract" | "unclassified";
+export type { MigrationClass, StepKind };
 /**
  * One statement in a plan.
  *
- * `backfill` is data; P16B runs it as written. `transactional: false` marks a
- * step that cannot share a transaction with a later use (`ALTER TYPE … ADD
- * VALUE`, spec 19.2).
+ * `backfill` is data. A step with {@link PlanStep.backfill} is one idempotent
+ * `UPDATE` per batch, outside the migration transaction. `transactional: false`
+ * also marks a step that cannot share a transaction (`ALTER TYPE … ADD VALUE`,
+ * a concurrent index).
  */
 export type PlanStep = {
     readonly sql: string;
     readonly class: MigrationClass;
+    /**
+     * Planner operation. Absent on a step built by hand.
+     *
+     * The class comes from this kind. A statement with no kind and no class
+     * comment is `raw-sql`.
+     */
+    readonly kind?: StepKind;
     readonly action: "ddl" | "backfill";
     readonly lock: string;
+    /**
+     * Tables the statement names.
+     *
+     * Used to look up `pg_class.reltuples` when a plan is printed against a
+     * reachable target. {@link formatPlan} does not write this into a file.
+     */
+    readonly tables?: readonly string[];
+    /**
+     * Set when the step was emitted by a safe rewrite (D193).
+     *
+     * Display only. A migration file does not record it.
+     */
+    readonly safeRewrite?: true;
     readonly transactional: boolean;
+    /**
+     * Set when the statement is a batched backfill.
+     *
+     * The header is `table`, `key`, and `batch`. The statement receives `$1`
+     * and `$2`. Absent on a data step written without that header.
+     */
+    readonly backfill?: BackfillSpec;
     /**
      * Set on an extension upgrade the planner could not check.
      *
@@ -39,6 +69,18 @@ export type PlanStep = {
      * The statement is expand. The flag says the body or the settings changed.
      */
     readonly behavior?: "change";
+    /**
+     * `-- okm-allow` lines directly above the statement.
+     *
+     * A reason silences that code only. An empty reason, or a code the
+     * statement did not trigger, is OKM1510 and silences nothing.
+     */
+    readonly allows?: readonly StepAllow[];
+};
+/** One `-- okm-allow CODE: reason` line above a statement. */
+export type StepAllow = {
+    readonly code: string;
+    readonly reason: string;
 };
 /** A named plan and the class of its strictest step. */
 export type MigrationPlan = {
@@ -55,6 +97,13 @@ export type PlanRequest = {
     readonly schema?: string;
     /** Concrete schema written into the SQL. Identities stay logical. */
     readonly name?: string;
+    /**
+     * Rows per backfill batch written into the step header.
+     *
+     * Omitted uses the built-in default of 1000. A later apply reads `batch=`
+     * from the file, which overrides `defineConfig({ backfill })`.
+     */
+    readonly batchSize?: number;
 };
 /**
  * Builds a plan from catalog `before` to catalog `after`.
@@ -64,12 +113,18 @@ export type PlanRequest = {
  */
 export declare function planMigration(input: PlanRequest): MigrationPlan;
 /**
- * Prints a plan. The text is SQL plus class comments, never TypeScript.
+ * Prints a plan. The header is the strictest class. Each step prints its
+ * class and lock. The text is SQL plus those comments, never TypeScript.
+ *
+ * `okm generate` calls this with no `lockText`, so a file stays free of row
+ * estimates. `okm migrate plan` passes `lockText` only after a reachable
+ * target has answered.
  *
  * @param plan - Plan from {@link planMigration}
- * @returns The text `okm generate` writes and `okm migrate plan` prints
+ * @param lockText - Replaces the lock comment when a target supplied estimates
+ * @returns The text `okm generate` writes. `okm migrate plan` uses the same text offline
  */
-export declare function formatPlan(plan: MigrationPlan): string;
+export declare function formatPlan(plan: MigrationPlan, lockText?: (step: PlanStep) => string): string;
 /**
  * Reads a plan written by {@link formatPlan}.
  *

package/dist/tooling/migrate/project.d.ts

@@ -11,6 +11,7 @@ import type { Catalog } from "../../contracts/catalog/types.js";
 import { type MigrateConfig } from "./config.js";
 import { type InvokeFlags } from "./policy.js";
 import { type MigrationPlan } from "./plan.js";
+import { type Finding } from "./lint.js";
 type Built = BuiltSchema<readonly AnyTable[]>;
 /**
  * Validates the schema and writes `.okm/`.
@@ -27,29 +28,47 @@ export declare function buildProject(cwd: string): Promise<string>;
  * @param cwd - Project directory
  * @param name - Migration name
  * @param flags - `--replace` values
- * @returns The SQL path, or `undefined` when nothing changed
+ * @returns The SQL path and lint findings, or `undefined` when nothing changed
  */
-export declare function generateProject(cwd: string, name: string, flags: readonly string[]): Promise<string | undefined>;
+export declare function generateProject(cwd: string, name: string, flags: readonly string[]): Promise<{
+    readonly path: string;
+    readonly findings: readonly Finding[];
+} | undefined>;
 /**
  * Plans and returns the text. Nothing is written.
  *
+ * When one target is configured, or `--target` names one, and that database
+ * answers, the printed lock lines include `pg_class` row estimates. No
+ * target, several targets without `--target`, or a target that cannot be
+ * reached leaves the text identical to {@link formatPlan}.
+ *
  * @param cwd - Project directory
  * @param name - Plan name
  * @param flags - `--replace` values
- * @returns The plan
+ * @param invoke - Target and protection flags, when the command passed them
+ * @returns The plan, its lint findings, and the text to print
  */
-export declare function planProject(cwd: string, name: string, flags: readonly string[]): Promise<MigrationPlan>;
+export declare function planProject(cwd: string, name: string, flags: readonly string[], invoke?: InvokeFlags): Promise<{
+    readonly plan: MigrationPlan;
+    readonly findings: readonly Finding[];
+    readonly text: string;
+}>;
 /**
  * Validates the schema, then reports stale renames and unlisted table files.
  *
- * When exactly one target is configured, or `--target` names one, a database
- * that already has `okm_meta` is compared with the schema. A difference is
+ * When exactly one target is configured, or `--target` names one, the
+ * read-only `check` and `drift` classes are allowed and a database that
+ * already has `okm_meta` is compared with the schema. A difference is
  * OKM1520. Several targets and no `--target` skip that comparison.
  *
+ * Lint findings are computed from the plan and the catalog before any
+ * connection. An error finding is OKM1510. Warnings are returned.
+ *
  * @param cwd - Project directory
  * @param flags - `--target`, when the caller passed one
+ * @returns Warning findings. Errors throw
  */
-export declare function checkProject(cwd: string, flags?: InvokeFlags): Promise<void>;
+export declare function checkProject(cwd: string, flags?: InvokeFlags): Promise<readonly Finding[]>;
 /**
  * Table files whose names do not appear in the schema module.
  *
@@ -83,6 +102,14 @@ export declare function openProject(cwd: string): Promise<{
     readonly previous: Catalog;
     readonly renames: readonly DeclaredRename[];
 }>;
+/**
+ * Loads the schema named by `config`.
+ *
+ * @param cwd - Project directory
+ * @param config - Project config
+ * @returns The built schema, with roles attached when the config declares them
+ */
+export declare function loadBuiltSchema(cwd: string, config: MigrateConfig): Promise<Built>;
 /**
  * Loads `okmodel.config.ts`.
  *
@@ -90,4 +117,12 @@ export declare function openProject(cwd: string): Promise<{
  * @returns The config object
  */
 export declare function loadConfig(cwd: string): Promise<MigrateConfig>;
+/**
+ * Loads the module named by `spec` and returns the schema it exports.
+ *
+ * @param cwd - Project directory
+ * @param spec - Path from `defineConfig({ schema })`, relative to `cwd`
+ * @returns The built schema
+ */
+export declare function loadSchema(cwd: string, spec: string): Promise<Built>;
 export {};

package/dist/tooling/migrate/provision.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `provision(target)` for one configured target (D198).
+ *
+ * Same rules as `okm migrate apply` on an empty target, including
+ * {@link assertTargetPolicy}. A target that is not empty is OKM1851.
+ * Tenant registry creation is M5.
+ */
+/**
+ * Provisions one configured target from the head snapshot.
+ *
+ * The target must be empty. Reference rows are inserted if missing. History
+ * records `provisioned@<migration id>` and no migration step.
+ *
+ * @param target - Configured target name. `default` is the `database` target
+ * @param cwd - Project directory. Defaults to the process working directory
+ * @returns The same text `okm migrate apply` prints for that run
+ */
+export declare function provision(target: string, cwd?: string): Promise<string>;

package/dist/tooling/migrate/reference.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reference rows declared on a table (D198).
+ *
+ * The rows live on the schema, not as a catalog diff. Apply inserts a row
+ * when its key is missing and does not update or delete. The statements are
+ * not migration steps, so OKM1542 does not see them.
+ */
+import type { Catalog } from "../../contracts/catalog/types.js";
+import { type AnyTable } from "../../dialects/pg/table.js";
+/** One value a reference row may store. */
+export type ReferenceValue = string | number | boolean | null;
+/** One table's reference declaration, in SQL names. */
+export type ReferenceTable = {
+    readonly table: string;
+    readonly key: readonly string[];
+    readonly rows: readonly (readonly (readonly [string, ReferenceValue])[])[];
+};
+/**
+ * Reads `reference` from the schema and checks it against the head catalog.
+ *
+ * A key must be a primary key, a unique constraint, or a unique index, in
+ * that column order. The catalog is not given a copy of the rows.
+ *
+ * @param tables - Tables the schema built
+ * @param casing - Schema casing. Absent means names are used as written
+ * @param head - Head snapshot the rows will be inserted into
+ * @returns One entry per table that declares rows
+ */
+export declare function readReference(tables: readonly AnyTable[], casing: "snake" | undefined, head: Catalog): readonly ReferenceTable[];
+/**
+ * Insert-if-missing statements for one schema.
+ *
+ * Each row is its own `INSERT … ON CONFLICT DO NOTHING`. There is no
+ * `UPDATE` and no `DELETE`.
+ *
+ * @param tables - Declarations from {@link readReference}
+ * @param schema - Schema the statements write
+ * @returns SQL in declaration order
+ */
+export declare function referenceInserts(tables: readonly ReferenceTable[], schema: string): readonly string[];