@mfdaves/okf-mcp 0.3.2-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.
- package/LICENSE +21 -0
- package/README.md +504 -0
- package/bin/okf-mcp.js +13 -0
- package/okf/bundles/okf-mcp/distribution/reference-bundle.md +42 -0
- package/okf/bundles/okf-mcp/index.md +17 -0
- package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +26 -0
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +34 -0
- package/okf/bundles/okf-mcp/overview/okf-mcp.md +28 -0
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +38 -0
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +30 -0
- package/okf/bundles/okf-mcp/runtime/indexer.md +34 -0
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +32 -0
- package/okf/bundles/okf-mcp/specs/concept-format.md +32 -0
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +30 -0
- package/okf/bundles/okf-mcp/workflows/concept-update.md +30 -0
- package/okf.project.yaml +5 -0
- package/package.json +55 -0
- package/src/authoring.js +334 -0
- package/src/cli.js +427 -0
- package/src/graph.js +278 -0
- package/src/http-server.js +137 -0
- package/src/index.js +15 -0
- package/src/indexer.js +437 -0
- package/src/mcp-server.js +816 -0
- package/src/parser.js +364 -0
- package/src/plugins.js +209 -0
- package/src/project.js +235 -0
- package/src/remote.js +179 -0
- package/src/search.js +179 -0
- package/src/store.js +341 -0
- package/src/validation.js +117 -0
package/src/parser.js
ADDED
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("fs");
|
|
4
|
+
const path = require("path");
|
|
5
|
+
const yaml = require("js-yaml");
|
|
6
|
+
|
|
7
|
+
function normalizeSlashes(value) {
|
|
8
|
+
return String(value || "").replace(/\\/g, "/");
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function isReservedPath(relativePath) {
|
|
12
|
+
const base = path.basename(relativePath).toLowerCase();
|
|
13
|
+
return base === "index.md" || base === "log.md";
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function parseFrontmatterYaml(source) {
|
|
17
|
+
let parsed;
|
|
18
|
+
try {
|
|
19
|
+
parsed = yaml.load(String(source || ""), {
|
|
20
|
+
schema: yaml.CORE_SCHEMA,
|
|
21
|
+
json: false,
|
|
22
|
+
});
|
|
23
|
+
} catch (error) {
|
|
24
|
+
const detail = error && error.message ? error.message : String(error);
|
|
25
|
+
throw new Error(`Invalid YAML mapping: ${detail}`);
|
|
26
|
+
}
|
|
27
|
+
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
28
|
+
throw new Error("YAML document root must be a mapping.");
|
|
29
|
+
}
|
|
30
|
+
return parsed;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function splitFrontmatter(text) {
|
|
34
|
+
if (!String(text || "").startsWith("---\n") && !String(text || "").startsWith("---\r\n")) {
|
|
35
|
+
return {
|
|
36
|
+
frontmatter: null,
|
|
37
|
+
body: String(text || ""),
|
|
38
|
+
rawFrontmatter: "",
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
const normalized = String(text).replace(/\r\n/g, "\n");
|
|
42
|
+
let end = normalized.indexOf("\n---\n", 4);
|
|
43
|
+
let markerLength = 5;
|
|
44
|
+
if (end === -1 && normalized.endsWith("\n---")) {
|
|
45
|
+
end = normalized.length - 4;
|
|
46
|
+
markerLength = 4;
|
|
47
|
+
}
|
|
48
|
+
if (end === -1) {
|
|
49
|
+
throw new Error("Opening frontmatter marker has no closing marker");
|
|
50
|
+
}
|
|
51
|
+
const rawFrontmatter = normalized.slice(4, end);
|
|
52
|
+
return {
|
|
53
|
+
frontmatter: parseFrontmatterYaml(rawFrontmatter),
|
|
54
|
+
body: normalized.slice(end + markerLength),
|
|
55
|
+
rawFrontmatter,
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function extractTitle(body, fallback) {
|
|
60
|
+
const match = String(body || "").match(/^#\s+(.+)$/m);
|
|
61
|
+
return match ? match[1].trim() : fallback;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function extractMarkdownLinks(body) {
|
|
65
|
+
const out = [];
|
|
66
|
+
const regex = /!?\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
|
|
67
|
+
let match;
|
|
68
|
+
while ((match = regex.exec(String(body || "")))) {
|
|
69
|
+
const target = match[2].trim();
|
|
70
|
+
if (!target || target.startsWith("http://") || target.startsWith("https://") || target.startsWith("mailto:") || target.startsWith("#")) {
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
out.push({
|
|
74
|
+
text: match[1],
|
|
75
|
+
href: target,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
return out;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function safeRelativePath(root, absolutePath) {
|
|
82
|
+
const resolvedRoot = path.resolve(root);
|
|
83
|
+
const resolvedPath = path.resolve(absolutePath);
|
|
84
|
+
const rel = path.relative(resolvedRoot, resolvedPath);
|
|
85
|
+
if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
|
|
86
|
+
return normalizeSlashes(rel);
|
|
87
|
+
}
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function conformanceDiagnostic(bundle, relativePath, code, message) {
|
|
92
|
+
return {
|
|
93
|
+
code,
|
|
94
|
+
severity: "error",
|
|
95
|
+
layer: "conformance",
|
|
96
|
+
bundle: bundle.id,
|
|
97
|
+
path: relativePath,
|
|
98
|
+
message,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function markdownLines(body) {
|
|
103
|
+
const lines = String(body || "").split(/\r?\n/);
|
|
104
|
+
let fence = null;
|
|
105
|
+
return lines.map((text, index) => {
|
|
106
|
+
const marker = text.match(/^\s*(```+|~~~+)/);
|
|
107
|
+
const hidden = Boolean(fence);
|
|
108
|
+
if (marker) {
|
|
109
|
+
if (!fence) {
|
|
110
|
+
fence = marker[1][0];
|
|
111
|
+
} else if (marker[1][0] === fence) {
|
|
112
|
+
fence = null;
|
|
113
|
+
}
|
|
114
|
+
return { index, text, hidden: true };
|
|
115
|
+
}
|
|
116
|
+
return { index, text, hidden };
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function validIsoDate(value) {
|
|
121
|
+
const match = String(value || "").match(/^(\d{4})-(\d{2})-(\d{2})$/);
|
|
122
|
+
if (!match) {
|
|
123
|
+
return false;
|
|
124
|
+
}
|
|
125
|
+
const year = Number(match[1]);
|
|
126
|
+
const month = Number(match[2]);
|
|
127
|
+
const day = Number(match[3]);
|
|
128
|
+
if (month < 1 || month > 12 || day < 1) {
|
|
129
|
+
return false;
|
|
130
|
+
}
|
|
131
|
+
const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
|
|
132
|
+
const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
|
|
133
|
+
return day <= daysInMonth;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function validateReservedIndex(bundle, relativePath, split) {
|
|
137
|
+
const diagnostics = [];
|
|
138
|
+
const rootIndex = normalizeSlashes(relativePath) === "index.md";
|
|
139
|
+
if (split.frontmatter) {
|
|
140
|
+
if (!rootIndex) {
|
|
141
|
+
diagnostics.push(conformanceDiagnostic(
|
|
142
|
+
bundle,
|
|
143
|
+
relativePath,
|
|
144
|
+
"reserved_index_frontmatter_not_allowed",
|
|
145
|
+
"Only a bundle-root index.md may declare frontmatter.",
|
|
146
|
+
));
|
|
147
|
+
} else {
|
|
148
|
+
const keys = Object.keys(split.frontmatter);
|
|
149
|
+
if (keys.some((key) => key !== "okf_version")) {
|
|
150
|
+
diagnostics.push(conformanceDiagnostic(
|
|
151
|
+
bundle,
|
|
152
|
+
relativePath,
|
|
153
|
+
"reserved_index_invalid_frontmatter",
|
|
154
|
+
"Bundle-root index.md frontmatter may contain only okf_version.",
|
|
155
|
+
));
|
|
156
|
+
}
|
|
157
|
+
if (
|
|
158
|
+
!Object.prototype.hasOwnProperty.call(split.frontmatter, "okf_version")
|
|
159
|
+
|| split.frontmatter.okf_version === null
|
|
160
|
+
|| typeof split.frontmatter.okf_version === "object"
|
|
161
|
+
|| String(split.frontmatter.okf_version).trim() === ""
|
|
162
|
+
) {
|
|
163
|
+
diagnostics.push(conformanceDiagnostic(
|
|
164
|
+
bundle,
|
|
165
|
+
relativePath,
|
|
166
|
+
"reserved_index_invalid_okf_version",
|
|
167
|
+
"Bundle-root index.md frontmatter must declare a non-empty scalar okf_version.",
|
|
168
|
+
));
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
const visible = markdownLines(split.body).filter((line) => !line.hidden);
|
|
173
|
+
if (!visible.some((line) => /^#{1,6}[ \t]+\S/.test(line.text))) {
|
|
174
|
+
diagnostics.push(conformanceDiagnostic(
|
|
175
|
+
bundle,
|
|
176
|
+
relativePath,
|
|
177
|
+
"reserved_index_missing_heading",
|
|
178
|
+
"Reserved index.md must contain at least one Markdown heading.",
|
|
179
|
+
));
|
|
180
|
+
}
|
|
181
|
+
if (!extractMarkdownLinks(split.body).length) {
|
|
182
|
+
diagnostics.push(conformanceDiagnostic(
|
|
183
|
+
bundle,
|
|
184
|
+
relativePath,
|
|
185
|
+
"reserved_index_missing_link",
|
|
186
|
+
"Reserved index.md must contain at least one local Markdown link entry.",
|
|
187
|
+
));
|
|
188
|
+
}
|
|
189
|
+
return diagnostics;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
function validateReservedLog(bundle, relativePath, split) {
|
|
193
|
+
const diagnostics = [];
|
|
194
|
+
if (split.frontmatter) {
|
|
195
|
+
diagnostics.push(conformanceDiagnostic(
|
|
196
|
+
bundle,
|
|
197
|
+
relativePath,
|
|
198
|
+
"reserved_log_frontmatter_not_allowed",
|
|
199
|
+
"Reserved log.md must not declare YAML frontmatter.",
|
|
200
|
+
));
|
|
201
|
+
}
|
|
202
|
+
const visible = markdownLines(split.body).filter((line) => !line.hidden);
|
|
203
|
+
const headings = visible.map((line) => {
|
|
204
|
+
const match = line.text.match(/^(#{1,6})[ \t]+(.+?)[ \t]*$/);
|
|
205
|
+
return match ? { index: line.index, level: match[1].length, text: match[2].trim() } : null;
|
|
206
|
+
}).filter(Boolean);
|
|
207
|
+
const h1 = headings.filter((heading) => heading.level === 1);
|
|
208
|
+
if (!h1.length) {
|
|
209
|
+
diagnostics.push(conformanceDiagnostic(
|
|
210
|
+
bundle,
|
|
211
|
+
relativePath,
|
|
212
|
+
"reserved_log_missing_h1",
|
|
213
|
+
"Reserved log.md must start with an H1 title.",
|
|
214
|
+
));
|
|
215
|
+
} else if (headings[0] !== h1[0]) {
|
|
216
|
+
diagnostics.push(conformanceDiagnostic(
|
|
217
|
+
bundle,
|
|
218
|
+
relativePath,
|
|
219
|
+
"reserved_log_h1_order",
|
|
220
|
+
"The H1 title in reserved log.md must precede its dated sections.",
|
|
221
|
+
));
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const h2 = headings.filter((heading) => heading.level === 2);
|
|
225
|
+
const sections = [];
|
|
226
|
+
h2.forEach((heading) => {
|
|
227
|
+
if (!/^\d{4}-\d{2}-\d{2}$/.test(heading.text)) {
|
|
228
|
+
diagnostics.push(conformanceDiagnostic(
|
|
229
|
+
bundle,
|
|
230
|
+
relativePath,
|
|
231
|
+
"reserved_log_invalid_date_heading",
|
|
232
|
+
`Log H2 heading must be a strict ISO date (YYYY-MM-DD): ${heading.text}`,
|
|
233
|
+
));
|
|
234
|
+
return;
|
|
235
|
+
}
|
|
236
|
+
if (!validIsoDate(heading.text)) {
|
|
237
|
+
diagnostics.push(conformanceDiagnostic(
|
|
238
|
+
bundle,
|
|
239
|
+
relativePath,
|
|
240
|
+
"reserved_log_invalid_date",
|
|
241
|
+
`Log H2 heading is not a valid calendar date: ${heading.text}`,
|
|
242
|
+
));
|
|
243
|
+
return;
|
|
244
|
+
}
|
|
245
|
+
sections.push(heading);
|
|
246
|
+
});
|
|
247
|
+
if (!sections.length) {
|
|
248
|
+
diagnostics.push(conformanceDiagnostic(
|
|
249
|
+
bundle,
|
|
250
|
+
relativePath,
|
|
251
|
+
"reserved_log_missing_date_section",
|
|
252
|
+
"Reserved log.md must contain at least one valid ISO-dated H2 section.",
|
|
253
|
+
));
|
|
254
|
+
}
|
|
255
|
+
for (let index = 1; index < sections.length; index += 1) {
|
|
256
|
+
if (sections[index - 1].text <= sections[index].text) {
|
|
257
|
+
diagnostics.push(conformanceDiagnostic(
|
|
258
|
+
bundle,
|
|
259
|
+
relativePath,
|
|
260
|
+
"reserved_log_dates_not_descending",
|
|
261
|
+
"Log date sections must be ordered newest first without duplicate dates.",
|
|
262
|
+
));
|
|
263
|
+
break;
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
sections.forEach((section) => {
|
|
267
|
+
const nextH2 = h2.find((heading) => heading.index > section.index);
|
|
268
|
+
const end = nextH2 ? nextH2.index : Number.POSITIVE_INFINITY;
|
|
269
|
+
const hasListItem = visible.some((line) => (
|
|
270
|
+
line.index > section.index
|
|
271
|
+
&& line.index < end
|
|
272
|
+
&& /^\s*(?:[-+*]|\d+[.)])\s+\S/.test(line.text)
|
|
273
|
+
));
|
|
274
|
+
if (!hasListItem) {
|
|
275
|
+
diagnostics.push(conformanceDiagnostic(
|
|
276
|
+
bundle,
|
|
277
|
+
relativePath,
|
|
278
|
+
"reserved_log_missing_list_item",
|
|
279
|
+
`Log date section ${section.text} must contain at least one prose list item.`,
|
|
280
|
+
));
|
|
281
|
+
}
|
|
282
|
+
});
|
|
283
|
+
return diagnostics;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
function validateReservedDocument(bundle, relativePath, split) {
|
|
287
|
+
const base = path.basename(relativePath).toLowerCase();
|
|
288
|
+
if (base === "index.md") {
|
|
289
|
+
return validateReservedIndex(bundle, relativePath, split);
|
|
290
|
+
}
|
|
291
|
+
if (base === "log.md") {
|
|
292
|
+
return validateReservedLog(bundle, relativePath, split);
|
|
293
|
+
}
|
|
294
|
+
return [];
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
function parseMarkdownText(bundle, relativePath, text, sourcePath) {
|
|
298
|
+
const reserved = isReservedPath(relativePath);
|
|
299
|
+
const split = splitFrontmatter(text);
|
|
300
|
+
const frontmatter = split.frontmatter || {};
|
|
301
|
+
const warnings = [];
|
|
302
|
+
if (!reserved && !split.frontmatter) {
|
|
303
|
+
warnings.push({ code: "missing_frontmatter", path: relativePath, message: "Concept file has no YAML frontmatter." });
|
|
304
|
+
}
|
|
305
|
+
if (!reserved && (!frontmatter.type || String(frontmatter.type).trim() === "")) {
|
|
306
|
+
warnings.push({ code: "missing_type", path: relativePath, message: "Concept file has no non-empty type field." });
|
|
307
|
+
}
|
|
308
|
+
if (!reserved && frontmatter.id && !String(frontmatter.id).startsWith("okf://")) {
|
|
309
|
+
warnings.push({ code: "invalid_id", path: relativePath, message: "Concept id must start with okf://." });
|
|
310
|
+
}
|
|
311
|
+
const conformanceDiagnostics = reserved
|
|
312
|
+
? validateReservedDocument(bundle, relativePath, split)
|
|
313
|
+
: warnings
|
|
314
|
+
.filter((warning) => warning.code === "missing_frontmatter" || warning.code === "missing_type")
|
|
315
|
+
.map((warning) => conformanceDiagnostic(bundle, relativePath, warning.code, warning.message));
|
|
316
|
+
const title = frontmatter.title || extractTitle(split.body, path.basename(relativePath, ".md"));
|
|
317
|
+
const pathUri = `okf://${bundle.id}/${relativePath}`;
|
|
318
|
+
const uri = frontmatter.id && String(frontmatter.id).startsWith("okf://") ? String(frontmatter.id) : pathUri;
|
|
319
|
+
return {
|
|
320
|
+
bundle: bundle.id,
|
|
321
|
+
bundleRoot: bundle.root,
|
|
322
|
+
path: relativePath,
|
|
323
|
+
absolutePath: sourcePath || relativePath,
|
|
324
|
+
uri,
|
|
325
|
+
pathUri,
|
|
326
|
+
reserved,
|
|
327
|
+
kind: reserved ? "reserved" : "concept",
|
|
328
|
+
frontmatter,
|
|
329
|
+
rawFrontmatter: split.rawFrontmatter,
|
|
330
|
+
body: split.body,
|
|
331
|
+
text,
|
|
332
|
+
type: frontmatter.type || null,
|
|
333
|
+
title,
|
|
334
|
+
description: frontmatter.description || "",
|
|
335
|
+
tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
|
|
336
|
+
aliases: Array.isArray(frontmatter.aliases) ? frontmatter.aliases.map(String) : [],
|
|
337
|
+
relations: Array.isArray(frontmatter.relations) ? frontmatter.relations : [],
|
|
338
|
+
links: extractMarkdownLinks(split.body),
|
|
339
|
+
warnings,
|
|
340
|
+
diagnostics: conformanceDiagnostics,
|
|
341
|
+
conformanceDiagnostics,
|
|
342
|
+
valid: reserved || Boolean(frontmatter.type && String(frontmatter.type).trim() !== ""),
|
|
343
|
+
};
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
function parseMarkdownFile(bundle, absolutePath) {
|
|
347
|
+
const relativePath = safeRelativePath(bundle.root, absolutePath);
|
|
348
|
+
if (relativePath === null) {
|
|
349
|
+
throw new Error(`Path is outside bundle root: ${absolutePath}`);
|
|
350
|
+
}
|
|
351
|
+
return parseMarkdownText(bundle, relativePath, fs.readFileSync(absolutePath, "utf8"), absolutePath);
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
module.exports = {
|
|
355
|
+
extractMarkdownLinks,
|
|
356
|
+
isReservedPath,
|
|
357
|
+
normalizeSlashes,
|
|
358
|
+
parseFrontmatterYaml,
|
|
359
|
+
parseMarkdownFile,
|
|
360
|
+
parseMarkdownText,
|
|
361
|
+
safeRelativePath,
|
|
362
|
+
splitFrontmatter,
|
|
363
|
+
validateReservedDocument,
|
|
364
|
+
};
|
package/src/plugins.js
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("fs");
|
|
4
|
+
const path = require("path");
|
|
5
|
+
const { isInsidePath } = require("./project");
|
|
6
|
+
|
|
7
|
+
function ensureDir(dirPath) {
|
|
8
|
+
fs.mkdirSync(dirPath, { recursive: true });
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function normalizeSlashes(value) {
|
|
12
|
+
return String(value || "").replace(/\\/g, "/");
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function slug(value) {
|
|
16
|
+
return String(value || "concept").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "concept";
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function yamlScalar(value) {
|
|
20
|
+
if (value === null) {
|
|
21
|
+
return "null";
|
|
22
|
+
}
|
|
23
|
+
if (typeof value === "boolean" || typeof value === "number") {
|
|
24
|
+
return String(value);
|
|
25
|
+
}
|
|
26
|
+
return JSON.stringify(String(value || ""));
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function yamlValue(lines, key, value) {
|
|
30
|
+
if (Array.isArray(value)) {
|
|
31
|
+
lines.push(`${key}:`);
|
|
32
|
+
value.forEach((entry) => {
|
|
33
|
+
if (entry && typeof entry === "object") {
|
|
34
|
+
const entries = Object.entries(entry);
|
|
35
|
+
const first = entries.shift();
|
|
36
|
+
lines.push(` - ${first[0]}: ${yamlScalar(first[1])}`);
|
|
37
|
+
entries.forEach(([childKey, childValue]) => {
|
|
38
|
+
lines.push(` ${childKey}: ${yamlScalar(childValue)}`);
|
|
39
|
+
});
|
|
40
|
+
} else {
|
|
41
|
+
lines.push(` - ${yamlScalar(entry)}`);
|
|
42
|
+
}
|
|
43
|
+
});
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
lines.push(`${key}: ${yamlScalar(value)}`);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function conceptMarkdown(frontmatter, bodyLines) {
|
|
50
|
+
const lines = ["---"];
|
|
51
|
+
Object.keys(frontmatter).forEach((key) => yamlValue(lines, key, frontmatter[key]));
|
|
52
|
+
lines.push("---", "");
|
|
53
|
+
return lines.concat(bodyLines || []).join("\n") + "\n";
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function walkFiles(root, extensions) {
|
|
57
|
+
const out = [];
|
|
58
|
+
if (!fs.existsSync(root)) {
|
|
59
|
+
return out;
|
|
60
|
+
}
|
|
61
|
+
fs.readdirSync(root, { withFileTypes: true }).forEach((entry) => {
|
|
62
|
+
const full = path.join(root, entry.name);
|
|
63
|
+
if (entry.isDirectory()) {
|
|
64
|
+
out.push.apply(out, walkFiles(full, extensions));
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
if (entry.isFile() && extensions.includes(path.extname(entry.name).toLowerCase())) {
|
|
68
|
+
out.push(full);
|
|
69
|
+
}
|
|
70
|
+
});
|
|
71
|
+
return out.sort();
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function outputRoot(project, plugin) {
|
|
75
|
+
if (!plugin.output) {
|
|
76
|
+
throw new Error(`Plugin ${plugin.name || plugin.type || "<unnamed>"} is missing output.`);
|
|
77
|
+
}
|
|
78
|
+
if (path.isAbsolute(String(plugin.output))) {
|
|
79
|
+
throw new Error(`Plugin ${plugin.name || plugin.type || "<unnamed>"} output must be relative to the project root.`);
|
|
80
|
+
}
|
|
81
|
+
const resolved = path.resolve(project.root, plugin.output);
|
|
82
|
+
if (!isInsidePath(project.root, resolved)) {
|
|
83
|
+
throw new Error(`Plugin ${plugin.name || plugin.type || "<unnamed>"} output resolves outside the project root.`);
|
|
84
|
+
}
|
|
85
|
+
return resolved;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function sourceRoot(project, plugin) {
|
|
89
|
+
if (!plugin.root) {
|
|
90
|
+
throw new Error(`Plugin ${plugin.name || plugin.type || "<unnamed>"} is missing root.`);
|
|
91
|
+
}
|
|
92
|
+
if (path.isAbsolute(String(plugin.root))) {
|
|
93
|
+
throw new Error(`Plugin ${plugin.name || plugin.type || "<unnamed>"} root must be relative to the project root.`);
|
|
94
|
+
}
|
|
95
|
+
const resolved = path.resolve(project.root, plugin.root);
|
|
96
|
+
if (!isInsidePath(project.root, resolved)) {
|
|
97
|
+
throw new Error(`Plugin ${plugin.name || plugin.type || "<unnamed>"} root resolves outside the project root.`);
|
|
98
|
+
}
|
|
99
|
+
return resolved;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function writeGeneratedFiles(root, files) {
|
|
103
|
+
ensureDir(root);
|
|
104
|
+
const written = [];
|
|
105
|
+
files.forEach((content, relativePath) => {
|
|
106
|
+
const full = path.join(root, relativePath);
|
|
107
|
+
ensureDir(path.dirname(full));
|
|
108
|
+
fs.writeFileSync(full, content, "utf8");
|
|
109
|
+
written.push(full);
|
|
110
|
+
});
|
|
111
|
+
return written;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function generateFilesystemConcepts(project, plugin) {
|
|
115
|
+
const root = sourceRoot(project, plugin);
|
|
116
|
+
const out = new Map();
|
|
117
|
+
const extensions = Array.isArray(plugin.extensions) ? plugin.extensions.map((ext) => ext.startsWith(".") ? ext : `.${ext}`) : [".md"];
|
|
118
|
+
walkFiles(root, extensions).forEach((filePath) => {
|
|
119
|
+
const relative = normalizeSlashes(path.relative(project.root, filePath));
|
|
120
|
+
const title = path.basename(filePath);
|
|
121
|
+
const idSlug = slug(relative.replace(/\.[^.]+$/, ""));
|
|
122
|
+
out.set(`${idSlug}.md`, conceptMarkdown({
|
|
123
|
+
id: `okf://${plugin.bundle || "generated"}/${idSlug}`,
|
|
124
|
+
type: plugin.conceptType || "Repository File",
|
|
125
|
+
title,
|
|
126
|
+
description: `Repository file ${relative}.`,
|
|
127
|
+
source: `repo://${relative}`,
|
|
128
|
+
tags: Array.isArray(plugin.tags) ? plugin.tags : ["generated", "file"],
|
|
129
|
+
}, [
|
|
130
|
+
`# ${title}`,
|
|
131
|
+
"",
|
|
132
|
+
`Repository file: \`${relative}\``,
|
|
133
|
+
"",
|
|
134
|
+
]));
|
|
135
|
+
});
|
|
136
|
+
return {
|
|
137
|
+
output: outputRoot(project, plugin),
|
|
138
|
+
files: out,
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function pickSpecKey(json, filePath) {
|
|
143
|
+
return json.key || json.name || json.id || path.basename(filePath, path.extname(filePath));
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
function generateJsonSpecConcepts(project, plugin) {
|
|
147
|
+
const root = sourceRoot(project, plugin);
|
|
148
|
+
const out = new Map();
|
|
149
|
+
walkFiles(root, [".json"]).forEach((filePath) => {
|
|
150
|
+
const raw = fs.readFileSync(filePath, "utf8");
|
|
151
|
+
const json = JSON.parse(raw);
|
|
152
|
+
const key = pickSpecKey(json, filePath);
|
|
153
|
+
const relative = normalizeSlashes(path.relative(project.root, filePath));
|
|
154
|
+
const destination = json.destination && json.destination.table ? json.destination.table : json.table || json.tablename || "";
|
|
155
|
+
const relations = destination && plugin.destinationBundle
|
|
156
|
+
? [{ type: "persists_to", target: `okf://${plugin.destinationBundle}/${slug(destination)}` }]
|
|
157
|
+
: [];
|
|
158
|
+
out.set(`${slug(key)}.md`, conceptMarkdown({
|
|
159
|
+
id: `okf://${plugin.bundle || "generated"}/${slug(key)}`,
|
|
160
|
+
type: plugin.conceptType || "JSON Spec",
|
|
161
|
+
title: key,
|
|
162
|
+
description: json.description || `Generated concept for JSON spec ${key}.`,
|
|
163
|
+
source: `repo://${relative}`,
|
|
164
|
+
tags: Array.isArray(plugin.tags) ? plugin.tags : ["generated", "spec"],
|
|
165
|
+
relations,
|
|
166
|
+
}, [
|
|
167
|
+
`# ${key}`,
|
|
168
|
+
"",
|
|
169
|
+
json.description || `Generated concept for JSON spec \`${key}\`.`,
|
|
170
|
+
"",
|
|
171
|
+
`Source: \`${relative}\``,
|
|
172
|
+
"",
|
|
173
|
+
]));
|
|
174
|
+
});
|
|
175
|
+
return {
|
|
176
|
+
output: outputRoot(project, plugin),
|
|
177
|
+
files: out,
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
function generateProject(project) {
|
|
182
|
+
const results = [];
|
|
183
|
+
project.plugins.forEach((plugin) => {
|
|
184
|
+
const type = plugin.type || plugin.name;
|
|
185
|
+
const generated = type === "filesystem"
|
|
186
|
+
? generateFilesystemConcepts(project, plugin)
|
|
187
|
+
: type === "json-spec"
|
|
188
|
+
? generateJsonSpecConcepts(project, plugin)
|
|
189
|
+
: null;
|
|
190
|
+
if (!generated) {
|
|
191
|
+
throw new Error(`Unknown OKF generator plugin: ${type}`);
|
|
192
|
+
}
|
|
193
|
+
const written = writeGeneratedFiles(generated.output, generated.files);
|
|
194
|
+
results.push({
|
|
195
|
+
plugin: plugin.name || type,
|
|
196
|
+
type,
|
|
197
|
+
output: normalizeSlashes(path.relative(project.root, generated.output)),
|
|
198
|
+
files: written.length,
|
|
199
|
+
});
|
|
200
|
+
});
|
|
201
|
+
return results;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
module.exports = {
|
|
205
|
+
conceptMarkdown,
|
|
206
|
+
generateProject,
|
|
207
|
+
generateFilesystemConcepts,
|
|
208
|
+
generateJsonSpecConcepts,
|
|
209
|
+
};
|