@prisma-next/migration-tools 0.5.0-dev.8 → 0.5.0-dev.80
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -22
- package/dist/{constants-BRi0X7B_.mjs → constants-DWV9_o2Z.mjs} +2 -2
- package/dist/{constants-BRi0X7B_.mjs.map → constants-DWV9_o2Z.mjs.map} +1 -1
- package/dist/errors-EPL_9p9f.mjs +297 -0
- package/dist/errors-EPL_9p9f.mjs.map +1 -0
- package/dist/exports/aggregate.d.mts +614 -0
- package/dist/exports/aggregate.d.mts.map +1 -0
- package/dist/exports/aggregate.mjs +611 -0
- package/dist/exports/aggregate.mjs.map +1 -0
- package/dist/exports/constants.d.mts.map +1 -1
- package/dist/exports/constants.mjs +2 -3
- package/dist/exports/errors.d.mts +68 -0
- package/dist/exports/errors.d.mts.map +1 -0
- package/dist/exports/errors.mjs +2 -0
- package/dist/exports/graph.d.mts +2 -0
- package/dist/exports/graph.mjs +1 -0
- package/dist/exports/hash.d.mts +52 -0
- package/dist/exports/hash.d.mts.map +1 -0
- package/dist/exports/hash.mjs +2 -0
- package/dist/exports/invariants.d.mts +34 -0
- package/dist/exports/invariants.d.mts.map +1 -0
- package/dist/exports/invariants.mjs +2 -0
- package/dist/exports/io.d.mts +66 -6
- package/dist/exports/io.d.mts.map +1 -1
- package/dist/exports/io.mjs +2 -3
- package/dist/exports/metadata.d.mts +2 -0
- package/dist/exports/metadata.mjs +1 -0
- package/dist/exports/migration-graph.d.mts +2 -0
- package/dist/exports/migration-graph.mjs +2 -0
- package/dist/exports/migration-ts.d.mts.map +1 -1
- package/dist/exports/migration-ts.mjs +2 -4
- package/dist/exports/migration-ts.mjs.map +1 -1
- package/dist/exports/migration.d.mts +15 -14
- package/dist/exports/migration.d.mts.map +1 -1
- package/dist/exports/migration.mjs +70 -43
- package/dist/exports/migration.mjs.map +1 -1
- package/dist/exports/package.d.mts +3 -0
- package/dist/exports/package.mjs +1 -0
- package/dist/exports/refs.d.mts.map +1 -1
- package/dist/exports/refs.mjs +3 -4
- package/dist/exports/refs.mjs.map +1 -1
- package/dist/exports/spaces.d.mts +550 -0
- package/dist/exports/spaces.d.mts.map +1 -0
- package/dist/exports/spaces.mjs +223 -0
- package/dist/exports/spaces.mjs.map +1 -0
- package/dist/graph-HMWAldoR.d.mts +28 -0
- package/dist/graph-HMWAldoR.d.mts.map +1 -0
- package/dist/hash-By50zM_E.mjs +74 -0
- package/dist/hash-By50zM_E.mjs.map +1 -0
- package/dist/invariants-Duc8f9NM.mjs +52 -0
- package/dist/invariants-Duc8f9NM.mjs.map +1 -0
- package/dist/io-D13dLvUh.mjs +239 -0
- package/dist/io-D13dLvUh.mjs.map +1 -0
- package/dist/metadata-CFvm3ayn.d.mts +2 -0
- package/dist/migration-graph-DGNnKDY5.mjs +523 -0
- package/dist/migration-graph-DGNnKDY5.mjs.map +1 -0
- package/dist/migration-graph-DulOITvG.d.mts +124 -0
- package/dist/migration-graph-DulOITvG.d.mts.map +1 -0
- package/dist/op-schema-D5qkXfEf.mjs +13 -0
- package/dist/op-schema-D5qkXfEf.mjs.map +1 -0
- package/dist/package-BjiZ7KDy.d.mts +21 -0
- package/dist/package-BjiZ7KDy.d.mts.map +1 -0
- package/dist/read-contract-space-contract-C3-1eyaI.mjs +298 -0
- package/dist/read-contract-space-contract-C3-1eyaI.mjs.map +1 -0
- package/package.json +44 -19
- package/src/aggregate/loader.ts +409 -0
- package/src/aggregate/marker-types.ts +16 -0
- package/src/aggregate/planner-types.ts +171 -0
- package/src/aggregate/planner.ts +158 -0
- package/src/aggregate/project-schema-to-space.ts +64 -0
- package/src/aggregate/strategies/graph-walk.ts +118 -0
- package/src/aggregate/strategies/synth.ts +122 -0
- package/src/aggregate/types.ts +89 -0
- package/src/aggregate/verifier.ts +230 -0
- package/src/assert-descriptor-self-consistency.ts +70 -0
- package/src/compute-extension-space-apply-path.ts +152 -0
- package/src/concatenate-space-apply-inputs.ts +90 -0
- package/src/detect-space-contract-drift.ts +91 -0
- package/src/emit-contract-space-artefacts.ts +70 -0
- package/src/errors.ts +251 -17
- package/src/exports/aggregate.ts +42 -0
- package/src/exports/errors.ts +8 -0
- package/src/exports/graph.ts +1 -0
- package/src/exports/hash.ts +2 -0
- package/src/exports/invariants.ts +1 -0
- package/src/exports/io.ts +3 -1
- package/src/exports/metadata.ts +1 -0
- package/src/exports/{dag.ts → migration-graph.ts} +3 -2
- package/src/exports/migration.ts +0 -1
- package/src/exports/package.ts +2 -0
- package/src/exports/spaces.ts +49 -0
- package/src/gather-disk-contract-space-state.ts +62 -0
- package/src/graph-ops.ts +57 -30
- package/src/graph.ts +25 -0
- package/src/hash.ts +91 -0
- package/src/invariants.ts +56 -0
- package/src/io.ts +163 -40
- package/src/metadata.ts +1 -0
- package/src/migration-base.ts +97 -56
- package/src/migration-graph.ts +676 -0
- package/src/op-schema.ts +11 -0
- package/src/package.ts +21 -0
- package/src/plan-all-spaces.ts +76 -0
- package/src/read-contract-space-contract.ts +44 -0
- package/src/read-contract-space-head-ref.ts +63 -0
- package/src/space-layout.ts +48 -0
- package/src/verify-contract-spaces.ts +272 -0
- package/dist/attestation-BnzTb0Qp.mjs +0 -65
- package/dist/attestation-BnzTb0Qp.mjs.map +0 -1
- package/dist/errors-BmiSgz1j.mjs +0 -160
- package/dist/errors-BmiSgz1j.mjs.map +0 -1
- package/dist/exports/attestation.d.mts +0 -37
- package/dist/exports/attestation.d.mts.map +0 -1
- package/dist/exports/attestation.mjs +0 -4
- package/dist/exports/dag.d.mts +0 -51
- package/dist/exports/dag.d.mts.map +0 -1
- package/dist/exports/dag.mjs +0 -386
- package/dist/exports/dag.mjs.map +0 -1
- package/dist/exports/types.d.mts +0 -35
- package/dist/exports/types.d.mts.map +0 -1
- package/dist/exports/types.mjs +0 -3
- package/dist/io-Cd6GLyjK.mjs +0 -153
- package/dist/io-Cd6GLyjK.mjs.map +0 -1
- package/dist/types-DyGXcWWp.d.mts +0 -71
- package/dist/types-DyGXcWWp.d.mts.map +0 -1
- package/src/attestation.ts +0 -81
- package/src/dag.ts +0 -426
- package/src/exports/attestation.ts +0 -2
- package/src/exports/types.ts +0 -10
- package/src/types.ts +0 -66
package/README.md
CHANGED
|
@@ -4,24 +4,32 @@
|
|
|
4
4
|
> and is published only to support its runtime. Its API is unstable and may change
|
|
5
5
|
> without notice. Do not depend on this package directly; install `prisma-next` instead.
|
|
6
6
|
|
|
7
|
-
On-disk migration persistence,
|
|
7
|
+
On-disk migration persistence, hash verification, and history reconstruction for Prisma Next.
|
|
8
8
|
|
|
9
9
|
## Responsibilities
|
|
10
10
|
|
|
11
|
-
- **Types**: Define the
|
|
11
|
+
- **Types**: Define the migration package shape (`MigrationMetadata`, `MigrationOps`, `MigrationPackage`, `MigrationGraph`)
|
|
12
12
|
- **I/O**: Read and write migration packages to/from disk (`migration.json` + `ops.json`)
|
|
13
|
-
- **
|
|
13
|
+
- **Hashing**: Compute and verify content-addressed migration hashes for tamper detection
|
|
14
14
|
- **History reconstruction**: Reconstruct and navigate migration history (path finding, latest migration detection, cycle/orphan detection)
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Hash framing
|
|
17
17
|
|
|
18
|
-
`
|
|
18
|
+
`computeMigrationHash` in `hash.ts` uses explicit framing:
|
|
19
19
|
|
|
20
|
-
1.
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
1. Strip identity-affecting fields (`migrationHash`, `signature`, `fromContract`,
|
|
21
|
+
`toContract`, `hints`) from the metadata envelope, then canonicalize the
|
|
22
|
+
stripped envelope and the ops array.
|
|
23
|
+
2. SHA-256 each canonical part independently.
|
|
24
|
+
3. SHA-256 the canonical JSON tuple `[hash(metadata), hash(ops)]`.
|
|
23
25
|
|
|
24
|
-
This avoids delimiter-ambiguity and
|
|
26
|
+
This avoids delimiter-ambiguity and pins `migrationHash` to a 2-tuple over
|
|
27
|
+
the on-disk storage shape. Per [ADR 199 — Storage-only migration identity],
|
|
28
|
+
contracts are anchored separately via storage-hash bookends inside the
|
|
29
|
+
metadata envelope, and planner hints are advisory and must not affect
|
|
30
|
+
identity.
|
|
31
|
+
|
|
32
|
+
[ADR 199 — Storage-only migration identity]: ../../../docs/architecture%20docs/adrs/ADR%20199%20-%20Storage-only%20migration%20identity.md
|
|
25
33
|
|
|
26
34
|
## Ops validation boundary
|
|
27
35
|
|
|
@@ -36,14 +44,15 @@ Full semantic validation happens in target/family migration planners and runners
|
|
|
36
44
|
|
|
37
45
|
```mermaid
|
|
38
46
|
graph TD
|
|
39
|
-
CLI["CLI commands<br/>(migration plan, apply,
|
|
40
|
-
CLI -->
|
|
41
|
-
CLI --> GRAPH["
|
|
42
|
-
IO -->
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
+
CLI["CLI commands<br/>(migration new, plan, apply, show, status)"] --> IO["io.ts<br/>File I/O"]
|
|
48
|
+
CLI --> HASH["hash.ts<br/>Migration hashing"]
|
|
49
|
+
CLI --> GRAPH["migration-graph.ts<br/>Graph operations"]
|
|
50
|
+
IO --> META["metadata.ts<br/>MigrationMetadata, MigrationHints"]
|
|
51
|
+
IO --> PKG["package.ts<br/>MigrationPackage, MigrationOps"]
|
|
52
|
+
HASH --> IO
|
|
53
|
+
HASH --> CAN["canonicalize-json.ts"]
|
|
54
|
+
HASH --> CP["@prisma-next/emitter<br/>canonicalizeContract"]
|
|
55
|
+
GRAPH --> GR["graph.ts<br/>MigrationGraph, MigrationEdge"]
|
|
47
56
|
GRAPH --> ABS["@prisma-next/migration-tools/constants<br/>EMPTY_CONTRACT_HASH"]
|
|
48
57
|
```
|
|
49
58
|
|
|
@@ -51,7 +60,7 @@ graph TD
|
|
|
51
60
|
|
|
52
61
|
| Package | Why |
|
|
53
62
|
|---|---|
|
|
54
|
-
| `@prisma-next/contract` | `Contract` type for embedded contracts in
|
|
63
|
+
| `@prisma-next/contract` | `Contract` type for embedded contracts in metadata |
|
|
55
64
|
| `@prisma-next/framework-components` | `MigrationPlanOperation` types (via `./control`) |
|
|
56
65
|
| `@prisma-next/emitter` | `canonicalizeContract` |
|
|
57
66
|
| `arktype` | Runtime shape validation for `migration.json` and `ops.json` |
|
|
@@ -66,10 +75,13 @@ graph TD
|
|
|
66
75
|
|
|
67
76
|
| Subpath | Contents |
|
|
68
77
|
|---|---|
|
|
69
|
-
| `./
|
|
78
|
+
| `./metadata` | `MigrationMetadata`, `MigrationHints` |
|
|
79
|
+
| `./package` | `MigrationPackage`, `MigrationOps` |
|
|
80
|
+
| `./graph` | `MigrationGraph`, `MigrationEdge` |
|
|
70
81
|
| `./io` | `writeMigrationPackage`, `readMigrationPackage`, `readMigrationsDir`, `formatMigrationDirName` |
|
|
71
|
-
| `./
|
|
72
|
-
| `./
|
|
82
|
+
| `./hash` | `computeMigrationHash`, `verifyMigrationHash` |
|
|
83
|
+
| `./migration-graph` | `reconstructGraph`, `findLeaf`, `findPath`, `detectCycles`, `detectOrphans` |
|
|
84
|
+
| `./errors` | `MigrationToolsError` |
|
|
73
85
|
| `./constants` | `EMPTY_CONTRACT_HASH` |
|
|
74
86
|
|
|
75
87
|
## On-Disk Format
|
|
@@ -79,7 +91,7 @@ Each migration is a directory containing two files:
|
|
|
79
91
|
```
|
|
80
92
|
migrations/
|
|
81
93
|
20260225T1430_add_users/
|
|
82
|
-
migration.json #
|
|
94
|
+
migration.json # MigrationMetadata
|
|
83
95
|
ops.json # MigrationPlanOperation[]
|
|
84
96
|
```
|
|
85
97
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* This is a human-readable marker, not a real SHA-256 hash.
|
|
5
5
|
*/
|
|
6
6
|
const EMPTY_CONTRACT_HASH = "sha256:empty";
|
|
7
|
-
|
|
8
7
|
//#endregion
|
|
9
8
|
export { EMPTY_CONTRACT_HASH as t };
|
|
10
|
-
|
|
9
|
+
|
|
10
|
+
//# sourceMappingURL=constants-DWV9_o2Z.mjs.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"constants-
|
|
1
|
+
{"version":3,"file":"constants-DWV9_o2Z.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Sentinel value representing the absence of a contract (empty/new project).\n * This is a human-readable marker, not a real SHA-256 hash.\n */\nexport const EMPTY_CONTRACT_HASH = 'sha256:empty' as const;\n"],"mappings":";;;;;AAIA,MAAa,sBAAsB"}
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
import { ifDefined } from "@prisma-next/utils/defined";
|
|
2
|
+
import { basename, dirname, relative } from "pathe";
|
|
3
|
+
//#region src/errors.ts
|
|
4
|
+
/**
|
|
5
|
+
* Build the canonical "re-emit this package" remediation hint.
|
|
6
|
+
*
|
|
7
|
+
* Every on-disk migration package ships its own `migration.ts` author-time
|
|
8
|
+
* file. Running it regenerates `migration.json` and `ops.json` with the
|
|
9
|
+
* correct hash + metadata, so it is the right primitive whenever a single
|
|
10
|
+
* package's on-disk artifacts are missing, malformed, or otherwise corrupt.
|
|
11
|
+
* Pointing users at `migration plan` would emit a *new* package rather than
|
|
12
|
+
* heal the broken one.
|
|
13
|
+
*/
|
|
14
|
+
function reemitHint(dir, fallback) {
|
|
15
|
+
const reemit = `Re-emit the package by running \`node "${relative(process.cwd(), dir)}/migration.ts"\``;
|
|
16
|
+
return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Structured error for migration tooling operations.
|
|
20
|
+
*
|
|
21
|
+
* Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
|
|
22
|
+
* the MIGRATION namespace. These are tooling-time errors (file I/O, hash
|
|
23
|
+
* verification, migration history reconstruction), distinct from the runtime
|
|
24
|
+
* MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,
|
|
25
|
+
* etc.).
|
|
26
|
+
*
|
|
27
|
+
* Fields:
|
|
28
|
+
* - code: Stable machine-readable code (MIGRATION.SUBCODE)
|
|
29
|
+
* - category: Always 'MIGRATION'
|
|
30
|
+
* - why: Explains the cause in plain language
|
|
31
|
+
* - fix: Actionable remediation step
|
|
32
|
+
* - details: Machine-readable structured data for agents
|
|
33
|
+
*/
|
|
34
|
+
var MigrationToolsError = class extends Error {
|
|
35
|
+
code;
|
|
36
|
+
category = "MIGRATION";
|
|
37
|
+
why;
|
|
38
|
+
fix;
|
|
39
|
+
details;
|
|
40
|
+
constructor(code, summary, options) {
|
|
41
|
+
super(summary);
|
|
42
|
+
this.name = "MigrationToolsError";
|
|
43
|
+
this.code = code;
|
|
44
|
+
this.why = options.why;
|
|
45
|
+
this.fix = options.fix;
|
|
46
|
+
this.details = options.details;
|
|
47
|
+
}
|
|
48
|
+
static is(error) {
|
|
49
|
+
if (!(error instanceof Error)) return false;
|
|
50
|
+
const candidate = error;
|
|
51
|
+
return candidate.name === "MigrationToolsError" && typeof candidate.code === "string";
|
|
52
|
+
}
|
|
53
|
+
};
|
|
54
|
+
function errorDirectoryExists(dir) {
|
|
55
|
+
return new MigrationToolsError("MIGRATION.DIR_EXISTS", "Migration directory already exists", {
|
|
56
|
+
why: `The directory "${dir}" already exists. Each migration must have a unique directory.`,
|
|
57
|
+
fix: "Use --name to pick a different name, or delete the existing directory and re-run.",
|
|
58
|
+
details: { dir }
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
function errorMissingFile(file, dir) {
|
|
62
|
+
return new MigrationToolsError("MIGRATION.FILE_MISSING", `Missing ${file}`, {
|
|
63
|
+
why: `Expected "${file}" in "${dir}" but the file does not exist.`,
|
|
64
|
+
fix: reemitHint(dir, "or delete the directory if the migration is unwanted and the source TypeScript is gone."),
|
|
65
|
+
details: {
|
|
66
|
+
file,
|
|
67
|
+
dir
|
|
68
|
+
}
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
function errorInvalidJson(filePath, parseError) {
|
|
72
|
+
return new MigrationToolsError("MIGRATION.INVALID_JSON", "Invalid JSON in migration file", {
|
|
73
|
+
why: `Failed to parse "${filePath}": ${parseError}`,
|
|
74
|
+
fix: reemitHint(dirname(filePath), "or restore the directory from version control."),
|
|
75
|
+
details: {
|
|
76
|
+
filePath,
|
|
77
|
+
parseError
|
|
78
|
+
}
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
function errorInvalidManifest(filePath, reason) {
|
|
82
|
+
return new MigrationToolsError("MIGRATION.INVALID_MANIFEST", "Invalid migration manifest", {
|
|
83
|
+
why: `Migration manifest at "${filePath}" is invalid: ${reason}`,
|
|
84
|
+
fix: reemitHint(dirname(filePath), "or restore the directory from version control."),
|
|
85
|
+
details: {
|
|
86
|
+
filePath,
|
|
87
|
+
reason
|
|
88
|
+
}
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
function errorInvalidOperationEntry(index, reason) {
|
|
92
|
+
return new MigrationToolsError("MIGRATION.INVALID_OPERATION_ENTRY", "Migration operation entry is malformed", {
|
|
93
|
+
why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,
|
|
94
|
+
fix: "Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').",
|
|
95
|
+
details: {
|
|
96
|
+
index,
|
|
97
|
+
reason
|
|
98
|
+
}
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
function errorStaleContractBookends(args) {
|
|
102
|
+
const { side, metaHash, contractHash } = args;
|
|
103
|
+
return new MigrationToolsError("MIGRATION.STALE_CONTRACT_BOOKENDS", "Migration manifest contract bookends disagree with describe()", {
|
|
104
|
+
why: `migration.json stores ${side}Contract.storage.storageHash "${contractHash}", but describe() returned meta.${side} = ${metaHash === null ? "null (baseline)" : `"${metaHash}"`}. The bookend is stale — most likely the migration's describe() was edited after the package was scaffolded by \`migration plan\`.`,
|
|
105
|
+
fix: "Re-run `migration plan` to regenerate the package with fresh contract bookends, or restore the directory from version control.",
|
|
106
|
+
details: {
|
|
107
|
+
side,
|
|
108
|
+
metaHash,
|
|
109
|
+
contractHash
|
|
110
|
+
}
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
function errorInvalidSlug(slug) {
|
|
114
|
+
return new MigrationToolsError("MIGRATION.INVALID_NAME", "Invalid migration name", {
|
|
115
|
+
why: `The slug "${slug}" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,
|
|
116
|
+
fix: "Provide a name with at least one alphanumeric character, e.g. --name add_users.",
|
|
117
|
+
details: { slug }
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
function errorInvalidDestName(destName) {
|
|
121
|
+
return new MigrationToolsError("MIGRATION.INVALID_DEST_NAME", "Invalid copy destination name", {
|
|
122
|
+
why: `The destination name "${destName}" must be a single path segment (no ".." or directory separators).`,
|
|
123
|
+
fix: "Use a simple file name such as \"contract.json\" for each destination in the copy list.",
|
|
124
|
+
details: { destName }
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
function errorInvalidSpaceId(spaceId) {
|
|
128
|
+
return new MigrationToolsError("MIGRATION.INVALID_SPACE_ID", "Invalid contract space identifier", {
|
|
129
|
+
why: `The space id "${spaceId}" does not match the required pattern /^[a-z][a-z0-9_-]{0,63}$/. Space ids are used as filesystem directory names under \`migrations/\`, so the pattern is conservative on purpose.`,
|
|
130
|
+
fix: "Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.",
|
|
131
|
+
details: { spaceId }
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
function errorDescriptorHeadHashMismatch(args) {
|
|
135
|
+
const { extensionId, recomputedHash, headRefHash } = args;
|
|
136
|
+
return new MigrationToolsError("MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH", "Extension descriptor's headRef.hash does not match its contractJson", {
|
|
137
|
+
why: `Extension "${extensionId}" publishes a \`contractSpace\` whose \`headRef.hash\` (${headRefHash}) does not match the canonical hash recomputed from \`contractSpace.contractJson\` (${recomputedHash}). This means the extension descriptor was published with stale \`headRef.hash\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,
|
|
138
|
+
fix: "Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).",
|
|
139
|
+
details: {
|
|
140
|
+
extensionId,
|
|
141
|
+
recomputedHash,
|
|
142
|
+
headRefHash
|
|
143
|
+
}
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
function errorDuplicateSpaceId(spaceId) {
|
|
147
|
+
return new MigrationToolsError("MIGRATION.DUPLICATE_SPACE_ID", "Duplicate contract space identifier", {
|
|
148
|
+
why: `The space id "${spaceId}" appears more than once in the per-space planner input. Each space id must be unique across the inputs (the per-space planner emits one output entry per id).`,
|
|
149
|
+
fix: "Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.",
|
|
150
|
+
details: { spaceId }
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
function errorSameSourceAndTarget(dir, hash) {
|
|
154
|
+
const dirName = basename(dir);
|
|
155
|
+
return new MigrationToolsError("MIGRATION.SAME_SOURCE_AND_TARGET", "Migration without data-transform operations has same source and target", {
|
|
156
|
+
why: `Migration "${dirName}" has from === to === "${hash}" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,
|
|
157
|
+
fix: reemitHint(dir, "and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted."),
|
|
158
|
+
details: {
|
|
159
|
+
dirName,
|
|
160
|
+
hash
|
|
161
|
+
}
|
|
162
|
+
});
|
|
163
|
+
}
|
|
164
|
+
function errorAmbiguousTarget(branchTips, context) {
|
|
165
|
+
const divergenceInfo = context ? `\nDivergence point: ${context.divergencePoint}\nBranches:\n${context.branches.map((b) => ` → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(" → ") || "direct"})`).join("\n")}` : "";
|
|
166
|
+
return new MigrationToolsError("MIGRATION.AMBIGUOUS_TARGET", "Ambiguous migration target", {
|
|
167
|
+
why: `The migration history has diverged into multiple branches: ${branchTips.join(", ")}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,
|
|
168
|
+
fix: "Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.",
|
|
169
|
+
details: {
|
|
170
|
+
branchTips,
|
|
171
|
+
...context ? {
|
|
172
|
+
divergencePoint: context.divergencePoint,
|
|
173
|
+
branches: context.branches
|
|
174
|
+
} : {}
|
|
175
|
+
}
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
function errorNoInitialMigration(nodes) {
|
|
179
|
+
return new MigrationToolsError("MIGRATION.NO_INITIAL_MIGRATION", "No initial migration found", {
|
|
180
|
+
why: `No migration starts from the empty contract state (known hashes: ${nodes.join(", ")}). At least one migration must originate from the empty state.`,
|
|
181
|
+
fix: "Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.",
|
|
182
|
+
details: { nodes }
|
|
183
|
+
});
|
|
184
|
+
}
|
|
185
|
+
function errorInvalidRefFile(filePath, reason) {
|
|
186
|
+
return new MigrationToolsError("MIGRATION.INVALID_REF_FILE", "Invalid ref file", {
|
|
187
|
+
why: `Ref file at "${filePath}" is invalid: ${reason}`,
|
|
188
|
+
fix: "Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.",
|
|
189
|
+
details: {
|
|
190
|
+
path: filePath,
|
|
191
|
+
reason
|
|
192
|
+
}
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
function errorInvalidRefName(refName) {
|
|
196
|
+
return new MigrationToolsError("MIGRATION.INVALID_REF_NAME", "Invalid ref name", {
|
|
197
|
+
why: `Ref name "${refName}" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no "." or ".." segments).`,
|
|
198
|
+
fix: `Use a valid ref name (e.g., "staging", "envs/production").`,
|
|
199
|
+
details: { refName }
|
|
200
|
+
});
|
|
201
|
+
}
|
|
202
|
+
function errorNoTarget(reachableHashes) {
|
|
203
|
+
return new MigrationToolsError("MIGRATION.NO_TARGET", "No migration target could be resolved", {
|
|
204
|
+
why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(", ")}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,
|
|
205
|
+
fix: "Use --from <hash> to specify the planning origin explicitly.",
|
|
206
|
+
details: { reachableHashes }
|
|
207
|
+
});
|
|
208
|
+
}
|
|
209
|
+
function errorInvalidRefValue(value) {
|
|
210
|
+
return new MigrationToolsError("MIGRATION.INVALID_REF_VALUE", "Invalid ref value", {
|
|
211
|
+
why: `Ref value "${value}" is not a valid contract hash. Values must be in the format "sha256:<64 hex chars>" or "sha256:empty".`,
|
|
212
|
+
fix: "Use a valid storage hash from `prisma-next contract emit` output or an existing migration.",
|
|
213
|
+
details: { value }
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
function errorDuplicateMigrationHash(migrationHash) {
|
|
217
|
+
return new MigrationToolsError("MIGRATION.DUPLICATE_MIGRATION_HASH", "Duplicate migrationHash in migration graph", {
|
|
218
|
+
why: `Multiple migrations share migrationHash "${migrationHash}". Each migration must have a unique content-addressed identity.`,
|
|
219
|
+
fix: "Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.",
|
|
220
|
+
details: { migrationHash }
|
|
221
|
+
});
|
|
222
|
+
}
|
|
223
|
+
function errorInvalidInvariantId(invariantId) {
|
|
224
|
+
return new MigrationToolsError("MIGRATION.INVALID_INVARIANT_ID", "Invalid invariantId", {
|
|
225
|
+
why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,
|
|
226
|
+
fix: "Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".",
|
|
227
|
+
details: { invariantId }
|
|
228
|
+
});
|
|
229
|
+
}
|
|
230
|
+
function errorDuplicateInvariantInEdge(invariantId) {
|
|
231
|
+
return new MigrationToolsError("MIGRATION.DUPLICATE_INVARIANT_IN_EDGE", "Duplicate invariantId on a single migration", {
|
|
232
|
+
why: `invariantId "${invariantId}" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,
|
|
233
|
+
fix: "Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.",
|
|
234
|
+
details: { invariantId }
|
|
235
|
+
});
|
|
236
|
+
}
|
|
237
|
+
function errorProvidedInvariantsMismatch(filePath, stored, derived) {
|
|
238
|
+
const storedSet = new Set(stored);
|
|
239
|
+
const derivedSet = new Set(derived);
|
|
240
|
+
const missing = [...derivedSet].filter((id) => !storedSet.has(id));
|
|
241
|
+
const extra = [...storedSet].filter((id) => !derivedSet.has(id));
|
|
242
|
+
return new MigrationToolsError("MIGRATION.PROVIDED_INVARIANTS_MISMATCH", "providedInvariants on migration.json disagrees with ops.json", {
|
|
243
|
+
why: missing.length === 0 && extra.length === 0 ? `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.` : `migration.json at "${filePath}" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`,
|
|
244
|
+
fix: reemitHint(dirname(filePath), "or restore the directory from version control."),
|
|
245
|
+
details: {
|
|
246
|
+
filePath,
|
|
247
|
+
stored,
|
|
248
|
+
derived,
|
|
249
|
+
difference: {
|
|
250
|
+
missing,
|
|
251
|
+
extra
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
});
|
|
255
|
+
}
|
|
256
|
+
function errorNoInvariantPath(args) {
|
|
257
|
+
const { refName, required, missing, structuralPath } = args;
|
|
258
|
+
const refClause = refName ? `Ref "${refName}"` : "Target";
|
|
259
|
+
const missingList = missing.map((id) => JSON.stringify(id)).join(", ");
|
|
260
|
+
return new MigrationToolsError("MIGRATION.NO_INVARIANT_PATH", "No path covers the required invariants", {
|
|
261
|
+
why: `${refClause} requires invariants the reachable path doesn't cover. required=[${required.map((id) => JSON.stringify(id)).join(", ")}], missing=[${missingList}].`,
|
|
262
|
+
fix: "Add a migration on the path that runs `dataTransform({ invariantId: \"<id>\", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.",
|
|
263
|
+
details: {
|
|
264
|
+
required,
|
|
265
|
+
missing,
|
|
266
|
+
structuralPath,
|
|
267
|
+
...ifDefined("refName", refName)
|
|
268
|
+
}
|
|
269
|
+
});
|
|
270
|
+
}
|
|
271
|
+
function errorUnknownInvariant(args) {
|
|
272
|
+
const { refName, unknown, declared } = args;
|
|
273
|
+
return new MigrationToolsError("MIGRATION.UNKNOWN_INVARIANT", "Ref declares invariants no migration in the graph provides", {
|
|
274
|
+
why: `${refName ? `Ref "${refName}" declares` : "Declares"} invariants no migration in the graph provides. unknown=[${unknown.map((id) => JSON.stringify(id)).join(", ")}].`,
|
|
275
|
+
fix: "Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.",
|
|
276
|
+
details: {
|
|
277
|
+
unknown,
|
|
278
|
+
declared,
|
|
279
|
+
...ifDefined("refName", refName)
|
|
280
|
+
}
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
function errorMigrationHashMismatch(dir, storedHash, computedHash) {
|
|
284
|
+
return new MigrationToolsError("MIGRATION.HASH_MISMATCH", "Migration package is corrupt", {
|
|
285
|
+
why: `Stored migrationHash "${storedHash}" does not match the recomputed hash "${computedHash}" for "${relative(process.cwd(), dir)}". The migration.json or ops.json has been edited or partially written since emit.`,
|
|
286
|
+
fix: reemitHint(dir, "or restore the directory from version control."),
|
|
287
|
+
details: {
|
|
288
|
+
dir,
|
|
289
|
+
storedHash,
|
|
290
|
+
computedHash
|
|
291
|
+
}
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
//#endregion
|
|
295
|
+
export { errorProvidedInvariantsMismatch as C, errorUnknownInvariant as E, errorNoTarget as S, errorStaleContractBookends as T, errorInvalidSpaceId as _, errorDuplicateInvariantInEdge as a, errorNoInitialMigration as b, errorInvalidDestName as c, errorInvalidManifest as d, errorInvalidOperationEntry as f, errorInvalidSlug as g, errorInvalidRefValue as h, errorDirectoryExists as i, errorInvalidInvariantId as l, errorInvalidRefName as m, errorAmbiguousTarget as n, errorDuplicateMigrationHash as o, errorInvalidRefFile as p, errorDescriptorHeadHashMismatch as r, errorDuplicateSpaceId as s, MigrationToolsError as t, errorInvalidJson as u, errorMigrationHashMismatch as v, errorSameSourceAndTarget as w, errorNoInvariantPath as x, errorMissingFile as y };
|
|
296
|
+
|
|
297
|
+
//# sourceMappingURL=errors-EPL_9p9f.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors-EPL_9p9f.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { ifDefined } from '@prisma-next/utils/defined';\nimport { basename, dirname, relative } from 'pathe';\n\n/**\n * Build the canonical \"re-emit this package\" remediation hint.\n *\n * Every on-disk migration package ships its own `migration.ts` author-time\n * file. Running it regenerates `migration.json` and `ops.json` with the\n * correct hash + metadata, so it is the right primitive whenever a single\n * package's on-disk artifacts are missing, malformed, or otherwise corrupt.\n * Pointing users at `migration plan` would emit a *new* package rather than\n * heal the broken one.\n */\nfunction reemitHint(dir: string, fallback?: string): string {\n const relativeDir = relative(process.cwd(), dir);\n const reemit = `Re-emit the package by running \\`node \"${relativeDir}/migration.ts\"\\``;\n return fallback ? `${reemit}, ${fallback}` : `${reemit}.`;\n}\n\n/**\n * Structured error for migration tooling operations.\n *\n * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under\n * the MIGRATION namespace. These are tooling-time errors (file I/O, hash\n * verification, migration history reconstruction), distinct from the runtime\n * MIGRATION.* codes for apply-time failures (PRECHECK_FAILED, POSTCHECK_FAILED,\n * etc.).\n *\n * Fields:\n * - code: Stable machine-readable code (MIGRATION.SUBCODE)\n * - category: Always 'MIGRATION'\n * - why: Explains the cause in plain language\n * - fix: Actionable remediation step\n * - details: Machine-readable structured data for agents\n */\nexport class MigrationToolsError extends Error {\n readonly code: string;\n readonly category = 'MIGRATION' as const;\n readonly why: string;\n readonly fix: string;\n readonly details: Record<string, unknown> | undefined;\n\n constructor(\n code: string,\n summary: string,\n options: {\n readonly why: string;\n readonly fix: string;\n readonly details?: Record<string, unknown>;\n },\n ) {\n super(summary);\n this.name = 'MigrationToolsError';\n this.code = code;\n this.why = options.why;\n this.fix = options.fix;\n this.details = options.details;\n }\n\n static is(error: unknown): error is MigrationToolsError {\n if (!(error instanceof Error)) return false;\n const candidate = error as MigrationToolsError;\n return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';\n }\n}\n\nexport function errorDirectoryExists(dir: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {\n why: `The directory \"${dir}\" already exists. Each migration must have a unique directory.`,\n fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',\n details: { dir },\n });\n}\n\nexport function errorMissingFile(file: string, dir: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {\n why: `Expected \"${file}\" in \"${dir}\" but the file does not exist.`,\n fix: reemitHint(\n dir,\n 'or delete the directory if the migration is unwanted and the source TypeScript is gone.',\n ),\n details: { file, dir },\n });\n}\n\nexport function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {\n why: `Failed to parse \"${filePath}\": ${parseError}`,\n fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n details: { filePath, parseError },\n });\n}\n\nexport function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {\n why: `Migration manifest at \"${filePath}\" is invalid: ${reason}`,\n fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n details: { filePath, reason },\n });\n}\n\nexport function errorInvalidOperationEntry(index: number, reason: string): MigrationToolsError {\n return new MigrationToolsError(\n 'MIGRATION.INVALID_OPERATION_ENTRY',\n 'Migration operation entry is malformed',\n {\n why: `Operation at index ${index} returned by the migration class failed schema validation: ${reason}.`,\n fix: \"Update the migration class so each entry of `operations` carries `id` (string), `label` (string), and `operationClass` (one of 'additive' | 'widening' | 'destructive' | 'data').\",\n details: { index, reason },\n },\n );\n}\n\nexport function errorStaleContractBookends(args: {\n readonly side: 'from' | 'to';\n readonly metaHash: string | null;\n readonly contractHash: string;\n}): MigrationToolsError {\n const { side, metaHash, contractHash } = args;\n // `meta.from` is `string | null` (null = baseline). Render `null` as a\n // human-readable token in the diagnostic so the message stays clear when\n // the mismatch is a baseline-vs-non-baseline disagreement.\n const renderedMetaHash = metaHash === null ? 'null (baseline)' : `\"${metaHash}\"`;\n return new MigrationToolsError(\n 'MIGRATION.STALE_CONTRACT_BOOKENDS',\n 'Migration manifest contract bookends disagree with describe()',\n {\n why: `migration.json stores ${side}Contract.storage.storageHash \"${contractHash}\", but describe() returned meta.${side} = ${renderedMetaHash}. The bookend is stale — most likely the migration's describe() was edited after the package was scaffolded by \\`migration plan\\`.`,\n fix: 'Re-run `migration plan` to regenerate the package with fresh contract bookends, or restore the directory from version control.',\n details: { side, metaHash, contractHash },\n },\n );\n}\n\nexport function errorInvalidSlug(slug: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {\n why: `The slug \"${slug}\" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,\n fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',\n details: { slug },\n });\n}\n\nexport function errorInvalidDestName(destName: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {\n why: `The destination name \"${destName}\" must be a single path segment (no \"..\" or directory separators).`,\n fix: 'Use a simple file name such as \"contract.json\" for each destination in the copy list.',\n details: { destName },\n });\n}\n\nexport function errorInvalidSpaceId(spaceId: string): MigrationToolsError {\n return new MigrationToolsError(\n 'MIGRATION.INVALID_SPACE_ID',\n 'Invalid contract space identifier',\n {\n why: `The space id \"${spaceId}\" does not match the required pattern /^[a-z][a-z0-9_-]{0,63}$/. Space ids are used as filesystem directory names under \\`migrations/\\`, so the pattern is conservative on purpose.`,\n fix: 'Pick a lowercase identifier that begins with a letter and contains only lowercase letters, digits, hyphens, or underscores; max 64 characters total.',\n details: { spaceId },\n },\n );\n}\n\nexport function errorDescriptorHeadHashMismatch(args: {\n readonly extensionId: string;\n readonly recomputedHash: string;\n readonly headRefHash: string;\n}): MigrationToolsError {\n const { extensionId, recomputedHash, headRefHash } = args;\n return new MigrationToolsError(\n 'MIGRATION.DESCRIPTOR_HEAD_HASH_MISMATCH',\n \"Extension descriptor's headRef.hash does not match its contractJson\",\n {\n why: `Extension \"${extensionId}\" publishes a \\`contractSpace\\` whose \\`headRef.hash\\` (${headRefHash}) does not match the canonical hash recomputed from \\`contractSpace.contractJson\\` (${recomputedHash}). This means the extension descriptor was published with stale \\`headRef.hash\\` — typically because the contract was bumped without rerunning the extension's emit pipeline.`,\n fix: 'Re-run the extension authoring pipeline so `contractJson.storage.storageHash` and `headRef.hash` agree, then republish the extension. If you are the extension author and you intentionally bumped `contractJson`, recompute and update `headRef.hash` (and refresh any on-disk migration metadata that derives from it).',\n details: { extensionId, recomputedHash, headRefHash },\n },\n );\n}\n\nexport function errorDuplicateSpaceId(spaceId: string): MigrationToolsError {\n return new MigrationToolsError(\n 'MIGRATION.DUPLICATE_SPACE_ID',\n 'Duplicate contract space identifier',\n {\n why: `The space id \"${spaceId}\" appears more than once in the per-space planner input. Each space id must be unique across the inputs (the per-space planner emits one output entry per id).`,\n fix: 'Deduplicate the inputs before passing them to `planAllSpaces` — typically by checking your `extensionPacks` declaration for repeated entries.',\n details: { spaceId },\n },\n );\n}\n\nexport function errorSameSourceAndTarget(dir: string, hash: string): MigrationToolsError {\n const dirName = basename(dir);\n return new MigrationToolsError(\n 'MIGRATION.SAME_SOURCE_AND_TARGET',\n 'Migration without data-transform operations has same source and target',\n {\n why: `Migration \"${dirName}\" has from === to === \"${hash}\" and declares no data-transform operations. Self-edges are only allowed when the migration runs at least one dataTransform — otherwise the migration is a no-op.`,\n fix: reemitHint(\n dir,\n 'and either change the contract so from ≠ to, add a dataTransform op, or delete the directory if the migration is unwanted.',\n ),\n details: { dirName, hash },\n },\n );\n}\n\nexport function errorAmbiguousTarget(\n branchTips: readonly string[],\n context?: {\n divergencePoint: string;\n branches: readonly {\n tip: string;\n edges: readonly { dirName: string; from: string; to: string }[];\n }[];\n },\n): MigrationToolsError {\n const divergenceInfo = context\n ? `\\nDivergence point: ${context.divergencePoint}\\nBranches:\\n${context.branches.map((b) => ` → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\\n')}`\n : '';\n return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {\n why: `The migration history has diverged into multiple branches: ${branchTips.join(', ')}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,\n fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',\n details: {\n branchTips,\n ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),\n },\n });\n}\n\nexport function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {\n why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,\n fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',\n details: { nodes },\n });\n}\n\nexport function errorInvalidRefs(refsPath: string, reason: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_REFS', 'Invalid refs.json', {\n why: `refs.json at \"${refsPath}\" is invalid: ${reason}`,\n fix: 'Ensure refs.json is a flat object mapping valid ref names to contract hash strings.',\n details: { path: refsPath, reason },\n });\n}\n\nexport function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {\n why: `Ref file at \"${filePath}\" is invalid: ${reason}`,\n fix: 'Ensure the ref file contains valid JSON with { \"hash\": \"sha256:<64 hex chars>\", \"invariants\": [\"...\"] }.',\n details: { path: filePath, reason },\n });\n}\n\nexport function errorInvalidRefName(refName: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {\n why: `Ref name \"${refName}\" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no \".\" or \"..\" segments).`,\n fix: `Use a valid ref name (e.g., \"staging\", \"envs/production\").`,\n details: { refName },\n });\n}\n\nexport function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {\n why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,\n fix: 'Use --from <hash> to specify the planning origin explicitly.',\n details: { reachableHashes },\n });\n}\n\nexport function errorInvalidRefValue(value: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_REF_VALUE', 'Invalid ref value', {\n why: `Ref value \"${value}\" is not a valid contract hash. Values must be in the format \"sha256:<64 hex chars>\" or \"sha256:empty\".`,\n fix: 'Use a valid storage hash from `prisma-next contract emit` output or an existing migration.',\n details: { value },\n });\n}\n\nexport function errorDuplicateMigrationHash(migrationHash: string): MigrationToolsError {\n return new MigrationToolsError(\n 'MIGRATION.DUPLICATE_MIGRATION_HASH',\n 'Duplicate migrationHash in migration graph',\n {\n why: `Multiple migrations share migrationHash \"${migrationHash}\". Each migration must have a unique content-addressed identity.`,\n fix: 'Regenerate one of the conflicting migrations so each migrationHash is unique, then re-run migration commands.',\n details: { migrationHash },\n },\n );\n}\n\nexport function errorInvalidInvariantId(invariantId: string): MigrationToolsError {\n return new MigrationToolsError('MIGRATION.INVALID_INVARIANT_ID', 'Invalid invariantId', {\n why: `invariantId ${JSON.stringify(invariantId)} is invalid. Ids must be non-empty and contain no whitespace or control characters (including Unicode whitespace like NBSP); other content (kebab-case, camelCase, namespaced, Unicode letters) is allowed.`,\n fix: 'Pick an invariantId without spaces, tabs, newlines, or control characters — e.g. \"backfill-user-phone\", \"users/backfill-phone\", or \"BackfillUserPhone\".',\n details: { invariantId },\n });\n}\n\nexport function errorDuplicateInvariantInEdge(invariantId: string): MigrationToolsError {\n return new MigrationToolsError(\n 'MIGRATION.DUPLICATE_INVARIANT_IN_EDGE',\n 'Duplicate invariantId on a single migration',\n {\n why: `invariantId \"${invariantId}\" is declared by more than one dataTransform on the same migration. The marker stores invariants as a set and the routing layer treats them as edge-level, so two ops cannot share a routing identity.`,\n fix: 'Rename one of the conflicting dataTransform invariantIds, or drop invariantId on the op that does not need to be routing-visible.',\n details: { invariantId },\n },\n );\n}\n\nexport function errorProvidedInvariantsMismatch(\n filePath: string,\n stored: readonly string[],\n derived: readonly string[],\n): MigrationToolsError {\n const storedSet = new Set(stored);\n const derivedSet = new Set(derived);\n const missing = [...derivedSet].filter((id) => !storedSet.has(id));\n const extra = [...storedSet].filter((id) => !derivedSet.has(id));\n // When sets agree but arrays don't, the only difference is ordering — call\n // it out so the reader doesn't stare at two visually-identical arrays.\n // Canonical providedInvariants is sorted ascending; a manifest with the\n // same ids in a different order is still a mismatch (the hash check would\n // also fail), but the human-readable diagnostic is otherwise unhelpful.\n const orderingOnly = missing.length === 0 && extra.length === 0;\n const why = orderingOnly\n ? `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the canonical value derived from ops.json is ${JSON.stringify(derived)} — same ids, different order. Canonical providedInvariants is sorted ascending.`\n : `migration.json at \"${filePath}\" stores providedInvariants ${JSON.stringify(stored)}, but the value derived from ops.json is ${JSON.stringify(derived)}. The manifest copy was likely hand-edited without re-emitting.`;\n return new MigrationToolsError(\n 'MIGRATION.PROVIDED_INVARIANTS_MISMATCH',\n 'providedInvariants on migration.json disagrees with ops.json',\n {\n why,\n fix: reemitHint(dirname(filePath), 'or restore the directory from version control.'),\n details: { filePath, stored, derived, difference: { missing, extra } },\n },\n );\n}\n\n/**\n * Wire-shape edge surfaced through the JSON envelope's\n * `meta.structuralPath` of `MIGRATION.NO_INVARIANT_PATH`. Slim by design —\n * authoring metadata (`createdAt`, `labels`) lives on `MigrationEdge` but\n * is intentionally dropped here so the envelope stays stable across\n * graph-internal refactors.\n *\n * Stability: any field added here is part of the public CLI JSON contract.\n * Callers (CLI consumers, agents) must be able to treat\n * `(dirName, migrationHash, from, to, invariants)` as the canonical shape.\n */\nexport interface NoInvariantPathStructuralEdge {\n readonly dirName: string;\n readonly migrationHash: string;\n readonly from: string;\n readonly to: string;\n readonly invariants: readonly string[];\n}\n\nexport function errorNoInvariantPath(args: {\n readonly refName?: string;\n readonly required: readonly string[];\n readonly missing: readonly string[];\n readonly structuralPath: readonly NoInvariantPathStructuralEdge[];\n}): MigrationToolsError {\n const { refName, required, missing, structuralPath } = args;\n const refClause = refName ? `Ref \"${refName}\"` : 'Target';\n const missingList = missing.map((id) => JSON.stringify(id)).join(', ');\n const requiredList = required.map((id) => JSON.stringify(id)).join(', ');\n return new MigrationToolsError(\n 'MIGRATION.NO_INVARIANT_PATH',\n 'No path covers the required invariants',\n {\n why: `${refClause} requires invariants the reachable path doesn't cover. required=[${requiredList}], missing=[${missingList}].`,\n fix: 'Add a migration on the path that runs `dataTransform({ invariantId: \"<id>\", … })` for each missing invariant, or retarget the ref to a hash whose path already provides them.',\n details: {\n required,\n missing,\n structuralPath,\n ...ifDefined('refName', refName),\n },\n },\n );\n}\n\nexport function errorUnknownInvariant(args: {\n readonly refName?: string;\n readonly unknown: readonly string[];\n readonly declared: readonly string[];\n}): MigrationToolsError {\n const { refName, unknown, declared } = args;\n const refClause = refName ? `Ref \"${refName}\" declares` : 'Declares';\n const unknownList = unknown.map((id) => JSON.stringify(id)).join(', ');\n return new MigrationToolsError(\n 'MIGRATION.UNKNOWN_INVARIANT',\n 'Ref declares invariants no migration in the graph provides',\n {\n why: `${refClause} invariants no migration in the graph provides. unknown=[${unknownList}].`,\n fix: 'Either the ref has a typo, or the declaring migration has not been authored/attested yet. Re-check the ref file and the migrations directory.',\n details: {\n unknown,\n declared,\n ...ifDefined('refName', refName),\n },\n },\n );\n}\n\nexport function errorMigrationHashMismatch(\n dir: string,\n storedHash: string,\n computedHash: string,\n): MigrationToolsError {\n // Render a cwd-relative path in the human-readable diagnostic so users\n // running CLI commands from the project root see a familiar short path.\n // Keep the absolute path in `details.dir` for machine consumers.\n const relativeDir = relative(process.cwd(), dir);\n return new MigrationToolsError('MIGRATION.HASH_MISMATCH', 'Migration package is corrupt', {\n why: `Stored migrationHash \"${storedHash}\" does not match the recomputed hash \"${computedHash}\" for \"${relativeDir}\". The migration.json or ops.json has been edited or partially written since emit.`,\n fix: reemitHint(dir, 'or restore the directory from version control.'),\n details: { dir, storedHash, computedHash },\n });\n}\n"],"mappings":"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"}
|