src/links.ts

Functions

Imports

It imports src/limits.ts. Imported by src/tools/docs-write.ts.

Source

1import { nsName, pathProblem } from "./limits";
2
3export const LINK_TYPES = ["governs", "references", "supersedes", "replaces", "depends-on"] as const;
4type LinkType = (typeof LINK_TYPES)[number];
5
6const isLinkType = (value: unknown): value is LinkType =>
7  typeof value === "string" && (LINK_TYPES as readonly string[]).includes(value);
8
9export interface LinkEdge {
10  type: LinkType;
11  to_ns: string;
12  to_path: string;
13}
14
15// Endpoints are document keys. Same pathProblem and nsName as the write path.
16// An empty array clears outgoing edges. to_ns defaults to the writing namespace.
17export function parseLinks(linksJson: string, fromNs: string): { edges: LinkEdge[] } | { error: string } {
18  let parsed: unknown;
19  try {
20    parsed = JSON.parse(linksJson);
21  } catch (err) {
22    return { error: `invalid links JSON: ${err instanceof Error ? err.message : String(err)}` };
23  }
24  if (!Array.isArray(parsed)) {
25    return { error: "links must be a JSON array of { type, to_path, to_ns? } edges (use [] to clear)" };
26  }
27  const edges: LinkEdge[] = [];
28  for (const e of parsed) {
29    if (!e || !isLinkType(e.type)) {
30      return { error: `each link needs a type in ${LINK_TYPES.join(", ")} (got ${JSON.stringify(e)})` };
31    }
32    if (typeof e.to_path !== "string" || !e.to_path.trim()) {
33      return { error: `each link needs a to_path (got ${JSON.stringify(e)})` };
34    }
35    const to_path = e.to_path.trim();
36    const problem = pathProblem(to_path);
37    if (problem) {
38      return { error: `link to_path ${JSON.stringify(to_path)} is not a document path: ${problem}` };
39    }
40    const to_ns = typeof e.to_ns === "string" && e.to_ns.trim() ? e.to_ns.trim() : fromNs;
41    if (!nsName.safeParse(to_ns).success) {
42      return { error: `link to_ns ${JSON.stringify(to_ns)} is not a namespace name` };
43    }
44    edges.push({ type: e.type, to_ns, to_path });
45  }
46  return { edges };
47}