@mfdaves/okf-mcp 0.9.1 → 0.13.0-rc.1

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 (115) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +452 -26
  3. package/bin/okf-mcp.js +6 -1
  4. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  5. package/okf/okf-mcp/index.md +2 -1
  6. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  7. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  8. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  9. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  10. package/okf/okf-mcp/policies/authoring-safety.md +28 -5
  11. package/okf/okf-mcp/runtime/indexer.md +14 -1
  12. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  13. package/okf/okf-mcp/specs/producer-api.md +16 -2
  14. package/package.json +17 -5
  15. package/server.json +38 -2
  16. package/src/assets.js +165 -73
  17. package/src/authoring/candidates.js +434 -0
  18. package/src/authoring/git-preflight.js +225 -0
  19. package/src/authoring/git-publish.js +783 -0
  20. package/src/authoring/live.js +757 -0
  21. package/src/authoring/paths.js +112 -0
  22. package/src/authoring/policy-hook.js +221 -0
  23. package/src/authoring/proposal-policy.js +159 -0
  24. package/src/authoring/receipts.js +373 -0
  25. package/src/authoring/render.js +38 -0
  26. package/src/authoring/shared.js +75 -0
  27. package/src/authoring/staging.js +216 -0
  28. package/src/authoring.js +386 -287
  29. package/src/cache/files.js +147 -0
  30. package/src/cache/lock.js +201 -0
  31. package/src/cache/paths.js +197 -0
  32. package/src/cache/store.js +703 -0
  33. package/src/catalog-text.js +19 -0
  34. package/src/cli/commands.js +448 -0
  35. package/src/cli/http-options.js +193 -0
  36. package/src/cli/options.js +554 -0
  37. package/src/cli/usage.js +96 -0
  38. package/src/cli.js +18 -932
  39. package/src/computation.js +99 -61
  40. package/src/context/assemble.js +567 -0
  41. package/src/context/cli-options.js +88 -0
  42. package/src/context/score.js +234 -0
  43. package/src/context/sections.js +274 -0
  44. package/src/embed/interface.js +160 -0
  45. package/src/embed/openai.js +715 -0
  46. package/src/embed/prepare.js +182 -0
  47. package/src/embed/units.js +96 -0
  48. package/src/error-details.js +53 -0
  49. package/src/git-source.js +112 -52
  50. package/src/graph.js +95 -37
  51. package/src/http-server.js +36 -17
  52. package/src/index.js +15 -0
  53. package/src/indexer/assemble.js +566 -0
  54. package/src/indexer/build.js +290 -0
  55. package/src/indexer/cache.js +81 -0
  56. package/src/indexer/edges.js +430 -0
  57. package/src/indexer/index.js +44 -0
  58. package/src/indexer/paths.js +178 -0
  59. package/src/indexer/resolve.js +282 -0
  60. package/src/indexer/update.js +720 -0
  61. package/src/indexer.js +3 -1068
  62. package/src/live-authoring.js +4 -2329
  63. package/src/markdown.js +21 -16
  64. package/src/mcp/auth.js +409 -0
  65. package/src/mcp/http.js +317 -0
  66. package/src/mcp/principal.js +59 -0
  67. package/src/mcp/registry.js +356 -0
  68. package/src/mcp/resources.js +45 -0
  69. package/src/mcp/server.js +567 -0
  70. package/src/mcp/tools/catalog.js +247 -0
  71. package/src/mcp/tools/computation.js +83 -0
  72. package/src/mcp/tools/context.js +133 -0
  73. package/src/mcp/tools/graph.js +167 -0
  74. package/src/mcp/tools/live-authoring.js +316 -0
  75. package/src/mcp/tools/migration.js +86 -0
  76. package/src/mcp/tools/producers.js +79 -0
  77. package/src/mcp/tools/proposals.js +225 -0
  78. package/src/mcp/tools/provenance.js +87 -0
  79. package/src/mcp/tools/remote.js +79 -0
  80. package/src/mcp/tools/search.js +242 -0
  81. package/src/mcp-server.js +3 -1611
  82. package/src/migration.js +431 -253
  83. package/src/parser.js +245 -130
  84. package/src/plugins.js +71 -48
  85. package/src/policy/write-policy.js +713 -0
  86. package/src/producer-publisher.js +202 -78
  87. package/src/producers.js +311 -103
  88. package/src/project.js +346 -93
  89. package/src/remote.js +96 -61
  90. package/src/search/cli-options.js +107 -0
  91. package/src/search/confidence.js +61 -0
  92. package/src/search/dense.js +304 -0
  93. package/src/search/embedding-cli.js +57 -0
  94. package/src/search/embedding-config.js +217 -0
  95. package/src/search/fusion.js +249 -0
  96. package/src/search/hybrid.js +526 -0
  97. package/src/search/languages.js +200 -0
  98. package/src/search/lexical.js +695 -0
  99. package/src/search/query.js +620 -0
  100. package/src/search/stem/among.js +43 -0
  101. package/src/search/stem/base-stemmer.js +311 -0
  102. package/src/search/stem/en-regions.js +456 -0
  103. package/src/search/stem/en-suffixes.js +664 -0
  104. package/src/search/stem/en-tables.js +176 -0
  105. package/src/search/stem/en.js +238 -0
  106. package/src/search/stem/it-regions.js +459 -0
  107. package/src/search/stem/it-suffixes.js +471 -0
  108. package/src/search/stem/it-tables.js +257 -0
  109. package/src/search/stem/it.js +155 -0
  110. package/src/search-index.js +2 -81
  111. package/src/search.js +2 -252
  112. package/src/store.js +134 -81
  113. package/src/tool-packs.js +346 -0
  114. package/src/v02.js +301 -105
  115. package/src/validation.js +24 -20
