@dogsbay/format-topicmap 0.2.0-beta.101

package/dist/parse.js

@@ -0,0 +1,143 @@
+import { load as loadYaml } from "js-yaml";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const parseEntry = (raw, mapPath, pointer, errors) => {
+    if (!isRecord(raw)) {
+        errors.push({
+            mapPath,
+            code: "invalid-entry",
+            message: `${pointer}: entry must be a mapping, got ${Array.isArray(raw) ? "array" : typeof raw}`,
+        });
+        return null;
+    }
+    const entry = {};
+    if (raw.navtitle !== undefined) {
+        if (typeof raw.navtitle !== "string" || raw.navtitle.trim().length === 0) {
+            // Empty labels would pass check but crash the downstream nav loader
+            errors.push({ mapPath, code: "invalid-entry", message: `${pointer}: navtitle must be a non-empty string` });
+        }
+        else {
+            entry.navtitle = raw.navtitle;
+        }
+    }
+    if (raw.href !== undefined) {
+        if (typeof raw.href !== "string" || raw.href.length === 0) {
+            errors.push({ mapPath, code: "invalid-entry", message: `${pointer}: href must be a non-empty string` });
+        }
+        else {
+            entry.href = raw.href;
+        }
+    }
+    if (raw.format !== undefined) {
+        if (raw.format === "topicmap" || raw.format === "md") {
+            entry.format = raw.format;
+        }
+        else {
+            errors.push({
+                mapPath,
+                code: "invalid-entry",
+                message: `${pointer}: format must be "topicmap" or "md", got ${JSON.stringify(raw.format)}`,
+            });
+        }
+    }
+    if (raw.toc !== undefined) {
+        if (typeof raw.toc !== "boolean") {
+            errors.push({ mapPath, code: "invalid-entry", message: `${pointer}: toc must be a boolean` });
+        }
+        else {
+            entry.toc = raw.toc;
+        }
+    }
+    if (raw.singlePage !== undefined) {
+        if (raw.singlePage === "yes" || raw.singlePage === "no" || raw.singlePage === "children") {
+            entry.singlePage = raw.singlePage;
+        }
+        else {
+            errors.push({
+                mapPath,
+                code: "invalid-entry",
+                message: `${pointer}: singlePage must be "yes", "no" or "children"`,
+            });
+        }
+    }
+    if (raw.meta !== undefined) {
+        if (isRecord(raw.meta)) {
+            entry.meta = raw.meta;
+        }
+        else {
+            errors.push({ mapPath, code: "invalid-entry", message: `${pointer}: meta must be a mapping` });
+        }
+    }
+    // `topics:` with nothing under it (a placeholder authors leave for later)
+    // is an empty list, not an error — it is a common hand-written shape
+    if (raw.topics !== undefined && raw.topics !== null) {
+        if (!Array.isArray(raw.topics)) {
+            errors.push({ mapPath, code: "invalid-entry", message: `${pointer}: topics must be an array` });
+        }
+        else {
+            entry.topics = raw.topics
+                .map((child, i) => parseEntry(child, mapPath, `${pointer}.topics[${i}]`, errors))
+                .filter((child) => child !== null);
+        }
+    }
+    if (entry.navtitle === undefined && entry.href === undefined) {
+        errors.push({
+            mapPath,
+            code: "invalid-entry",
+            message: `${pointer}: entry needs a navtitle or an href`,
+        });
+        return null;
+    }
+    if (entry.format === "topicmap" && entry.href === undefined) {
+        errors.push({
+            mapPath,
+            code: "invalid-entry",
+            message: `${pointer}: format "topicmap" requires an href`,
+        });
+        return null;
+    }
+    return entry;
+};
+/**
+ * Parse a topic map YAML source. Never throws — problems are collected as
+ * structured errors so builds can report all of them at once.
+ */
+export const parseTopicMap = (source, mapPath = "") => {
+    const errors = [];
+    let raw;
+    try {
+        raw = loadYaml(source);
+    }
+    catch (error) {
+        errors.push({
+            mapPath,
+            code: "invalid-yaml",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { map: null, errors };
+    }
+    if (!isRecord(raw)) {
+        errors.push({ mapPath, code: "invalid-shape", message: "topic map must be a YAML mapping" });
+        return { map: null, errors };
+    }
+    // `topics:` with nothing under it is an empty map (a placeholder authors leave), not an error
+    const rawTopics = raw.topics === null ? [] : raw.topics;
+    if (!Array.isArray(rawTopics)) {
+        errors.push({ mapPath, code: "invalid-shape", message: 'topic map requires a "topics" array' });
+        return { map: null, errors };
+    }
+    const map = {
+        topics: rawTopics
+            .map((entry, i) => parseEntry(entry, mapPath, `topics[${i}]`, errors))
+            .filter((entry) => entry !== null),
+    };
+    if (raw.title !== undefined) {
+        if (typeof raw.title === "string") {
+            map.title = raw.title;
+        }
+        else {
+            errors.push({ mapPath, code: "invalid-shape", message: "title must be a string" });
+        }
+    }
+    return { map, errors };
+};
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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

package/dist/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal POSIX-style path helpers. Deliberately not node:path so the
+ * package runs unmodified in browsers and extension contexts.
+ */
+export declare const normalizePath: (path: string) => string;
+export declare const dirname: (path: string) => string;
+export declare const joinPath: (...segments: string[]) => string;
+/** True for scheme-prefixed URLs (https://, mailto:, …) that must never be path-resolved. */
+export declare const isExternalHref: (href: string) => boolean;
+/** Resolve `href` (map-relative) against the directory of the containing map. */
+export declare const resolveHref: (href: string, containingMapPath: string) => string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAmB5C,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAMtC,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,GAAG,UAAU,MAAM,EAAE,KAAG,MACE,CAAC;AAEpD,6FAA6F;AAC7F,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAAiD,CAAC;AAEhG,iFAAiF;AACjF,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,mBAAmB,MAAM,KAAG,MAerE,CAAC"}

package/dist/paths.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal POSIX-style path helpers. Deliberately not node:path so the
+ * package runs unmodified in browsers and extension contexts.
+ */
+export const normalizePath = (path) => {
+    const isAbsolute = path.startsWith("/");
+    const parts = path.split("/");
+    const out = [];
+    for (const part of parts) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (out.length > 0 && out[out.length - 1] !== "..") {
+                out.pop();
+            }
+            else if (!isAbsolute) {
+                out.push("..");
+            }
+            continue;
+        }
+        out.push(part);
+    }
+    return (isAbsolute ? "/" : "") + out.join("/");
+};
+export const dirname = (path) => {
+    const normalized = normalizePath(path);
+    const idx = normalized.lastIndexOf("/");
+    if (idx === -1)
+        return "";
+    if (idx === 0)
+        return "/";
+    return normalized.slice(0, idx);
+};
+export const joinPath = (...segments) => normalizePath(segments.filter(Boolean).join("/"));
+/** True for scheme-prefixed URLs (https://, mailto:, …) that must never be path-resolved. */
+export const isExternalHref = (href) => /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(href);
+/** Resolve `href` (map-relative) against the directory of the containing map. */
+export const resolveHref = (href, containingMapPath) => {
+    if (isExternalHref(href))
+        return href;
+    if (href.startsWith("/"))
+        return normalizePath(href);
+    // Relative child of a remote map: join scheme-safely so the `//` after
+    // the scheme is never collapsed by path normalization
+    if (isExternalHref(containingMapPath)) {
+        const match = containingMapPath.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]+)(\/.*)?$/);
+        if (!match)
+            return href;
+        const origin = match[1];
+        const dir = dirname(match[2] ?? "/") || "/";
+        return origin + normalizePath(`${dir}/${href}`);
+    }
+    return joinPath(dirname(containingMapPath), href);
+};
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE;IACpD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAa,EAAE,CAAC;IAEzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,GAAG;YAAE,SAAS;QAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;gBACnD,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;iBAAM,IAAI,CAAC,UAAU,EAAE,CAAC;gBACvB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;YACD,SAAS;QACX,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACjD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE;IAC9C,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAG,QAAkB,EAAU,EAAE,CACxD,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEpD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEhG,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,iBAAyB,EAAU,EAAE;IAC7E,IAAI,cAAc,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAErD,uEAAuE;IACvE,sDAAsD;IACtD,IAAI,cAAc,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QACtF,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC;QAC5C,OAAO,MAAM,GAAG,aAAa,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,13 @@
+import type { ResolveOptions, ResolvedTopicMap } from "./types.js";
+/**
+ * Recursively resolve a topic map: load and splice `format: topicmap`
+ * includes (cycle-safe, depth-limited), resolve minja variables in
+ * navtitle/href, and rewrite hrefs relative to the root map's directory so
+ * consumers see one consistent path space.
+ *
+ * Never throws for content problems — all issues land in `errors` and the
+ * affected entries are dropped, so a broken sub-map cannot take down the
+ * whole build.
+ */
+export declare const resolveTopicMap: (rootPath: string, options: ResolveOptions) => Promise<ResolvedTopicMap>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AAsCpB;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,EAChB,SAAS,cAAc,KACtB,OAAO,CAAC,gBAAgB,CA+G1B,CAAC"}

