@dogsbay/format-topicmap 0.2.0-beta.101

package/README.md

@@ -0,0 +1,32 @@
+# @dogsbay/format-topicmap
+
+Recursive YAML topic maps for Dogsbay — a DITA-map-equivalent way to author
+documentation structure in plain, versionable YAML.
+
+```yaml
+# root.topicmap.yml
+title: Product Docs
+topics:
+  - navtitle: Getting Started
+    topics:
+      - href: welcome.md
+      - href: quickstart.md
+  - navtitle: Installing
+    href: installing/installing.topicmap.yml
+    format: topicmap        # maps compose: teams own their own sub-maps
+```
+
+```ts
+import { resolveTopicMap, topicMapToNav } from "@dogsbay/format-topicmap";
+
+const { map, errors } = await resolveTopicMap("docs/root.topicmap.yml", {
+  loader: async (path) => fs.readFile(path, "utf8"),
+  variables: { product: "Dogsbay" },
+});
+const nav = topicMapToNav(map); // NavItem[] → nav.json
+```
+
+Features: unlimited nesting, cycle detection, minja variable resolution
+(eval-free), `toc: false` exclusions, `singlePage` granularity roll-ups,
+provenance metadata for DITA round-trip. Browser-safe (injected loader, no
+Node APIs). See `CLAUDE.md` for the full API.

package/dist/edit-source.d.ts

@@ -0,0 +1,29 @@
+import { type AddRefInput, type MoveRefInput, type SetPropsInput, type EditResult, type ExistsFn } from "./edit.js";
+import type { TopicMapEntry } from "./types.js";
+export type MapEditOp = ({
+    kind: "add";
+} & AddRefInput) | ({
+    kind: "move";
+} & MoveRefInput) | {
+    kind: "remove";
+    at: string;
+    keepChildren?: boolean;
+} | ({
+    kind: "set";
+} & SetPropsInput);
+export type SourceEditResult = EditResult<{
+    source: string;
+    pointer: string;
+    entry: TopicMapEntry;
+    changed?: string[];
+    childrenRemoved?: number;
+    childrenHoisted?: number;
+    from?: string;
+    target?: string;
+}>;
+/**
+ * Apply one structural edit to `source`. Returns the new source (untouched
+ * regions byte-identical) or a refusal (source untouched).
+ */
+export declare function applyMapEdit(source: string, mapFile: string, op: MapEditOp, exists?: ExistsFn): SourceEditResult;
+//# sourceMappingURL=edit-source.d.ts.map

package/dist/edit-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-source.d.ts","sourceRoot":"","sources":["../src/edit-source.ts"],"names":[],"mappings":"AAuBA,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAElB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,SAAS,GACjB,CAAC;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG,WAAW,CAAC,GAC/B,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAAC,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACtD,CAAC;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG,aAAa,CAAC,CAAC;AAEtC,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AA+EH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,gBAAgB,CAsEhH"}

package/dist/edit-source.js

