@nekostack/schema 1.0.0

package/dist/src/migrations/parse-provenance.js

@@ -0,0 +1,157 @@
+/**
+ * Provenance parser for `*.migration.ts` files (v0.8 Step 2).
+ *
+ * Reads the migration-header metadata out of an authored migration
+ * file so `buildMigrationRegistry` can index by
+ * `(schemaId, fromVersion, toVersion)` and `verifyMigrationProvenance`
+ * can compare the recorded hashes against the current schema
+ * registry. Migration files use **JSDoc-only** carriers — there is
+ * no JSON variant because migrations are TypeScript modules, not
+ * data documents.
+ *
+ * Expected header shape (generated by the v0.8 stub generator;
+ * humans edit the body, not the header):
+ *
+ *     /**
+ *      * @migration by @nekostack/schema
+ *      * schemaId:         com.x.User
+ *      * fromVersion:      1.0.0
+ *      * toVersion:        2.0.0
+ *      * fromIrHash:       sha256:<64-hex>
+ *      * toIrHash:         sha256:<64-hex>
+ *      * fromSourceHash:   sha256:<64-hex>
+ *      * toSourceHash:     sha256:<64-hex>
+ *      * generator:        neko-schema-migrate-stub
+ *      * generatorVersion: @nekostack/schema@0.8.0
+ *      *
+ *      * DO NOT REMOVE THE HEADER. Authors EDIT THE BODY.
+ *      * /
+ *
+ * The function is **pure**: no `fs.*`, no `import()`, no path
+ * argument, no module evaluation. The CLI reads the migration file
+ * text from disk and hands it in; this module parses and returns.
+ * Master plan Decision #1 boundary applies.
+ *
+ * **Fail-loud, never silent** (v0.8 Round-2 lock — intentional
+ * departure from v0.7 Decision #5). A `.migration.ts` file exists
+ * specifically to declare a `(schemaId, fromVersion, toVersion)`
+ * transition. Missing or malformed provenance is treated as an
+ * invalid declaration, not a "skip and continue" condition.
+ * Malformed input surfaces as `Result<...>` failure with one
+ * `integrity_error` `Issue` whose `metadata.reason` records the
+ * sub-mode (`missing_migration_provenance`, `missing_field`,
+ * `malformed_hash`, `malformed_field`, `unknown_format`).
+ *
+ * The shape of `reason` deliberately overlaps with the v0.7
+ * provenance-parser reasons where the failure mode is the same —
+ * a missing JSDoc block reads identically in both worlds, so
+ * `missing_provenance` would have worked, but the migration-specific
+ * `missing_migration_provenance` name lets downstream consumers
+ * disambiguate without parsing `message`.
+ */
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/**
+ * Parse the migration JSDoc header out of a migration file's text
+ * content. Returns `Result.success` with the parsed fields on a
+ * valid header, `Result.failure` with an `integrity_error` `Issue`
+ * on every failure mode.
+ */
+export function parseMigrationProvenanceFromText(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith("/**")) {
+        return fail("unknown_format", "Migration file does not start with a `/** ... */` JSDoc header.");
+    }
+    return parseJsdocHeader(content);
+}
+// =============================================================================
+// JSDoc header parsing
+// =============================================================================
+const JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//;
+const JSDOC_FIELD = /^\s*\*\s+(\w+):\s*(.+?)\s*$/;
+function parseJsdocHeader(content) {
+    const block = JSDOC_BLOCK.exec(content);
+    if (!block) {
+        return fail("missing_migration_provenance", "No `/** ... */` JSDoc header found at the top of the migration file.");
+    }
+    const fields = new Map();
+    for (const line of block[1].split(/\r?\n/)) {
+        const m = JSDOC_FIELD.exec(line);
+        if (!m)
+            continue;
+        fields.set(m[1], m[2]);
+    }
+    return assembleMigrationProvenance(fields);
+}
+// =============================================================================
+// Field assembly + validation
+// =============================================================================
+const REQUIRED_FIELDS = [
+    "generator",
+    "generatorVersion",
+    "schemaId",
+    "fromVersion",
+    "toVersion",
+    "fromIrHash",
+    "toIrHash",
+    "fromSourceHash",
+    "toSourceHash",
+];
+const HASH_FIELDS = [
+    "fromIrHash",
+    "toIrHash",
+    "fromSourceHash",
+    "toSourceHash",
+];
+function assembleMigrationProvenance(fields) {
+    // 1. Every required field must be present.
+    for (const name of REQUIRED_FIELDS) {
+        if (fields.get(name) === undefined) {
+            return fail("missing_field", `Migration provenance is missing required field \`${name}\`.`);
+        }
+    }
+    // 2. String-shape fields must be non-empty (the JSDoc regex
+    //    already rejects whitespace-only values, but an empty value
+    //    after a colon could still slip through on a malformed line —
+    //    treat that as `malformed_field`).
+    for (const name of REQUIRED_FIELDS) {
+        const value = fields.get(name);
+        if (value.length === 0) {
+            return fail("malformed_field", `Migration provenance field \`${name}\` is empty.`);
+        }
+    }
+    // 3. Every hash field must match the sha256 shape.
+    for (const name of HASH_FIELDS) {
+        const value = fields.get(name);
+        if (!SHA256_PATTERN.test(value)) {
+            return fail("malformed_hash", `Migration provenance \`${name}\` must match \`sha256:<64 hex>\`; got "${value}".`);
+        }
+    }
+    return {
+        success: true,
+        data: {
+            generator: fields.get("generator"),
+            generatorVersion: fields.get("generatorVersion"),
+            schemaId: fields.get("schemaId"),
+            fromVersion: fields.get("fromVersion"),
+            toVersion: fields.get("toVersion"),
+            fromIrHash: fields.get("fromIrHash"),
+            toIrHash: fields.get("toIrHash"),
+            fromSourceHash: fields.get("fromSourceHash"),
+            toSourceHash: fields.get("toSourceHash"),
+        },
+    };
+}
+// =============================================================================
+// Failure helper
+// =============================================================================
+function fail(reason, message) {
+    const issue = {
+        code: "integrity_error",
+        path: [],
+        message,
+        severity: "error",
+        metadata: { reason },
+    };
+    return { success: false, issues: [issue] };
+}
+//# sourceMappingURL=parse-provenance.js.map

