@mfdaves/okf-mcp 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/indexer.js CHANGED
@@ -171,23 +171,169 @@ function registerPortableConceptId(map, ambiguous, key, document) {
171
171
  map.set(normalized, document);
172
172
  }
173
173
 
174
+ function portableConceptKeys(value) {
175
+ const normalized = normalizeSlashes(String(value || ""))
176
+ .replace(/^\/+/, "")
177
+ .split("#")[0];
178
+ if (!normalized) return [];
179
+ return normalized.toLowerCase().endsWith(".md")
180
+ ? [normalized, normalized.slice(0, -3)]
181
+ : [normalized, `${normalized}.md`];
182
+ }
183
+
184
+ function portableConceptMatches(index, value) {
185
+ for (const key of portableConceptKeys(value)) {
186
+ const matches = (index.documents || []).filter((doc) => doc.conceptId === key || doc.path === key);
187
+ if (matches.length) {
188
+ return matches.sort((left, right) => left.uri.localeCompare(right.uri));
189
+ }
190
+ }
191
+ return [];
192
+ }
193
+
174
194
  function resolveConcept(index, locator) {
175
195
  const raw = String(locator || "").trim();
176
196
  if (!raw || !index) {
177
197
  return null;
178
198
  }
179
- const byUri = index.byUri && index.byUri.get(raw);
199
+ const fragmentless = normalizeSlashes(raw).split("#")[0];
200
+ const byUri = index.byUri && (index.byUri.get(raw) || index.byUri.get(fragmentless));
180
201
  if (byUri) {
181
202
  return byUri;
182
203
  }
183
- const normalized = normalizeSlashes(raw).replace(/^\/+/, "").split("#")[0];
184
- if (!normalized || !index.byConceptId) {
204
+ if ((index.ambiguousAliases || new Set()).has(raw)
205
+ || (index.ambiguousAliases || new Set()).has(fragmentless)) {
185
206
  return null;
186
207
  }
187
- return index.byConceptId.get(normalized)
188
- || index.byConceptId.get(normalized.replace(/\.md$/i, ""))
189
- || index.byConceptId.get(`${normalized}.md`)
190
- || null;
208
+ const uriMatch = fragmentless.match(/^okf:\/\/([^/]+)\/(.+)$/);
209
+ if (fragmentless.startsWith("okf://")) {
210
+ if (!uriMatch || (index.bundles || []).some((bundle) => bundle.id === uriMatch[1])) {
211
+ return null;
212
+ }
213
+ }
214
+ for (const key of portableConceptKeys(uriMatch ? `${uriMatch[1]}/${uriMatch[2]}` : fragmentless)) {
215
+ if ((index.ambiguousConceptIds || new Set()).has(key)) return null;
216
+ const owner = index.byConceptId && index.byConceptId.get(key);
217
+ if (owner) return owner;
218
+ }
219
+ return null;
220
+ }
221
+
222
+ function normalizeConceptTitle(value) {
223
+ return String(value || "").normalize("NFKC").trim().replace(/\s+/gu, " ").toLowerCase();
224
+ }
225
+
226
+ function conceptTitleSlug(value) {
227
+ return normalizeConceptTitle(value)
228
+ .replace(/[^a-z0-9]+/g, "-")
229
+ .replace(/^-+|-+$/g, "");
230
+ }
231
+
232
+ function conceptIsGeneratedFile(doc) {
233
+ const frontmatter = doc && doc.frontmatter || {};
234
+ return Boolean(doc && (doc.generatedFile === true || doc.isGenerated === true)
235
+ || frontmatter.generated_file === true || frontmatter.generatedFile === true);
236
+ }
237
+
238
+ function conceptMatchSummary(doc, matchReasons) {
239
+ const generated = doc && doc.signals && doc.signals.generated;
240
+ return {
241
+ uri: doc.uri,
242
+ bundle: doc.bundle,
243
+ path: doc.path,
244
+ conceptId: doc.conceptId || doc.path.replace(/\.md$/i, ""),
245
+ type: doc.type || doc.frontmatter && doc.frontmatter.type,
246
+ title: doc.title,
247
+ generatedBy: generated && generated.by || null,
248
+ ...(conceptIsGeneratedFile(doc) ? { generatedFile: true } : {}),
249
+ ...(matchReasons && matchReasons.length ? { matchReasons } : {}),
250
+ };
251
+ }
252
+
253
+ function findConceptMatches(index, options) {
254
+ const config = options || {};
255
+ const title = config.title === undefined ? null : normalizeConceptTitle(config.title);
256
+ const prefix = normalizeSlashes(String(config.pathPrefix || "")).replace(/^\/+|\/+$/g, "");
257
+ const documents = index && Array.isArray(index.concepts)
258
+ ? index.concepts
259
+ : index && Array.isArray(index.documents) ? index.documents : [];
260
+ return documents
261
+ .filter((doc) => (
262
+ doc && doc.valid !== false && !doc.reserved
263
+ && typeof doc.path === "string"
264
+ && (!config.bundle || doc.bundle === config.bundle)
265
+ && (!config.type || doc.type === config.type)
266
+ && (title === null || normalizeConceptTitle(doc.title) === title)
267
+ && (!prefix || doc.path === prefix || doc.path.startsWith(`${prefix}/`))
268
+ ))
269
+ .sort((left, right) => left.path.localeCompare(right.path) || left.uri.localeCompare(right.uri));
270
+ }
271
+
272
+ function recoveryReceipt(locator, entries, limit, allowRetry, forcedAmbiguity) {
273
+ const maximum = Math.max(1, Math.min(Number(limit || 5), 20));
274
+ const candidates = entries.slice(0, maximum)
275
+ .map((entry) => conceptMatchSummary(entry.doc, entry.reasons));
276
+ const actionable = entries.length === 1 && entries[0].doc.valid && !entries[0].doc.reserved;
277
+ return {
278
+ status: forcedAmbiguity || entries.length > 1 ? "ambiguous"
279
+ : actionable ? "replacement_found" : "not_found",
280
+ requestedLocator: locator,
281
+ candidates,
282
+ omitted: Math.max(0, entries.length - candidates.length),
283
+ ...(allowRetry && !forcedAmbiguity && actionable
284
+ ? { retryWith: { uri: entries[0].doc.uri } } : {}),
285
+ };
286
+ }
287
+
288
+ function recoverConceptLocator(index, locator, options) {
289
+ const config = options || {};
290
+ const raw = normalizeSlashes(String(locator || "").trim()).split("#")[0];
291
+ const uriMatch = raw.match(/^okf:\/\/([^/]+)\/(.+)$/);
292
+ if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw) && !uriMatch) {
293
+ return { status: "not_found", requestedLocator: raw, candidates: [], omitted: 0 };
294
+ }
295
+ const knownBundle = uriMatch && (index.bundles || []).some((entry) => entry.id === uriMatch[1]);
296
+ const bundle = knownBundle ? uriMatch[1] : config.bundle || "";
297
+ const portablePath = (uriMatch && knownBundle
298
+ ? uriMatch[2]
299
+ : raw.replace(/^okf:\/\//, ""))
300
+ .replace(/^\/+/, "");
301
+ const aliasOwners = (index.documents || []).filter((doc) => (
302
+ (index.ambiguousAliases || new Set()).has(raw) && (doc.uriAliases || []).includes(raw)
303
+ )).sort((left, right) => left.uri.localeCompare(right.uri));
304
+ const exact = aliasOwners.length ? aliasOwners : knownBundle ? [] : portableConceptMatches(index, portablePath);
305
+ if (exact.length) {
306
+ const portableAmbiguous = portableConceptKeys(portablePath)
307
+ .some((key) => (index.ambiguousConceptIds || new Set()).has(key));
308
+ return recoveryReceipt(raw, exact.map((doc) => ({
309
+ doc, reasons: [aliasOwners.length ? "uri_alias" : "portable_id"],
310
+ })), config.limit, !aliasOwners.length && !portableAmbiguous,
311
+ aliasOwners.length > 0 || portableAmbiguous);
312
+ }
313
+ const requestedPath = portablePath.replace(/\.md$/i, "");
314
+ const requestedBase = path.posix.basename(requestedPath).toLowerCase();
315
+ const requestedSlug = conceptTitleSlug(requestedBase);
316
+ const ranked = [];
317
+ if (!requestedSlug) return recoveryReceipt(raw, [], config.limit, false);
318
+ findConceptMatches(index, { bundle }).forEach((doc) => {
319
+ const base = path.posix.basename(doc.conceptId || doc.path.replace(/\.md$/i, "")).toLowerCase();
320
+ const reasons = [];
321
+ if (base === requestedBase) reasons.push("path_basename");
322
+ if (conceptTitleSlug(doc.title) === requestedSlug) reasons.push("title_slug");
323
+ if ((doc.aliases || []).some((alias) => conceptTitleSlug(alias) === requestedSlug)) reasons.push("alias");
324
+ if (!reasons.length) return;
325
+ ranked.push({
326
+ doc,
327
+ reasons,
328
+ score: (reasons.includes("path_basename") ? 4 : 0)
329
+ + (reasons.includes("title_slug") ? 2 : 0)
330
+ + (reasons.includes("alias") ? 1 : 0),
331
+ });
332
+ });
333
+ ranked.sort((left, right) => right.score - left.score
334
+ || left.doc.path.localeCompare(right.doc.path)
335
+ || left.doc.uri.localeCompare(right.doc.uri));
336
+ return recoveryReceipt(raw, ranked, config.limit, true);
191
337
  }
192
338
 
193
339
  function resolveIndexedLink(bundleId, resolved, href, documentsByPath) {
@@ -900,10 +1046,15 @@ module.exports = {
900
1046
  attachProject,
901
1047
  conceptSummary,
902
1048
  conceptSignals,
1049
+ conceptIsGeneratedFile,
1050
+ conceptMatchSummary,
903
1051
  bundleAllowsPath,
904
1052
  bundleExcludesPath,
1053
+ findConceptMatches,
905
1054
  loadProjectBundles,
1055
+ normalizeConceptTitle,
906
1056
  parseBundleArg,
1057
+ recoverConceptLocator,
907
1058
  resolveLinkPath,
908
1059
  resolveConcept,
909
1060
  semanticReferences,