@shivaedev/work-board 0.2.1 → 0.4.0

package/src/history/script.ts

@@ -0,0 +1,112 @@
+export function historyScript(): string {
+	return `
+import { swap, remember } from "/_board/swap.js";
+import { captureReading, restoreReading } from "/_board/reading-state.js";
+const key = "work-board:changes:" + document.documentElement.dataset.workspace;
+let memory;
+let storageNotice = "";
+let unavailableHtml = "";
+let generation = 0;
+let controller;
+const baseline = () => {
+ if (memory !== undefined) return memory;
+ try { return localStorage.getItem(key); }
+ catch { memory = null; storageNotice = "Browser storage unavailable; history applies to this page only."; return memory; }
+};
+const forget = () => {
+ memory = null;
+ try { localStorage.removeItem(key); memory = undefined; }
+ catch { storageNotice = "Cleared for this page, but browser storage could not be cleared. Reload may restore older data."; }
+};
+const keep = (raw) => {
+ memory = raw;
+ try { localStorage.setItem(key, raw); memory = undefined; storageNotice = ""; }
+ catch {
+  storageNotice = "Snapshot remembered for this page only; browser storage is unavailable.";
+  try { localStorage.removeItem(key); }
+  catch { storageNotice += " Reload may restore older data."; }
+ }
+};
+const controls = (available, busy = false) => {
+ const mark = document.getElementById("history-mark");
+ const clear = document.getElementById("history-clear");
+ if (!mark || !clear) return;
+ const exists = baseline() !== null;
+ mark.textContent = exists ? "Mark current workspace seen" : "Start remembering changes";
+ mark.disabled = busy || !available;
+ clear.disabled = busy || !exists;
+ document.getElementById("history-storage").textContent = storageNotice;
+};
+const render = (html) => {
+ const content = document.getElementById("changes-content");
+ if (!content) return;
+ const reading = captureReading();
+ const next = content.cloneNode(false);
+ next.innerHTML = html;
+ swap(content, next);
+ remember(content);
+ restoreReading({ ...reading, selection: null }, false);
+};
+const query = async (action) => {
+ const mine = ++generation;
+ controller?.abort();
+ controller = new AbortController();
+ const raw = baseline();
+ const response = await fetch("/_board/history", {
+  method: "POST", headers: { "content-type": "application/json" },
+  body: JSON.stringify({ action, baseline: raw }), signal: controller.signal, cache: "no-store",
+ });
+ if (!response.ok) throw new Error("History query failed");
+ const result = await response.json();
+ if (mine !== generation) return null;
+ if (result.discardBaseline && baseline() === raw) { forget(); unavailableHtml = result.html; }
+ return result;
+};
+const refresh = async () => {
+ const visible = document.getElementById("doc")?.dataset.view === "changes";
+ try {
+  const result = await query(visible ? "compare" : "check");
+  if (!result) return;
+  if (visible && document.getElementById("doc")?.dataset.view === "changes") {
+   render(baseline() === null && unavailableHtml ? unavailableHtml : result.html);
+   controls(result.snapshot !== null);
+  }
+ } catch (error) {
+  if (error.name === "AbortError") return;
+  if (visible) {
+   render("<p>History is unavailable: the current observation could not be loaded. No comparison or removals are inferred.</p>");
+   controls(false);
+  }
+ }
+};
+document.addEventListener("click", async (event) => {
+ if (event.target.closest?.("#history-clear")) {
+  ++generation;
+  controller?.abort();
+  forget();
+  unavailableHtml = "";
+  await refresh();
+ }
+ if (event.target.closest?.("#history-mark")) {
+  controls(false, true);
+  try {
+   const result = await query("observe");
+   if (!result) return;
+   if (result.snapshot === null) { render(result.html); controls(false); return; }
+   keep(result.snapshot);
+   unavailableHtml = "";
+   await refresh();
+  } catch (error) {
+   if (error.name !== "AbortError") { render("<p>Could not remember the current observation. Your previous baseline is preserved.</p>"); controls(false); }
+  }
+ }
+});
+document.addEventListener("board-page", refresh);
+document.addEventListener("visibilitychange", () => { if (!document.hidden) refresh(); });
+window.addEventListener("storage", (event) => {
+ if (event.key === key || event.key === null) { memory = undefined; storageNotice = ""; unavailableHtml = ""; refresh(); }
+});
+setInterval(() => { if (baseline() !== null) refresh(); }, 60000);
+refresh();
+`;
+}

