okf-core 2.1.0 → 3.0.1

package/README.md

@@ -17,6 +17,19 @@ bundle. The library retains YAML source byte-for-byte beside its parsed mapping
 and reads Markdown links from a CommonMark AST. Conformance errors, format
 guidance, and consumer profile findings remain separate throughout the result.
 
+## Generated directory indexes
+
+`generateBundleIndexes(analysis)` returns one `okf.index.v1` navigation object
+per directory. `selectBundleIndex(indexes, directory)` selects the root (`.`)
+or a confined bundle-relative directory. Each index contains its immediate
+pages' titles and descriptions, child directories, and rendered Markdown.
+The root Markdown retains the analyzed `okf_version` declaration; nested
+indexes have no frontmatter. Neither function writes to storage.
+
+Indexes and logs are excluded from `buildGraph`. Navigation entries are not
+semantic relationships. Useful prose previously kept in a reserved `index.md`
+belongs in an ordinary typed page before an authored index is retired.
+
 ## Metadata and profile boundaries
 
 `content`, `frontmatter.raw`, and `frontmatter.yaml` retain authored bytes. The

package/dist/graph.d.ts

@@ -2,13 +2,8 @@ import type { AnalyzedDocument, BundleGraph } from "okf-contracts";
 /**
  * Project a bundle onto its graph.
  *
- * Indexes are included. They carry no frontmatter, so they have nothing to say about their own
- * type or trust, but their links are authored: somebody wrote each entry, grouped it under a
- * heading, and described it. Dropping them dropped the spine of a bundle and drew the rest as
- * unrelated islands — a picture that asserts the opposite of what the bundle says.
- *
- * Logs stay out. A log is a dated history of changes to a scope, so its links point at what
- * happened rather than at what relates to what.
+ * Reserved indexes provide navigation and logs record history. Neither declares semantic
+ * relationships between concepts; those relationships come from the concept documents.
  */
 export declare function buildGraph(documents: readonly AnalyzedDocument[]): BundleGraph;
 //# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EAGZ,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,GAAG,WAAW,CA8C9E"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EAGZ,MAAM,eAAe,CAAC;AAIvB;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,GAAG,WAAW,CA4C9E"}

package/dist/graph.js