@@ -0,0 +1,196 @@
+/**
+ * Structural edits applied to the topic map SOURCE — comment-, key-order-,
+ * quoting- and unknown-key-preserving (plans/topicmap-editor.md: "unknown
+ * keys survive", "minimal diff"). This is what both the IDE's Structure
+ * panel and the agent's `map-*` verbs write through.
+ *
+ * Two layers, one truth:
+ *   1. the MODEL transforms in `edit.ts` run first on `parseTopicMap(source)`
+ *      — addressing, guardrails (dangling href, self-include, move into own
+ *      subtree, empty entry) and the result pointer; a refusal returns
+ *      before anything is touched;
+ *   2. the SAME structural change is replayed on the `yaml` Document (CST-
+ *      backed AST): nodes are moved/spliced/set in place, and everything
+ *      not touched — comments, blank lines, anchors, unknown keys, scalar
+ *      styles — comes back byte-identical from `doc.toString()`.
+ *
+ * Pointer parity: model indices must equal document indices, so a source
+ * whose parse reports ANY error (an entry the model dropped, a mistyped
+ * field) is refused with `map-has-errors` — editing it blind would delete
+ * what the parser could not represent. Fix the YAML in Source mode first.
+ */
+import { parseDocument, isMap, isSeq, isScalar, YAMLMap, YAMLSeq, Scalar } from "yaml";
+import { parseTopicMap } from "./parse.js";
+import { addRef, moveRef, removeRef, setProps, resolveAddress, } from "./edit.js";
+const refuse = (code, message, extra) => ({ ok: false, code, message, ...(extra ? { extra } : {}) });
+/** Strings a YAML 1.1 reader would take for a bool/null/number are quoted (`singlePage: 'yes'`), as serialize.ts does. */
+const AMBIGUOUS = /^(?:yes|no|on|off|y|n|true|false|null|~|[-+]?(?:\d[\d_]*\.?[\d_]*|\.\d+)(?:e[-+]?\d+)?|0x[0-9a-f]+|0o[0-7]+)$/i;
+const scalarFor = (value) => {
+    const sc = new Scalar(value);
+    if (typeof value === "string" && (value === "" || AMBIGUOUS.test(value) || /^\s|\s$/.test(value)))
+        sc.type = Scalar.QUOTE_SINGLE;
+    return sc;
+};
+/** Canonical key order for a NEW entry mapping (matches serialize.ts). */
+const KEY_ORDER = ["navtitle", "href", "format", "toc", "singlePage", "meta", "topics"];
+/** The YAMLSeq that holds the entries at `path` (root `topics`, or an entry's `topics`, created when `create`). */
+/** `topics` of a mapping node as a YAMLSeq; `topics:` (null) or absent becomes an empty seq when `create`. */
+function topicsSeq(node, create) {
+    const cur = node.get("topics", true);
+    if (isSeq(cur))
+        return cur;
+    const isNullish = cur === undefined || cur === null || (isScalar(cur) && cur.value === null);
+    if (!isNullish || !create)
+        return undefined;
+    const fresh = new YAMLSeq();
+    node.set("topics", fresh);
+    return fresh;
+}
+function seqAt(doc, path, create) {
+    const root = doc.contents;
+    if (!isMap(root))
+        return undefined;
+    let seq = topicsSeq(root, create);
+    if (!seq)
+        return undefined;
+    for (const idx of path) {
+        const entry = seq.items[idx];
+        if (!isMap(entry))
+            return undefined;
+        const child = topicsSeq(entry, create);
+        if (!child)
+            return undefined;
+        seq = child;
+    }
+    return seq;
+}
+function entryNodeAt(doc, path) {
+    if (!path.length)
+        return undefined;
+    const seq = seqAt(doc, path.slice(0, -1), false);
+    const node = seq?.items[path[path.length - 1]];
+    return isMap(node) ? node : undefined;
+}
+function newEntryNode(entry) {
+    const m = new YAMLMap();
+    for (const key of KEY_ORDER) {
+        const v = entry[key];
+        if (v === undefined)
+            continue;
+        if (key === "topics")
+            continue; // a new entry has none
+        m.set(key, typeof v === "string" ? scalarFor(v) : v);
+    }
+    return m;
+}
+/** Set a scalar key on an entry mapping, preserving position when it already exists; delete on undefined. */
+function setKey(node, key, value) {
+    if (value === undefined) {
+        node.delete(key);
+        return;
+    }
+    const existing = node.get(key, true);
+    const next = scalarFor(value);
+    if (isScalar(existing)) {
+        // keep the author's scalar style where the value type allows it (a quoted style always allows a string)
+        if (typeof value === "string" && typeof existing.value === "string" && existing.type && existing.type !== Scalar.PLAIN)
+            next.type = existing.type;
+        const pair = node.items.find((p) => isScalar(p.key) && p.key.value === key);
+        if (pair)
+            pair.value = next;
+        else
+            node.set(key, next);
+    }
+    else {
+        node.set(key, next);
+    }
+}
+/**
+ * Apply one structural edit to `source`. Returns the new source (untouched
+ * regions byte-identical) or a refusal (source untouched).
+ */
+export function applyMapEdit(source, mapFile, op, exists) {
+    const parsed = parseTopicMap(source, mapFile);
+    if (!parsed.map)
+        return refuse("map-invalid", parsed.errors[0]?.message ?? "invalid topic map");
+    if (parsed.errors.length) {
+        return refuse("map-has-errors", `the map has ${parsed.errors.length} parse error${parsed.errors.length === 1 ? "" : "s"}; fix them in Source mode before structural edits (${parsed.errors[0].message})`, { errors: parsed.errors });
+    }
+    const map = parsed.map;
+    const doc = parseDocument(source, { keepSourceTokens: true });
+    if (doc.errors.length)
+        return refuse("map-invalid", doc.errors[0].message);
+    if (!isMap(doc.contents))
+        return refuse("map-invalid", "topic map must be a mapping");
+    switch (op.kind) {
+        case "add": {
+            // resolve the parent BEFORE the model mutates (indices are positions)
+            const parent = resolveAddress(map, op.parent ?? "");
+            if (!parent.ok)
+                return parent;
+            const r = addRef(map, mapFile, op, exists);
+            if (!r.ok)
+                return r;
+            const seq = seqAt(doc, parent.path, true);
+            if (!seq)
+                return refuse("map-invalid", "cannot locate the parent in the document");
+            const index = op.index === undefined ? seq.items.length : Math.min(op.index, seq.items.length);
+            seq.items.splice(index, 0, newEntryNode(r.entry));
+            return { ok: true, source: doc.toString(), pointer: r.pointer, entry: r.entry, ...(r.target ? { target: r.target } : {}) };
+        }
+        case "move": {
+            const from = resolveAddress(map, op.from);
+            if (!from.ok)
+                return from;
+            const toParent = op.toParent === undefined ? { ok: true, path: from.path.slice(0, -1) } : resolveAddress(map, op.toParent);
+            if (!toParent.ok)
+                return toParent;
+            const r = moveRef(map, op);
+            if (!r.ok)
+                return r;
+            const srcSeq = seqAt(doc, from.path.slice(0, -1), false);
+            const dstSeq = seqAt(doc, toParent.path, true);
+            if (!srcSeq || !dstSeq)
+                return refuse("map-invalid", "cannot locate the entry in the document");
+            const [node] = srcSeq.items.splice(from.path[from.path.length - 1], 1);
+            const index = op.index === undefined ? dstSeq.items.length : Math.min(op.index, dstSeq.items.length);
+            dstSeq.items.splice(index, 0, node);
+            // an emptied `topics:` list on the old parent stays as `[]` — the author's key, kept
+            return { ok: true, source: doc.toString(), pointer: r.to, from: r.from, entry: r.entry };
+        }
+        case "remove": {
+            const at = resolveAddress(map, op.at);
+            if (!at.ok)
+                return at;
+            const r = removeRef(map, op);
+            if (!r.ok)
+                return r;
+            const seq = seqAt(doc, at.path.slice(0, -1), false);
+            const node = seq?.items[at.path[at.path.length - 1]];
+            if (!seq || !isMap(node))
+                return refuse("map-invalid", "cannot locate the entry in the document");
+            const children = op.keepChildren ? node.get("topics", true) : undefined;
+            const hoisted = isSeq(children) ? children.items : [];
+            seq.items.splice(at.path[at.path.length - 1], 1, ...hoisted);
+            return { ok: true, source: doc.toString(), pointer: r.pointer, entry: r.entry, childrenRemoved: r.childrenRemoved, childrenHoisted: r.childrenHoisted };
+        }
+        case "set": {
+            const at = resolveAddress(map, op.at);
+            if (!at.ok)
+                return at;
+            const r = setProps(map, mapFile, op, exists);
+            if (!r.ok)
+                return r;
+            const node = entryNodeAt(doc, at.path);
+            if (!node)
+                return refuse("map-invalid", "cannot locate the entry in the document");
+            // replay from the model's post-state so `format` bookkeeping matches
+            for (const key of r.changed)
+                setKey(node, key, r.entry[key]);
+            if (r.changed.includes("href") && !r.changed.includes("format"))
+                setKey(node, "format", r.entry.format);
+            return { ok: true, source: doc.toString(), pointer: r.pointer, entry: r.entry, changed: r.changed };
+        }
+    }
+}
+//# sourceMappingURL=edit-source.js.map