package/dist/src/migrations/parse-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-provenance.js","sourceRoot":"","sources":["../../../src/migrations/parse-provenance.ts"],"names":[],"mappings":"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"}

package/dist/src/migrations/plan-migration.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `planMigration(opts)` — diff-aware migration planner (v0.8 Step 4).
+ *
+ * The v0.8 Round-3 lock: this primitive consumes BOTH the schema
+ * registry AND the migration registry. Without the schema registry
+ * it can't compute the diff that determines whether a missing
+ * migration is acceptable; without the migration registry it can't
+ * resolve a chain when one is required. The signature mirrors what
+ * the audit pinned in `PHASE_PLAN_v0.8.md`.
+ *
+ * Locked behavior (Round-3 contract — restated here so the
+ * implementation is easy to compare against the plan doc):
+ *
+ *   1. Resolve endpoints in `schemaRegistry`. If either is absent
+ *      → `Result.failure` with `migration_missing_endpoint`. No
+ *      diff is computed in this case.
+ *   2. Compute `diffNodes(from.schema.node, to.schema.node)`.
+ *      `worstSeverity` is the max-severity over the change list
+ *      (precedence `breaking > additive > cosmetic`; `null` when
+ *      empty), exactly as `diffHandler` aggregates it in v0.7.
+ *   3. Look up the exact migration for `(schemaId, fromVersion,
+ *      toVersion)` if any.
+ *   4. Dispatch on `worstSeverity`:
+ *      - `null` / `"cosmetic"` → success with empty chain. If an
+ *        exact migration exists for the pair, attach an
+ *        `over_specified` `PlanNote`. The migration is NOT included
+ *        in the chain — at this severity the diff says no
+ *        transformation is needed.
+ *      - `"additive"` → if an exact migration exists, include it
+ *        in the chain. If not, success with empty chain plus an
+ *        `additive_no_migration` note.
+ *      - `"breaking"` → chain is **required**. Run DFS chain
+ *        resolution over the schemaId's `from → to` adjacency map.
+ *        0 chains: `migration_not_found` (no migrations for the
+ *        schemaId at all) or `migration_chain_broken` (some exist
+ *        but can't bridge). 1 chain: success. 2+ chains:
+ *        `migration_ambiguous_chain`.
+ *
+ * **Pure.** No `fs.*`, no `import()`, no `process.*`, no
+ * `console.*`. **Never invokes `migration.transform`** — chain
+ * resolution is structural; transform execution is v0.9+.
+ *
+ * `MigrationPlan.versionPath` always reflects the actual hop
+ * sequence: `[fromVersion, toVersion]` for empty chains;
+ * `[fromVersion, ...intermediateVersions, toVersion]` for non-empty
+ * chains derived from the chain entries.
+ */
+import type { MigrationPlanOpts, MigrationPlanResult } from "./types.js";
+export declare function planMigration(opts: MigrationPlanOpts): MigrationPlanResult;
+//# sourceMappingURL=plan-migration.d.ts.map

package/dist/src/migrations/plan-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-migration.d.ts","sourceRoot":"","sources":["../../../src/migrations/plan-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAUH,OAAO,KAAK,EAGV,iBAAiB,EACjB,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAiG1E"}

package/dist/src/migrations/plan-migration.js

@@ -0,0 +1,256 @@
+/**
+ * `planMigration(opts)` — diff-aware migration planner (v0.8 Step 4).
+ *
+ * The v0.8 Round-3 lock: this primitive consumes BOTH the schema
+ * registry AND the migration registry. Without the schema registry
+ * it can't compute the diff that determines whether a missing
+ * migration is acceptable; without the migration registry it can't
+ * resolve a chain when one is required. The signature mirrors what
+ * the audit pinned in `PHASE_PLAN_v0.8.md`.
+ *
+ * Locked behavior (Round-3 contract — restated here so the
+ * implementation is easy to compare against the plan doc):
+ *
+ *   1. Resolve endpoints in `schemaRegistry`. If either is absent
+ *      → `Result.failure` with `migration_missing_endpoint`. No
+ *      diff is computed in this case.
+ *   2. Compute `diffNodes(from.schema.node, to.schema.node)`.
+ *      `worstSeverity` is the max-severity over the change list
+ *      (precedence `breaking > additive > cosmetic`; `null` when
+ *      empty), exactly as `diffHandler` aggregates it in v0.7.
+ *   3. Look up the exact migration for `(schemaId, fromVersion,
+ *      toVersion)` if any.
+ *   4. Dispatch on `worstSeverity`:
+ *      - `null` / `"cosmetic"` → success with empty chain. If an
+ *        exact migration exists for the pair, attach an
+ *        `over_specified` `PlanNote`. The migration is NOT included
+ *        in the chain — at this severity the diff says no
+ *        transformation is needed.
+ *      - `"additive"` → if an exact migration exists, include it
+ *        in the chain. If not, success with empty chain plus an
+ *        `additive_no_migration` note.
+ *      - `"breaking"` → chain is **required**. Run DFS chain
+ *        resolution over the schemaId's `from → to` adjacency map.
+ *        0 chains: `migration_not_found` (no migrations for the
+ *        schemaId at all) or `migration_chain_broken` (some exist
+ *        but can't bridge). 1 chain: success. 2+ chains:
+ *        `migration_ambiguous_chain`.
+ *
+ * **Pure.** No `fs.*`, no `import()`, no `process.*`, no
+ * `console.*`. **Never invokes `migration.transform`** — chain
+ * resolution is structural; transform execution is v0.9+.
+ *
+ * `MigrationPlan.versionPath` always reflects the actual hop
+ * sequence: `[fromVersion, toVersion]` for empty chains;
+ * `[fromVersion, ...intermediateVersions, toVersion]` for non-empty
+ * chains derived from the chain entries.
+ */
+import { findSchema } from "../registry/build-registry.js";
+import { diffNodes } from "../registry/diff.js";
+// =============================================================================
+// Public entry
+// =============================================================================
+export function planMigration(opts) {
+    // 1. Resolve endpoints in the schema registry.
+    const fromEntry = findSchema(opts.schemaRegistry, opts.schemaId, opts.fromVersion);
+    const toEntry = findSchema(opts.schemaRegistry, opts.schemaId, opts.toVersion);
+    if (fromEntry === undefined || toEntry === undefined) {
+        return failure(missingEndpointIssue(opts.schemaId, opts.fromVersion, opts.toVersion, fromEntry === undefined, toEntry === undefined));
+    }
+    // 2. Compute the endpoint-to-endpoint diff and worst severity.
+    const changes = diffNodes(fromEntry.schema.node, toEntry.schema.node);
+    const worstSeverity = computeWorstSeverity(changes);
+    // 3. Look up the exact-pair migration (if any) for the
+    //    over_specified / additive-with-migration branches.
+    const exact = findExactMigration(opts.migrationRegistry, opts.schemaId, opts.fromVersion, opts.toVersion);
+    // 4. Dispatch on severity.
+    if (worstSeverity === null || worstSeverity === "cosmetic") {
+        const notes = exact !== undefined ? [{ kind: "over_specified", migration: exact }] : [];
+        return success({
+            schemaId: opts.schemaId,
+            chain: [],
+            versionPath: [opts.fromVersion, opts.toVersion],
+            worstSeverity,
+            notes,
+        });
+    }
+    if (worstSeverity === "additive") {
+        if (exact !== undefined) {
+            return success({
+                schemaId: opts.schemaId,
+                chain: [exact],
+                versionPath: [opts.fromVersion, opts.toVersion],
+                worstSeverity,
+                notes: [],
+            });
+        }
+        return success({
+            schemaId: opts.schemaId,
+            chain: [],
+            versionPath: [opts.fromVersion, opts.toVersion],
+            worstSeverity,
+            notes: [{ kind: "additive_no_migration", worstSeverity }],
+        });
+    }
+    // worstSeverity === "breaking" — chain is required.
+    const adjacency = opts.migrationRegistry.get(opts.schemaId);
+    const noMigrationsForSchema = adjacency === undefined || adjacency.size === 0;
+    if (noMigrationsForSchema) {
+        return failure(notFoundIssue(opts.schemaId, opts.fromVersion, opts.toVersion));
+    }
+    const chains = enumerateChains(adjacency, opts.fromVersion, opts.toVersion);
+    if (chains.length === 0) {
+        return failure(chainBrokenIssue(opts.schemaId, opts.fromVersion, opts.toVersion));
+    }
+    if (chains.length > 1) {
+        return failure(ambiguousChainIssue(opts.schemaId, opts.fromVersion, opts.toVersion, chains));
+    }
+    const chain = chains[0];
+    return success({
+        schemaId: opts.schemaId,
+        chain,
+        versionPath: versionPathFromChain(opts.fromVersion, chain),
+        worstSeverity,
+        notes: [],
+    });
+}
+// =============================================================================
+// Helpers — registry lookups
+// =============================================================================
+function findExactMigration(registry, schemaId, fromVersion, toVersion) {
+    return registry.get(schemaId)?.get(fromVersion)?.get(toVersion);
+}
+// =============================================================================
+// Helpers — worstSeverity (same precedence as v0.7 diffHandler)
+// =============================================================================
+const SEVERITY_RANK = {
+    cosmetic: 0,
+    additive: 1,
+    breaking: 2,
+};
+function computeWorstSeverity(changes) {
+    if (changes.length === 0)
+        return null;
+    let worst = "cosmetic";
+    for (const c of changes) {
+        if (SEVERITY_RANK[c.severity] > SEVERITY_RANK[worst]) {
+            worst = c.severity;
+        }
+    }
+    return worst;
+}
+/**
+ * Enumerate every simple path of migration entries from `start` to
+ * `end` over the schemaId's adjacency map. "Simple" = no version
+ * is visited twice within a single chain (no cycles).
+ *
+ * v0.8 doesn't cap the number of enumerated chains — but it stops
+ * walking each path at the first revisit of any version it already
+ * entered on that path. The graph is the consumer's authored
+ * migrations, so practical depth is small.
+ */
+function enumerateChains(adjacency, start, end) {
+    if (start === end)
+        return [];
+    const out = [];
+    const visited = new Set([start]);
+    const chain = [];
+    dfs(adjacency, start, end, visited, chain, out);
+    return out;
+}
+function dfs(adjacency, current, end, visited, chain, out) {
+    const outgoing = adjacency.get(current);
+    if (outgoing === undefined)
+        return;
+    for (const [toVer, entry] of outgoing) {
+        if (visited.has(toVer))
+            continue;
+        chain.push(entry);
+        if (toVer === end) {
+            out.push([...chain]);
+        }
+        else {
+            visited.add(toVer);
+            dfs(adjacency, toVer, end, visited, chain, out);
+            visited.delete(toVer);
+        }
+        chain.pop();
+    }
+}
+function versionPathFromChain(fromVersion, chain) {
+    if (chain.length === 0)
+        return [fromVersion, fromVersion];
+    const path = [fromVersion];
+    for (const entry of chain)
+        path.push(entry.toVersion);
+    return path;
+}
+// =============================================================================
+// Result + Issue helpers
+// =============================================================================
+function success(data) {
+    return { success: true, data };
+}
+function failure(issue) {
+    return { success: false, issues: [issue] };
+}
+function missingEndpointIssue(schemaId, fromVersion, toVersion, fromMissing, toMissing) {
+    const missing = [];
+    if (fromMissing)
+        missing.push(`from=${fromVersion}`);
+    if (toMissing)
+        missing.push(`to=${toVersion}`);
+    return {
+        code: "migration_missing_endpoint",
+        path: [],
+        message: `Cannot plan migration for \`${schemaId}\`: ` +
+            `${missing.join(", ")} not in the schema registry.`,
+        severity: "error",
+        metadata: {
+            schemaId,
+            fromVersion,
+            toVersion,
+            missing: missing.map((s) => s.split("=")[0]),
+        },
+    };
+}
+function notFoundIssue(schemaId, fromVersion, toVersion) {
+    return {
+        code: "migration_not_found",
+        path: [],
+        message: `Breaking transition for \`${schemaId}\` requires a migration; ` +
+            `no migrations are registered for this schemaId.`,
+        severity: "error",
+        metadata: { schemaId, fromVersion, toVersion },
+    };
+}
+function chainBrokenIssue(schemaId, fromVersion, toVersion) {
+    return {
+        code: "migration_chain_broken",
+        path: [],
+        message: `Migrations exist for \`${schemaId}\` but no chain bridges ` +
+            `${fromVersion} → ${toVersion}.`,
+        severity: "error",
+        metadata: { schemaId, fromVersion, toVersion },
+    };
+}
+function ambiguousChainIssue(schemaId, fromVersion, toVersion, chains) {
+    return {
+        code: "migration_ambiguous_chain",
+        path: [],
+        message: `Multiple distinct migration chains bridge \`${schemaId}\` ` +
+            `${fromVersion} → ${toVersion}; the planner refuses to pick. ` +
+            `Remove one or constrain the registry.`,
+        severity: "error",
+        metadata: {
+            schemaId,
+            fromVersion,
+            toVersion,
+            chainCount: chains.length,
+            chainSummaries: chains.map((chain) => chain
+                .map((entry) => `${entry.fromVersion}→${entry.toVersion}`)
+                .join(", ")),
+        },
+    };
+}
+//# sourceMappingURL=plan-migration.js.map

package/dist/src/migrations/plan-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-migration.js","sourceRoot":"","sources":["../../../src/migrations/plan-migration.ts"],"names":[],"mappings":"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"}

package/dist/src/migrations/stub.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `stubMigration(opts)` — pure migration-stub generator (v0.8 Step 6).
+ *
+ * Produces a `MigrationStub` payload — a `suggestedPath` and the
+ * full file `content` for a new `*.migration.ts` file. The CLI is
+ * responsible for actually writing the file; this primitive is
+ * pure (no `fs.*`, no `import()`, no `process.*`, no `console.*`).
+ *
+ * The content follows the locked migration shape (Decision #5 +
+ * Decision #6):
+ *
+ *   - JSDoc provenance header on top, generated by this function.
+ *   - `import type { Migration } from "@nekostack/schema/cli";`
+ *     (NOT root — Decision #6 keeps the v0.8 surface package-internal).
+ *   - A `const migration: Migration<schemaId, from, to> = { ... }`
+ *     with a skeleton `transform` that throws "Not yet implemented".
+ *     Authors edit the body; v0.8 never invokes `transform`.
+ *   - `export default migration;` so `buildMigrationRegistry` /
+ *     `verifyMigrationProvenance` can find it via the
+ *     `MigrationSourceEntry.migration` field.
+ *
+ * `suggestedPath` follows the locked path convention
+ * (Decision #5):
+ *
+ *   <schema-dir>/migrations/<basename>.<from-slug>-to-<to-slug>.migration.ts
+ *
+ * with the slug rule reused verbatim from `v0.7 src/registry/handlers/generate.ts`:
+ *   `lowercase → non-alphanumeric runs collapse to "-" → trim`.
+ *
+ * Reusing v0.7's `slugify` shape means one slug rule across the
+ * whole package — and it handles prerelease/build version markers
+ * (`1.0.0-beta.1`, `2.0.0+build.5`) cleanly.
+ *
+ * Failure path: if either operand version is absent from the schema
+ * registry → `Result.failure` with `migration_missing_endpoint`
+ * (same code as Step 4's planner uses for the same condition).
+ */
+import type { MigrationStubOpts, MigrationStubResult } from "./types.js";
+export declare function stubMigration(opts: MigrationStubOpts): MigrationStubResult;
+/**
+ * Translate a schema's `sourcePath` plus a version pair into the
+ * locked migration-file path:
+ *
+ *     <schema-dir>/migrations/<basename>.<from-slug>-to-<to-slug>.migration.ts
+ *
+ * `basename` strips a `.schema.{ts,js,mts,cts}` suffix when present;
+ * falls back to "filename minus last extension" otherwise. Forward
+ * slashes are canonical even on Windows — the CLI normalizes back
+ * to platform separators on write.
+ *
+ * Exported so the CLI's `stub` verb can advertise the same path
+ * without re-deriving the rule.
+ */
+export declare function suggestedMigrationPathFor(sourcePath: string, fromVersion: string, toVersion: string): string;
+//# sourceMappingURL=stub.d.ts.map

package/dist/src/migrations/stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["../../../src/migrations/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,KAAK,EAEV,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,GACtB,mBAAmB,CAuCrB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,MAAM,CAUR"}