@runeditrun/rer 0.2.93 → 0.2.95

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.
Files changed (79) hide show
  1. package/README.md +3 -0
  2. package/cli/README.md +3 -0
  3. package/cli/agent-door.mjs +20 -10
  4. package/cli/agent-history-database.mjs +82 -0
  5. package/cli/agent-history-isolation.mjs +68 -0
  6. package/cli/agent-history.mjs +58 -0
  7. package/cli/agent-journey-fixtures.mjs +3 -3
  8. package/cli/agent-network.mjs +12 -6
  9. package/cli/authoring.mjs +1 -1
  10. package/cli/business/carry-files.mjs +115 -0
  11. package/cli/business/carry.mjs +20 -81
  12. package/cli/business/choices.mjs +12 -7
  13. package/cli/business/command.mjs +19 -0
  14. package/cli/business/setup-command.mjs +14 -1
  15. package/cli/contract.mjs +1 -1
  16. package/cli/door-clauses.mjs +28 -2
  17. package/cli/export.mjs +1 -1
  18. package/cli/hosted-hosts.mjs +21 -0
  19. package/cli/hosted-output.mjs +93 -8
  20. package/cli/hosted-queue-producers.mjs +43 -0
  21. package/cli/jsonc.mjs +1 -115
  22. package/cli/lifecycle.mjs +5 -0
  23. package/cli/local.mjs +1 -1
  24. package/cli/parse.mjs +1 -1
  25. package/cli/port.mjs +1 -2
  26. package/cli/portability-evidence.d.mts +5 -0
  27. package/cli/portability-evidence.mjs +85 -0
  28. package/cli/portability-migrations.mjs +3 -5
  29. package/edition-authoring/archive-source.mjs +86 -1
  30. package/edition-authoring/base-copies.mjs +15 -45
  31. package/edition-authoring/cli.mjs +1 -1
  32. package/edition-authoring/edition-migrations.mjs +2 -2
  33. package/edition-authoring/module-closure.mjs +119 -50
  34. package/edition-authoring/module-edges.mjs +14 -1
  35. package/edition-authoring/module-packages.mjs +12 -5
  36. package/edition-authoring/module-syntax.mjs +13 -50
  37. package/edition-authoring/runtime-dependencies.mjs +4 -4
  38. package/foundation/runtime/contract-anchor.mjs +87 -0
  39. package/foundation/runtime/contract-docs.mjs +20 -4
  40. package/global/CHANGELOG.md +74 -0
  41. package/global/README.md +3 -0
  42. package/install.sh +4 -1
  43. package/modules/agent-door/CLAUSES.md +12 -0
  44. package/modules/agent-door/conformance/audit.mjs +22 -4
  45. package/modules/agent-door/conformance/discovery.mjs +32 -1
  46. package/modules/agent-door/conformance/erasure.mjs +103 -0
  47. package/modules/agent-door/conformance/injection.mjs +5 -3
  48. package/modules/agent-door/conformance/journey.mjs +20 -2
  49. package/modules/agent-door/conformance/policy-phases.mjs +6 -0
  50. package/modules/agent-door/conformance/protocol.mjs +13 -3
  51. package/modules/deploy-kit/README.md +1 -1
  52. package/modules/deploy-kit/jsonc.mjs +115 -0
  53. package/modules/deploy-kit/migration-directory.mjs +16 -0
  54. package/modules/deploy-kit/prepare.mjs +5 -2
  55. package/modules/deploy-kit/templates.mjs +9 -4
  56. package/modules/erasure/cascade.mjs +4 -4
  57. package/modules/erasure/index.d.mts +1 -1
  58. package/modules/erasure/index.mjs +1 -1
  59. package/modules/import-kit/src/d1/README.md +16 -1
  60. package/modules/import-kit/src/d1/preserved-reverse.ts +5 -2
  61. package/modules/import-kit/src/d1/read-fence.ts +14 -2
  62. package/modules/import-kit/src/d1/reverse.ts +4 -1
  63. package/modules/import-kit/src/d1/sets.ts +8 -0
  64. package/modules/import-kit/src/d1/snapshot-text.ts +68 -0
  65. package/modules/import-kit/src/d1/undo-report.ts +4 -1
  66. package/modules/import-kit/src/door/ADOPTING.md +9 -4
  67. package/modules/portability/README.md +68 -10
  68. package/modules/portability/bookkeeping.mjs +8 -4
  69. package/modules/portability/catalogue.mjs +11 -1
  70. package/modules/portability/checkout-history.mjs +20 -0
  71. package/modules/portability/import.mjs +1 -1
  72. package/modules/portability/index.d.mts +1 -1
  73. package/modules/portability/library-history.mjs +2 -7
  74. package/modules/portability/restore-safety.mjs +6 -3
  75. package/modules/portability/storage.mjs +7 -1
  76. package/modules/portability/worker-history.d.mts +9 -0
  77. package/modules/portability/worker-history.mjs +29 -0
  78. package/onboarding/adapter.mjs +25 -13
  79. package/package.json +9 -1
@@ -5,6 +5,7 @@ import {raw, safe, requirePhysical, testSource, freedEntries, toolFile} from './
5
5
  import {dependencies, resolve, external, bindings, lexicalExports} from './runtime-dependencies.mjs';
6
6
  import {relocateDependencies} from './module-edges.mjs';
7
7
  import {sharedNamespaces} from './copy-namespaces.mjs';
8
+ import {fileURLToPath} from 'node:url';
8
9
  import {acknowledgementCommand} from './base-acknowledgements.mjs';
9
10
  import {checkModulePackages} from './module-packages.mjs';
10
11
  const code = name => /\.(?:[cm]?[jt]s|[jt]sx)$/.test(name) && !testSource(name);
@@ -18,6 +19,7 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
18
19
  const mappings = plans.filter(plan => !plan.retired).map(({copy}) => ({copy, ...namespace(copy)})).filter(mapping => mapping.from);