package/src/http/assets.ts

@@ -1,15 +1,32 @@
 import { createRequire } from "node:module";
 import { Data, Effect, FileSystem, Path } from "effect";
 import type { HttpRouter, HttpServerRequest } from "effect/unstable/http";
-import { client } from "#page/client.ts";
+import { historyScript } from "#history/script.ts";
+import { client, preferences } from "#page/client.ts";
 import { diagrams } from "#page/diagrams.ts";
+import { libraryScript } from "#page/libraryScript.ts";
+import { navigationScript } from "#page/navigationScript.ts";
+import { readingStateScript } from "#page/readingStateScript.ts";
+import { searchResultsScript } from "#page/searchResultsScript.ts";
+import { searchScript } from "#page/searchScript.ts";
+import { pageStateScript } from "#page/stateScript.ts";
 import { style } from "#page/style.ts";
 import { swap } from "#page/swap.ts";
+import { savedScript } from "#views/savedScript.ts";
 import { respond } from "./respond.ts";
 
 export const ASSETS: ReadonlyArray<readonly [HttpRouter.PathInput, string, string]> = [
 	["/_board/style.css", style, "text/css"],
+	["/_board/saved-views.js", savedScript(), "text/javascript"],
 	["/_board/client.js", client, "text/javascript"],
+	["/_board/history.js", historyScript(), "text/javascript"],
+	["/_board/preferences.js", preferences, "text/javascript"],
+	["/_board/search.js", searchScript(), "text/javascript"],
+	["/_board/search-results.js", searchResultsScript(), "text/javascript"],
+	["/_board/library.js", libraryScript(), "text/javascript"],
+	["/_board/navigation.js", navigationScript(), "text/javascript"],
+	["/_board/page-state.js", pageStateScript(), "text/javascript"],
+	["/_board/reading-state.js", readingStateScript(), "text/javascript"],
 	["/_board/diagrams.js", diagrams, "text/javascript"],
 	["/_board/swap.js", swap, "text/javascript"],
 ];

package/src/http/history.ts

@@ -0,0 +1,50 @@
+import { Clock, Effect, FileSystem, Schema } from "effect";
+import { HttpIncomingMessage, HttpServerRequest } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { changesHtml } from "#history/html.ts";
+import { MAX_BYTES } from "#history/limits.ts";
+import { historyResponse } from "#history/response.ts";
+import { HistoryInput, HistoryOutput } from "#history/schema.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function changesPage(changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.changesPage")(function* () {
+		const nav = navHtml(yield* changes.files, "", home);
+		return respond(shell("Changes", nav, changesHtml(), changes.realRoot, true, undefined, "changes"), "text/html");
+	});
+}
+function sameOrigin(request: HttpServerRequest.HttpServerRequest): boolean {
+	const origin = request.headers.origin;
+	if (origin === undefined) {
+		return true;
+	}
+	try {
+		const url = new URL(origin);
+		return url.protocol === "http:" && url.host === request.headers.host;
+	} catch {
+		return false;
+	}
+}
+export function history(index: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	return Effect.fn("WorkBoard.history")(function* (request: HttpServerRequest.HttpServerRequest) {
+		if (!sameOrigin(request)) {
+			return respond("Local same-origin requests only", "text/plain", 403);
+		}
+		const decoded = yield* HttpServerRequest.schemaBodyJson(HistoryInput, { onExcessProperty: "error" }).pipe(
+			Effect.provideService(HttpServerRequest.HttpServerRequest, request),
+			Effect.provideService(HttpIncomingMessage.MaxBodySize, FileSystem.Size(4 * MAX_BYTES + 4096)),
+			Effect.result,
+		);
+		if (decoded._tag === "Failure") {
+			return respond("Invalid history query", "text/plain", 400);
+		}
+		const input = decoded.success;
+		const now = yield* Clock.currentTimeMillis;
+		const snapshot = input.action === "check" ? undefined : yield* index;
+		const output = historyResponse(input.baseline, now, snapshot);
+		return respond(Schema.encodeSync(Schema.fromJsonString(HistoryOutput))(output), "application/json");
+	});
+}

package/src/http/identity.ts