package/dist/edit-source.js.map

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

package/dist/edit.d.ts

@@ -0,0 +1,95 @@
+import { type TopicMap, type TopicMapEntry } from "./types.js";
+export interface EditRefusal {
+    ok: false;
+    code: string;
+    message: string;
+    extra?: Record<string, unknown>;
+}
+export type EditResult<T extends object = Record<string, never>> = ({
+    ok: true;
+} & T) | EditRefusal;
+export declare const parsePointer: (pointer: string) => number[] | undefined;
+export declare const pointerOf: (path: number[]) => string;
+/** The `topics` array a pointer's PARENT owns, plus the index. Read-only: never creates arrays. */
+export declare const locate: (map: TopicMap, path: number[]) => {
+    siblings: TopicMapEntry[];
+    index: number;
+    entry: TopicMapEntry;
+} | undefined;
+/** The container to insert INTO (root or an entry's topics, created on demand for the write path). */
+export declare const containerOf: (map: TopicMap, path: number[]) => TopicMapEntry[] | undefined;
+/** Pointer of an entry by IDENTITY (after a splice, indices may have shifted). */
+export declare const pathOfEntry: (map: TopicMap, target: TopicMapEntry) => number[] | undefined;
+/** Workspace path an href points at (undefined for external / fragment-only). */
+export declare const hrefTarget: (mapFile: string, href: string) => string | undefined;
+/** A local href that resolves to the map itself is a self-include, whatever the format flag says. */
+export declare const isSelfInclude: (mapFile: string, href: string) => boolean;
+/** All entries matching an href or navtitle. */
+export declare const findByHref: (map: TopicMap, href: string) => number[][];
+/** Pointer, or unique href/navtitle (`@x` forces name matching), to a path. */
+export declare const resolveAddress: (map: TopicMap, at: string) => EditResult<{
+    path: number[];
+}>;
+export interface FlatEntry {
+    pointer: string;
+    depth: number;
+    navtitle?: string;
+    href?: string;
+    format?: string;
+    toc?: boolean;
+    singlePage?: string;
+    children: number;
+}
+export declare const flattenTopicMap: (map: TopicMap) => FlatEntry[];
+/** Sync existence predicate over workspace-relative paths (the caller resolves it). */
+export type ExistsFn = (workspacePath: string) => boolean;
+export interface AddRefInput {
+    /** Optional when a navtitle is given (a title-only grouping entry). */
+    href?: string;
+    navtitle?: string;
+    /** Parent pointer/href; "" = root. */
+    parent?: string;
+    index?: number;
+    format?: "topicmap" | "md";
+    toc?: boolean;
+    singlePage?: "yes" | "no" | "children";
+}
+export declare const addRef: (map: TopicMap, mapFile: string, input: AddRefInput, exists?: ExistsFn) => EditResult<{
+    pointer: string;
+    entry: TopicMapEntry;
+    target?: string;
+}>;
+export interface MoveRefInput {
+    from: string;
+    /** New parent pointer/href; "" = root; undefined = same parent. */
+    toParent?: string;
+    index?: number;
+}
+export declare const moveRef: (map: TopicMap, input: MoveRefInput) => EditResult<{
+    from: string;
+    to: string;
+    entry: TopicMapEntry;
+}>;
+export declare const removeRef: (map: TopicMap, input: {
+    at: string;
+    keepChildren?: boolean;
+}) => EditResult<{
+    pointer: string;
+    entry: TopicMapEntry;
+    childrenRemoved: number;
+    childrenHoisted: number;
+}>;
+export interface SetPropsInput {
+    at: string;
+    navtitle?: string | null;
+    href?: string | null;
+    format?: "topicmap" | "md" | null;
+    toc?: boolean | null;
+    singlePage?: "yes" | "no" | "children" | null;
+}
+export declare const setProps: (map: TopicMap, mapFile: string, input: SetPropsInput, exists?: ExistsFn) => EditResult<{
+    pointer: string;
+    changed: string[];
+    entry: TopicMapEntry;
+}>;
+//# sourceMappingURL=edit.d.ts.map

package/dist/edit.d.ts.map

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