19
20
  const shared = sharedNamespaces(mappings);
20
21
  const cache = new Map(), planned = new Map(), recorded = new Map(), queue = [], withheld = [];
22
+ const retainedTargets = new Set();
21
23
  const disk = {has: name => {
22
24
  try { return fs.lstatSync(path.join(root, name)).isFile(); }
23
25
  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return false; throw error; }
@@ -32,10 +34,11 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
32
34
  if (stat) removedObjects.add(target, stat);
33
35
  }
34
36
  const inspect = target => requirePhysical(root, safe(target), {cache, freed: removedObjects.has});
35
- function enqueue(plan, source, entry, adapted = false) {
37
+ function enqueue(plan, source, entry, retained = false) {
36
38
  const target = mapped(source, plan.copy);
37
- if (!adapted) planned.set(target, {plan, source, entry});
38
- if (code(source)) queue.push({plan, source, target, entry, adapted});
39
+ if (retained) retainedTargets.add(target);
40
+ else planned.set(target, {plan, source, entry});
41
+ if (code(source)) queue.push({plan, source, target, entry, retained});
39
42
  }
40
43
  for (const plan of plans) {
41
44
  for (const target of Object.keys(plan.copy.files)) recorded.set(target, plan);
@@ -44,7 +47,7 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
44
47
  }
45
48
  const directoryAdditions = new Set([...planned].filter(([target, {plan}]) => !Object.hasOwn(plan.copy.files, target) && !tree.has(plan.copy.originPath)).map(([target]) => target));
46
49
  const packageRoots = new Set([...planned.keys()].filter(target => !directoryAdditions.has(target)));
47
- for (const {target, adapted} of queue) if (adapted) packageRoots.add(target);
50
+ for (const {target, retained} of queue) if (retained) packageRoots.add(target);
48
51
  function namespace(copy) {
49
52
  const file = Object.hasOwn(copy.files, copy.path) || tree.has(copy.originPath);
50
53
  if (file && path.posix.basename(copy.path) !== path.posix.basename(copy.originPath)) return {};
@@ -82,7 +85,15 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
82
85
  if (index.has(target)) {
83
86
  if (!physical.stat) refuse(target, 'tracked edition source is missing', `git restore -- ${quote(target)}`);
84
87
  ownerSources.set(target, source);
85
- return; // Tracked, unrecorded source remains edition-owned, even at equal bytes.
88
+ // Retain ownership and bytes, but close Base edges introduced by seed
89
+ // reconciliation just as for an acknowledged adaptation. Seed-only
90
+ // helpers have no Base source and do not acquire a guessed origin.
91
+ if (tree.has(source) && code(source) && !retainedTargets.has(target)) {
92
+ retainedTargets.add(target);
93
+ packageRoots.add(target);
94
+ queue.push({source, target, retained: true});
95
+ }
96
+ return;
86
97
  }
87
98
  if (physical.stat && !index.has(target)) refuse(target, 'existing file has no Base copy record or Git index entry', `git add -f -- ${quote(target)}`);
88
99
  let plan = plans.find(plan => inside(target, plan.copy.path));
@@ -110,7 +121,7 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
110
121
  // records and plans satisfy that local edge before looking for a new source.
111
122
  const view = {
112
123
  has: name => planned.has(name) || recorded.has(name) || index.has(name) && disk.has(name),
113
- read: name => planned.has(name) ? blob(planned.get(name).entry) : local(name),
124
+ read: name => planned.has(name) ? relocations.get(name)?.toString('utf8') ?? blob(planned.get(name).entry) : local(name),
114
125
  };
115
126
  function requests(bytes, source, target) {
116
127
  return dependencies(bytes, source).filter(request => {
@@ -125,6 +136,9 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
125
136
  const originScope = {}, targetScope = {}, manifests = new Set();
126
137
  const dependency = resolve(tree, source, specifier, {...request, manifests, package: originScope});
127
138
  const destination = resolve(view, target, specifier, {...request, package: targetScope});
139
+ // A retained file's own relative imports without a Base counterpart stay
140
+ // seed-owned. Only Base dependencies participate in copy delivery.
141
+ if (retainedTargets.has(target) && specifier.startsWith('.') && !dependency) return {...request, external: true};
128
142
  if (!specifier.startsWith('.')) {
129
143
  if (originScope.external && targetScope.external && originScope.value === targetScope.value) return {...request, external: true};
130
144
  if (!targetScope.managed || originScope.external || targetScope.external) return {...request, reason: 'runtime package scope differs from its Base source'};
@@ -140,9 +154,9 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
140
154
  return {...request, dependency: source, destination, satisfied: true};
141
155
  }
142
156
  const expected = dependency && path.posix.join(path.posix.dirname(target), path.posix.relative(path.posix.dirname(source), dependency));
143
- // Relocate only new deliveries. Existing files and acknowledged adaptations
144
- // retain their current imports and ownership, including old missing edges.
145
- if (specifier.startsWith('.') && dependency && !recorded.has(target) && !witness(expected, dependency)) {
157
+ // Relocate only new deliveries. Retained files keep their seed-owned
158
+ // imports; a missing Base edge must have a witness at that exact path.
159
+ if (specifier.startsWith('.') && dependency && !recorded.has(target) && !retainedTargets.has(target) && !witness(expected, dependency)) {
146
160
  const destinations = recordedDestination(dependency);
147
161
  if (destinations.length > 1) return {...request, manifests, dependency, destination: expected,
148
162
  reason: `ambiguous Base copy mappings for ${dependency}: ${destinations.join(', ')}`};
@@ -164,16 +178,16 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
164
178
  // Preserve these edges during traversal; required planned files may still
165
179
  // complete a sparse historical copy by satisfying them.
166
180
  const baseline = new Set();
167
- for (const {plan, source, target} of queue) {
168
- if (!Object.hasOwn(plan.copy.files, target) || !disk.has(target) || bootstrap(source)) continue;
181
+ for (const {plan, source, target, retained} of queue) {
182
+ if (retained || !Object.hasOwn(plan.copy.files, target) || !disk.has(target) || bootstrap(source)) continue;
169
183
  for (const request of requests(local(target), source, target)) {
170
184
  const candidate = edge(source, target, request);
171
185
  if (!resolve(disk, target, request.specifier, request) && !recorded.has(candidate.destination)) baseline.add(key(target, request));
172
186
  }
173
187
  }
174
188
  // Do not let an optional directory addition incidentally fill an old edge.
175
- for (const {plan, source, target} of queue) {
176
- if (!Object.hasOwn(plan.copy.files, target) || !disk.has(target)) continue;
189
+ for (const {plan, source, target, retained} of queue) {
190
+ if (retained || !Object.hasOwn(plan.copy.files, target) || !disk.has(target)) continue;
177
191
  for (const request of requests(local(target), source, target)) if (baseline.has(key(target, request))) {
178
192
  const destination = resolve(view, target, request.specifier, request);
179
193
  if (!directoryAdditions.has(destination)) continue;
@@ -183,40 +197,51 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
183
197
  withheld.push({path: destination, originPath: addition.source, dependency: request.specifier});
184
198
  }
185
199
  }
186
- const incoming = new Set();
187
- for (const item of queue) for (const request of requests(item.adapted ? local(item.target) : blob(item.entry), item.source, item.target)) {
200
+ const incoming = new Set(), newlyRequired = new Set();
201
+ for (const item of queue) for (const request of requests(item.retained ? local(item.target) : blob(item.entry), item.source, item.target)) {
188
202
  if (baseline.has(key(item.target, request))) continue;
189
203
  const {destination} = edge(item.source, item.target, request);
190
- if (destination) incoming.add(destination);
204
+ if (destination) {
205
+ incoming.add(destination);
206
+ if (!item.retained) {
207
+ const before = disk.has(item.target) ? local(item.target) : '';
208
+ const previous = dependencies(before, item.source);
209
+ const oldNames = bindings(before, request.types, item.source).get(request.specifier);
210
+ const names = bindings(blob(item.entry), request.types, item.source).get(request.specifier);
211
+ if (!previous.some(old => key(item.target, old) === key(item.target, request)) ||
212
+ [...names ?? []].some(name => !oldNames?.has(name))) newlyRequired.add(destination);
213
+ }
214
+ }
191
215
  }
192
216
  function exportsAt(target, types = false, seen = new Set()) {
193
217
  if (seen.has(target)) return new Set();
194
218
  seen.add(target); inspect(target);
195
- if (!disk.has(target)) return null;
219
+ if (!view.has(target)) return null;
196
220
  if (!types && /\.d\.[cm]?ts$/.test(target)) return new Set();
197
221
  if (target.endsWith('.json')) return new Set(['default']);
198
- const result = lexicalExports(local(target), specifier => {
199
- const next = resolve(disk, target, specifier, {types});
222
+ const result = lexicalExports(view.read(target), specifier => {
223
+ const next = resolve(view, target, specifier, {types});
200
224
  return next ? exportsAt(next, types, seen) : null;
201
- }, types);
225
+ }, types, target);
202
226
  if (result === null) return null;
203
227
  const declaration = target.replace(/\.mjs$/, '.d.mts').replace(/\.js$/, '.d.ts');
204
- if (types && declaration !== target && disk.has(declaration)) {
228
+ if (types && declaration !== target && view.has(declaration)) {
205
229
  const declared = exportsAt(declaration, true, seen);
206
230
  if (declared === null) return null;
207
231
  for (const name of declared) result.add(name);
208
232
  }
209
233
  return result;
210
234
  }
235
+ const missingExports = new Map(), exportChecks = [];
211
236
  const seen = new Set();
212
237
  for (let i = 0; i < queue.length; i++) {
213
- const item = queue[i], {plan, source, target, entry, adapted} = item;
214
- if (seen.has(target) || !adapted && !plan.sources.some(([name]) => name === source)) continue;
238
+ const item = queue[i], {plan, source, target, entry, retained} = item;
239
+ if (seen.has(target) || !retained && !plan.sources.some(([name]) => name === source)) continue;
215
240
  seen.add(target);
216
- const bytes = adapted ? local(target) : blob(entry);
217
- const before = Object.hasOwn(plan.copy.files, target) && disk.has(target) ? local(target) : '';
218
- const imports = bindings(bytes), oldBindings = bindings(before);
219
- const typeImports = bindings(bytes, true), oldTypes = bindings(before, true);
241
+ const bytes = retained ? local(target) : blob(entry);
242
+ const before = !retained && Object.hasOwn(plan.copy.files, target) && disk.has(target) ? local(target) : '';
243
+ const imports = bindings(bytes, false, source), oldBindings = bindings(before, false, source);
244
+ const typeImports = bindings(bytes, true, source), oldTypes = bindings(before, true, source);
220
245
  const edges = requests(bytes, source, target).map(request => edge(source, target, request));
221
246
  // lock.mjs reads the whole tool dynamically to identify it. Deliver that
222
247
  // same file set, including parser notices and modules outside its imports.
@@ -232,7 +257,13 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
232
257
  const declaration = source.replace(/\.mjs$/, '.d.mts').replace(/\.cjs$/, '.d.cts');
233
258
  if (declaration !== source && tree.has(declaration)) edges.push({dependency: declaration, destination: target.replace(/\.mjs$/, '.d.mts').replace(/\.cjs$/, '.d.cts')});
234
259
  const novel = directoryAdditions.has(target) && !required.has(target) && !incoming.has(target);
235
- const preserved = request => baseline.has(key(target, request));
260
+ // An incoming importer can newly require a file which the seed has just
261
+ // restored and recorded at this target pin. Close that pristine Base file
262
+ // now; its unresolved siblings are the recovery refresh's deliveries.
263
+ // Ordinary older copies retain their historical edges. Seed-owned roots
264
+ // instead close the Base dependencies of their current local bytes.
265
+ const restored = !retained && plan.copy.revision === revision && newlyRequired.has(target);
266
+ const preserved = request => !restored && baseline.has(key(target, request));
236
267
  let hold;
237
268
  for (const edge of edges) {
238
269
  const {specifier, dependency, destination, satisfied} = edge;
@@ -253,38 +284,76 @@ export function completeModuleCopies(root, plans, {tree, read, revision, base, b
253
284
  if (edge.external || preserved(edge)) continue;
254
285
  include(dependency, destination);
255
286
  const owner = recorded.get(destination);
256
- if (!adapted && !planned.has(destination) && (index.has(destination) || owner?.copy.adapted?.[destination])) {
257
- for (const [types, current, previous] of [[false, imports, oldBindings], [true, typeImports, oldTypes]]) {
258
- const exported = exportsAt(destination, types);
259
- for (const name of current.get(specifier) ?? []) if (exported && !exported.has(name) && !previous.get(specifier)?.has(name)) {
260
- const comparison = destination + '.base';
261
- const extract = baseArchive ? `cp ${quote(path.join(baseArchive, dependency))} ${quote(comparison)}` :
262
- `git -C ${quote(base)} show ${quote(revision + ':' + dependency)} > ${quote(comparison)}`;
263
- throw Error([
264
- `Cannot refresh module ${target}: ${destination} does not export ${name} required by Base ${dependency} at ${revision}. No files were refreshed.`,
265
- 'Save the incoming dependency for comparison:', extract,
266
- `Merge the required exports from ${quote(comparison)} into ${quote(destination)}, preserving seed edits.`,
267
- ...(owner?.copy.adapted?.[destination] ? ['Review the reconciled bytes and mode, then acknowledge this adaptation:', acknowledgementCommand(root, destination, recordPath)] : []),
268
- `Remove ${quote(comparison)} after reconciliation, then repeat refresh-base.`,
269
- ].join('\n'));
270
- }
271
- }
287
+ if (dependency && (retained || !planned.has(destination) && (index.has(destination) || owner?.copy.adapted?.[destination]))) {
288
+ exportChecks.push({target, destination, dependency, specifier, imports, oldBindings, typeImports, oldTypes,
289
+ ancestor: owner?.copy.adapted?.[destination] ?? owner?.copy.revision ?? plan?.copy.revision ?? revision});
290
+ }
291
+ }
292
+ if (!retained && edges.some(edge => edge.relocation)) relocations.set(target, Buffer.from(relocateDependencies(bytes, edges)));
293
+ }
294
+ // Validate against the complete effective graph, including dependencies just
295
+ // planned through a retained file's re-exports. Unknown exports must not mask
296
+ // a genuinely absent name merely because those dependencies were missing.
297
+ for (const {target, destination, dependency, specifier, imports, oldBindings, typeImports, oldTypes, ancestor} of exportChecks) {
298
+ for (const [types, current, previous] of [[false, imports, oldBindings], [true, typeImports, oldTypes]]) {
299
+ const exported = exportsAt(destination, types);
300
+ for (const name of current.get(specifier) ?? []) if (exported && !exported.has(name) && !previous.get(specifier)?.has(name)) {
301
+ const key = JSON.stringify([target, destination, name, types]);
302
+ missingExports.set(key, {target, destination, dependency, name, ancestor});
272
303
  }
273
304
  }
274
- if (!adapted && edges.some(edge => edge.relocation)) relocations.set(target, Buffer.from(relocateDependencies(bytes, edges)));
275
305
  }
276
306
  const modules = new Map();
277
307
  for (const [target, {source, entry}] of planned) if (/\.(?:[cm]?[jt]s|[jt]sx)$/.test(source)) {
278
308
  const bytes = blob(entry);
279
309
  modules.set(target, {source, bytes, dependencies: requests(bytes, source, target).map(request => edge(source, target, request).destination).filter(Boolean)});
280
310
  }
281
- for (const {source, target, adapted} of queue) if (adapted) {
311
+ for (const {source, target, retained} of queue) if (retained) {
282
312
  const bytes = local(target);
283
- // Adaptations are roots of the retained graph; their own package choices
284
- // stay seed-owned, while new delivered dependencies must be declared.
285
- modules.set(target, {source, bytes: '', dependencies: requests(bytes, source, target).map(request => edge(source, target, request).destination).filter(Boolean)});
313
+ // Only Base imports still used by the retained file participate in package
314
+ // adoption. Seed-only package choices remain outside refresh's ownership.
315
+ const baseRequests = tree.has(source) ? dependencies(tree.read(source), source) : [];
316
+ const packageRequests = dependencies(bytes, source).filter(request => baseRequests.some(incoming => key(target, incoming) === key(target, request)));
317
+ modules.set(target, {source, bytes, packageRequests,
318
+ dependencies: requests(bytes, source, target).map(request => edge(source, target, request).destination).filter(Boolean)});
319
+ }
320
+ const refusals = [...missingExports.values()].map(({target, destination, dependency, name}) =>
321
+ `Cannot refresh module ${target}: ${destination} does not export ${name} required by Base ${dependency} at ${revision}.`);
322
+ let packages;
323
+ try { packages = checkModulePackages(root, modules, packageRoots, tree); }
324
+ catch (error) { refusals.push(error.message); }
325
+ if (missingExports.size) {
326
+ refusals.push('No files were refreshed. Reconcile each retained dependency in this order:');
327
+ const retained = new Map([...missingExports.values()].map(item => [item.destination, item]));
328
+ for (const {destination, dependency, ancestor} of retained.values()) {
329
+ const comparison = destination + '.base', saved = destination + '.seed', original = destination + '.ancestor';
330
+ const extract = baseArchive ? `cp ${quote(path.join(baseArchive, dependency))} ${quote(comparison)}` :
331
+ `git -C ${quote(base)} show ${quote(revision + ':' + dependency)} > ${quote(comparison)}`;
332
+ const acquisition = baseArchive ? `--base-archive ${quote(baseArchive)}` : `--base ${quote(base)}`;
333
+ const record = recordPath === 'base-copies.json' ? '' : ` --record ${quote(recordPath)}`;
334
+ refusals.push(
335
+ `Save seed edits and the original Base version used as the merge ancestor for ${quote(destination)} (use unused backup paths):`,
336
+ `cp ${quote(destination)} ${quote(saved)}`,
337
+ ...(baseArchive ? ['Obtain the original Base version from the recorded pin for the merge ancestor.'] :
338
+ [`git -C ${quote(base)} show ${quote(ancestor + ':' + dependency)} > ${quote(original)}`]),
339
+ 'Save the incoming dependency for comparison:', extract,
340
+ 'Install and record the incoming Base file before refreshing:',
341
+ `cp ${quote(comparison)} ${quote(destination)}`,
342
+ `node ${quote(fileURLToPath(new URL('./cli.mjs', import.meta.url)))} record-base ${quote(destination)} ${quote(dependency)} ${quote(revision)} ${acquisition}${record}`,
343
+ "Add all named packages at Base's listed versions with the seed's package manager.",
344
+ `rer refresh-base --ref ${quote(revision)} ${acquisition}${record}`,
345
+ 'After refresh delivers the new Base dependencies, merge the saved seed edits onto the new Base file; resolve any conflicts:',
346
+ `git merge-file ${quote(destination)} ${quote(original)} ${quote(saved)}`,
347
+ 'If the seed source has no Base ancestor, reconcile its edits explicitly instead of guessing an ancestor.',
348
+ 'Review the reconciled bytes and mode, then acknowledge this adaptation:',
349
+ acknowledgementCommand(root, destination, recordPath),
350
+ `rer refresh-base --ref ${quote(revision)} ${acquisition}${record}`,
351
+ `Remove ${quote(comparison)}, ${quote(original)} and ${quote(saved)} after reconciliation.`,
352
+ );
353
+ }
286
354
  }
287
- const packages = checkModulePackages(root, modules, packageRoots, tree);
355
+ if (refusals.length) throw Error(refusals.join('\n'));
356
+
288
357
  for (const [target, item] of packages.withheld) {
289
358
  const {plan, source} = planned.get(target);
290
359
  plan.sources = plan.sources.filter(([name]) => name !== source);
@@ -22,9 +22,16 @@ function* nodes(root) {
22
22
 
23
23
  const parsed = new Map();
24
24
 
25
+ // Authoring follows module imports. History isolation also follows URL resources
26
+ // that bundlers can publish without importing them into the authoring tool.
27
+ export function dependencies(source, filename = 'module.mjs', {resources = false} = {}) {
28
+ const result = edges(source, filename);
29
+ return resources ? result : result.filter(request => request.kind !== 'resource');
30
+ }
31
+
25
32
  // Parsing, including erased TS edges and calls nested in templates/JSX, precedes
26
33
  // resolution. Every resulting edge uses the same virtual Node resolver.
27
- export function dependencies(source, filename = 'module.mjs') {
34
+ function edges(source, filename) {
28
35
  let versions = parsed.get(filename);
29
36
  if (versions?.has(source)) return versions.get(source);
30
37
  const plugins = ['decorators-legacy', 'deprecatedImportAssert'];
@@ -82,6 +89,12 @@ export function dependencies(source, filename = 'module.mjs') {
82
89
  else if (node.type === 'ImportExpression') add(node.source, 'import');
83
90
  else if (call(node)) {
84
91
  let callee = unwrap(node.callee), argument = node.arguments[0];
92
+ // Vite emits literal import.meta.url resources, including the URL nested
93
+ // in Worker/SharedWorker constructors, without an import declaration.
94
+ const base = unwrap(node.arguments[1]), meta = unwrap(base?.object);
95
+ if (node.type === 'NewExpression' && callee?.type === 'Identifier' && callee.name === 'URL'
96
+ && member(base) && property(base) === 'url' && meta?.type === 'MetaProperty'
97
+ && meta.meta.name === 'import' && meta.property.name === 'meta') add(argument, 'resource');
85
98
  if (member(callee) && property(callee) === 'bind' && requireFunction(callee.object)) { add(node.arguments[1], 'require'); continue; }
86
99
  if (member(callee) && callee.object?.type === 'Identifier' && callee.object.name === 'Reflect' && ['apply', 'construct'].includes(property(callee)) && requireFunction(node.arguments[0])) {
87
100
  add(node.arguments[property(callee) === 'apply' ? 2 : 1]?.elements?.[0], 'require'); continue;
@@ -36,7 +36,7 @@ export function checkModulePackages(root, modules, roots, tree) {
36
36
  if (!manifests.has(reference)) manifests.set(reference, JSON.parse(tree.read(reference)));
37
37
  return version(manifests.get(reference), name);
38
38
  }
39
- for (const [target, module] of modules) for (const request of dependencies(module.bytes, module.source)) {
39
+ for (const [target, module] of modules) for (const request of module.packageRequests ?? dependencies(module.bytes, module.source)) {
40
40
  const name = packageName(request.specifier);
41
41
  if (!name) continue;
42
42
  const scope = {};
@@ -47,7 +47,10 @@ export function checkModulePackages(root, modules, roots, tree) {
47
47
  if (!packages.has(key)) packages.set(key, {package: name, version: declared ?? null, baseVersion: pinned ?? null,
48
48
  conflict: Boolean(declared && pinned && declared !== pinned), files: []});
49
49
  packages.get(key).files.push(target);
50
- if (!declared) missing.set(target, {package: name, baseVersion: pinned ?? null});
50
+ if (!declared) {
51
+ if (!missing.has(target)) missing.set(target, new Map());
52
+ missing.get(target).set(name, {package: name, baseVersion: pinned ?? null});
53
+ }
51
54
  }
52
55
  const required = new Set();
53
56
  function retain(target) {
@@ -56,9 +59,13 @@ export function checkModulePackages(root, modules, roots, tree) {
56
59
  for (const dependency of modules.get(target).dependencies) retain(dependency);
57
60
  }
58
61
  roots.forEach(retain);
59
- for (const [target, item] of missing) if (required.has(target)) {
60
- throw Error(`Cannot refresh module ${target}: package ${item.package} is not declared in the seed's package.json${item.baseVersion ? ` (Base uses ${item.baseVersion})` : ''}. This module is required by retained source. Review its adoption, declare and install the dependency with the seed's package manager, then repeat refresh-base; no files were refreshed.`);
62
+ const refusals = [];
63
+ for (const [target, items] of missing) if (required.has(target)) for (const item of items.values()) {
64
+ refusals.push(`Cannot refresh module ${target}: package ${item.package} is not declared in the seed's package.json${item.baseVersion ? ` (Base uses ${item.baseVersion})` : ''}. This module is required by retained source.`);
61
65
  }
66
+ if (refusals.length) throw Error([...refusals,
67
+ "Review their adoption, declare and install all named dependencies at Base's listed versions with the seed's package manager, then repeat refresh-base; no files were refreshed.",
68
+ ].join('\n'));
62
69
  // Withhold the whole connected optional addition, including its importers
63
70
  // and exclusive siblings, rather than leaving half of a feature behind.
64
71
  const neighbours = new Map([...modules.keys()].map(target => [target, new Set()]));
@@ -71,6 +78,6 @@ export function checkModulePackages(root, modules, roots, tree) {
71
78
  withheld.set(target, {...reason, path: target, originPath: modules.get(target).source, reason: 'undeclared-package'});
72
79
  for (const neighbour of neighbours.get(target)) hold(neighbour, reason);
73
80
  }
74
- for (const [target, reason] of missing) hold(target, reason);
81
+ for (const [target, items] of missing) hold(target, items.values().next().value);
75
82
  return {withheld, packageDependencies: [...packages.values()].map(item => ({...item, files: [...new Set(item.files)].sort()}))};
76
83
  }
@@ -1,53 +1,16 @@
1
- // Lex module syntax without treating comments, strings or template text as code.
2
- // Template interpolations are code, including nested templates and import().
3
- export function tokens(source) {
4
- const result = [];
5
- let i = 0;
6
- function quoted(quote) {
7
- const start = i++;
8
- while (i < source.length) {
9
- if (source[i] === '\\') { i += 2; continue; }
10
- if (source[i++] === quote) break;
11
- }
12
- return source.slice(start, i);
13
- }
14
- function template() {
15
- const start = i++;
16
- let interpolated = false;
17
- while (i < source.length) {
18
- if (source[i] === '\\') { i += 2; continue; }
19
- if (source[i] === '`') { i++; break; }
20
- if (source[i] === '$' && source[i + 1] === '{') {
21
- interpolated = true; i += 2; result.push(';'); scan(true); result.push(';');
22
- } else i++;
23
- }
24
- if (!interpolated) result.push(source.slice(start, i));
25
- }
26
- function scan(interpolation = false) {
27
- let braces = 0;
28
- while (i < source.length) {
29
- const c = source[i];
30
- if (/\s/.test(c)) { i++; continue; }
31
- if (source.startsWith('//', i)) {
32
- while (i < source.length && source[i] !== '\n') i++;
33
- continue;
34
- }
35
- if (source.startsWith('/*', i)) {
36
- const end = source.indexOf('*/', i + 2); i = end < 0 ? source.length : end + 2; continue;
37
- }
38
- if (c === "'" || c === '"') { result.push(quoted(c)); continue; }
39
- if (c === '`') { template(); continue; }
40
- if (interpolation && c === '}' && !braces) { i++; return; }
41
- if (c === '{') braces++;
42
- if (c === '}') braces--;
43
- if (/[\w$]/.test(c)) {
44
- const start = i++;
45
- while (i < source.length && /[\w$]/.test(source[i])) i++;
46
- result.push(source.slice(start, i));
47
- } else { result.push(c); i++; }
48
- }
49
- }
50
- scan(); return result;
1
+ import {parse} from './vendor/babel-parser/babel-parser/index.mjs';
2
+
3
+ // Let the maintained parser distinguish strings, regex literals and template
4
+ // text. Keep raw token spelling for the conservative binding/export checks.
5
+ export function tokens(source, filename = 'module.ts') {
6
+ const plugins = ['decorators-legacy', 'deprecatedImportAssert'];
7
+ if (/\.[cm]?tsx?$/.test(filename)) plugins.push(['typescript', {dts: /\.d\.[cm]?ts$/.test(filename)}]);
8
+ if (/\.[jt]sx$/.test(filename)) plugins.push('jsx');
9
+ const ast = parse(source, {sourceFilename: filename, sourceType: 'unambiguous', tokens: true,
10
+ allowReturnOutsideFunction: true, allowUndeclaredExports: true, plugins});
11
+ return ast.tokens.filter(token => typeof token.type !== 'string' &&
12
+ !['eof', 'template', '`'].includes(token.type.label)).map(token =>
13
+ token.type.label === '${' ? ';' : source.slice(token.start, token.end));
51
14
  }
52
15
 
53
16
  export function unquote(value) {
@@ -5,8 +5,8 @@ export {resolve, external} from './module-resolution.mjs';
5
5
  export {dependencies} from './module-edges.mjs';
6
6
 
7
7
  // Binding checks are lexical: unknown export forms remain unknown, never absent.
8
- export function bindings(source, types = false) {
9
- const t = tokens(source), result = new Map();
8
+ export function bindings(source, types = false, filename = 'module.ts') {
9
+ const t = tokens(source, filename), result = new Map();
10
10
  for (let i = 0; i < t.length; i++) {
11
11
  if (!['import', 'export'].includes(t[i]) || ['.', '('].includes(t[i + 1])) continue;
12
12
  let end = i + 1;
@@ -31,8 +31,8 @@ export function bindings(source, types = false) {
31
31
  }
32
32
  return result;
33
33
  }
34
- export function lexicalExports(source, star, types = false) {
35
- const t = tokens(source), names = new Set();
34
+ export function lexicalExports(source, star, types = false, filename = 'module.ts') {
35
+ const t = tokens(source, filename), names = new Set();
36
36
  for (let i = 0; i < t.length; i++) {
37
37
  if (t[i] !== 'export') continue;
38
38
  let j = i + 1;
@@ -0,0 +1,87 @@
1
+ import fs from 'node:fs'
2
+ import { createHash } from 'node:crypto'
3
+ import { execFileSync } from 'node:child_process'
4
+
5
+ export const anchorPath = 'docs/contract/ANCHOR.json'
6
+ const sourceFiles = ['CONTRACT.md', 'ACCEPTANCE.md', 'docs/CLAIMS.md', 'CLAIMS.md']
7
+ const sha = /^[0-9a-f]{40}$/
8
+ const fail = message => { throw Error(`${anchorPath}: contract_anchor_invalid: ${message}`) }
9
+ const objectId = (type, bytes) => createHash('sha1').update(`${type} ${bytes.length}\0`).update(bytes).digest('hex')
10
+
11
+ // The commit authenticates the root tree, which authenticates each source blob
12
+ // (and absence of optional sources). No hash supplied only by the record is trusted.
13
+ function resolveSnapshot(commit, load) {
14
+ if (!sha.test(commit)) fail('expected a full anchor commit SHA.')
15
+ const object = (type, id) => {
16
+ const bytes = load(type, id)
17
+ if (objectId(type, bytes) !== id) fail(`${type} ${id} has mismatching bytes.`)
18
+ return bytes
19
+ }
20
+ const treeId = /^tree ([0-9a-f]{40})\n/.exec(object('commit', commit).toString('utf8'))?.[1]
21
+ if (!treeId) fail('anchor commit has no root tree.')
22
+ const trees = new Map()
23
+ function tree(id) {
24
+ if (trees.has(id)) return trees.get(id)
25
+ const bytes = object('tree', id), entries = new Map()
26
+ let offset = 0
27
+ while (offset < bytes.length) {
28
+ const end = bytes.indexOf(0, offset)
29
+ if (end < 0 || end + 21 > bytes.length) fail(`malformed tree ${id}.`)
30
+ const entry = /^(40000|100644|100755|120000|160000) ([^/\0]+)$/.exec(bytes.subarray(offset, end).toString('utf8'))
31
+ if (!entry || entries.has(entry[2])) fail(`malformed or duplicate entry in tree ${id}.`)
32
+ entries.set(entry[2], { mode: entry[1], id: bytes.subarray(end + 1, end + 21).toString('hex') })
33
+ offset = end + 21
34
+ }
35
+ trees.set(id, entries)
36
+ return entries
37
+ }
38
+ const files = {}
39
+ for (const name of sourceFiles) {
40
+ const parts = name.split('/')
41
+ let directory = treeId, entry
42
+ for (const [index, part] of parts.entries()) {
43
+ entry = tree(directory).get(part)
44
+ if (!entry) break
45
+ if (index < parts.length - 1) {
46
+ if (entry.mode !== '40000') { entry = undefined; break }
47
+ directory = entry.id
48
+ }
49
+ }
50
+ if (!entry) continue
51
+ if (!['100644', '100755', '120000'].includes(entry.mode)) fail(`${name} is not a blob.`)
52
+ files[name] = object('blob', entry.id).toString('utf8')
53
+ }
54
+ if (!files['CONTRACT.md']) fail('anchor has no CONTRACT.md.')
55
+ return { commit, files }
56
+ }
57
+
58
+ export function readAnchor(commit) {
59
+ if (!fs.existsSync(anchorPath)) return undefined
60
+ let record
61
+ try { record = JSON.parse(fs.readFileSync(anchorPath, 'utf8')) }
62
+ catch { fail('record must be valid JSON.') }
63
+ if (record?.schema !== 1 || record.commit !== commit || !record.objects || typeof record.objects !== 'object' || Array.isArray(record.objects))
64
+ fail(`expected schema 1 and anchor commit ${commit}.`)
65
+ const used = new Set()
66
+ const snapshot = resolveSnapshot(commit, (type, id) => {
67
+ used.add(id)
68
+ const entry = Object.hasOwn(record.objects, id) ? record.objects[id] : undefined
69
+ if (entry?.type !== type || typeof entry.data !== 'string') fail(`missing ${type} ${id}.`)
70
+ const bytes = Buffer.from(entry.data, 'base64')
71
+ if (bytes.toString('base64') !== entry.data) fail(`${type} ${id} is not canonical base64.`)
72
+ return bytes
73
+ })
74
+ if (Object.keys(record.objects).some(id => !used.has(id))) fail('record contains objects outside the anchor proof.')
75
+ return snapshot
76
+ }
77
+
78
+ // Run once while the anchor is available, then commit this portable proof.
79
+ export function createAnchor(commit) {
80
+ const objects = {}
81
+ resolveSnapshot(commit, (type, id) => {
82
+ const bytes = execFileSync('git', ['cat-file', type, id], { stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 })
83
+ objects[id] = { type, data: bytes.toString('base64') }
84
+ return bytes
85
+ })
86
+ return { schema: 1, commit, objects }
87
+ }
@@ -5,6 +5,7 @@ import path from 'node:path'
5
5
  import { execFileSync } from 'node:child_process'
6
6
  import { parseContract, clauseIdSource, plainText } from './seed-contract.mjs'
7
7
  import { contractProseFindings, printProseFindings } from './contract-prose.mjs'
8
+ import { anchorPath, createAnchor, readAnchor } from './contract-anchor.mjs'
8
9
 
9
10
  const marker = '<!-- Generated from CONTRACT.md by contract-docs. Edit CONTRACT.md, then regenerate. -->'
10
11
  const idPattern = new RegExp(`^${clauseIdSource}$`)
@@ -54,6 +55,12 @@ function snapshot(reference) {
54
55
  if (!files['CONTRACT.md']) throw Error(`${reference} has no CONTRACT.md.`)
55
56
  return { commit, files }
56
57
  }
58
+ function anchoredSnapshot(commit) {
59
+ const recorded = readAnchor(commit)
60
+ if (recorded) return recorded
61
+ try { return snapshot(commit) }
62
+ catch (error) { throw Error(`${anchorPath}: contract_anchor_missing: original ${commit} is unavailable; record it with anchor --old <ref> in a checkout with history. ${error.message}`) }
63
+ }
57
64
  function summaryRange(text) {
58
65
  const lines = linesOf(text), start = lines.findIndex(line => cells(line).join('|') === 'Clauses|Done|Partial|Missing|Total')
59
66
  if (start < 0) return undefined
@@ -169,7 +176,7 @@ function generate(check = false) {
169
176
  const coverage = read(covMapPath)
170
177
  if (coverage !== undefined) {
171
178
  let original
172
- try { original = snapshot(JSON.parse(coverage).old?.commit) }
179
+ try { original = anchoredSnapshot(JSON.parse(coverage).old?.commit) }
173
180
  catch (error) { throw Error(`${covMapPath}: original SHA is unavailable: ${error.message}`) }
174
181
  validateOriginalClaims(original)
175
182
  }
@@ -380,7 +387,7 @@ function validateClaimSource(text, rows = claimRows(text), old) {
380
387
  }
381
388
  if (old && record.old !== old.commit) throw Error('CONTRACT.md: contract-claim-source old SHA differs from the coverage original.')
382
389
  let original
383
- try { original = old ?? snapshot(record.old) } catch (error) { throw Error(`CONTRACT.md: contract-claim-source old ${record.old}: ${error.message}`) }
390
+ try { original = old ?? anchoredSnapshot(record.old) } catch (error) { throw Error(`CONTRACT.md: contract-claim-source old ${record.old}: ${error.message}`) }
384
391
  const selected = originalClaims(original), ids = new Set(parseContract(original.files['CONTRACT.md']).clauses.map(clause => clause.id))
385
392
  validateOriginalClaims(original, rows)
386
393
  if (record.claims.length !== selected.rows.length) throw Error('CONTRACT.md: contract-claim-source must retain every original claim once.')
@@ -928,12 +935,12 @@ function checkProse() {
928
935
  const text = read('CONTRACT.md');
929
936
  if (text === undefined) throw Error('CONTRACT.md does not exist.');
930
937
  const coverage = read(covMapPath) === undefined ? undefined : covReadMap();
931
- const sources = coverage ? covScope(snapshot(coverage.old?.commit)) : [];
938
+ const sources = coverage ? covScope(anchoredSnapshot(coverage.old?.commit)) : [];
932
939
  const findings = contractProseFindings({ text, clauses: parseContract(withoutSummary(text)).clauses, coverage, sources, generatedStatement: covGeneratedStatement });
933
940
  if (printProseFindings(findings)) process.exitCode = 1;
934
941
  }
935
942
 
936
- const usage = 'Usage: contract-docs.mjs write|check|check-prose|id-map --old <ref>|coverage init|check --old <ref>|coverage rebase --from <ref> --onto <ref>|convert --old <ref> [--old-acceptance <ref>] [--claim-map <file>]';
943
+ const usage = 'Usage: contract-docs.mjs write|check|check-prose|anchor --old <ref>|id-map --old <ref>|coverage init|check --old <ref>|coverage rebase --from <ref> --onto <ref>|convert --old <ref> [--old-acceptance <ref>] [--claim-map <file>]';
937
944
  function main(args) {
938
945
  const [command, ...rest] = args
939
946
  const option = (name, description = 'Git reference') => {
@@ -946,6 +953,15 @@ function main(args) {
946
953
  else if (command === 'check' && !rest.length) { checkProse(); generate(true) }
947
954
  else if (command === 'check-prose' && !rest.length) checkProse()
948
955
  else if (command === '--help' && !rest.length) console.log(usage)
956
+ else if (command === 'anchor') {
957
+ const old = snapshot(option('--old'))
958
+ const expected = read(covMapPath) === undefined ? undefined : covReadMap().old?.commit
959
+ if (expected !== undefined && old.commit !== expected) throw Error(`${anchorPath}: contract_anchor_invalid: --old must match COVERAGE.json old.commit ${expected}.`)
960
+ const provenance = readClaimSource(read('CONTRACT.md') ?? '')
961
+ if (provenance && old.commit !== provenance.old) throw Error(`${anchorPath}: contract_anchor_invalid: --old must match contract-claim-source old ${provenance.old}.`)
962
+ put(anchorPath, json(createAnchor(old.commit)))
963
+ console.log(`Recorded ${anchorPath} for ${old.commit}.`)
964
+ }
949
965
  else if (command === 'id-map') idMap(snapshot(option('--old')))
950
966
  else if (command === 'coverage' && rest[0] === 'init') coverageInit(snapshot(option('--old')))
951
967
  else if (command === 'coverage' && rest[0] === 'check') coverageCheck(snapshot(option('--old')))