@@ -0,0 +1,62 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { fileUrl } from "#files/url.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import type { page } from "./page.ts";
+import { respond } from "./respond.ts";
+
+function requestedIdentity(pathname: string): string {
+	try {
+		return decodeURIComponent(pathname.slice("/_board/item/".length).replace(/\/$/u, ""));
+	} catch {
+		return "";
+	}
+}
+
+export function identity(
+	index: Effect.Success<ReturnType<typeof searchSnapshot>>,
+	pages: ReturnType<typeof page>,
+	changes: Changes,
+	home: string | undefined,
+) {
+	return Effect.fn("WorkBoard.identity")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const pathname = new URL(request.url, "http://127.0.0.1").pathname;
+		const id = requestedIdentity(pathname);
+		if (!pathname.endsWith("/") && /\.md$/iu.exec(id) !== null) {
+			return yield* pages(request);
+		}
+		const snapshot = yield* index;
+		const matches = snapshot.model.ids.get(id) ?? [];
+		if (snapshot.unavailable.length > 0) {
+			return respond(
+				shell(
+					`Item ${id}`,
+					"",
+					`<p class="empty">The workspace index is incomplete. Could not read ${escapeHtml(snapshot.unavailable.join(", "))}; item identity could not be validated. Retry when the files are readable.</p>`,
+					changes.realRoot,
+					false,
+				),
+				"text/html",
+				503,
+			);
+		}
+		if (matches.length === 1 && matches[0]) {
+			return yield* pages(request, matches[0].file, id);
+		}
+		const text =
+			matches.length > 0
+				? `The ID ${id} is duplicated. No document was selected.`
+				: `No item with ID ${id} is available. It may be missing, renamed, or invalid.`;
+		const choices = matches.map((document) => `<li><a href="${escapeHtml(fileUrl(document.file))}">${escapeHtml(document.file)}</a></li>`).join("");
+		const nav = navHtml(yield* changes.files, "", home);
+		return respond(
+			shell(`Item ${id}`, nav, `<p class="empty">${escapeHtml(text)}</p>${choices ? `<ul>${choices}</ul>` : ""}`, changes.realRoot, false),
+			"text/html",
+			matches.length > 0 ? 409 : 404,
+		);
+	});
+}

package/src/http/overview.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import { overviewHtml } from "#attention/overviewHtml.ts";
+import type { Changes } from "#files/changes.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function overview(index: Effect.Success<ReturnType<typeof searchSnapshot>>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.overview")(function* () {
+		const snapshot = yield* index;
+		const nav = navHtml(yield* changes.files, "", home);
+		return respond(
+			shell("Overview", nav, overviewHtml(snapshot), changes.realRoot, true, undefined, "overview"),
+			"text/html",
+			snapshot.unavailable.length > 0 ? 503 : 200,
+		);
+	});
+}

package/src/http/page.ts

@@ -1,13 +1,18 @@
-import { Effect, FileSystem, Option, Path } from "effect";
+import { Effect, FileSystem, Option } from "effect";
 import type { HttpServerRequest } from "effect/unstable/http";
 import type { Changes } from "#files/changes.ts";
-import { type MarkdownFile, within } from "#files/list.ts";
+import type { MarkdownFile } from "#files/list.ts";
+import { markdownPath } from "#files/markdownPath.ts";
+import { metadataModel } from "#metadata/model.ts";
+import { metadataParse } from "#metadata/parse.ts";
 import { boardHtml } from "#page/board.ts";
 import { documentHtml } from "#page/document.ts";
 import { escapeHtml } from "#page/escape.ts";
