@niscorp/strata 0.1.0
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/DESIGN.md +208 -0
- package/LICENSE +202 -0
- package/README.md +195 -0
- package/dist/check/index.cjs +223 -0
- package/dist/check/index.cjs.map +1 -0
- package/dist/check/index.d.cts +63 -0
- package/dist/check/index.d.ts +63 -0
- package/dist/check/index.js +4 -0
- package/dist/check/index.js.map +1 -0
- package/dist/chunk-EGFF63GA.js +16 -0
- package/dist/chunk-EGFF63GA.js.map +1 -0
- package/dist/chunk-HMT7HHFJ.js +156 -0
- package/dist/chunk-HMT7HHFJ.js.map +1 -0
- package/dist/chunk-ICWKTTKN.js +129 -0
- package/dist/chunk-ICWKTTKN.js.map +1 -0
- package/dist/chunk-MY3TGSV3.js +206 -0
- package/dist/chunk-MY3TGSV3.js.map +1 -0
- package/dist/chunk-U5CPF4LQ.js +175 -0
- package/dist/chunk-U5CPF4LQ.js.map +1 -0
- package/dist/documents-BjlM94Ea.d.cts +90 -0
- package/dist/documents-BjlM94Ea.d.ts +90 -0
- package/dist/index.cjs +370 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +16 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +42 -0
- package/dist/index.js.map +1 -0
- package/dist/node/index.cjs +629 -0
- package/dist/node/index.cjs.map +1 -0
- package/dist/node/index.d.cts +19 -0
- package/dist/node/index.d.ts +19 -0
- package/dist/node/index.js +164 -0
- package/dist/node/index.js.map +1 -0
- package/dist/plan-BAewc8DG.d.ts +53 -0
- package/dist/plan-BEIlXVUt.d.cts +53 -0
- package/dist/postgres/index.cjs +333 -0
- package/dist/postgres/index.cjs.map +1 -0
- package/dist/postgres/index.d.cts +44 -0
- package/dist/postgres/index.d.ts +44 -0
- package/dist/postgres/index.js +145 -0
- package/dist/postgres/index.js.map +1 -0
- package/dist/upgrade/index.cjs +236 -0
- package/dist/upgrade/index.cjs.map +1 -0
- package/dist/upgrade/index.d.cts +54 -0
- package/dist/upgrade/index.d.ts +54 -0
- package/dist/upgrade/index.js +5 -0
- package/dist/upgrade/index.js.map +1 -0
- package/package.json +94 -0
|
@@ -0,0 +1,629 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
var fs = require('fs');
|
|
4
|
+
var path = require('path');
|
|
5
|
+
var zod = require('zod');
|
|
6
|
+
|
|
7
|
+
// src/node/index.ts
|
|
8
|
+
var SEQUENCE_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
|
|
9
|
+
var MIGRATION_REF = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+\/[1-9][0-9]*$/;
|
|
10
|
+
var KIND_NAME = /^[a-z][a-z0-9-]*$/;
|
|
11
|
+
var KIND_REF = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+\/[a-z][a-z0-9-]*$/;
|
|
12
|
+
var EMBED_PATH = /^([A-Za-z_$][\w$]*|\*)(\[\])?(\.([A-Za-z_$][\w$]*|\*)(\[\])?)*$/;
|
|
13
|
+
var SqlStepSchema = zod.z.object({
|
|
14
|
+
kind: zod.z.literal("sql"),
|
|
15
|
+
sql: zod.z.string().min(1).describe(
|
|
16
|
+
"ONE SQL statement. A driver that prepares statements (PGlite, pg with parameters) refuses a string carrying several \u2014 split them into steps rather than joining them with semicolons."
|
|
17
|
+
)
|
|
18
|
+
}).strict().describe("A statement run against the database, inside the migration transaction.");
|
|
19
|
+
var DocumentStepSchema = zod.z.object({
|
|
20
|
+
kind: zod.z.literal("document"),
|
|
21
|
+
at: zod.z.string().regex(KIND_REF).describe('The kind of document this step rewrites, e.g. "nisc.nova/layout" \u2014 wherever one sits, at any depth.'),
|
|
22
|
+
transform: zod.z.unknown().describe(
|
|
23
|
+
"A transform config (Prism) run by the injected evaluator over { document, path }: `document` is ONE document of the `at` kind, `path` where it sits. It returns that document rewritten. Nested documents are found by the grammar's embeddings and rewritten on their own, deepest first \u2014 a transform only ever sees one flat node."
|
|
24
|
+
)
|
|
25
|
+
}).strict().describe("A rewrite of stored JSON documents of one kind.");
|
|
26
|
+
var StepSchema = zod.z.discriminatedUnion("kind", [SqlStepSchema, DocumentStepSchema]);
|
|
27
|
+
var DocumentKindSchema = zod.z.object({
|
|
28
|
+
embeds: zod.z.record(zod.z.string().regex(EMBED_PATH), zod.z.string().regex(KIND_REF)).optional().describe("Where other documents sit inside this one: path \u2192 the kind found there (possibly this kind itself).")
|
|
29
|
+
}).strict();
|
|
30
|
+
var MigrationSchema = zod.z.object({
|
|
31
|
+
description: zod.z.string().min(1).describe("One sentence: what this migration does. It is the changelog line and the ledger's description."),
|
|
32
|
+
steps: zod.z.array(StepSchema).describe(
|
|
33
|
+
"Applied in order, in the same transaction as every other pending migration. Empty is a MARKER: the version moves and nothing runs \u2014 how an addition to a strict grammar tells older readers to refuse."
|
|
34
|
+
),
|
|
35
|
+
dependsOn: zod.z.array(zod.z.string().regex(MIGRATION_REF)).optional().describe('Migrations of OTHER sequences that must be applied first, each as "<sequence>/<n>".')
|
|
36
|
+
}).strict();
|
|
37
|
+
var SequenceSchema = zod.z.object({
|
|
38
|
+
id: zod.z.string().regex(SEQUENCE_ID).describe('Namespaced and lowercase, e.g. "nisc.vex.cache" or "midas.app".'),
|
|
39
|
+
documents: zod.z.record(zod.z.string().regex(KIND_NAME), DocumentKindSchema).optional().describe('The document kinds this sequence owns (a GRAMMAR sequence), each named "<id>/<kind>" elsewhere.'),
|
|
40
|
+
migrations: zod.z.array(MigrationSchema).describe("Append-only. A migration is numbered by its position (from 1); the sequence's version is its length.")
|
|
41
|
+
}).strict().superRefine((sequence, ctx) => {
|
|
42
|
+
const kinds = new Set(sequence.migrations.flatMap((m) => m.steps.map((s) => s.kind)));
|
|
43
|
+
if (kinds.has("sql") && (kinds.has("document") || sequence.documents !== void 0)) {
|
|
44
|
+
ctx.addIssue({
|
|
45
|
+
code: "custom",
|
|
46
|
+
message: "A sequence either owns tables (sql steps) or documents (document steps and `documents`), not both."
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
// src/checksum.ts
|
|
52
|
+
var canonical = (value) => {
|
|
53
|
+
if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
|
|
54
|
+
if (value !== null && typeof value === "object") {
|
|
55
|
+
const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
|
|
56
|
+
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
|
|
57
|
+
}
|
|
58
|
+
return JSON.stringify(value);
|
|
59
|
+
};
|
|
60
|
+
var effectOf = (sql) => sql.split("\n").filter((line) => !line.trimStart().startsWith("--")).map((line) => line.trimEnd()).join("\n").trim();
|
|
61
|
+
var checksumOf = async (migration) => {
|
|
62
|
+
const steps = migration.steps.map((step) => step.kind === "sql" ? { ...step, sql: effectOf(step.sql) } : step);
|
|
63
|
+
const bytes = new TextEncoder().encode(canonical(steps));
|
|
64
|
+
const digest = await crypto.subtle.digest("SHA-256", bytes);
|
|
65
|
+
return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
// src/errors.ts
|
|
69
|
+
var StrataError = class extends Error {
|
|
70
|
+
code;
|
|
71
|
+
details;
|
|
72
|
+
constructor(code, message, details = [], options) {
|
|
73
|
+
super(details.length > 0 ? `${message}
|
|
74
|
+
${details.map((d) => ` ${d}`).join("\n")}` : message, options);
|
|
75
|
+
this.name = "StrataError";
|
|
76
|
+
this.code = code;
|
|
77
|
+
this.details = details;
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
// src/plan.ts
|
|
82
|
+
var refOf = (sequence, n) => `${sequence}/${n}`;
|
|
83
|
+
var prepare = async (sequences) => {
|
|
84
|
+
const seen = /* @__PURE__ */ new Set();
|
|
85
|
+
const prepared = [];
|
|
86
|
+
for (const input of sequences) {
|
|
87
|
+
const parsed = SequenceSchema.safeParse(input);
|
|
88
|
+
if (!parsed.success) {
|
|
89
|
+
const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`);
|
|
90
|
+
throw new StrataError("INVALID_SEQUENCE", `A sequence does not parse${typeof input.id === "string" ? ` ("${input.id}")` : ""}.`, issues);
|
|
91
|
+
}
|
|
92
|
+
const sequence = parsed.data;
|
|
93
|
+
if (seen.has(sequence.id)) {
|
|
94
|
+
throw new StrataError("INVALID_SEQUENCE", `Two sequences are both called "${sequence.id}" \u2014 a sequence id names one owner.`);
|
|
95
|
+
}
|
|
96
|
+
seen.add(sequence.id);
|
|
97
|
+
const migrations = [];
|
|
98
|
+
for (const [index, migration] of sequence.migrations.entries()) {
|
|
99
|
+
const n = index + 1;
|
|
100
|
+
migrations.push({
|
|
101
|
+
sequence: sequence.id,
|
|
102
|
+
n,
|
|
103
|
+
ref: refOf(sequence.id, n),
|
|
104
|
+
description: migration.description,
|
|
105
|
+
checksum: await checksumOf(migration),
|
|
106
|
+
steps: migration.steps,
|
|
107
|
+
dependsOn: migration.dependsOn ?? []
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
const grammar = sequence.documents !== void 0 || sequence.migrations.some((m) => m.steps.some((s) => s.kind === "document"));
|
|
111
|
+
prepared.push({ id: sequence.id, grammar, documents: sequence.documents ?? {}, migrations });
|
|
112
|
+
}
|
|
113
|
+
return prepared;
|
|
114
|
+
};
|
|
115
|
+
var orderPending = (queues, alreadyDone) => {
|
|
116
|
+
const done = new Set(alreadyDone);
|
|
117
|
+
const waiting = queues.map((q) => [...q.waiting]);
|
|
118
|
+
const pending = [];
|
|
119
|
+
let moved = true;
|
|
120
|
+
while (moved) {
|
|
121
|
+
moved = false;
|
|
122
|
+
for (const queue of waiting) {
|
|
123
|
+
for (let head = queue[0]; head !== void 0; head = queue[0]) {
|
|
124
|
+
if (!head.dependsOn.every((d) => done.has(d))) break;
|
|
125
|
+
pending.push(head);
|
|
126
|
+
done.add(head.ref);
|
|
127
|
+
queue.shift();
|
|
128
|
+
moved = true;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return { pending, stuck: waiting.flat() };
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
// src/documents.ts
|
|
136
|
+
var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
137
|
+
var pathText = (path) => path.reduce((text, key) => typeof key === "number" ? `${text}[${key}]` : text === "" ? key : `${text}.${key}`, "");
|
|
138
|
+
var reach = (value, pattern) => {
|
|
139
|
+
let frontier = [{ path: [], value }];
|
|
140
|
+
for (const segment of pattern.split(".")) {
|
|
141
|
+
const array = segment.endsWith("[]");
|
|
142
|
+
const key = array ? segment.slice(0, -2) : segment;
|
|
143
|
+
const next = [];
|
|
144
|
+
for (const at of frontier) {
|
|
145
|
+
if (!isRecord(at.value)) continue;
|
|
146
|
+
const found = key === "*" ? Object.entries(at.value).map(([k, v]) => ({ path: [...at.path, k], value: v })) : key in at.value ? [{ path: [...at.path, key], value: at.value[key] }] : [];
|
|
147
|
+
for (const f of found) {
|
|
148
|
+
if (!array) next.push(f);
|
|
149
|
+
else if (Array.isArray(f.value)) f.value.forEach((item, i) => next.push({ path: [...f.path, i], value: item }));
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
frontier = next;
|
|
153
|
+
}
|
|
154
|
+
return frontier;
|
|
155
|
+
};
|
|
156
|
+
var getAt = (root, path) => path.reduce((at, key) => {
|
|
157
|
+
if (typeof key === "number") return Array.isArray(at) ? at[key] : void 0;
|
|
158
|
+
return isRecord(at) ? at[key] : void 0;
|
|
159
|
+
}, root);
|
|
160
|
+
var setAt = (root, path, value) => {
|
|
161
|
+
const [head, ...rest] = path;
|
|
162
|
+
if (head === void 0) return value;
|
|
163
|
+
if (typeof head === "number" && Array.isArray(root)) return root.map((item, i) => i === head ? setAt(item, rest, value) : item);
|
|
164
|
+
if (typeof head === "string" && isRecord(root)) return { ...root, [head]: setAt(root[head], rest, value) };
|
|
165
|
+
return root;
|
|
166
|
+
};
|
|
167
|
+
var createUpgrader = async (sequences, options) => {
|
|
168
|
+
const prepared = await prepare(sequences);
|
|
169
|
+
const tables = prepared.filter((s) => !s.grammar);
|
|
170
|
+
if (tables.length > 0) {
|
|
171
|
+
throw new StrataError(
|
|
172
|
+
"WRONG_OWNER",
|
|
173
|
+
"Documents are upgraded by grammar sequences; these own tables and belong to a database's ledger (`migrate`).",
|
|
174
|
+
tables.map((s) => s.id)
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
const grammars = prepared;
|
|
178
|
+
const kinds = /* @__PURE__ */ new Map();
|
|
179
|
+
for (const sequence of grammars) {
|
|
180
|
+
for (const [name, kind] of Object.entries(sequence.documents)) kinds.set(`${sequence.id}/${name}`, kind);
|
|
181
|
+
}
|
|
182
|
+
const unknown = [
|
|
183
|
+
...grammars.flatMap((s) => s.migrations.flatMap((m) => m.steps.flatMap((step) => step.kind === "document" && !kinds.has(step.at) ? [`${m.ref} rewrites ${step.at}`] : []))),
|
|
184
|
+
...[...kinds].flatMap(([ref, kind]) => Object.entries(kind.embeds ?? {}).flatMap(([path, target]) => kinds.has(target) ? [] : [`${ref} embeds ${target} at ${path}`]))
|
|
185
|
+
];
|
|
186
|
+
if (unknown.length > 0) throw new StrataError("UNKNOWN_KIND", "A document kind is named that no sequence declares.", unknown);
|
|
187
|
+
const stamp = Object.fromEntries(grammars.map((s) => [s.id, s.migrations.length]));
|
|
188
|
+
const locate = (document, kind) => {
|
|
189
|
+
if (!kinds.has(kind)) throw new StrataError("UNKNOWN_KIND", `No sequence declares the document kind "${kind}".`, [...kinds.keys()]);
|
|
190
|
+
const found = [];
|
|
191
|
+
const visit = (value, at, path) => {
|
|
192
|
+
if (!isRecord(value)) return;
|
|
193
|
+
found.push({ path, kind: at, value });
|
|
194
|
+
for (const [pattern, target] of Object.entries(kinds.get(at)?.embeds ?? {})) {
|
|
195
|
+
for (const hit of reach(value, pattern)) visit(hit.value, target, [...path, ...hit.path]);
|
|
196
|
+
}
|
|
197
|
+
};
|
|
198
|
+
visit(document, kind, []);
|
|
199
|
+
return found;
|
|
200
|
+
};
|
|
201
|
+
const positionOf = (given, id) => given?.[id] ?? 0;
|
|
202
|
+
const behind = (given) => {
|
|
203
|
+
const ahead = grammars.filter((s) => positionOf(given, s.id) > s.migrations.length);
|
|
204
|
+
if (ahead.length > 0) {
|
|
205
|
+
throw new StrataError(
|
|
206
|
+
"TOO_NEW",
|
|
207
|
+
"This document was written by newer code than this \u2014 reading it would be guessing.",
|
|
208
|
+
ahead.map((s) => `${s.id}: the document is at ${positionOf(given, s.id)}, this code knows ${s.migrations.length}`)
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
return grammars.some((s) => positionOf(given, s.id) < s.migrations.length);
|
|
212
|
+
};
|
|
213
|
+
const upgrade = (document, { kind, stamp: given }) => {
|
|
214
|
+
if (!isRecord(document)) throw new StrataError("STEP_FAILED", `A ${kind} document must be a JSON object.`);
|
|
215
|
+
if (!kinds.has(kind)) throw new StrataError("UNKNOWN_KIND", `No sequence declares the document kind "${kind}".`, [...kinds.keys()]);
|
|
216
|
+
if (!behind(given)) return { document, stamp, applied: [] };
|
|
217
|
+
const done = new Set(grammars.flatMap((s) => s.migrations.filter((m) => m.n <= positionOf(given, s.id)).map((m) => m.ref)));
|
|
218
|
+
const { pending, stuck } = orderPending(
|
|
219
|
+
grammars.map((s) => ({ waiting: s.migrations.filter((m) => !done.has(m.ref)) })),
|
|
220
|
+
done
|
|
221
|
+
);
|
|
222
|
+
if (stuck.length > 0) throw new StrataError("CYCLE", "Document migrations wait on each other and can never run.", stuck.map((m) => m.ref));
|
|
223
|
+
let current = document;
|
|
224
|
+
const applied = [];
|
|
225
|
+
const runStep = (migration, at, transform) => {
|
|
226
|
+
const targets = locate(current, kind).filter((l) => l.kind === at).sort((a, b) => b.path.length - a.path.length);
|
|
227
|
+
for (const target of targets) {
|
|
228
|
+
const value = getAt(current, target.path);
|
|
229
|
+
let rewritten;
|
|
230
|
+
try {
|
|
231
|
+
rewritten = options.transform(transform, { document: value, path: pathText(target.path) });
|
|
232
|
+
} catch (cause) {
|
|
233
|
+
throw new StrataError(
|
|
234
|
+
"STEP_FAILED",
|
|
235
|
+
`${migration.ref} ("${migration.description}") failed on the ${at} at ${pathText(target.path) || "(root)"}.`,
|
|
236
|
+
[cause instanceof Error ? cause.message : String(cause)],
|
|
237
|
+
{ cause }
|
|
238
|
+
);
|
|
239
|
+
}
|
|
240
|
+
if (!isRecord(rewritten)) {
|
|
241
|
+
throw new StrataError("STEP_FAILED", `${migration.ref} turned the ${at} at ${pathText(target.path) || "(root)"} into something that is not a document.`, [
|
|
242
|
+
JSON.stringify(rewritten)?.slice(0, 200) ?? String(rewritten)
|
|
243
|
+
]);
|
|
244
|
+
}
|
|
245
|
+
const next = setAt(current, target.path, rewritten);
|
|
246
|
+
if (isRecord(next)) current = next;
|
|
247
|
+
}
|
|
248
|
+
};
|
|
249
|
+
for (const migration of pending) {
|
|
250
|
+
for (const step of migration.steps) if (step.kind === "document") runStep(migration, step.at, step.transform);
|
|
251
|
+
applied.push(migration.ref);
|
|
252
|
+
}
|
|
253
|
+
return { document: current, stamp, applied };
|
|
254
|
+
};
|
|
255
|
+
return { stamp, upgrade, locate, behind };
|
|
256
|
+
};
|
|
257
|
+
|
|
258
|
+
// src/check/index.ts
|
|
259
|
+
var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
260
|
+
var byKey = ([a], [b]) => a < b ? -1 : a > b ? 1 : 0;
|
|
261
|
+
var sortKeys = (value) => {
|
|
262
|
+
if (Array.isArray(value)) return value.map(sortKeys);
|
|
263
|
+
if (!isRecord2(value)) return value;
|
|
264
|
+
return Object.fromEntries(Object.entries(value).sort(byKey).map(([k, v]) => [k, sortKeys(v)]));
|
|
265
|
+
};
|
|
266
|
+
var NAMED = /* @__PURE__ */ new Set(["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"]);
|
|
267
|
+
var DATA = /* @__PURE__ */ new Set(["const", "enum", "default", "examples"]);
|
|
268
|
+
var normalize = (value) => {
|
|
269
|
+
if (Array.isArray(value)) return value.map(normalize);
|
|
270
|
+
if (!isRecord2(value)) return value;
|
|
271
|
+
return Object.fromEntries(
|
|
272
|
+
Object.entries(value).filter(([key]) => key !== "description" && key !== "$schema").sort(byKey).map(([key, v]) => [key, NAMED.has(key) && isRecord2(v) ? namedSchemas(v, normalize) : DATA.has(key) ? sortKeys(v) : normalize(v)])
|
|
273
|
+
);
|
|
274
|
+
};
|
|
275
|
+
var namedSchemas = (map, each) => Object.fromEntries(Object.entries(map).sort(byKey).map(([name, schema]) => [name, each(schema)]));
|
|
276
|
+
var diffLines = (a, b, path, out, limit, canon = normalize, sets = true) => {
|
|
277
|
+
if (out.length >= limit) return;
|
|
278
|
+
if (JSON.stringify(a) === JSON.stringify(b)) return;
|
|
279
|
+
if (isRecord2(a) && isRecord2(b)) {
|
|
280
|
+
for (const key of [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
|
|
281
|
+
const at = path === "" ? key : `${path}.${key}`;
|
|
282
|
+
if (!(key in a)) out.push(`+ ${at}`);
|
|
283
|
+
else if (!(key in b)) out.push(`- ${at}`);
|
|
284
|
+
else diffLines(a[key], b[key], at, out, limit, canon, sets);
|
|
285
|
+
if (out.length >= limit) return;
|
|
286
|
+
}
|
|
287
|
+
return;
|
|
288
|
+
}
|
|
289
|
+
if (Array.isArray(a) && Array.isArray(b) && !sets && a.length === b.length) {
|
|
290
|
+
a.forEach((item, i) => diffLines(item, b[i], `${path}[${i}]`, out, limit, canon, sets));
|
|
291
|
+
return;
|
|
292
|
+
}
|
|
293
|
+
if (Array.isArray(a) && Array.isArray(b)) {
|
|
294
|
+
const text = (v) => JSON.stringify(canon(v));
|
|
295
|
+
const label = (v) => isRecord2(v) && isRecord2(v["properties"]) ? Object.keys(v["properties"]).join(",") : (text(v) ?? "").slice(0, 50);
|
|
296
|
+
const onlyA = a.filter((x) => !b.some((y) => text(y) === text(x)));
|
|
297
|
+
const onlyB = b.filter((y) => !a.some((x) => text(x) === text(y)));
|
|
298
|
+
const byLabel = new Map(onlyB.map((y) => [label(y), y]));
|
|
299
|
+
for (const x of onlyA) {
|
|
300
|
+
const partner = byLabel.get(label(x));
|
|
301
|
+
if (partner !== void 0) {
|
|
302
|
+
diffLines(x, partner, `${path}[${label(x)}]`, out, limit, canon, sets);
|
|
303
|
+
byLabel.delete(label(x));
|
|
304
|
+
} else {
|
|
305
|
+
out.push(`- ${path}[${label(x)}]`);
|
|
306
|
+
}
|
|
307
|
+
if (out.length >= limit) return;
|
|
308
|
+
}
|
|
309
|
+
for (const [name] of byLabel) {
|
|
310
|
+
out.push(`+ ${path}[${name}]`);
|
|
311
|
+
if (out.length >= limit) return;
|
|
312
|
+
}
|
|
313
|
+
return;
|
|
314
|
+
}
|
|
315
|
+
out.push(`~ ${path || "(root)"}: ${JSON.stringify(a)?.slice(0, 60)} \u2192 ${JSON.stringify(b)?.slice(0, 60)}`);
|
|
316
|
+
};
|
|
317
|
+
var diffJson = (a, b, limit = 20) => {
|
|
318
|
+
const out = [];
|
|
319
|
+
diffLines(a, b, "", out, limit, sortKeys, false);
|
|
320
|
+
return out;
|
|
321
|
+
};
|
|
322
|
+
|
|
323
|
+
// src/upgrade/index.ts
|
|
324
|
+
var keyOf = (doc) => `${doc.kind}:${doc.id}`;
|
|
325
|
+
var sortKeys2 = (value) => {
|
|
326
|
+
if (Array.isArray(value)) return value.map(sortKeys2);
|
|
327
|
+
if (typeof value !== "object" || value === null) return value;
|
|
328
|
+
return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, sortKeys2(v)]));
|
|
329
|
+
};
|
|
330
|
+
var sameJson = (a, b) => JSON.stringify(sortKeys2(a)) === JSON.stringify(sortKeys2(b));
|
|
331
|
+
var changedStrings = (before, after) => {
|
|
332
|
+
const found = /* @__PURE__ */ new Set();
|
|
333
|
+
const visit = (a, b) => {
|
|
334
|
+
if (JSON.stringify(a) === JSON.stringify(b)) return;
|
|
335
|
+
if (typeof a === "string") {
|
|
336
|
+
found.add(a);
|
|
337
|
+
return;
|
|
338
|
+
}
|
|
339
|
+
if (Array.isArray(a)) {
|
|
340
|
+
a.forEach((item, i) => visit(item, Array.isArray(b) ? b[i] : void 0));
|
|
341
|
+
return;
|
|
342
|
+
}
|
|
343
|
+
if (typeof a === "object" && a !== null) {
|
|
344
|
+
for (const [k, v] of Object.entries(a)) visit(v, typeof b === "object" && b !== null && !Array.isArray(b) ? Reflect.get(b, k) : void 0);
|
|
345
|
+
}
|
|
346
|
+
};
|
|
347
|
+
visit(before, after);
|
|
348
|
+
return [...found].filter((s) => s.length >= 4);
|
|
349
|
+
};
|
|
350
|
+
var planSourceUpgrade = async (options) => {
|
|
351
|
+
const { upgrader, stamp, documents, schemas, describe } = options;
|
|
352
|
+
const seen = /* @__PURE__ */ new Set();
|
|
353
|
+
const planned = [];
|
|
354
|
+
const untouched = [];
|
|
355
|
+
const problems = [];
|
|
356
|
+
for (const doc of documents) {
|
|
357
|
+
const key = keyOf(doc);
|
|
358
|
+
if (seen.has(key)) throw new StrataError("INVALID_SEQUENCE", `Two artifacts are both ${key} \u2014 an artifact needs one identity to be planned.`);
|
|
359
|
+
seen.add(key);
|
|
360
|
+
const result = upgrader.upgrade(doc.document, { kind: doc.kind, stamp });
|
|
361
|
+
if (sameJson(result.document, doc.document)) {
|
|
362
|
+
untouched.push(key);
|
|
363
|
+
continue;
|
|
364
|
+
}
|
|
365
|
+
planned.push({
|
|
366
|
+
kind: doc.kind,
|
|
367
|
+
id: doc.id,
|
|
368
|
+
...doc.file === void 0 ? {} : { file: doc.file },
|
|
369
|
+
applied: result.applied,
|
|
370
|
+
changes: diffJson(doc.document, result.document),
|
|
371
|
+
expected: result.document
|
|
372
|
+
});
|
|
373
|
+
const schema = schemas?.[doc.kind];
|
|
374
|
+
if (schema !== void 0) {
|
|
375
|
+
const checked = await schema["~standard"].validate(result.document);
|
|
376
|
+
if (checked.issues !== void 0) {
|
|
377
|
+
problems.push(`${key}: the migrated artifact does not pass ${doc.kind}'s current schema \u2014 ${checked.issues.slice(0, 2).map((i) => i.message).join("; ")}`);
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
const from = stamp;
|
|
382
|
+
const to = upgrader.stamp;
|
|
383
|
+
const migrations = Object.entries(to).flatMap(
|
|
384
|
+
([id, n]) => Array.from({ length: Math.max(0, n - (from[id] ?? 0)) }, (_, i) => `${id}/${(from[id] ?? 0) + i + 1}`)
|
|
385
|
+
);
|
|
386
|
+
return {
|
|
387
|
+
from,
|
|
388
|
+
to,
|
|
389
|
+
migrations: migrations.map((ref) => ({ ref, description: describe(ref) })),
|
|
390
|
+
documents: planned.sort((a, b) => keyOf(a) < keyOf(b) ? -1 : 1),
|
|
391
|
+
untouched: untouched.sort(),
|
|
392
|
+
problems
|
|
393
|
+
};
|
|
394
|
+
};
|
|
395
|
+
var verifySourceUpgrade = (options) => {
|
|
396
|
+
const { plan, upgrader, documents } = options;
|
|
397
|
+
const now = new Map(documents.map((d) => [keyOf(d), d]));
|
|
398
|
+
const lines = [];
|
|
399
|
+
for (const want of plan.documents) {
|
|
400
|
+
const key = keyOf(want);
|
|
401
|
+
const got = now.get(key);
|
|
402
|
+
if (got === void 0) {
|
|
403
|
+
lines.push({ ok: false, text: `${key} is gone \u2014 the plan expected it rewritten, not removed` });
|
|
404
|
+
} else if (sameJson(got.document, want.expected)) {
|
|
405
|
+
lines.push({ ok: true, text: `${key} matches its migrated JSON` });
|
|
406
|
+
} else {
|
|
407
|
+
lines.push({ ok: false, text: `${key} does not match its migrated JSON yet`, detail: diffJson(got.document, want.expected, 12) });
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
for (const key of plan.untouched) {
|
|
411
|
+
const got = now.get(key);
|
|
412
|
+
if (got === void 0) {
|
|
413
|
+
lines.push({ ok: false, text: `${key} is gone \u2014 no migration asked for that` });
|
|
414
|
+
continue;
|
|
415
|
+
}
|
|
416
|
+
const again = upgrader.upgrade(got.document, { kind: got.kind, stamp: plan.from });
|
|
417
|
+
if (!sameJson(again.document, got.document)) {
|
|
418
|
+
lines.push({ ok: false, text: `${key} was not in the plan, but the migrations would change it now`, detail: diffJson(got.document, again.document, 12) });
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
const known = /* @__PURE__ */ new Set([...plan.documents.map(keyOf), ...plan.untouched]);
|
|
422
|
+
for (const key of now.keys()) {
|
|
423
|
+
if (!known.has(key)) lines.push({ ok: false, text: `${key} is new since the plan \u2014 plan again so it is checked too` });
|
|
424
|
+
}
|
|
425
|
+
const ok = lines.every((l) => l.ok);
|
|
426
|
+
if (ok) lines.push({ ok: true, text: `${plan.untouched.length} artifact(s) no migration touches, still untouched` });
|
|
427
|
+
return { ok, lines };
|
|
428
|
+
};
|
|
429
|
+
var renderReport = (plan, expectedPathOf) => {
|
|
430
|
+
const stamp = (s) => Object.entries(s).map(([k, v]) => `${k} ${v}`).join(", ");
|
|
431
|
+
const out = [
|
|
432
|
+
"# strata upgrade",
|
|
433
|
+
"",
|
|
434
|
+
`The source is written at **${stamp(plan.from)}**; the installed grammars are at **${stamp(plan.to)}**.`,
|
|
435
|
+
"",
|
|
436
|
+
"## Migrations",
|
|
437
|
+
"",
|
|
438
|
+
...plan.migrations.map((m) => `- \`${m.ref}\` \u2014 ${m.description}`),
|
|
439
|
+
""
|
|
440
|
+
];
|
|
441
|
+
if (plan.problems.length > 0) {
|
|
442
|
+
out.push("## Stop: a migration is wrong", "", "These artifacts would not pass their current schema after migrating \u2014 no edit can make `verify` pass. Fix the migration, then plan again.", "", ...plan.problems.map((p) => `- ${p}`), "");
|
|
443
|
+
}
|
|
444
|
+
if (plan.documents.length === 0) {
|
|
445
|
+
out.push("## Nothing to edit", "", `No artifact changes (${plan.untouched.length} checked). Run \`verify\` to move the lock.`, "");
|
|
446
|
+
} else {
|
|
447
|
+
out.push(
|
|
448
|
+
`## ${plan.documents.length} artifact(s) to edit`,
|
|
449
|
+
"",
|
|
450
|
+
"Edit each so that it serialises to EXACTLY its expected JSON (key order aside) \u2014 then run `verify`. Only what is listed changes; every other artifact must stay as it is.",
|
|
451
|
+
""
|
|
452
|
+
);
|
|
453
|
+
for (const doc of plan.documents) {
|
|
454
|
+
out.push(
|
|
455
|
+
`### \`${doc.id}\` (${doc.kind})`,
|
|
456
|
+
"",
|
|
457
|
+
doc.file === void 0 ? "" : `- **File:** \`${doc.file}\``,
|
|
458
|
+
doc.lookIn === void 0 || doc.lookIn.length === 0 ? "" : `- **Look in:** ${doc.lookIn.map((f) => `\`${f}\``).join(", ")} \u2014 where the changing values are written`,
|
|
459
|
+
`- **Migrations:** ${doc.applied.map((r) => `\`${r}\``).join(", ")}`,
|
|
460
|
+
`- **Expected JSON:** \`${expectedPathOf(doc)}\``,
|
|
461
|
+
"- **Changes:**",
|
|
462
|
+
"",
|
|
463
|
+
"```",
|
|
464
|
+
...doc.changes,
|
|
465
|
+
"```",
|
|
466
|
+
""
|
|
467
|
+
);
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
return out.filter((line, i, all) => !(line === "" && all[i - 1] === "")).join("\n");
|
|
471
|
+
};
|
|
472
|
+
|
|
473
|
+
// src/node/index.ts
|
|
474
|
+
var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
475
|
+
var stampText = (s) => Object.entries(s).map(([k, v]) => `${k} ${v}`).join(", ") || "(nothing)";
|
|
476
|
+
var filesUnder = (dir) => fs.existsSync(dir) ? fs.readdirSync(dir).flatMap((name) => {
|
|
477
|
+
const path$1 = path.join(dir, name);
|
|
478
|
+
if (name === "node_modules" || name.startsWith(".")) return [];
|
|
479
|
+
return fs.statSync(path$1).isDirectory() ? filesUnder(path$1) : /\.(ts|tsx|js|mjs)$/.test(name) ? [path$1] : [];
|
|
480
|
+
}) : [];
|
|
481
|
+
var runSourceUpgrade = async (options, argv) => {
|
|
482
|
+
const log = options.log ?? ((line) => console.log(line));
|
|
483
|
+
const command = argv.find((a) => !a.startsWith("-")) ?? "status";
|
|
484
|
+
const lockPath = path.join(options.root, options.lock ?? "strata.lock.json");
|
|
485
|
+
const work = path.join(options.root, options.workDir ?? path.join(".strata", "upgrade"));
|
|
486
|
+
const rel = (path$1) => path.relative(options.root, path$1).split(path.sep).join("/");
|
|
487
|
+
const upgrader = await createUpgrader(options.grammars, { transform: options.transform });
|
|
488
|
+
const descriptions = new Map(options.grammars.flatMap((g) => g.migrations.map((m, i) => [`${g.id}/${i + 1}`, m.description])));
|
|
489
|
+
const readLock = () => {
|
|
490
|
+
if (!fs.existsSync(lockPath)) return void 0;
|
|
491
|
+
const raw = JSON.parse(fs.readFileSync(lockPath, "utf8"));
|
|
492
|
+
if (!isRecord3(raw) || !isRecord3(raw["grammar"])) throw new StrataError("INVALID_SEQUENCE", `${rel(lockPath)} is not a lock: expected { "grammar": { \u2026 } }.`);
|
|
493
|
+
return Object.fromEntries(Object.entries(raw["grammar"]).map(([k, v]) => [k, Number(v)]));
|
|
494
|
+
};
|
|
495
|
+
const writeLock = (stamp) => fs.writeFileSync(lockPath, `${JSON.stringify({ grammar: Object.fromEntries(Object.entries(stamp).sort(([a], [b]) => a < b ? -1 : 1)) }, null, 2)}
|
|
496
|
+
`);
|
|
497
|
+
const sourceText = () => new Map(filesUnder(path.join(options.root, options.sources ?? "src")).map((f) => [f, fs.readFileSync(f, "utf8")]));
|
|
498
|
+
const loadDocuments = async () => {
|
|
499
|
+
const text = sourceText();
|
|
500
|
+
const fileOf = (id) => {
|
|
501
|
+
const needles = [`id: '${id}'`, `id: "${id}"`, `"id": "${id}"`];
|
|
502
|
+
for (const [path, body] of text) if (needles.some((n) => body.includes(n))) return rel(path);
|
|
503
|
+
return void 0;
|
|
504
|
+
};
|
|
505
|
+
return (await options.documents()).map((d) => {
|
|
506
|
+
const document = JSON.parse(JSON.stringify(d.document));
|
|
507
|
+
const file = d.file ?? fileOf(d.id);
|
|
508
|
+
return { kind: d.kind, id: d.id, document, ...file === void 0 ? {} : { file } };
|
|
509
|
+
});
|
|
510
|
+
};
|
|
511
|
+
const lock = readLock();
|
|
512
|
+
if (command === "init") {
|
|
513
|
+
if (lock !== void 0) {
|
|
514
|
+
log(`[fail] ${rel(lockPath)} already records ${stampText(lock)} \u2014 init only records a source that has never had a lock.`);
|
|
515
|
+
return 1;
|
|
516
|
+
}
|
|
517
|
+
writeLock(upgrader.stamp);
|
|
518
|
+
log(`[pass] recorded: the source is written at ${stampText(upgrader.stamp)} (${rel(lockPath)}). Only true if it is \u2014 commit it.`);
|
|
519
|
+
return 0;
|
|
520
|
+
}
|
|
521
|
+
if (lock === void 0) {
|
|
522
|
+
log(`[fail] no ${rel(lockPath)} \u2014 nothing records which grammars this source is written in.`);
|
|
523
|
+
log(` If it is written at the installed ones (${stampText(upgrader.stamp)}), run: strata init`);
|
|
524
|
+
return 1;
|
|
525
|
+
}
|
|
526
|
+
let behind;
|
|
527
|
+
try {
|
|
528
|
+
behind = upgrader.behind(lock);
|
|
529
|
+
} catch (error) {
|
|
530
|
+
log(`[fail] ${error instanceof Error ? error.message.split("\n").join("\n ") : String(error)}`);
|
|
531
|
+
log(" The lock is ahead of the installed grammars \u2014 install the newer packages, or the lock is wrong.");
|
|
532
|
+
return 1;
|
|
533
|
+
}
|
|
534
|
+
if (command === "status") {
|
|
535
|
+
if (!behind) {
|
|
536
|
+
log(`[pass] the source is written at the installed grammars (${stampText(lock)})`);
|
|
537
|
+
return 0;
|
|
538
|
+
}
|
|
539
|
+
log(`[${argv.includes("--check") ? "fail" : "info"}] the source is written at ${stampText(lock)}; the installed grammars are at ${stampText(upgrader.stamp)}.`);
|
|
540
|
+
log(" Run: strata upgrade \u2014 then edit what REPORT.md lists \u2014 then: strata verify");
|
|
541
|
+
return argv.includes("--check") ? 1 : 0;
|
|
542
|
+
}
|
|
543
|
+
if (command === "upgrade") {
|
|
544
|
+
if (!behind) {
|
|
545
|
+
log(`[pass] nothing to upgrade \u2014 the source is written at the installed grammars (${stampText(lock)})`);
|
|
546
|
+
return 0;
|
|
547
|
+
}
|
|
548
|
+
const documents = await loadDocuments();
|
|
549
|
+
const drafted = await planSourceUpgrade({
|
|
550
|
+
upgrader,
|
|
551
|
+
stamp: lock,
|
|
552
|
+
documents,
|
|
553
|
+
...options.schemas === void 0 ? {} : { schemas: options.schemas },
|
|
554
|
+
describe: (ref) => descriptions.get(ref) ?? "(no description)"
|
|
555
|
+
});
|
|
556
|
+
const text = sourceText();
|
|
557
|
+
const byKey2 = new Map(documents.map((d) => [`${d.kind}:${d.id}`, d]));
|
|
558
|
+
const plan = {
|
|
559
|
+
...drafted,
|
|
560
|
+
documents: drafted.documents.map((doc) => {
|
|
561
|
+
const needles = changedStrings(byKey2.get(`${doc.kind}:${doc.id}`)?.document, doc.expected).flatMap((s) => [`'${s}'`, `"${s}"`]);
|
|
562
|
+
const lookIn = [...text].filter(([, body]) => needles.some((n) => body.includes(n))).map(([path]) => rel(path));
|
|
563
|
+
return { ...doc, lookIn };
|
|
564
|
+
})
|
|
565
|
+
};
|
|
566
|
+
fs.rmSync(work, { recursive: true, force: true });
|
|
567
|
+
fs.mkdirSync(work, { recursive: true });
|
|
568
|
+
const expectedPathOf = (doc) => path.join(work, "expected", doc.kind.replace(/[^a-z0-9.-]/gi, "_"), `${doc.id.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
|
|
569
|
+
for (const doc of plan.documents) {
|
|
570
|
+
const path$1 = expectedPathOf(doc);
|
|
571
|
+
fs.mkdirSync(path.join(path$1, ".."), { recursive: true });
|
|
572
|
+
fs.writeFileSync(path$1, `${JSON.stringify(doc.expected, null, 2)}
|
|
573
|
+
`);
|
|
574
|
+
}
|
|
575
|
+
fs.writeFileSync(path.join(work, "plan.json"), `${JSON.stringify(plan, null, 2)}
|
|
576
|
+
`);
|
|
577
|
+
fs.writeFileSync(path.join(work, "REPORT.md"), `${renderReport(plan, (d) => rel(expectedPathOf(d)))}
|
|
578
|
+
`);
|
|
579
|
+
log(`[plan] ${stampText(plan.from)} \u2192 ${stampText(plan.to)}: ${plan.migrations.length} migration(s)`);
|
|
580
|
+
for (const m of plan.migrations) log(` ${m.ref} ${m.description}`);
|
|
581
|
+
log(` ${plan.documents.length} artifact(s) to edit, ${plan.untouched.length} untouched.`);
|
|
582
|
+
for (const d of plan.documents) log(` ${d.file ?? "(file not found)"} ${d.id}`);
|
|
583
|
+
log(` Report: ${rel(path.join(work, "REPORT.md"))} \u2014 edit, then: strata verify`);
|
|
584
|
+
for (const p of plan.problems) log(`[fail] ${p}`);
|
|
585
|
+
return plan.problems.length > 0 ? 1 : 0;
|
|
586
|
+
}
|
|
587
|
+
if (command === "verify") {
|
|
588
|
+
const planPath = path.join(work, "plan.json");
|
|
589
|
+
if (!fs.existsSync(planPath)) {
|
|
590
|
+
log(`[fail] no plan at ${rel(planPath)} \u2014 run: strata upgrade`);
|
|
591
|
+
return 1;
|
|
592
|
+
}
|
|
593
|
+
const raw = JSON.parse(fs.readFileSync(planPath, "utf8"));
|
|
594
|
+
if (!isRecord3(raw) || !isRecord3(raw["to"]) || !isRecord3(raw["from"]) || !Array.isArray(raw["documents"]) || !Array.isArray(raw["untouched"])) {
|
|
595
|
+
log(`[fail] ${rel(planPath)} is not a plan \u2014 run: strata upgrade`);
|
|
596
|
+
return 1;
|
|
597
|
+
}
|
|
598
|
+
const plan = {
|
|
599
|
+
from: Object.fromEntries(Object.entries(raw["from"]).map(([k, v]) => [k, Number(v)])),
|
|
600
|
+
to: Object.fromEntries(Object.entries(raw["to"]).map(([k, v]) => [k, Number(v)])),
|
|
601
|
+
migrations: [],
|
|
602
|
+
documents: raw["documents"].flatMap(
|
|
603
|
+
(d) => isRecord3(d) && typeof d["kind"] === "string" && typeof d["id"] === "string" ? [{ kind: d["kind"], id: d["id"], applied: [], changes: [], expected: d["expected"] }] : []
|
|
604
|
+
),
|
|
605
|
+
untouched: raw["untouched"].map(String),
|
|
606
|
+
problems: []
|
|
607
|
+
};
|
|
608
|
+
if (JSON.stringify(plan.to) !== JSON.stringify(upgrader.stamp)) {
|
|
609
|
+
log(`[fail] the plan was made for ${stampText(plan.to)}, but the installed grammars are at ${stampText(upgrader.stamp)} \u2014 plan again: strata upgrade`);
|
|
610
|
+
return 1;
|
|
611
|
+
}
|
|
612
|
+
const result = verifySourceUpgrade({ plan, upgrader, documents: await loadDocuments() });
|
|
613
|
+
for (const line of result.lines) {
|
|
614
|
+
log(`[${line.ok ? "pass" : "fail"}] ${line.text}`);
|
|
615
|
+
for (const d of line.detail ?? []) log(` ${d}`);
|
|
616
|
+
}
|
|
617
|
+
if (!result.ok) return 1;
|
|
618
|
+
writeLock(plan.to);
|
|
619
|
+
fs.rmSync(path.join(options.root, options.workDir ?? ".strata"), { recursive: true, force: true });
|
|
620
|
+
log(`[pass] the source is now written at ${stampText(plan.to)} \u2014 ${rel(lockPath)} updated. Commit it with the edits.`);
|
|
621
|
+
return 0;
|
|
622
|
+
}
|
|
623
|
+
log(`[fail] unknown command "${command}" \u2014 status [--check] | init | upgrade | verify`);
|
|
624
|
+
return 1;
|
|
625
|
+
};
|
|
626
|
+
|
|
627
|
+
exports.runSourceUpgrade = runSourceUpgrade;
|
|
628
|
+
//# sourceMappingURL=index.cjs.map
|
|
629
|
+
//# sourceMappingURL=index.cjs.map
|