@@ -2,26 +2,19 @@ import { byCodePoint } from "./paths.js";
 /**
  * Project a bundle onto its graph.
  *
- * Indexes are included. They carry no frontmatter, so they have nothing to say about their own
- * type or trust, but their links are authored: somebody wrote each entry, grouped it under a
- * heading, and described it. Dropping them dropped the spine of a bundle and drew the rest as
- * unrelated islands — a picture that asserts the opposite of what the bundle says.
- *
- * Logs stay out. A log is a dated history of changes to a scope, so its links point at what
- * happened rather than at what relates to what.
+ * Reserved indexes provide navigation and logs record history. Neither declares semantic
+ * relationships between concepts; those relationships come from the concept documents.
  */
 export function buildGraph(documents) {
     const linked = documents
-        .filter((document) => document.kind === "concept" || document.kind === "index")
+        .filter((document) => document.kind === "concept")
         .sort((left, right) => byCodePoint(left.path, right.path));
     const known = new Set(linked.map((document) => document.path));
     const nodes = linked.map((document) => ({
         id: document.path,
         path: document.path,
         title: document.derived.title,
-        // An index declares no type. Naming it one keeps the vocabulary honest and lets a reader
-        // tell a table of contents from a claim.
-        type: document.derived.type ?? (document.kind === "index" ? "Index" : "Concept"),
+        type: document.derived.type ?? "Concept",
         description: document.derived.description,
         status: document.derived.status,
         trustTier: document.derived.trustTier,

package/dist/graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { analyzeBundle, parseBundleDocument } from "./analyze.js";
 export { canonicalChangeJson, parseChange } from "./changes.js";
 export { documentExtensions } from "./derive.js";
 export { buildGraph } from "./graph.js";
+export { generateBundleIndexes, selectBundleIndex } from "./indexes.js";
 export { extractMarkdownLinks } from "./links.js";
 export type { ExtractLinksOptions } from "./links.js";
 export { listBundleEntries } from "./listing.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@ export { analyzeBundle, parseBundleDocument } from "./analyze.js";
 export { canonicalChangeJson, parseChange } from "./changes.js";
 export { documentExtensions } from "./derive.js";
 export { buildGraph } from "./graph.js";
+export { generateBundleIndexes, selectBundleIndex } from "./indexes.js";
 export { extractMarkdownLinks } from "./links.js";
 export { listBundleEntries } from "./listing.js";
 export { byCodePoint, canonicalizeBundlePath, canonicalizeOperationPath, InvalidBundlePathError, resolveWithinBundle, validateBundlePath, } from "./paths.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/indexes.d.ts

@@ -0,0 +1,5 @@
+import type { BundleAnalysis, BundleDirectoryIndex } from "okf-contracts";
+/** Derive directory navigation without changing authored documents or semantic edges. */
+export declare function generateBundleIndexes(analysis: BundleAnalysis): BundleDirectoryIndex[];
+export declare function selectBundleIndex(indexes: readonly BundleDirectoryIndex[], requested?: string): BundleDirectoryIndex;
+//# sourceMappingURL=indexes.d.ts.map

package/dist/indexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../src/indexes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAoB,MAAM,eAAe,CAAC;AAY5F,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,cAAc,GAAG,oBAAoB,EAAE,CAqCtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,EAAE,SAAS,SAAM,GAAG,oBAAoB,CAKjH"}

package/dist/indexes.js

@@ -0,0 +1,58 @@
+import { byCodePoint, validateBundlePath } from "./paths.js";
+function label(value) {
+    return value.replace(/\s+/g, " ").replace(/[\\`*_[\]<>]/g, "\\$&");
+}
+function href(value) {
+    return value.split("/").map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`)).join("/");
+}
+/** Derive directory navigation without changing authored documents or semantic edges. */
+export function generateBundleIndexes(analysis) {
+    const directories = new Set(["."]);
+    for (const document of analysis.documents) {
+        const parts = document.path.split("/");
+        for (let count = 1; count < parts.length; count += 1) {
+            directories.add(parts.slice(0, count).join("/"));
+        }
+    }
+    const titles = new Map(analysis.documents.filter((document) => document.kind === "index")
+        .map((document) => [document.path, document.derived.title]));
+    return [...directories].sort(byCodePoint).map((directory) => {
+        const prefix = directory === "." ? "" : `${directory}/`;
+        const indexPath = `${prefix}index.md`;
+        const title = titles.get(indexPath) ?? (directory === "." ? "Bundle" : directory.split("/").at(-1));
+        const entries = [];
+        for (const child of directories) {
+            if (child === "." || !child.startsWith(prefix))
+                continue;
+            const relative = child.slice(prefix.length);
+            if (relative.includes("/") || relative === "")
+                continue;
+            entries.push({ kind: "directory", path: child, title: titles.get(`${child}/index.md`) ?? relative,
+                description: null, href: `${href(relative)}/index.md` });
+        }
+        for (const document of analysis.documents) {
+            if (document.kind === "index" || !document.path.startsWith(prefix))
+                continue;
+            const relative = document.path.slice(prefix.length);
+            if (relative.includes("/"))
+                continue;
+            entries.push({ kind: "document", path: document.path, title: document.derived.title,
+                description: document.derived.description, href: href(relative) });
+        }
+        entries.sort((left, right) => byCodePoint(left.path, right.path));
+        const version = directory === "." && analysis.okfVersion !== null
+            ? `---\nokf_version: ${JSON.stringify(analysis.okfVersion)}\n---\n\n` : "";
+        const lines = entries.map((entry) => `- [${label(entry.title)}](${entry.href})${entry.description
+            ? ` — ${label(entry.description)}` : ""}`);
+        return { schema: "okf.index.v1", generated: true, directory, path: indexPath, title, entries,
+            content: `${version}# ${label(title)}\n\n${lines.length ? `${lines.join("\n")}\n` : ""}` };
+    });
+}
+export function selectBundleIndex(indexes, requested = ".") {
+    const directory = requested === "." ? "." : validateBundlePath(requested);
+    const index = indexes.find((candidate) => candidate.directory === directory);
+    if (!index)
+        throw new Error(`directory does not exist in bundle: ${requested}`);
+    return index;
+}
+//# sourceMappingURL=indexes.js.map

package/dist/indexes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.js","sourceRoot":"","sources":["../src/indexes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE7D,SAAS,KAAK,CAAC,KAAa;IAC1B,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,IAAI,CAAC,KAAa;IACzB,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,EAC/E,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxF,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,QAAwB;IAC5D,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACrD,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,OAAO,CAAC;SACtF,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QAC1D,MAAM,MAAM,GAAG,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC;QACxD,MAAM,SAAS,GAAG,GAAG,MAAM,UAAU,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;QACrG,MAAM,OAAO,GAAuB,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,KAAK,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,SAAS;YACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5C,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,EAAE;gBAAE,SAAS;YACxD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,WAAW,CAAC,IAAI,QAAQ;gBAC/F,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,SAAS;YAC7E,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACpD,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,SAAS;YACrC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK;gBACjF,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAClE,MAAM,OAAO,GAAG,SAAS,KAAK,GAAG,IAAI,QAAQ,CAAC,UAAU,KAAK,IAAI;YAC/D,CAAC,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,WAAW;YAC/F,CAAC,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO;YAC1F,OAAO,EAAE,GAAG,OAAO,KAAK,KAAK,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;IAC/F,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAwC,EAAE,SAAS,GAAG,GAAG;IACzF,MAAM,SAAS,GAAG,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IAC7E,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,SAAS,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okf-core",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Canonical parser, validator, link resolver, graph, and search engine for OKF v0.2",
   "type": "module",
   "repository": {
@@ -32,7 +32,7 @@
     "diff": "^9.0.0",
     "mdast-util-from-markdown": "^2.0.2",
     "yaml": "^2.9.0",
-    "okf-contracts": "1.1.0"
+    "okf-contracts": "2.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",