package/dist/resolve.js

@@ -0,0 +1,140 @@
+import { render, MemoryLoader } from "@dogsbay/minja";
+import { parseTopicMap } from "./parse.js";
+import { normalizePath, resolveHref, isExternalHref } from "./paths.js";
+const DEFAULT_MAX_DEPTH = 10;
+// Shared empty loader: entry-level templating only uses variables, never includes
+const NO_INCLUDES = new MemoryLoader({});
+const hasTemplateSyntax = (value) => value.includes("{{") || value.includes("{%");
+/**
+ * Resolve minja variables in a single string value. Undefined variables are
+ * preserved (multi-stage pipelines may resolve them later).
+ */
+const renderValue = async (value, variables, mapPath, errors) => {
+    if (!hasTemplateSyntax(value))
+        return value;
+    try {
+        return await render(value, {
+            context: variables,
+            loader: NO_INCLUDES,
+            undefinedBehavior: "preserve",
+        });
+    }
+    catch (error) {
+        errors.push({
+            mapPath,
+            code: "variable-error",
+            message: `failed to resolve variables in ${JSON.stringify(value)}: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return value;
+    }
+};
+/**
+ * Recursively resolve a topic map: load and splice `format: topicmap`
+ * includes (cycle-safe, depth-limited), resolve minja variables in
+ * navtitle/href, and rewrite hrefs relative to the root map's directory so
+ * consumers see one consistent path space.
+ *
+ * Never throws for content problems — all issues land in `errors` and the
+ * affected entries are dropped, so a broken sub-map cannot take down the
+ * whole build.
+ */
+export const resolveTopicMap = async (rootPath, options) => {
+    const { loader, variables = {}, maxDepth = DEFAULT_MAX_DEPTH } = options;
+    const errors = [];
+    const loadMap = async (path, stack) => {
+        // Remote map URLs must not be path-normalized (https:// would collapse)
+        const normalized = isExternalHref(path) ? path : normalizePath(path);
+        if (stack.includes(normalized)) {
+            errors.push({
+                mapPath: normalized,
+                code: "cycle",
+                message: `circular topic map include: ${[...stack, normalized].join(" → ")}`,
+            });
+            return null;
+        }
+        if (stack.length >= maxDepth) {
+            errors.push({
+                mapPath: normalized,
+                code: "max-depth",
+                message: `maximum topic map depth (${maxDepth}) exceeded`,
+            });
+            return null;
+        }
+        let source;
+        try {
+            source = await loader(normalized);
+        }
+        catch (error) {
+            errors.push({
+                mapPath: normalized,
+                code: "load-failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+        const parsed = parseTopicMap(source, normalized);
+        errors.push(...parsed.errors);
+        if (!parsed.map)
+            return null;
+        const resolveEntries = async (entries) => {
+            const out = [];
+            for (const entry of entries) {
+                const resolved = { ...entry };
+                if (resolved.navtitle !== undefined) {
+                    resolved.navtitle = await renderValue(resolved.navtitle, variables, normalized, errors);
+                }
+                if (resolved.href !== undefined) {
+                    const rendered = await renderValue(resolved.href, variables, normalized, errors);
+                    resolved.href = resolveHref(rendered, normalized);
+                }
+                if (resolved.format === "topicmap" && resolved.href) {
+                    const child = await loadMap(resolved.href, [...stack, normalized]);
+                    if (child === null) {
+                        // Error already recorded; drop the broken include
+                        continue;
+                    }
+                    // Entries authored under the include are preserved, appended
+                    // after the child map's topics (DITA topicref-with-children order)
+                    const authored = resolved.topics ? await resolveEntries(resolved.topics) : [];
+                    const mergedTopics = [...child.topics, ...authored];
+                    const label = resolved.navtitle ?? child.title;
+                    if (label !== undefined) {
+                        out.push({
+                            navtitle: label,
+                            ...(resolved.toc !== undefined && { toc: resolved.toc }),
+                            ...(resolved.singlePage !== undefined && { singlePage: resolved.singlePage }),
+                            ...(resolved.meta !== undefined && { meta: resolved.meta }),
+                            topics: mergedTopics,
+                        });
+                    }
+                    else if (resolved.toc === false) {
+                        // No wrapper node to carry the exclusion — propagate it to
+                        // every spliced entry so hidden content stays hidden
+                        out.push(...mergedTopics.map((topic) => ({ ...topic, toc: false })));
+                    }
+                    else {
+                        // No label anywhere: splice the child's entries inline
+                        out.push(...mergedTopics);
+                    }
+                    continue;
+                }
+                if (resolved.topics) {
+                    resolved.topics = await resolveEntries(resolved.topics);
+                }
+                out.push(resolved);
+            }
+            return out;
+        };
+        let title = parsed.map.title;
+        if (title !== undefined) {
+            title = await renderValue(title, variables, normalized, errors);
+        }
+        return {
+            ...(title !== undefined && { title }),
+            topics: await resolveEntries(parsed.map.topics),
+        };
+    };
+    const map = (await loadMap(rootPath, [])) ?? { topics: [] };
+    return { map, errors };
+};
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

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

package/dist/serialize.d.ts

@@ -0,0 +1,3 @@
+import type { TopicMap } from "./types.js";
+export declare const serializeTopicMap: (map: TopicMap) => string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAC;AAe1D,eAAO,MAAM,iBAAiB,GAAI,KAAK,QAAQ,KAAG,MAMjD,CAAC"}

package/dist/serialize.js

@@ -0,0 +1,28 @@
+import { dump as dumpYaml } from "js-yaml";
+// Stable key order so serialized maps diff cleanly in git
+const orderEntry = (entry) => {
+    const out = {};
+    if (entry.navtitle !== undefined)
+        out.navtitle = entry.navtitle;
+    if (entry.href !== undefined)
+        out.href = entry.href;
+    if (entry.format !== undefined)
+        out.format = entry.format;
+    if (entry.toc !== undefined)
+        out.toc = entry.toc;
+    if (entry.singlePage !== undefined)
+        out.singlePage = entry.singlePage;
+    if (entry.meta !== undefined)
+        out.meta = entry.meta;
+    if (entry.topics !== undefined)
+        out.topics = entry.topics.map(orderEntry);
+    return out;
+};
+export const serializeTopicMap = (map) => {
+    const out = {};
+    if (map.title !== undefined)
+        out.title = map.title;
+    out.topics = map.topics.map(orderEntry);
+    return dumpYaml(out, { lineWidth: 100, noRefs: true });
+};
+//# sourceMappingURL=serialize.js.map

package/dist/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG3C,0DAA0D;AAC1D,MAAM,UAAU,GAAG,CAAC,KAAoB,EAA2B,EAAE;IACnE,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,GAAG,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACpD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1D,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;QAAE,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACjD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACtE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACpD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC1E,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAa,EAAU,EAAE;IACzD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACnD,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAExC,OAAO,QAAQ,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Topic map model — the authored source of truth for site structure.
+ *
+ * A topic map is a recursive YAML file (`*.topicmap.yml`) equivalent to a
+ * DITA map: entries reference content files or other topic maps
+ * (`format: topicmap`), nested to any depth. Builds resolve maps to
+ * NavItem[] (nav.json is a build output, never the source).
+ */
+export interface TopicMapEntry {
+    /** Display name in navigation. Optional when `href` provides one. */
+    navtitle?: string;
+    /** Path to a content file or (with `format: topicmap`) another map, relative to the containing map. */
+    href?: string;
+    /** `topicmap` marks `href` as a nested topic map to splice in. */
+    format?: "topicmap" | "md";
+    /** `false` excludes the entry from navigation (still built/addressable). */
+    toc?: boolean;
+    /** Granularity roll-up, passed through to NavItem (plans/granularity-views.md). */
+    singlePage?: "yes" | "no" | "children";
+    /** Child entries. */
+    topics?: TopicMapEntry[];
+    /** Provenance and processing hints (e.g. `meta.dita` from import-ditamap). */
+    meta?: Record<string, unknown>;
+}
+export interface TopicMap {
+    /** Map title; used as the group label when the map is included without a navtitle. */
+    title?: string;
+    topics: TopicMapEntry[];
+}
+export interface TopicMapError {
+    /** Path of the map file the error was found in ("" for inline sources). */
+    mapPath: string;
+    /** Machine-readable error kind. */
+    code: "invalid-yaml" | "invalid-shape" | "invalid-entry" | "cycle" | "max-depth" | "load-failed" | "variable-error";
+    message: string;
+}
+/** Loads a topic map source by normalized path. Injectable: fs, fetch, memory. */
+export type TopicMapLoader = (path: string) => Promise<string>;
+export interface ResolveOptions {
+    loader: TopicMapLoader;
+    /** minja context for `{{ var }}` resolution in navtitle/href values. */
+    variables?: Record<string, unknown>;
+    /** Maximum include depth (defence against runaway nesting). Default 10. */
+    maxDepth?: number;
+}
+export interface ResolvedTopicMap {
+    /** Fully resolved map: no `format: topicmap` entries remain. */
+    map: TopicMap;
+    /** Non-fatal errors collected during resolution (MarkMind pattern). */
+    errors: TopicMapError[];
+}
+export declare const TOPICMAP_EXTENSIONS: readonly [".topicmap.yml", ".topicmap.yaml"];
+export declare const isTopicMapPath: (path: string) => boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uGAAuG;IACvG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,mFAAmF;IACnF,UAAU,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,UAAU,CAAC;IACvC,qBAAqB;IACrB,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,IAAI,EACA,cAAc,GACd,eAAe,GACf,eAAe,GACf,OAAO,GACP,WAAW,GACX,aAAa,GACb,gBAAgB,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,cAAc,CAAC;IACvB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,GAAG,EAAE,QAAQ,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,eAAO,MAAM,mBAAmB,8CAA+C,CAAC;AAEhF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OACS,CAAC"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Topic map model — the authored source of truth for site structure.
+ *
+ * A topic map is a recursive YAML file (`*.topicmap.yml`) equivalent to a
+ * DITA map: entries reference content files or other topic maps
+ * (`format: topicmap`), nested to any depth. Builds resolve maps to
+ * NavItem[] (nav.json is a build output, never the source).
+ */
+export const TOPICMAP_EXTENSIONS = [".topicmap.yml", ".topicmap.yaml"];
+export const isTopicMapPath = (path) => TOPICMAP_EXTENSIONS.some((ext) => path.endsWith(ext));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0DH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,eAAe,EAAE,gBAAgB,CAAU,CAAC;AAEhF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAAY,EAAW,EAAE,CACtD,mBAAmB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dogsbay/format-topicmap",
+  "version": "0.2.0-beta.101",
+  "description": "Recursive YAML topic maps — DITA-map-equivalent authored structure, resolved to NavItem trees",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "js-yaml": "^5.2.1",
+    "yaml": "^2.9.0",
+    "@dogsbay/minja": "0.2.0-beta.101",
+    "@dogsbay/types": "0.2.0-beta.101"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/format-topicmap"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/format-topicmap",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}