@mfdaves/okf-mcp 0.3.3 → 0.5.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.
- package/.agents/skills/okf-v02-migration/SKILL.md +37 -0
- package/.agents/skills/okf-v02-migration/agents/openai.yaml +6 -0
- package/.agents/skills/okf-v02-migration/references/field-mapping.md +26 -0
- package/README.md +217 -79
- package/okf/bundles/okf-mcp/distribution/reference-bundle.md +2 -2
- package/okf/bundles/okf-mcp/index.md +7 -0
- package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +2 -2
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +9 -5
- package/okf/bundles/okf-mcp/overview/okf-mcp.md +2 -2
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +5 -3
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +7 -5
- package/okf/bundles/okf-mcp/runtime/indexer.md +6 -4
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +7 -7
- package/okf/bundles/okf-mcp/specs/attested-computation.md +24 -0
- package/okf/bundles/okf-mcp/specs/concept-format.md +5 -3
- package/okf/bundles/okf-mcp/specs/git-sources.md +23 -0
- package/okf/bundles/okf-mcp/workflows/v02-migration.md +24 -0
- package/package.json +10 -3
- package/server.json +5 -5
- package/src/assets.js +469 -0
- package/src/authoring.js +492 -20
- package/src/cli.js +468 -37
- package/src/computation.js +366 -0
- package/src/git-source.js +551 -0
- package/src/graph.js +71 -18
- package/src/http-server.js +8 -1
- package/src/index.js +5 -0
- package/src/indexer.js +428 -24
- package/src/markdown.js +129 -0
- package/src/mcp-server.js +450 -315
- package/src/migration.js +687 -0
- package/src/parser.js +135 -54
- package/src/plugins.js +30 -50
- package/src/project.js +74 -17
- package/src/remote.js +232 -17
- package/src/search-index.js +83 -0
- package/src/search.js +103 -47
- package/src/store.js +421 -25
- package/src/v02.js +545 -0
- package/src/validation.js +13 -2
- package/src/mcp-protocol.js +0 -283
package/src/migration.js
ADDED
|
@@ -0,0 +1,687 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const path = require("path");
|
|
4
|
+
const {
|
|
5
|
+
itemLiteral,
|
|
6
|
+
markdownStructure,
|
|
7
|
+
nodeText,
|
|
8
|
+
sectionNodes,
|
|
9
|
+
} = require("./markdown");
|
|
10
|
+
|
|
11
|
+
const V02_VERSION = "0.2";
|
|
12
|
+
|
|
13
|
+
const V02_ADDITIVE_FIELDS = new Set([
|
|
14
|
+
"sources",
|
|
15
|
+
"usage_window",
|
|
16
|
+
"generated",
|
|
17
|
+
"verified",
|
|
18
|
+
"status",
|
|
19
|
+
"stale_after",
|
|
20
|
+
"runtime",
|
|
21
|
+
"parameters",
|
|
22
|
+
"computation",
|
|
23
|
+
"executor",
|
|
24
|
+
"attester",
|
|
25
|
+
]);
|
|
26
|
+
|
|
27
|
+
function hasOwn(value, key) {
|
|
28
|
+
return Boolean(value && Object.prototype.hasOwnProperty.call(value, key));
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function normalizePath(value) {
|
|
32
|
+
return String(value || "").replace(/\\/g, "/");
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function documentsFrom(source) {
|
|
36
|
+
if (Array.isArray(source)) {
|
|
37
|
+
return source;
|
|
38
|
+
}
|
|
39
|
+
if (source && Array.isArray(source.documents)) {
|
|
40
|
+
return source.documents;
|
|
41
|
+
}
|
|
42
|
+
if (source && source.index && Array.isArray(source.index.documents)) {
|
|
43
|
+
return source.index.documents;
|
|
44
|
+
}
|
|
45
|
+
return [];
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function sourceIndex(source) {
|
|
49
|
+
return source && source.index && Array.isArray(source.index.documents)
|
|
50
|
+
? source.index
|
|
51
|
+
: source || {};
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function documentIdentity(doc) {
|
|
55
|
+
return String((doc && (doc.uri || doc.pathUri || doc.path)) || "<unknown>");
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function documentSummary(doc) {
|
|
59
|
+
return {
|
|
60
|
+
uri: documentIdentity(doc),
|
|
61
|
+
path: normalizePath(doc && doc.path),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function issue(code, message, details) {
|
|
66
|
+
return Object.assign({
|
|
67
|
+
code,
|
|
68
|
+
severity: "error",
|
|
69
|
+
message,
|
|
70
|
+
}, details || {});
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
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");
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function uniqueIssues(entries) {
|
|
84
|
+
const seen = new Set();
|
|
85
|
+
return entries.filter((entry) => {
|
|
86
|
+
const key = issueKey(entry);
|
|
87
|
+
if (seen.has(key)) {
|
|
88
|
+
return false;
|
|
89
|
+
}
|
|
90
|
+
seen.add(key);
|
|
91
|
+
return true;
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function citationSource(item) {
|
|
96
|
+
const text = String(item || "").trim();
|
|
97
|
+
const markdownLink = text.match(/^\[([^\]]+)]\(([^)\s]+)(?:\s+"[^"]*")?\)$/);
|
|
98
|
+
if (markdownLink) {
|
|
99
|
+
return {
|
|
100
|
+
resource: markdownLink[2],
|
|
101
|
+
title: markdownLink[1].trim(),
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
const url = text.match(/^(?:([^\n]+?)\s*[:;–—-]\s*)?(https?:\/\/[^\s<>]+)$/);
|
|
105
|
+
if (url) {
|
|
106
|
+
const title = String(url[1] || "").trim();
|
|
107
|
+
return Object.assign({ resource: url[2] }, title ? { title } : {});
|
|
108
|
+
}
|
|
109
|
+
const pathValue = text.match(/^`((?:\.\.?\/|\/|references\/)[^`]+)`$/)
|
|
110
|
+
|| text.match(/^((?:\.\.?\/|\/|references\/)[^\s]+)$/);
|
|
111
|
+
if (pathValue) {
|
|
112
|
+
return { resource: pathValue[1] };
|
|
113
|
+
}
|
|
114
|
+
if (/^[A-Za-z][A-Za-z0-9+.-]*:[^\s]+$/.test(text)) {
|
|
115
|
+
return { resource: text };
|
|
116
|
+
}
|
|
117
|
+
return null;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function extractLegacyCitations(body) {
|
|
121
|
+
const structure = markdownStructure(body);
|
|
122
|
+
const headings = structure.headings.filter((heading) => (
|
|
123
|
+
heading.level === 1 && heading.text.toLowerCase() === "citations"
|
|
124
|
+
));
|
|
125
|
+
if (!headings.length) {
|
|
126
|
+
return { found: false, sources: [], unparsed: [], sectionCount: 0 };
|
|
127
|
+
}
|
|
128
|
+
if (headings.length > 1) {
|
|
129
|
+
return { found: true, sources: [], unparsed: [], sectionCount: headings.length };
|
|
130
|
+
}
|
|
131
|
+
const heading = headings[0];
|
|
132
|
+
const blocks = sectionNodes(heading);
|
|
133
|
+
const firstNonList = blocks.findIndex((node) => node.type !== "list");
|
|
134
|
+
const flatBlocks = firstNonList === -1 ? blocks : blocks.slice(0, firstNonList);
|
|
135
|
+
const lists = new Set(flatBlocks.filter((node) => node.type === "list"));
|
|
136
|
+
const sources = [];
|
|
137
|
+
const unparsed = blocks.filter((node) => node.type !== "list").map((node) => (
|
|
138
|
+
nodeText(node).trim() || `[${node.type}]`
|
|
139
|
+
));
|
|
140
|
+
const seen = new Set();
|
|
141
|
+
const items = structure.items.filter((item) => lists.has(item.node.parent));
|
|
142
|
+
for (const item of items) {
|
|
143
|
+
const literal = itemLiteral(structure, item);
|
|
144
|
+
const source = literal && citationSource(literal);
|
|
145
|
+
if (!source) {
|
|
146
|
+
unparsed.push(literal || structure.lines.slice(item.startLine - 1, item.endLine).join(" ").trim());
|
|
147
|
+
continue;
|
|
148
|
+
}
|
|
149
|
+
if (!seen.has(source.resource)) {
|
|
150
|
+
seen.add(source.resource);
|
|
151
|
+
sources.push(source);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
return { found: true, sources, unparsed, sectionCount: 1 };
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function normalizedTimestamp(value) {
|
|
158
|
+
if (value instanceof Date && Number.isFinite(value.getTime())) {
|
|
159
|
+
return value.toISOString();
|
|
160
|
+
}
|
|
161
|
+
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
|
+
if (!match) {
|
|
164
|
+
return null;
|
|
165
|
+
}
|
|
166
|
+
const year = Number(match[1]);
|
|
167
|
+
const month = Number(match[2]);
|
|
168
|
+
const day = Number(match[3]);
|
|
169
|
+
const hour = Number(match[4]);
|
|
170
|
+
const minute = Number(match[5]);
|
|
171
|
+
const second = match[6] === undefined ? 0 : Number(match[6]);
|
|
172
|
+
const offsetHour = match[8] === undefined ? 0 : Number(match[8]);
|
|
173
|
+
const offsetMinute = match[9] === undefined ? 0 : Number(match[9]);
|
|
174
|
+
const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
|
|
175
|
+
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) {
|
|
178
|
+
return null;
|
|
179
|
+
}
|
|
180
|
+
return Number.isFinite(Date.parse(text)) ? text : null;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
function unsafeLocalResource(documentPath, resource) {
|
|
184
|
+
const raw = String(resource || "").trim().replace(/\\/g, "/").split("#")[0];
|
|
185
|
+
if (!raw || raw.startsWith("//") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) {
|
|
186
|
+
return false;
|
|
187
|
+
}
|
|
188
|
+
const relative = raw.startsWith("/")
|
|
189
|
+
? path.posix.normalize(raw.slice(1))
|
|
190
|
+
: path.posix.normalize(path.posix.join(path.posix.dirname(normalizePath(documentPath)), raw));
|
|
191
|
+
return !relative || relative === "." || relative === ".." || relative.startsWith("../") || path.posix.isAbsolute(relative);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
function validActor(value) {
|
|
195
|
+
const actor = String(value || "").trim();
|
|
196
|
+
return /^(?:human:[^\s]+|process:[^\s]+|[^\s/:]+\/[^\s/]+)$/.test(actor);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function actorMappingFor(doc, options) {
|
|
200
|
+
const mappings = (options && options.actorMappings) || {};
|
|
201
|
+
const keys = [doc && doc.uri, doc && doc.pathUri, doc && doc.path, "$default"]
|
|
202
|
+
.filter(Boolean);
|
|
203
|
+
for (const key of keys) {
|
|
204
|
+
if (!hasOwn(mappings, key)) {
|
|
205
|
+
continue;
|
|
206
|
+
}
|
|
207
|
+
const mapping = mappings[key];
|
|
208
|
+
if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) {
|
|
209
|
+
return { key, by: "", confirmed: false, valid: false };
|
|
210
|
+
}
|
|
211
|
+
const by = String(mapping.by || "").trim();
|
|
212
|
+
const confirmed = mapping.confirmed === true;
|
|
213
|
+
return { key, by, confirmed, valid: confirmed && validActor(by) };
|
|
214
|
+
}
|
|
215
|
+
return null;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
function generatedPathSet(options) {
|
|
219
|
+
const configured = options && (options.generatedPaths || options.generatedFiles);
|
|
220
|
+
if (configured instanceof Set) {
|
|
221
|
+
return new Set(Array.from(configured, normalizePath));
|
|
222
|
+
}
|
|
223
|
+
return new Set(Array.isArray(configured) ? configured.map(normalizePath) : []);
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
function isGeneratedFile(doc, options) {
|
|
227
|
+
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;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
function discoverCollisions(documents, options) {
|
|
235
|
+
const ids = new Map();
|
|
236
|
+
const aliases = new Map();
|
|
237
|
+
const collisions = [];
|
|
238
|
+
|
|
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: [] });
|
|
254
|
+
}
|
|
255
|
+
aliases.get(normalized).documents.push(documentSummary(doc));
|
|
256
|
+
});
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
ids.forEach((entry) => {
|
|
260
|
+
if (entry.documents.length > 1) {
|
|
261
|
+
collisions.push({ kind: "id", value: entry.value, documents: entry.documents, origin: "discovered" });
|
|
262
|
+
}
|
|
263
|
+
});
|
|
264
|
+
aliases.forEach((entry, key) => {
|
|
265
|
+
if (entry.documents.length > 1) {
|
|
266
|
+
collisions.push({ kind: "alias", value: entry.value, documents: entry.documents, origin: "discovered" });
|
|
267
|
+
}
|
|
268
|
+
if (ids.has(key)) {
|
|
269
|
+
const idEntry = ids.get(key);
|
|
270
|
+
const documentUris = new Set(entry.documents.map((doc) => doc.uri));
|
|
271
|
+
const crossDocuments = idEntry.documents.filter((doc) => !documentUris.has(doc.uri));
|
|
272
|
+
if (crossDocuments.length) {
|
|
273
|
+
collisions.push({
|
|
274
|
+
kind: "alias_id",
|
|
275
|
+
value: entry.value,
|
|
276
|
+
documents: entry.documents.concat(crossDocuments),
|
|
277
|
+
origin: "discovered",
|
|
278
|
+
});
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
});
|
|
282
|
+
|
|
283
|
+
[
|
|
284
|
+
["id", options && options.idCollisions],
|
|
285
|
+
["alias", options && options.aliasCollisions],
|
|
286
|
+
].forEach(([kind, entries]) => {
|
|
287
|
+
(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 || {}));
|
|
291
|
+
});
|
|
292
|
+
});
|
|
293
|
+
return collisions;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
function referenceKind(resource) {
|
|
297
|
+
const value = String(resource || "");
|
|
298
|
+
if (/^https?:\/\//i.test(value)) {
|
|
299
|
+
return "external_url";
|
|
300
|
+
}
|
|
301
|
+
if (value.startsWith("/")) {
|
|
302
|
+
return "bundle_absolute";
|
|
303
|
+
}
|
|
304
|
+
if (value.startsWith("./") || value.startsWith("../") || value.includes("/")) {
|
|
305
|
+
return "relative_path";
|
|
306
|
+
}
|
|
307
|
+
return "opaque";
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
function collectReferencedAssets(documents) {
|
|
311
|
+
const assets = [];
|
|
312
|
+
const seen = new Set();
|
|
313
|
+
function add(doc, field, kind, resource, extra) {
|
|
314
|
+
if (typeof resource !== "string" || !resource.trim()) {
|
|
315
|
+
return;
|
|
316
|
+
}
|
|
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 || {});
|
|
325
|
+
const key = [entry.uri, field, entry.resource, entry.sourceId || ""].join("\u0000");
|
|
326
|
+
if (!seen.has(key)) {
|
|
327
|
+
seen.add(key);
|
|
328
|
+
assets.push(entry);
|
|
329
|
+
}
|
|
330
|
+
}
|
|
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
|
+
}
|
|
338
|
+
});
|
|
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
|
+
return assets;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
function resolveBundle(documents, options) {
|
|
347
|
+
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)));
|
|
349
|
+
if (requested) {
|
|
350
|
+
return requested;
|
|
351
|
+
}
|
|
352
|
+
if (bundleIds.length > 1) {
|
|
353
|
+
throw new TypeError("checkV02Migration requires options.bundle when documents contain multiple bundles.");
|
|
354
|
+
}
|
|
355
|
+
return bundleIds[0] || "bundle";
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
function checkV02Migration(source, options) {
|
|
359
|
+
const config = options || {};
|
|
360
|
+
const allDocuments = documentsFrom(source);
|
|
361
|
+
const bundle = resolveBundle(allDocuments, config);
|
|
362
|
+
const documents = allDocuments.filter((doc) => !doc.bundle || String(doc.bundle) === bundle);
|
|
363
|
+
const index = sourceIndex(source);
|
|
364
|
+
const rootIndex = documents.find((doc) => normalizePath(doc.path) === "index.md") || null;
|
|
365
|
+
const rootFrontmatter = (rootIndex && rootIndex.frontmatter) || {};
|
|
366
|
+
const declaredVersion = hasOwn(rootFrontmatter, "okf_version")
|
|
367
|
+
? String(rootFrontmatter.okf_version).trim()
|
|
368
|
+
: null;
|
|
369
|
+
const timestampCandidates = [];
|
|
370
|
+
const citationCandidates = [];
|
|
371
|
+
const actorMappingNeeds = [];
|
|
372
|
+
const generatedFileSkips = [];
|
|
373
|
+
const nativeFieldWins = [];
|
|
374
|
+
const blockers = [];
|
|
375
|
+
let legacyMarkers = 0;
|
|
376
|
+
let pendingLegacyMarkers = 0;
|
|
377
|
+
let nativeMarkers = 0;
|
|
378
|
+
|
|
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)));
|
|
415
|
+
}
|
|
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
|
+
));
|
|
453
|
+
}
|
|
454
|
+
if (!citations.sources.length) {
|
|
455
|
+
blockers.push(issue("empty_legacy_citations", "Legacy # Citations has no safely convertible entries.", Object.assign({ bundle }, summary)));
|
|
456
|
+
}
|
|
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
|
+
));
|
|
463
|
+
}
|
|
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
|
+
));
|
|
470
|
+
}
|
|
471
|
+
}
|
|
472
|
+
|
|
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
|
+
}
|
|
485
|
+
|
|
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)));
|
|
494
|
+
});
|
|
495
|
+
});
|
|
496
|
+
|
|
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
|
+
}));
|
|
504
|
+
});
|
|
505
|
+
});
|
|
506
|
+
|
|
507
|
+
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
|
+
}));
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
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
|
+
});
|
|
530
|
+
(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)));
|
|
534
|
+
});
|
|
535
|
+
|
|
536
|
+
const collisions = discoverCollisions(documents, config);
|
|
537
|
+
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
|
+
));
|
|
543
|
+
});
|
|
544
|
+
|
|
545
|
+
const rootPresent = Boolean(rootIndex);
|
|
546
|
+
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
|
+
));
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
let contentClassification;
|
|
555
|
+
const declaredV01 = declaredVersion === "0.1";
|
|
556
|
+
const declaredV02 = declaredVersion === V02_VERSION;
|
|
557
|
+
if ((pendingLegacyMarkers > 0 && nativeMarkers > 0)
|
|
558
|
+
|| (declaredV01 && nativeMarkers > 0)
|
|
559
|
+
|| (declaredV02 && pendingLegacyMarkers > 0)) {
|
|
560
|
+
contentClassification = "mixed";
|
|
561
|
+
} else if (pendingLegacyMarkers > 0 || declaredV01) {
|
|
562
|
+
contentClassification = "v0.1";
|
|
563
|
+
} else if (nativeMarkers > 0 || declaredV02) {
|
|
564
|
+
contentClassification = "v0.2";
|
|
565
|
+
} else {
|
|
566
|
+
contentClassification = "undeclared";
|
|
567
|
+
}
|
|
568
|
+
|
|
569
|
+
const uniqueBlockers = uniqueIssues(blockers);
|
|
570
|
+
const classification = uniqueBlockers.length ? "blocked" : contentClassification;
|
|
571
|
+
const conceptCandidates = timestampCandidates.length + citationCandidates.length;
|
|
572
|
+
const readyConceptCandidates = timestampCandidates.filter((entry) => entry.ready).length
|
|
573
|
+
+ citationCandidates.filter((entry) => entry.ready).length;
|
|
574
|
+
return {
|
|
575
|
+
bundle,
|
|
576
|
+
targetVersion: V02_VERSION,
|
|
577
|
+
declaredVersion,
|
|
578
|
+
classification,
|
|
579
|
+
contentClassification,
|
|
580
|
+
legacyMarkers,
|
|
581
|
+
pendingLegacyMarkers,
|
|
582
|
+
nativeMarkers,
|
|
583
|
+
candidates: {
|
|
584
|
+
timestamps: timestampCandidates,
|
|
585
|
+
citations: citationCandidates,
|
|
586
|
+
},
|
|
587
|
+
nativeFieldWins,
|
|
588
|
+
actorMappingNeeds,
|
|
589
|
+
collisions,
|
|
590
|
+
generatedFileSkips,
|
|
591
|
+
referencedAssets: collectReferencedAssets(documents),
|
|
592
|
+
blockers: uniqueBlockers,
|
|
593
|
+
readiness: {
|
|
594
|
+
stageA: uniqueBlockers.length === 0 && conceptCandidates === readyConceptCandidates,
|
|
595
|
+
conceptProposals: conceptCandidates === readyConceptCandidates,
|
|
596
|
+
versionDeclaration: uniqueBlockers.length === 0 && conceptCandidates === readyConceptCandidates && rootPresent,
|
|
597
|
+
rootIndexPresent: rootPresent,
|
|
598
|
+
},
|
|
599
|
+
readOnly: true,
|
|
600
|
+
writesPerformed: false,
|
|
601
|
+
};
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
function buildV02MigrationPlan(source, options) {
|
|
605
|
+
const report = checkV02Migration(source, options);
|
|
606
|
+
const proposals = new Map();
|
|
607
|
+
|
|
608
|
+
function proposalFor(candidate) {
|
|
609
|
+
if (!proposals.has(candidate.uri)) {
|
|
610
|
+
proposals.set(candidate.uri, {
|
|
611
|
+
kind: "concept_update",
|
|
612
|
+
phase: "stage-a",
|
|
613
|
+
target: { bundle: report.bundle, uri: candidate.uri, path: candidate.path },
|
|
614
|
+
tool: "okf_propose_update",
|
|
615
|
+
arguments: {
|
|
616
|
+
uri: candidate.uri,
|
|
617
|
+
frontmatter: {},
|
|
618
|
+
message: "Prepare a review-only OKF v0.2 Stage-A metadata migration.",
|
|
619
|
+
},
|
|
620
|
+
retainedLegacyFields: [],
|
|
621
|
+
requiresExplicitApproval: true,
|
|
622
|
+
});
|
|
623
|
+
}
|
|
624
|
+
return proposals.get(candidate.uri);
|
|
625
|
+
}
|
|
626
|
+
|
|
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
|
+
});
|
|
635
|
+
|
|
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
|
+
});
|
|
641
|
+
|
|
642
|
+
const conceptProposals = Array.from(proposals.values()).sort((left, right) => (
|
|
643
|
+
left.target.path.localeCompare(right.target.path)
|
|
644
|
+
));
|
|
645
|
+
conceptProposals.forEach((proposal, index) => {
|
|
646
|
+
proposal.sequence = index + 1;
|
|
647
|
+
proposal.retainedLegacyFields = Array.from(new Set(proposal.retainedLegacyFields));
|
|
648
|
+
});
|
|
649
|
+
|
|
650
|
+
let versionDeclaration = null;
|
|
651
|
+
if (report.readiness.versionDeclaration && report.declaredVersion !== V02_VERSION) {
|
|
652
|
+
versionDeclaration = {
|
|
653
|
+
kind: "bundle_version_declaration",
|
|
654
|
+
phase: "after-stage-a-validation",
|
|
655
|
+
sequence: conceptProposals.length + 1,
|
|
656
|
+
operation: "propose_reserved_index_update",
|
|
657
|
+
target: { bundle: report.bundle, path: "index.md" },
|
|
658
|
+
frontmatter: { okf_version: V02_VERSION },
|
|
659
|
+
prerequisites: [
|
|
660
|
+
"all Stage-A concept proposals are explicitly approved and accepted",
|
|
661
|
+
"the complete bundle passes validation after those acceptances",
|
|
662
|
+
],
|
|
663
|
+
requiresExplicitApproval: true,
|
|
664
|
+
};
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
return {
|
|
668
|
+
stage: "A",
|
|
669
|
+
targetVersion: V02_VERSION,
|
|
670
|
+
classification: report.classification,
|
|
671
|
+
ready: report.readiness.stageA,
|
|
672
|
+
report,
|
|
673
|
+
conceptProposals,
|
|
674
|
+
versionDeclaration,
|
|
675
|
+
steps: versionDeclaration ? conceptProposals.concat(versionDeclaration) : conceptProposals.slice(),
|
|
676
|
+
writesPerformed: false,
|
|
677
|
+
proposalsCreated: false,
|
|
678
|
+
proposalsAccepted: false,
|
|
679
|
+
};
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
module.exports = {
|
|
683
|
+
V02_VERSION,
|
|
684
|
+
buildV02MigrationPlan,
|
|
685
|
+
checkV02Migration,
|
|
686
|
+
extractLegacyCitations,
|
|
687
|
+
};
|