+import { metadataHtml } from "#page/metadata.ts";
 import { navHtml } from "#page/nav.ts";
 import { shell } from "#page/shell.ts";
 import { boardOf } from "#render/board.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
 import { respond } from "./respond.ts";
 
 export interface PageOptions {
@@ -26,29 +31,61 @@ const requestedPath = (url: string): string => {
 
 const message = (text: string): string => `<p class="empty">${escapeHtml(text)}</p>`;
 
-export const page = (options: PageOptions, changes: Changes) => {
-	const body = Effect.fn("WorkBoard.pageBody")(function* (file: MarkdownFile) {
+export const page = (options: PageOptions, changes: Changes, index: Effect.Success<ReturnType<typeof searchSnapshot>>) => {
+	const body = Effect.fn("WorkBoard.pageBody")(function* (file: MarkdownFile, expectedIdentity?: string) {
 		const fs = yield* FileSystem.FileSystem;
-		const path = yield* Path.Path;
-		const real = yield* Effect.option(fs.realPath(path.join(options.root, file.path)));
-		if (Option.isNone(real) || !within(changes.realRoot, path.sep, real.value)) {
+		const real = yield* markdownPath(options.root, changes.realRoot, file.path);
+		if (real === undefined) {
 			return Option.none();
 		}
-		const source = yield* fs.readFileString(real.value);
-		return Option.some(file.path === options.home ? yield* boardHtml(boardOf(source), file.path, file.modified) : yield* documentHtml(source, file));
+		const source = yield* fs.readFileString(real);
+		const parsed = metadataParse(source);
+		let identity: string | undefined;
+		const snapshot = yield* index;
+		const model = metadataModel(
+			[...snapshot.documents.filter((document) => document.file !== file.path), { file: file.path, parsed }],
+			snapshot.unavailable,
+			options.home ?? (yield* changes.files)[0]?.path,
+		);
+		const metadata = metadataHtml(parsed, file.path, model);
+		if (snapshot.unavailable.length === 0 && parsed.fields.id && model.ids.get(parsed.fields.id)?.length === 1) {
+			identity = parsed.fields.id;
+		}
+		if (expectedIdentity && identity !== expectedIdentity) {
+			return Option.none();
+		}
+		const html =
+			file.path === options.home
+				? yield* boardHtml(boardOf(parsed.body), file.path, file.modified, metadata)
+				: yield* documentHtml(parsed.body, file, metadata);
+		return Option.some({ html, identity });
 	});
-	return Effect.fn("WorkBoard.page")(function* (request: HttpServerRequest.HttpServerRequest) {
+	return Effect.fn("WorkBoard.page")(function* (request: HttpServerRequest.HttpServerRequest, resolved?: string, expectedIdentity?: string) {
 		const files = yield* changes.files;
-		const requested = requestedPath(request.url) || options.home || files[0]?.path || "";
+		const requested = resolved ?? (requestedPath(request.url) || options.home || files[0]?.path || "");
 		const file = files.find((candidate) => candidate.path === requested);
 		const nav = navHtml(files, requested, options.home);
-		const missing = () => respond(shell(requested, nav, message(`No markdown file at ${requested || options.root}.`)), "text/html", 404);
+		function layout(content: string, identity?: string) {
+			return shell(requested, nav, content, changes.realRoot, requested === options.home, identity);
+		}
+		const missing = () =>
+			respond(
+				layout(
+					message(
+						expectedIdentity
+							? `No item with ID ${expectedIdentity} at ${requested}; its source identity changed or is invalid.`
+							: `No markdown file at ${requested || options.root}.`,
+					),
+				),
+				"text/html",
+				404,
+			);
 		if (file === undefined) {
 			return missing();
 		}
-		return yield* body(file).pipe(
-			Effect.map(Option.match({ onNone: missing, onSome: (main) => respond(shell(file.path, nav, main), "text/html") })),
-			Effect.catch(() => Effect.succeed(respond(shell(file.path, nav, message(`${file.path} could not be read.`)), "text/html", 500))),
+		return yield* body(file, expectedIdentity).pipe(
+			Effect.map(Option.match({ onNone: missing, onSome: (main) => respond(layout(main.html, main.identity), "text/html") })),
+			Effect.catch(() => Effect.succeed(respond(layout(message(`${file.path} could not be read.`)), "text/html", 500))),
 		);
 	});
 };

package/src/http/search.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { searchMatch } from "#search/match.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function search(index: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	return Effect.fn("WorkBoard.search")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const query = new URL(request.url, "http://127.0.0.1").searchParams.get("q") ?? "";
+		const snapshot = yield* index;
+		return respond(JSON.stringify({ ...searchMatch(snapshot.entries, query), unavailable: snapshot.unavailable }), "application/json");
+	});
+}

package/src/http/work.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { searchSnapshot } from "#search/snapshot.ts";
+import { stateOf } from "#views/state.ts";
+import { workHtml } from "#views/workHtml.ts";
+import { respond } from "./respond.ts";
+
+export function work(index: Effect.Success<ReturnType<typeof searchSnapshot>>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.work")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const snapshot = yield* index;
+		const nav = navHtml(yield* changes.files, "", home);
+		if (snapshot.unavailable.length > 0) {
+			return respond(
+				shell(
+					"Work",
+					nav,
+					`<h1>Workspace incomplete</h1><p class="empty">Could not read ${escapeHtml(snapshot.unavailable.join(", "))}. Work identity and view counts cannot be validated. Read available source files or retry when the workspace is readable.</p>`,
+					changes.realRoot,
+					true,
+					undefined,
+					true,
+				),
+				"text/html",
+				503,
+			);
+		}
+		const result = yield* workHtml(snapshot, stateOf(request.url)).pipe(
+			Effect.catch(() =>
+				Effect.succeed({
+					html: '<h1>Work unavailable</h1><p class="empty">The selected source could not be rendered. Read its Markdown file or retry.</p>',
+					status: 500,
+				}),
+			),
+		);
+		return respond(shell("Work", nav, result.html, changes.realRoot, true, undefined, true), "text/html", result.status);
+	});
+}

package/src/metadata/attentionProblems.ts

@@ -0,0 +1,18 @@
+import type { MetadataDocument } from "./model.ts";
+import type { Diagnostic } from "./parse.ts";
+
+export function attentionProblems(document: MetadataDocument): readonly Diagnostic[] {
+	const { fields, lines } = document.parsed;
+	const requests = fields.attention ?? [];
+	return requests.flatMap((request, index) => {
+		const line = lines[`attention.${index}.id`] ?? lines.attention ?? 2;
+		const problems: Diagnostic[] = [];
+		if (!fields.id) {
+			problems.push({ field: "attention", line, message: "Attention requests require an explicit item ID; this source remains unclassified." });
+		}
+		if (requests.filter((other) => other.id === request.id).length > 1) {
+			problems.push({ field: "attention", line, message: `Duplicate attention request ID ${request.id}; neither request is selected.` });
+		}
+		return problems;
+	});
+}

package/src/metadata/backlinks.ts

@@ -0,0 +1,46 @@
+import type { MetadataDocument, MetadataModel } from "./model.ts";
+import { referenceFile, sourceFile } from "./sourceLinks.ts";
+
+export interface Backlink {
+	readonly file: string;
+	readonly kind: string;
+	readonly line?: number;
+}
+
+function references(document: MetadataDocument, model: MetadataModel) {
+	const { fields, lines } = document.parsed;
+	return [
+		...(fields.attention?.flatMap((request, index) =>
+			request.unblocks.map((target, targetIndex) => ({
+				kind: "attention target",
+				line: lines[`attention.${index}.unblocks.${targetIndex}`],
+				target: referenceFile(target, model),
+			})),
+		) ?? []),
+		...(fields.relationships?.map((link, index) => ({
+			kind: link.kind,
+			line: lines[`relationships.${index}.target`],
+			target: referenceFile(link.target, model),
+		})) ?? []),
+		...(fields.items?.map((item, index) => ({ kind: "board member", line: lines[`items.${index}`], target: referenceFile(item, model) })) ?? []),
+		...(fields.evidence?.flatMap((evidence, index) => [
+			{ kind: "evidence source", line: lines[`evidence.${index}.source`], target: sourceFile(evidence.source, document.file, model) },
+			{
+				kind: "criterion evidence",
+				line: lines[`evidence.${index}.criterion`],
+				target: evidence.criterion ? referenceFile(evidence.criterion, model) : undefined,
+			},
+		]) ?? []),
+		...(document.links?.map((link) => ({ kind: "Markdown link", line: undefined, target: sourceFile(link, document.file, model) })) ?? []),
+	];
+}
+
+export function backlinksOf(file: string, model: MetadataModel): readonly Backlink[] {
+	return model.documents.flatMap((document) =>
+		document.file === file
+			? []
+			: references(document, model)
+					.filter((reference) => reference.target === file)
+					.map((reference) => ({ file: document.file, kind: reference.kind, ...(reference.line === undefined ? {} : { line: reference.line }) })),
+	);
+}

package/src/metadata/fields.ts

@@ -0,0 +1,26 @@
+import { Option, Schema } from "effect";
+import type { Diagnostic } from "./parse.ts";
+import { Metadata } from "./schema.ts";
+
+const schemas: ReadonlyMap<string, Schema.ConstraintDecoder<unknown, never>> = new Map(Object.entries(Metadata.to.fields));
+const sourceKeys = new Map([["next_action", "nextAction"]]);
+
+export function metadataFields(data: object, lines: Readonly<Record<string, number>>) {
+	const fields: Record<string, unknown> = {};
+	const diagnostics: Diagnostic[] = [];
+	for (const [field, value] of Object.entries(data)) {
+		const key = sourceKeys.get(field) ?? field;
+		const schema = field === "nextAction" ? undefined : schemas.get(key);
+		if (!schema) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Unknown field ${field}; kept in the original frontmatter.` });
+			continue;
+		}
+		const decoded = Schema.decodeUnknownOption(schema, { onExcessProperty: "error" })(value);
+		if (Option.isNone(decoded)) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Invalid ${field}; kept in the original frontmatter and not interpreted.` });
+		} else {
+			fields[key] = decoded.value;
+		}
+	}
+	return { diagnostics, fields: Schema.decodeUnknownSync(Schema.toType(Metadata))(fields) };
+}

package/src/metadata/links.ts

@@ -0,0 +1,19 @@
+import type { MetadataModel } from "./model.ts";
+
+export function identityUrl(id: string): string {
+	return `/_board/item/${encodeURIComponent(id)}/`;
+}
+export function referenceTarget(reference: string, model: MetadataModel): string | undefined {
+	if (model.unavailable.length > 0) {
+		return undefined;
+	}
+	const [id = "", criterion] = reference.split("#");
+	const targets = model.ids.get(id);
+	if (targets?.length !== 1) {
+		return undefined;
+	}
+	if (criterion && targets[0]?.parsed.fields.criteria?.filter((item) => item.id === criterion).length !== 1) {
+		return undefined;
+	}
+	return identityUrl(id) + (criterion ? `#criterion-${encodeURIComponent(criterion)}` : "");
+}

package/src/metadata/locations.ts

@@ -0,0 +1,34 @@
+import { isMap, isNode, isScalar, isSeq, type LineCounter, type Node, type YAMLMap } from "yaml";
+
+function recordMap(node: YAMLMap, field: string, counter: LineCounter, lines: Record<string, number>) {
+	for (const pair of node.items) {
+		if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
+			continue;
+		}
+		const key = field ? `${field}.${pair.key.value}` : pair.key.value;
+		visit(pair.value, key, counter, lines);
+		if (pair.key.range) {
+			lines[key] = counter.linePos(pair.key.range[0]).line + 1;
+		}
+	}
+}
+function visit(value: unknown, field: string, counter: LineCounter, lines: Record<string, number>) {
+	if (!isNode(value)) {
+		return;
+	}
+	if (value.range && field) {
+		lines[field] = counter.linePos(value.range[0]).line + 1;
+	}
+	if (isMap(value)) {
+		recordMap(value, field, counter, lines);
+	} else if (isSeq(value)) {
+		value.items.forEach((item, index) => {
+			visit(item, `${field}.${index}`, counter, lines);
+		});
+	}
+}
+export function metadataLocations(node: Node | null, counter: LineCounter): Readonly<Record<string, number>> {
+	const lines: Record<string, number> = {};
+	visit(node, "", counter, lines);
+	return lines;
+}

package/src/metadata/model.ts

@@ -0,0 +1,27 @@
+import type { Diagnostic, ParsedMetadata } from "./parse.ts";
+import { metadataProblems } from "./problems.ts";
+
+export interface MetadataDocument {
+	readonly file: string;
+	readonly links?: readonly string[];
+	readonly parsed: ParsedMetadata;
+}
+export interface MetadataModel {
+	readonly diagnostics: ReadonlyMap<string, readonly Diagnostic[]>;
+	readonly documents: readonly MetadataDocument[];
+	readonly ids: ReadonlyMap<string, readonly MetadataDocument[]>;
+	readonly rootFile: string | undefined;
+	readonly unavailable: readonly string[];
+}
+
+export function metadataModel(documents: readonly MetadataDocument[], unavailable: readonly string[] = [], rootFile?: string): MetadataModel {
+	const ids = new Map<string, MetadataDocument[]>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			ids.set(id, [...(ids.get(id) ?? []), document]);
+		}
+	}
+	const diagnostics = new Map(documents.map((document) => [document.file, metadataProblems(document, ids, unavailable)]));
+	return { diagnostics, documents, ids, rootFile, unavailable };
+}