package/src/migration.js CHANGED
@@ -1,12 +1,7 @@
1
1
  "use strict";
2
2
 
3
3
  const path = require("path");
4
- const {
5
- itemLiteral,
6
- markdownStructure,
7
- nodeText,
8
- sectionNodes,
9
- } = require("./markdown");
4
+ const { itemLiteral, markdownStructure, nodeText, sectionNodes } = require("./markdown");
10
5
 
11
6
  const V02_VERSION = "0.2";
12
7
 
@@ -63,21 +58,20 @@ function documentSummary(doc) {
63
58
  }
64
59
 
65
60
  function issue(code, message, details) {
66
- return Object.assign({
67
- code,
68
- severity: "error",
69
- message,
70
- }, details || {});
61
+ return Object.assign(
62
+ {
63
+ code,
64
+ severity: "error",
65
+ message,
66
+ },
67
+ details || {},
68
+ );
71
69
  }
72
70
 
73
71
  function issueKey(entry) {
74
- return [
75
- entry.code,
76
- entry.bundle,
77
- entry.path || entry.uri,
78
- entry.value,
79
- entry.message,
80
- ].map((value) => String(value || "")).join("\u0000");
72
+ return [entry.code, entry.bundle, entry.path || entry.uri, entry.value, entry.message]
73
+ .map((value) => String(value || ""))
74
+ .join("\u0000");
81
75
  }
82
76
 
83
77
  function uniqueIssues(entries) {
@@ -106,8 +100,9 @@ function citationSource(item) {
106
100
  const title = String(url[1] || "").trim();
107
101
  return Object.assign({ resource: url[2] }, title ? { title } : {});
108
102
  }
109
- const pathValue = text.match(/^`((?:\.\.?\/|\/|references\/)[^`]+)`$/)
110
- || text.match(/^((?:\.\.?\/|\/|references\/)[^\s]+)$/);
103
+ const pathValue =
104
+ text.match(/^`((?:\.\.?\/|\/|references\/)[^`]+)`$/) ||
105
+ text.match(/^((?:\.\.?\/|\/|references\/)[^\s]+)$/);
111
106
  if (pathValue) {
112
107
  return { resource: pathValue[1] };
113
108
  }
@@ -119,9 +114,9 @@ function citationSource(item) {
119
114
 
120
115
  function extractLegacyCitations(body) {
121
116
  const structure = markdownStructure(body);
122
- const headings = structure.headings.filter((heading) => (
123
- heading.level === 1 && heading.text.toLowerCase() === "citations"
124
- ));
117
+ const headings = structure.headings.filter(
118
+ (heading) => heading.level === 1 && heading.text.toLowerCase() === "citations",
119
+ );
125
120
  if (!headings.length) {
126
121
  return { found: false, sources: [], unparsed: [], sectionCount: 0 };
127
122
  }
@@ -134,16 +129,22 @@ function extractLegacyCitations(body) {
134
129
  const flatBlocks = firstNonList === -1 ? blocks : blocks.slice(0, firstNonList);
135
130
  const lists = new Set(flatBlocks.filter((node) => node.type === "list"));
136
131
  const sources = [];
137
- const unparsed = blocks.filter((node) => node.type !== "list").map((node) => (
138
- nodeText(node).trim() || `[${node.type}]`
139
- ));
132
+ const unparsed = blocks
133
+ .filter((node) => node.type !== "list")
134
+ .map((node) => nodeText(node).trim() || `[${node.type}]`);
140
135
  const seen = new Set();
141
136
  const items = structure.items.filter((item) => lists.has(item.node.parent));
142
137
  for (const item of items) {
143
138
  const literal = itemLiteral(structure, item);
144
139
  const source = literal && citationSource(literal);
145
140
  if (!source) {
146
- unparsed.push(literal || structure.lines.slice(item.startLine - 1, item.endLine).join(" ").trim());
141
+ unparsed.push(
142
+ literal ||
143
+ structure.lines
144
+ .slice(item.startLine - 1, item.endLine)
145
+ .join(" ")
146
+ .trim(),
147
+ );
147
148
  continue;
148
149
  }
149
150
  if (!seen.has(source.resource)) {
@@ -159,7 +160,9 @@ function normalizedTimestamp(value) {
159
160
  return value.toISOString();
160
161
  }
161
162
  const text = String(value || "").trim();
162
- const match = text.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-](\d{2}):(\d{2}))$/);
163
+ const match = text.match(
164
+ /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-](\d{2}):(\d{2}))$/,
165
+ );
163
166
  if (!match) {
164
167
  return null;
165
168
  }
@@ -173,22 +176,40 @@ function normalizedTimestamp(value) {
173
176
  const offsetMinute = match[9] === undefined ? 0 : Number(match[9]);
174
177
  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
175
178
  const monthDays = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
176
- if (month < 1 || month > 12 || day < 1 || day > monthDays[month - 1]
177
- || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
179
+ if (
180
+ month < 1 ||
181
+ month > 12 ||
182
+ day < 1 ||
183
+ day > monthDays[month - 1] ||
184
+ hour > 23 ||
185
+ minute > 59 ||
186
+ second > 59 ||
187
+ offsetHour > 23 ||
188
+ offsetMinute > 59
189
+ ) {
178
190
  return null;
179
191
  }
180
192
  return Number.isFinite(Date.parse(text)) ? text : null;
181
193
  }
182
194
 
183
195
  function unsafeLocalResource(documentPath, resource) {
184
- const raw = String(resource || "").trim().replace(/\\/g, "/").split("#")[0];
196
+ const raw = String(resource || "")
197
+ .trim()
198
+ .replace(/\\/g, "/")
199
+ .split("#")[0];
185
200
  if (!raw || raw.startsWith("//") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) {
186
201
  return false;
187
202
  }
188
203
  const relative = raw.startsWith("/")
189
204
  ? path.posix.normalize(raw.slice(1))
190
205
  : path.posix.normalize(path.posix.join(path.posix.dirname(normalizePath(documentPath)), raw));
191
- return !relative || relative === "." || relative === ".." || relative.startsWith("../") || path.posix.isAbsolute(relative);
206
+ return (
207
+ !relative ||
208
+ relative === "." ||
209
+ relative === ".." ||
210
+ relative.startsWith("../") ||
211
+ path.posix.isAbsolute(relative)
212
+ );
192
213
  }
193
214
 
194
215
  function validActor(value) {
@@ -198,8 +219,7 @@ function validActor(value) {
198
219
 
199
220
  function actorMappingFor(doc, options) {
200
221
  const mappings = (options && options.actorMappings) || {};
201
- const keys = [doc && doc.uri, doc && doc.pathUri, doc && doc.path, "$default"]
202
- .filter(Boolean);
222
+ const keys = [doc && doc.uri, doc && doc.pathUri, doc && doc.path, "$default"].filter(Boolean);
203
223
  for (const key of keys) {
204
224
  if (!hasOwn(mappings, key)) {
205
225
  continue;
@@ -225,10 +245,12 @@ function generatedPathSet(options) {
225
245
 
226
246
  function isGeneratedFile(doc, options) {
227
247
  const frontmatter = (doc && doc.frontmatter) || {};
228
- return generatedPathSet(options).has(normalizePath(doc && doc.path))
229
- || Boolean(doc && (doc.generatedFile === true || doc.isGenerated === true))
230
- || frontmatter.generated_file === true
231
- || frontmatter.generatedFile === true;
248
+ return (
249
+ generatedPathSet(options).has(normalizePath(doc && doc.path)) ||
250
+ Boolean(doc && (doc.generatedFile === true || doc.isGenerated === true)) ||
251
+ frontmatter.generated_file === true ||
252
+ frontmatter.generatedFile === true
253
+ );
232
254
  }
233
255
 
234
256
  function discoverCollisions(documents, options) {
@@ -236,34 +258,46 @@ function discoverCollisions(documents, options) {
236
258
  const aliases = new Map();
237
259
  const collisions = [];
238
260
 
239
- documents.filter((doc) => !doc.reserved).forEach((doc) => {
240
- const frontmatter = doc.frontmatter || {};
241
- const id = String(frontmatter.id || doc.uri || doc.pathUri || "").trim();
242
- if (id) {
243
- const normalized = id.toLowerCase();
244
- if (!ids.has(normalized)) {
245
- ids.set(normalized, { value: id, documents: [] });
246
- }
247
- ids.get(normalized).documents.push(documentSummary(doc));
248
- }
249
- const docAliases = Array.isArray(doc.uriAliases) ? doc.uriAliases : [];
250
- new Set(docAliases.map((value) => String(value).trim()).filter(Boolean)).forEach((alias) => {
251
- const normalized = alias.toLowerCase();
252
- if (!aliases.has(normalized)) {
253
- aliases.set(normalized, { value: alias, documents: [] });
261
+ documents
262
+ .filter((doc) => !doc.reserved)
263
+ .forEach((doc) => {
264
+ const frontmatter = doc.frontmatter || {};
265
+ const id = String(frontmatter.id || doc.uri || doc.pathUri || "").trim();
266
+ if (id) {
267
+ const normalized = id.toLowerCase();
268
+ if (!ids.has(normalized)) {
269
+ ids.set(normalized, { value: id, documents: [] });
270
+ }
271
+ ids.get(normalized).documents.push(documentSummary(doc));
254
272
  }
255
- aliases.get(normalized).documents.push(documentSummary(doc));
273
+ const docAliases = Array.isArray(doc.uriAliases) ? doc.uriAliases : [];
274
+ new Set(docAliases.map((value) => String(value).trim()).filter(Boolean)).forEach((alias) => {
275
+ const normalized = alias.toLowerCase();
276
+ if (!aliases.has(normalized)) {
277
+ aliases.set(normalized, { value: alias, documents: [] });
278
+ }
279
+ aliases.get(normalized).documents.push(documentSummary(doc));
280
+ });
256
281
  });
257
- });
258
282
 
259
283
  ids.forEach((entry) => {
260
284
  if (entry.documents.length > 1) {
261
- collisions.push({ kind: "id", value: entry.value, documents: entry.documents, origin: "discovered" });
285
+ collisions.push({
286
+ kind: "id",
287
+ value: entry.value,
288
+ documents: entry.documents,
289
+ origin: "discovered",
290
+ });
262
291
  }
263
292
  });
264
293
  aliases.forEach((entry, key) => {
265
294
  if (entry.documents.length > 1) {
266
- collisions.push({ kind: "alias", value: entry.value, documents: entry.documents, origin: "discovered" });
295
+ collisions.push({
296
+ kind: "alias",
297
+ value: entry.value,
298
+ documents: entry.documents,
299
+ origin: "discovered",
300
+ });
267
301
  }
268
302
  if (ids.has(key)) {
269
303
  const idEntry = ids.get(key);
@@ -285,9 +319,11 @@ function discoverCollisions(documents, options) {
285
319
  ["alias", options && options.aliasCollisions],
286
320
  ].forEach(([kind, entries]) => {
287
321
  (Array.isArray(entries) ? entries : []).forEach((entry) => {
288
- collisions.push(typeof entry === "string"
289
- ? { kind, value: entry, documents: [], origin: "provided" }
290
- : Object.assign({ kind, documents: [], origin: "provided" }, entry || {}));
322
+ collisions.push(
323
+ typeof entry === "string"
324
+ ? { kind, value: entry, documents: [], origin: "provided" }
325
+ : Object.assign({ kind, documents: [], origin: "provided" }, entry || {}),
326
+ );
291
327
  });
292
328
  });
293
329
  return collisions;
@@ -314,43 +350,59 @@ function collectReferencedAssets(documents) {
314
350
  if (typeof resource !== "string" || !resource.trim()) {
315
351
  return;
316
352
  }
317
- const entry = Object.assign({
318
- uri: documentIdentity(doc),
319
- path: normalizePath(doc.path),
320
- field,
321
- kind,
322
- resource: resource.trim(),
323
- referenceKind: referenceKind(resource),
324
- }, extra || {});
353
+ const entry = Object.assign(
354
+ {
355
+ uri: documentIdentity(doc),
356
+ path: normalizePath(doc.path),
357
+ field,
358
+ kind,
359
+ resource: resource.trim(),
360
+ referenceKind: referenceKind(resource),
361
+ },
362
+ extra || {},
363
+ );
325
364
  const key = [entry.uri, field, entry.resource, entry.sourceId || ""].join("\u0000");
326
365
  if (!seen.has(key)) {
327
366
  seen.add(key);
328
367
  assets.push(entry);
329
368
  }
330
369
  }
331
- documents.filter((doc) => !doc.reserved).forEach((doc) => {
332
- const fm = doc.frontmatter || {};
333
- add(doc, "resource", "concept_resource", fm.resource);
334
- (Array.isArray(fm.sources) ? fm.sources : []).forEach((source, index) => {
335
- if (source && typeof source === "object") {
336
- add(doc, `sources[${index}].resource`, "source", source.resource, { sourceId: source.id || null });
337
- }
370
+ documents
371
+ .filter((doc) => !doc.reserved)
372
+ .forEach((doc) => {
373
+ const fm = doc.frontmatter || {};
374
+ add(doc, "resource", "concept_resource", fm.resource);
375
+ (Array.isArray(fm.sources) ? fm.sources : []).forEach((source, index) => {
376
+ if (source && typeof source === "object") {
377
+ add(doc, `sources[${index}].resource`, "source", source.resource, {
378
+ sourceId: source.id || null,
379
+ });
380
+ }
381
+ });
382
+ add(doc, "computation", "computation", fm.computation);
383
+ add(doc, "executor.resource", "executor", fm.executor && fm.executor.resource);
384
+ add(doc, "attester.resource", "attester", fm.attester && fm.attester.resource);
338
385
  });
339
- add(doc, "computation", "computation", fm.computation);
340
- add(doc, "executor.resource", "executor", fm.executor && fm.executor.resource);
341
- add(doc, "attester.resource", "attester", fm.attester && fm.attester.resource);
342
- });
343
386
  return assets;
344
387
  }
345
388
 
346
389
  function resolveBundle(documents, options) {
347
390
  const requested = options && options.bundle ? String(options.bundle) : "";
348
- const bundleIds = Array.from(new Set(documents.map((doc) => doc && doc.bundle).filter(Boolean).map(String)));
391
+ const bundleIds = Array.from(
392
+ new Set(
393
+ documents
394
+ .map((doc) => doc && doc.bundle)
395
+ .filter(Boolean)
396
+ .map(String),
397
+ ),
398
+ );
349
399
  if (requested) {
350
400
  return requested;
351
401
  }
352
402
  if (bundleIds.length > 1) {
353
- throw new TypeError("checkV02Migration requires options.bundle when documents contain multiple bundles.");
403
+ throw new TypeError(
404
+ "checkV02Migration requires options.bundle when documents contain multiple bundles.",
405
+ );
354
406
  }
355
407
  return bundleIds[0] || "bundle";
356
408
  }
@@ -376,187 +428,303 @@ function checkV02Migration(source, options) {
376
428
  let pendingLegacyMarkers = 0;
377
429
  let nativeMarkers = 0;
378
430
 
379
- documents.filter((doc) => !doc.reserved).forEach((doc) => {
380
- const fm = doc.frontmatter || {};
381
- const citations = extractLegacyCitations(doc.body);
382
- const generatedFile = isGeneratedFile(doc, config);
383
- const summary = documentSummary(doc);
384
- const hasTimestamp = hasOwn(fm, "timestamp");
385
- const hasGenerated = hasOwn(fm, "generated");
386
- const hasSources = hasOwn(fm, "sources");
387
- const hasNativeFields = Object.keys(fm).some((key) => V02_ADDITIVE_FIELDS.has(key))
388
- || String(fm.type || "").toLowerCase() === "attested computation";
389
-
390
- if (hasTimestamp) {
391
- legacyMarkers += 1;
392
- }
393
- if (citations.found) {
394
- legacyMarkers += 1;
395
- }
396
- if (hasNativeFields) {
397
- nativeMarkers += 1;
398
- }
399
-
400
- if (hasTimestamp && hasGenerated) {
401
- nativeFieldWins.push(Object.assign({ nativeField: "generated", legacyField: "timestamp" }, summary));
402
- } else if (hasTimestamp) {
403
- pendingLegacyMarkers += 1;
404
- const timestamp = normalizedTimestamp(fm.timestamp);
405
- const mapping = actorMappingFor(doc, config);
406
- const candidate = Object.assign({
407
- timestamp: timestamp || String(fm.timestamp || ""),
408
- actorMapping: mapping,
409
- ready: Boolean(timestamp && mapping && mapping.valid && !generatedFile),
410
- skipped: generatedFile,
411
- }, summary);
412
- timestampCandidates.push(candidate);
413
- if (!timestamp) {
414
- blockers.push(issue("invalid_legacy_timestamp", "Legacy timestamp is not an ISO 8601 datetime.", Object.assign({ bundle }, summary)));
431
+ documents
432
+ .filter((doc) => !doc.reserved)
433
+ .forEach((doc) => {
434
+ const fm = doc.frontmatter || {};
435
+ const citations = extractLegacyCitations(doc.body);
436
+ const generatedFile = isGeneratedFile(doc, config);
437
+ const summary = documentSummary(doc);
438
+ const hasTimestamp = hasOwn(fm, "timestamp");
439
+ const hasGenerated = hasOwn(fm, "generated");
440
+ const hasSources = hasOwn(fm, "sources");
441
+ const hasNativeFields =
442
+ Object.keys(fm).some((key) => V02_ADDITIVE_FIELDS.has(key)) ||
443
+ String(fm.type || "").toLowerCase() === "attested computation";
444
+
445
+ if (hasTimestamp) {
446
+ legacyMarkers += 1;
415
447
  }
416
- if (!mapping || !mapping.valid) {
417
- const need = Object.assign({
418
- field: "generated.by",
419
- reason: mapping ? "mapping_not_confirmed_or_invalid" : "mapping_missing",
420
- }, summary);
421
- actorMappingNeeds.push(need);
422
- blockers.push(issue(
423
- "truthful_actor_mapping_required",
424
- "A confirmed, convention-valid actor mapping is required before migrating timestamp to generated.at.",
425
- Object.assign({ bundle }, need),
426
- ));
427
- }
428
- }
429
-
430
- if (citations.found && hasSources) {
431
- nativeFieldWins.push(Object.assign({ nativeField: "sources", legacyField: "# Citations" }, summary));
432
- } else if (citations.found) {
433
- pendingLegacyMarkers += 1;
434
- const candidate = Object.assign({
435
- sources: citations.sources,
436
- unparsed: citations.unparsed,
437
- sectionCount: citations.sectionCount,
438
- unsafeResources: citations.sources.filter((source) => unsafeLocalResource(doc.path, source.resource)).map((source) => source.resource),
439
- ready: citations.sources.length > 0
440
- && citations.unparsed.length === 0
441
- && citations.sectionCount === 1
442
- && !citations.sources.some((source) => unsafeLocalResource(doc.path, source.resource))
443
- && !generatedFile,
444
- skipped: generatedFile,
445
- }, summary);
446
- citationCandidates.push(candidate);
447
- if (citations.sectionCount > 1) {
448
- blockers.push(issue(
449
- "multiple_legacy_citation_sections",
450
- "Multiple legacy # Citations sections are ambiguous and require manual consolidation.",
451
- Object.assign({ bundle, sectionCount: citations.sectionCount }, summary),
452
- ));
448
+ if (citations.found) {
449
+ legacyMarkers += 1;
453
450
  }
454
- if (!citations.sources.length) {
455
- blockers.push(issue("empty_legacy_citations", "Legacy # Citations has no safely convertible entries.", Object.assign({ bundle }, summary)));
451
+ if (hasNativeFields) {
452
+ nativeMarkers += 1;
456
453
  }
457
- if (citations.unparsed.length) {
458
- blockers.push(issue(
459
- "unparseable_legacy_citation",
460
- "One or more legacy citation entries cannot be converted without interpretation.",
461
- Object.assign({ bundle, entries: citations.unparsed }, summary),
462
- ));
454
+
455
+ if (hasTimestamp && hasGenerated) {
456
+ nativeFieldWins.push(
457
+ Object.assign({ nativeField: "generated", legacyField: "timestamp" }, summary),
458
+ );
459
+ } else if (hasTimestamp) {
460
+ pendingLegacyMarkers += 1;
461
+ const timestamp = normalizedTimestamp(fm.timestamp);
462
+ const mapping = actorMappingFor(doc, config);
463
+ const candidate = Object.assign(
464
+ {
465
+ timestamp: timestamp || String(fm.timestamp || ""),
466
+ actorMapping: mapping,
467
+ ready: Boolean(timestamp && mapping && mapping.valid && !generatedFile),
468
+ skipped: generatedFile,
469
+ },
470
+ summary,
471
+ );
472
+ timestampCandidates.push(candidate);
473
+ if (!timestamp) {
474
+ blockers.push(
475
+ issue(
476
+ "invalid_legacy_timestamp",
477
+ "Legacy timestamp is not an ISO 8601 datetime.",
478
+ Object.assign({ bundle }, summary),
479
+ ),
480
+ );
481
+ }
482
+ if (!mapping || !mapping.valid) {
483
+ const need = Object.assign(
484
+ {
485
+ field: "generated.by",
486
+ reason: mapping ? "mapping_not_confirmed_or_invalid" : "mapping_missing",
487
+ },
488
+ summary,
489
+ );
490
+ actorMappingNeeds.push(need);
491
+ blockers.push(
492
+ issue(
493
+ "truthful_actor_mapping_required",
494
+ "A confirmed, convention-valid actor mapping is required before migrating timestamp to generated.at.",
495
+ Object.assign({ bundle }, need),
496
+ ),
497
+ );
498
+ }
463
499
  }
464
- if (candidate.unsafeResources.length) {
465
- blockers.push(issue(
466
- "unsafe_legacy_citation_resource",
467
- "A legacy citation resource resolves outside the bundle and cannot be migrated.",
468
- Object.assign({ bundle, resources: candidate.unsafeResources }, summary),
469
- ));
500
+
501
+ if (citations.found && hasSources) {
502
+ nativeFieldWins.push(
503
+ Object.assign({ nativeField: "sources", legacyField: "# Citations" }, summary),
504
+ );
505
+ } else if (citations.found) {
506
+ pendingLegacyMarkers += 1;
507
+ const candidate = Object.assign(
508
+ {
509
+ sources: citations.sources,
510
+ unparsed: citations.unparsed,
511
+ sectionCount: citations.sectionCount,
512
+ unsafeResources: citations.sources
513
+ .filter((source) => unsafeLocalResource(doc.path, source.resource))
514
+ .map((source) => source.resource),
515
+ ready:
516
+ citations.sources.length > 0 &&
517
+ citations.unparsed.length === 0 &&
518
+ citations.sectionCount === 1 &&
519
+ !citations.sources.some((source) => unsafeLocalResource(doc.path, source.resource)) &&
520
+ !generatedFile,
521
+ skipped: generatedFile,
522
+ },
523
+ summary,
524
+ );
525
+ citationCandidates.push(candidate);
526
+ if (citations.sectionCount > 1) {
527
+ blockers.push(
528
+ issue(
529
+ "multiple_legacy_citation_sections",
530
+ "Multiple legacy # Citations sections are ambiguous and require manual consolidation.",
531
+ Object.assign({ bundle, sectionCount: citations.sectionCount }, summary),
532
+ ),
533
+ );
534
+ }
535
+ if (!citations.sources.length) {
536
+ blockers.push(
537
+ issue(
538
+ "empty_legacy_citations",
539
+ "Legacy # Citations has no safely convertible entries.",
540
+ Object.assign({ bundle }, summary),
541
+ ),
542
+ );
543
+ }
544
+ if (citations.unparsed.length) {
545
+ blockers.push(
546
+ issue(
547
+ "unparseable_legacy_citation",
548
+ "One or more legacy citation entries cannot be converted without interpretation.",
549
+ Object.assign({ bundle, entries: citations.unparsed }, summary),
550
+ ),
551
+ );
552
+ }
553
+ if (candidate.unsafeResources.length) {
554
+ blockers.push(
555
+ issue(
556
+ "unsafe_legacy_citation_resource",
557
+ "A legacy citation resource resolves outside the bundle and cannot be migrated.",
558
+ Object.assign({ bundle, resources: candidate.unsafeResources }, summary),
559
+ ),
560
+ );
561
+ }
470
562
  }
471
- }
472
563
 
473
- if (generatedFile && (
474
- (hasTimestamp && !hasGenerated)
475
- || (citations.found && !hasSources)
476
- )) {
477
- const skip = Object.assign({ reason: "generated_file_requires_generator_change" }, summary);
478
- generatedFileSkips.push(skip);
479
- blockers.push(issue(
480
- "generated_file_requires_generator_change",
481
- "Generated concepts must be migrated in their generator, not through a concept update proposal.",
482
- Object.assign({ bundle }, summary),
483
- ));
484
- }
564
+ if (generatedFile && ((hasTimestamp && !hasGenerated) || (citations.found && !hasSources))) {
565
+ const skip = Object.assign({ reason: "generated_file_requires_generator_change" }, summary);
566
+ generatedFileSkips.push(skip);
567
+ blockers.push(
568
+ issue(
569
+ "generated_file_requires_generator_change",
570
+ "Generated concepts must be migrated in their generator, not through a concept update proposal.",
571
+ Object.assign({ bundle }, summary),
572
+ ),
573
+ );
574
+ }
485
575
 
486
- if (doc.valid === false) {
487
- blockers.push(issue("invalid_concept", "Invalid concepts block a truthful v0.2 version declaration.", Object.assign({ bundle }, summary)));
488
- }
489
- (doc.conformanceDiagnostics || []).filter((entry) => entry.severity === "error").forEach((entry) => {
490
- blockers.push(issue(entry.code || "conformance_error", entry.message || "Conformance error.", Object.assign({ bundle }, summary)));
491
- });
492
- (doc.v02Diagnostics || []).forEach((entry) => {
493
- blockers.push(issue(entry.code || "invalid_v02_metadata", entry.message || "Invalid OKF v0.2 metadata.", Object.assign({ bundle }, summary)));
576
+ if (doc.valid === false) {
577
+ blockers.push(
578
+ issue(
579
+ "invalid_concept",
580
+ "Invalid concepts block a truthful v0.2 version declaration.",
581
+ Object.assign({ bundle }, summary),
582
+ ),
583
+ );
584
+ }
585
+ (doc.conformanceDiagnostics || [])
586
+ .filter((entry) => entry.severity === "error")
587
+ .forEach((entry) => {
588
+ blockers.push(
589
+ issue(
590
+ entry.code || "conformance_error",
591
+ entry.message || "Conformance error.",
592
+ Object.assign({ bundle }, summary),
593
+ ),
594
+ );
595
+ });
596
+ (doc.v02Diagnostics || []).forEach((entry) => {
597
+ blockers.push(
598
+ issue(
599
+ entry.code || "invalid_v02_metadata",
600
+ entry.message || "Invalid OKF v0.2 metadata.",
601
+ Object.assign({ bundle }, summary),
602
+ ),
603
+ );
604
+ });
494
605
  });
495
- });
496
606
 
497
- documents.filter((doc) => doc.reserved).forEach((doc) => {
498
- (doc.conformanceDiagnostics || []).filter((entry) => entry.severity === "error").forEach((entry) => {
499
- blockers.push(issue(entry.code || "conformance_error", entry.message || "Reserved resource conformance error.", {
500
- bundle,
501
- path: normalizePath(doc.path),
502
- uri: documentIdentity(doc),
503
- }));
607
+ documents
608
+ .filter((doc) => doc.reserved)
609
+ .forEach((doc) => {
610
+ (doc.conformanceDiagnostics || [])
611
+ .filter((entry) => entry.severity === "error")
612
+ .forEach((entry) => {
613
+ blockers.push(
614
+ issue(
615
+ entry.code || "conformance_error",
616
+ entry.message || "Reserved resource conformance error.",
617
+ {
618
+ bundle,
619
+ path: normalizePath(doc.path),
620
+ uri: documentIdentity(doc),
621
+ },
622
+ ),
623
+ );
624
+ });
504
625
  });
505
- });
506
626
 
507
627
  if (declaredVersion && declaredVersion !== "0.1" && declaredVersion !== V02_VERSION) {
508
- blockers.push(issue("unsupported_declared_version", `Unsupported declared OKF version: ${declaredVersion}`, {
509
- bundle,
510
- path: rootIndex && rootIndex.path,
511
- }));
628
+ blockers.push(
629
+ issue(
630
+ "unsupported_declared_version",
631
+ `Unsupported declared OKF version: ${declaredVersion}`,
632
+ {
633
+ bundle,
634
+ path: rootIndex && rootIndex.path,
635
+ },
636
+ ),
637
+ );
512
638
  }
513
639
 
514
640
  const indexErrors = Array.isArray(index.errors) ? index.errors : [];
515
- indexErrors.filter((entry) => !entry.bundle || String(entry.bundle) === bundle).forEach((entry) => {
516
- blockers.push(issue(entry.code || "index_error", entry.message || "Index error blocks migration.", Object.assign({ bundle }, entry)));
517
- });
518
- (Array.isArray(index.diagnostics) ? index.diagnostics : []).filter((entry) => (
519
- (!entry.bundle || String(entry.bundle) === bundle)
520
- && (entry.invalidatesProject || entry.severity === "error")
521
- )).forEach((entry) => {
522
- blockers.push(issue(entry.code || "project_validation_error", entry.message || "Project validation error blocks migration.", Object.assign({ bundle }, entry)));
523
- });
524
- (Array.isArray(index.warnings) ? index.warnings : []).filter((entry) => (
525
- (!entry.bundle || String(entry.bundle) === bundle)
526
- && String(entry.code || "").startsWith("asset_")
527
- )).forEach((entry) => {
528
- blockers.push(issue(entry.code, entry.message || "Referenced asset error blocks migration.", Object.assign({ bundle }, entry)));
529
- });
641
+ indexErrors
642
+ .filter((entry) => !entry.bundle || String(entry.bundle) === bundle)
643
+ .forEach((entry) => {
644
+ blockers.push(
645
+ issue(
646
+ entry.code || "index_error",
647
+ entry.message || "Index error blocks migration.",
648
+ Object.assign({ bundle }, entry),
649
+ ),
650
+ );
651
+ });
652
+ (Array.isArray(index.diagnostics) ? index.diagnostics : [])
653
+ .filter(
654
+ (entry) =>
655
+ (!entry.bundle || String(entry.bundle) === bundle) &&
656
+ (entry.invalidatesProject || entry.severity === "error"),
657
+ )
658
+ .forEach((entry) => {
659
+ blockers.push(
660
+ issue(
661
+ entry.code || "project_validation_error",
662
+ entry.message || "Project validation error blocks migration.",
663
+ Object.assign({ bundle }, entry),
664
+ ),
665
+ );
666
+ });
667
+ (Array.isArray(index.warnings) ? index.warnings : [])
668
+ .filter(
669
+ (entry) =>
670
+ (!entry.bundle || String(entry.bundle) === bundle) &&
671
+ String(entry.code || "").startsWith("asset_"),
672
+ )
673
+ .forEach((entry) => {
674
+ blockers.push(
675
+ issue(
676
+ entry.code,
677
+ entry.message || "Referenced asset error blocks migration.",
678
+ Object.assign({ bundle }, entry),
679
+ ),
680
+ );
681
+ });
530
682
  (Array.isArray(config.blockers) ? config.blockers : []).forEach((entry) => {
531
- blockers.push(typeof entry === "string"
532
- ? issue("provided_blocker", entry, { bundle })
533
- : issue(entry.code || "provided_blocker", entry.message || "Provided migration blocker.", Object.assign({ bundle }, entry)));
683
+ blockers.push(
684
+ typeof entry === "string"
685
+ ? issue("provided_blocker", entry, { bundle })
686
+ : issue(
687
+ entry.code || "provided_blocker",
688
+ entry.message || "Provided migration blocker.",
689
+ Object.assign({ bundle }, entry),
690
+ ),
691
+ );
534
692
  });
535
693
 
536
694
  const collisions = discoverCollisions(documents, config);
537
695
  collisions.forEach((collision) => {
538
- blockers.push(issue(
539
- `${collision.kind}_collision`,
540
- `Migration is blocked by ${collision.kind.replace(/_/g, "/")} collision: ${collision.value || "<unknown>"}`,
541
- { bundle, value: collision.value, documents: collision.documents, origin: collision.origin },
542
- ));
696
+ blockers.push(
697
+ issue(
698
+ `${collision.kind}_collision`,
699
+ `Migration is blocked by ${collision.kind.replace(/_/g, "/")} collision: ${collision.value || "<unknown>"}`,
700
+ {
701
+ bundle,
702
+ value: collision.value,
703
+ documents: collision.documents,
704
+ origin: collision.origin,
705
+ },
706
+ ),
707
+ );
543
708
  });
544
709
 
545
710
  const rootPresent = Boolean(rootIndex);
546
711
  if (!rootPresent) {
547
- blockers.push(issue(
548
- "missing_root_index",
549
- "A bundle-root index.md is required before declaring OKF v0.2.",
550
- { bundle, path: "index.md" },
551
- ));
712
+ blockers.push(
713
+ issue("missing_root_index", "A bundle-root index.md is required before declaring OKF v0.2.", {
714
+ bundle,
715
+ path: "index.md",
716
+ }),
717
+ );
552
718
  }
553
719
 
554
720
  let contentClassification;
555
721
  const declaredV01 = declaredVersion === "0.1";
556
722
  const declaredV02 = declaredVersion === V02_VERSION;
557
- if ((pendingLegacyMarkers > 0 && nativeMarkers > 0)
558
- || (declaredV01 && nativeMarkers > 0)
559
- || (declaredV02 && pendingLegacyMarkers > 0)) {
723
+ if (
724
+ (pendingLegacyMarkers > 0 && nativeMarkers > 0) ||
725
+ (declaredV01 && nativeMarkers > 0) ||
726
+ (declaredV02 && pendingLegacyMarkers > 0)
727
+ ) {
560
728
  contentClassification = "mixed";
561
729
  } else if (pendingLegacyMarkers > 0 || declaredV01) {
562
730
  contentClassification = "v0.1";
@@ -569,8 +737,9 @@ function checkV02Migration(source, options) {
569
737
  const uniqueBlockers = uniqueIssues(blockers);
570
738
  const classification = uniqueBlockers.length ? "blocked" : contentClassification;
571
739
  const conceptCandidates = timestampCandidates.length + citationCandidates.length;
572
- const readyConceptCandidates = timestampCandidates.filter((entry) => entry.ready).length
573
- + citationCandidates.filter((entry) => entry.ready).length;
740
+ const readyConceptCandidates =
741
+ timestampCandidates.filter((entry) => entry.ready).length +
742
+ citationCandidates.filter((entry) => entry.ready).length;
574
743
  return {
575
744
  bundle,
576
745
  targetVersion: V02_VERSION,
@@ -593,7 +762,8 @@ function checkV02Migration(source, options) {
593
762
  readiness: {
594
763
  stageA: uniqueBlockers.length === 0 && conceptCandidates === readyConceptCandidates,
595
764
  conceptProposals: conceptCandidates === readyConceptCandidates,
596
- versionDeclaration: uniqueBlockers.length === 0 && conceptCandidates === readyConceptCandidates && rootPresent,
765
+ versionDeclaration:
766
+ uniqueBlockers.length === 0 && conceptCandidates === readyConceptCandidates && rootPresent,
597
767
  rootIndexPresent: rootPresent,
598
768
  },
599
769
  readOnly: true,
@@ -624,24 +794,30 @@ function buildV02MigrationPlan(source, options) {
624
794
  return proposals.get(candidate.uri);
625
795
  }
626
796
 
627
- report.candidates.timestamps.filter((candidate) => candidate.ready).forEach((candidate) => {
628
- const proposal = proposalFor(candidate);
629
- proposal.arguments.frontmatter.generated = {
630
- by: candidate.actorMapping.by,
631
- at: candidate.timestamp,
632
- };
633
- proposal.retainedLegacyFields.push("timestamp");
634
- });
797
+ report.candidates.timestamps
798
+ .filter((candidate) => candidate.ready)
799
+ .forEach((candidate) => {
800
+ const proposal = proposalFor(candidate);
801
+ proposal.arguments.frontmatter.generated = {
802
+ by: candidate.actorMapping.by,
803
+ at: candidate.timestamp,
804
+ };
805
+ proposal.retainedLegacyFields.push("timestamp");
806
+ });
635
807
 
636
- report.candidates.citations.filter((candidate) => candidate.ready).forEach((candidate) => {
637
- const proposal = proposalFor(candidate);
638
- proposal.arguments.frontmatter.sources = candidate.sources.map((sourceEntry) => Object.assign({}, sourceEntry));
639
- proposal.retainedLegacyFields.push("# Citations");
640
- });
808
+ report.candidates.citations
809
+ .filter((candidate) => candidate.ready)
810
+ .forEach((candidate) => {
811
+ const proposal = proposalFor(candidate);
812
+ proposal.arguments.frontmatter.sources = candidate.sources.map((sourceEntry) =>
813
+ Object.assign({}, sourceEntry),
814
+ );
815
+ proposal.retainedLegacyFields.push("# Citations");
816
+ });
641
817
 
642
- const conceptProposals = Array.from(proposals.values()).sort((left, right) => (
643
- left.target.path.localeCompare(right.target.path)
644
- ));
818
+ const conceptProposals = Array.from(proposals.values()).sort((left, right) =>
819
+ left.target.path.localeCompare(right.target.path),
820
+ );
645
821
  conceptProposals.forEach((proposal, index) => {
646
822
  proposal.sequence = index + 1;
647
823
  proposal.retainedLegacyFields = Array.from(new Set(proposal.retainedLegacyFields));
@@ -672,7 +848,9 @@ function buildV02MigrationPlan(source, options) {
672
848
  report,
673
849
  conceptProposals,
674
850
  versionDeclaration,
675
- steps: versionDeclaration ? conceptProposals.concat(versionDeclaration) : conceptProposals.slice(),
851
+ steps: versionDeclaration
852
+ ? conceptProposals.concat(versionDeclaration)
853
+ : conceptProposals.slice(),
676
854
  writesPerformed: false,
677
855
  proposalsCreated: false,
678
856
  proposalsAccepted: false,