@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/generators/template-source-annotate.ts

@@ -0,0 +1,290 @@
+// Annotated-template IR (linked-template-source-docs, Task 1).
+//
+// annotateTemplate parses a Mustache template into an ordered TplToken[] where
+// every {{variable}} / {{#section}} is resolved to the payload field it
+// references plus that field's doc link. It tokenizes with the SAME parser
+// verify walks (`parseTemplate` from @metaobjectsdev/render) and resolves each
+// path with verify's EXPORTED `resolveTemplateVariable` — so the annotator and
+// the build-time drift gate share ONE resolution and can never disagree (a
+// later conformance gate asserts exactly that).
+//
+// Reuse, not reimplementation:
+//   • parseTemplate          — the render verify engine's Mustache.parse.
+//   • resolveTemplateVariable — verify's context-stack walk (sections push the
+//                               nested subtree; dotted paths descend). Generic
+//                               over the node, so an ENRICHED tree (carrying
+//                               owner/type/required) resolves identically.
+//
+// The annotator is a pure function over an enriched payload tree + the source —
+// no metadata import, no I/O — so it is unit-testable and golden-pinnable.
+
+import {
+	parseTemplate,
+	resolveTemplateVariable,
+	type PayloadField,
+	type ResolveStack,
+} from "@metaobjectsdev/render";
+import { fieldAnchorSlug } from "./field-anchor.js";
+
+/**
+ * An enriched payload-field node. Structurally a verify `PayloadField` (so the
+ * shared resolver walks it), plus the per-field doc metadata the annotator needs
+ * to emit a `ResolvedField` + link: `owner` (the VO that declares the field),
+ * `type`, and `required`. Container fields (object / array-of-object) carry
+ * `fields` whose nodes are owned by the nested VO.
+ */
+export interface AnnotatePayloadField extends PayloadField {
+	owner: string;
+	type: string;
+	required: boolean;
+	fields?: AnnotatePayloadField[];
+}
+
+/** The field a `{{variable}}` / `{{#section}}` resolves to. */
+export interface ResolvedField {
+	owner: string;
+	name: string;
+	type: string;
+	required: boolean;
+}
+
+/** One ordered token of the annotated template. `raw` is the verbatim source
+ *  span of the tag (text tokens carry `text`), so the source round-trips. */
+export type TplToken =
+	| { kind: "text"; text: string }
+	| {
+			kind: "var" | "unescaped";
+			raw: string;
+			path: string;
+			field?: ResolvedField;
+			href?: string;
+			valid: boolean;
+	  }
+	| {
+			kind: "section" | "inverted" | "close";
+			raw: string;
+			path: string;
+			field?: ResolvedField;
+			href?: string;
+	  }
+	| { kind: "partial"; raw: string; ref: string; href?: string }
+	| { kind: "comment"; raw: string };
+
+export interface AnnotateOptions {
+	/** The root payload VO's short name (owner of the root-context fields). Used
+	 *  only for diagnostics / callers; per-field owner comes off the tree node. */
+	ownerVoName: string;
+	/**
+	 * Resolve a partial `{{>ref}}` to a doc-page href, if the ref names a
+	 * documented template. Returns the href or undefined (highlight-only).
+	 * Optional — when absent, partials are captured ref-only (no href).
+	 */
+	resolvePartialHref?: (ref: string) => string | undefined;
+	/**
+	 * Override how a resolved field's doc-page href is built (owner page + the
+	 * shared `#field-<name>` fragment). Optional — when absent, the flat default
+	 * `./<owner>.md#field-<name>` is used (byte-identical to today). A caller with
+	 * the output layout + page placement in scope injects a layout-aware resolver
+	 * (the SAME `docPageHref(layout, …)` the Payload cross-link uses) so the link
+	 * resolves under package layout too.
+	 */
+	fieldHref?: (owner: string, name: string) => string;
+}
+
+// A Mustache parse token: [type, value, start, end, subTokens?, closeStart?, ...].
+type Token = readonly unknown[];
+
+/** The doc-page href for a resolved field: `./<OwnerVO>.md#field-<name>`. The
+ *  anchor slug comes from the SHARED `fieldAnchorSlug()` (prefixed — avoids
+ *  colliding with other page anchors), the SAME helper the entity page uses to
+ *  emit its per-field `<a id="field-<name>">` anchor, so the link and the anchor
+ *  can never drift. */
+function fieldHref(owner: string, name: string): string {
+	return `./${owner}.md#${fieldAnchorSlug(name)}`;
+}
+
+function toResolvedField(f: AnnotatePayloadField): ResolvedField {
+	return { owner: f.owner, name: f.name, type: f.type, required: f.required };
+}
+
+/**
+ * Parse `source` into an annotated IR, resolving each variable/section against
+ * the enriched `payload` tree using verify's shared resolution.
+ */
+export function annotateTemplate(
+	source: string,
+	payload: AnnotatePayloadField[],
+	opts: AnnotateOptions,
+): TplToken[] {
+	const root = payload;
+	const out: TplToken[] = [];
+	let cursor = 0;
+
+	// How a resolved field's href is built: the injected layout-aware resolver
+	// when provided, else the flat default (byte-identical to today's output).
+	const buildFieldHref = opts.fieldHref ?? fieldHref;
+
+	// Emit verbatim source between `cursor` and `to` as a text token, advancing
+	// the cursor. This recovers literal text AND any span Mustache trimmed as
+	// standalone (e.g. the newline after a standalone partial/section), so the
+	// concatenated tokens reproduce the source byte-for-byte.
+	function emitTextUpTo(to: number): void {
+		if (to > cursor) {
+			out.push({ kind: "text", text: source.slice(cursor, to) });
+			cursor = to;
+		}
+	}
+
+	function resolveAt(
+		stack: ResolveStack<AnnotatePayloadField>,
+		path: string,
+	): { field: ResolvedField; href: string } | undefined {
+		const hit = resolveTemplateVariable(stack, path);
+		if (!hit) return undefined;
+		const field = toResolvedField(hit);
+		return { field, href: buildFieldHref(field.owner, field.name) };
+	}
+
+	// Build a variable token ({{x}} or {{&x}}/{{{x}}}). The implicit iterator
+	// `.` is always valid against the current context; any other path resolves
+	// against the enriched tree (carrying field + href when found).
+	function makeVarToken(
+		kind: "var" | "unescaped",
+		raw: string,
+		value: string,
+		stack: ResolveStack<AnnotatePayloadField>,
+	): TplToken {
+		if (value === ".") return { kind, raw, path: value, valid: true };
+		const r = resolveAt(stack, value);
+		return r
+			? { kind, raw, path: value, field: r.field, href: r.href, valid: true }
+			: { kind, raw, path: value, valid: false };
+	}
+
+	function walk(
+		tokens: Token[],
+		stack: ResolveStack<AnnotatePayloadField>,
+	): void {
+		for (const tok of tokens) {
+			const type = tok[0] as string;
+			const value = tok[1] as string;
+			const start = tok[2] as number;
+			const end = tok[3] as number;
+
+			// Recover any source between the previous token and this tag (literal
+			// text, or trimmed standalone whitespace).
+			emitTextUpTo(start);
+
+			switch (type) {
+				case "text": {
+					out.push({ kind: "text", text: source.slice(start, end) });
+					cursor = end;
+					break;
+				}
+				case "name": {
+					// {{x}} — escaped variable.
+					const raw = source.slice(start, end);
+					cursor = end;
+					out.push(makeVarToken("var", raw, value, stack));
+					break;
+				}
+				case "&":
+				case "{": {
+					// {{&x}} / {{{x}}} — unescaped variable (mustache.js emits "&" for both).
+					const raw = source.slice(start, end);
+					cursor = end;
+					out.push(makeVarToken("unescaped", raw, value, stack));
+					break;
+				}
+				case "#":
+				case "^": {
+					// {{#x}}…{{/x}} (section) / {{^x}}…{{/x}} (inverted). `end` is the end
+					// of the OPENING tag; subTokens at [4]; [5] is where the closing tag
+					// begins. Emit the open tag, recurse the body in the pushed context,
+					// then emit the close tag.
+					const sub = Array.isArray(tok[4]) ? (tok[4] as Token[]) : [];
+					const closeStart = tok[5] as number;
+					const openRaw = source.slice(start, end);
+					cursor = end;
+
+					const isImplicit = value === ".";
+					const r = isImplicit ? undefined : resolveAt(stack, value);
+					const kind = type === "#" ? "section" : "inverted";
+					out.push(
+						r
+							? {
+									kind,
+									raw: openRaw,
+									path: value,
+									field: r.field,
+									href: r.href,
+								}
+							: { kind, raw: openRaw, path: value },
+					);
+
+					// `#` over a container pushes its element fields; `^` (and `#` over a
+					// scalar conditional) keep the current context — EXACTLY verify's rule.
+					const hit = isImplicit
+						? undefined
+						: resolveTemplateVariable(stack, value);
+					const nested = type === "#" ? hit?.fields : undefined;
+					const childStack: ResolveStack<AnnotatePayloadField> =
+						nested !== undefined ? [...stack, nested] : stack;
+					walk(sub, childStack);
+
+					// The closing tag `{{/value}}` runs from closeStart to the end of the
+					// section. Recover any body remainder Mustache trimmed, then emit close.
+					emitTextUpTo(closeStart);
+					// The close tag's exact end isn't in the token; derive it from the
+					// literal `{{/…}}` form starting at closeStart so the raw is verbatim.
+					const closeRaw = readCloseTag(source, closeStart, value);
+					out.push({ kind: "close", raw: closeRaw, path: value });
+					cursor = closeStart + closeRaw.length;
+					break;
+				}
+				case ">": {
+					// {{>ref}} — partial.
+					const raw = source.slice(start, end);
+					cursor = end;
+					const href = opts.resolvePartialHref?.(value);
+					out.push(
+						href !== undefined
+							? { kind: "partial", raw, ref: value, href }
+							: { kind: "partial", raw, ref: value },
+					);
+					break;
+				}
+				case "!": {
+					// {{! comment }}.
+					out.push({ kind: "comment", raw: source.slice(start, end) });
+					cursor = end;
+					break;
+				}
+				default: {
+					// set-delimiter (=) or any other: preserve verbatim as text.
+					if (Number.isFinite(end) && end > start) {
+						out.push({ kind: "text", text: source.slice(start, end) });
+						cursor = end;
+					}
+					break;
+				}
+			}
+		}
+	}
+
+	walk(parseTemplate(source) as Token[], [root]);
+	// Any trailing source after the last token (e.g. a standalone-trimmed final
+	// newline) is recovered as text.
+	emitTextUpTo(source.length);
+
+	return out;
+}
+
+// Read the verbatim closing tag `{{/name}}` (with any inner whitespace the
+// author wrote) starting at `from`. Mustache only gives the close-tag start, so
+// we locate the terminating `}}` from there to recover the exact source span.
+function readCloseTag(source: string, from: number, _name: string): string {
+	const close = source.indexOf("}}", from);
+	if (close === -1) return source.slice(from);
+	return source.slice(from, close + 2);
+}

package/src/generators/template-source-render.ts

@@ -0,0 +1,203 @@
+// Template-source renderers (linked-template-source-docs, Task 3).
+//
+// ONE annotated IR (the TplToken[] from annotateTemplate), THREE doc forms — no
+// re-derivation, no second parse. All three are pure functions over the tokens:
+//
+//   • renderSourceBlock     — the verbatim template inside a ```mustache fence.
+//                             The annotator round-trips the source via text/raw,
+//                             so the fenced body equals the original byte-for-byte
+//                             and any viewer/site highlighter colors it.
+//   • renderVariablesTable  — a Markdown table of the UNIQUE referenced variables
+//                             (vars + sections that resolve to a field), each a
+//                             Markdown-native `[owner.name](href)` link (or flagged
+//                             "not on payload" when unresolved). Agent-clean.
+//   • renderRichLinkedHtml  — a collapsed <details> whose <pre> reproduces the
+//                             template with each token in a SELF-CONTAINED
+//                             inline-styled <span> (color per kind) and each
+//                             resolved variable/section wrapped in a clickable
+//                             <a href>. Inline styles only (no external CSS) so it
+//                             renders identically on GitHub and a static site.
+//
+// Color (block + rich view), links (table + rich view), agent-cleanliness (block
+// + table) — all from the same source of truth.
+
+import type { TplToken } from "./template-source-annotate.js";
+
+// ── 1. Source block ────────────────────────────────────────────────────────
+
+/**
+ * Reconstruct the verbatim template source from the tokens and wrap it in a
+ * ```mustache fenced block. Concatenating `text` (text tokens) / `raw` (tag
+ * tokens) round-trips the original source byte-for-byte (the annotator pins
+ * this), so the fence body is the clean, highlightable source.
+ */
+export function renderSourceBlock(tokens: TplToken[]): string {
+	const source = reconstructSource(tokens);
+	return "```mustache\n" + source + "\n```";
+}
+
+/** Concatenate the verbatim span of every token (text or tag raw). */
+function reconstructSource(tokens: TplToken[]): string {
+	let out = "";
+	for (const t of tokens) out += t.kind === "text" ? t.text : t.raw;
+	return out;
+}
+
+// ── 2. Variables table ─────────────────────────────────────────────────────
+
+interface VarRow {
+	path: string;
+	owner: string | undefined;
+	name: string | undefined;
+	type: string | undefined;
+	required: boolean | undefined;
+	href: string | undefined;
+}
+
+/** Collect the unique referenced variables (vars/unescaped + sections/inverted
+ *  that carry a path), deduped by path, in first-seen order. Implicit-iterator
+ *  `.` tokens and close tokens are not "variables" and are skipped. */
+function collectVarRows(tokens: TplToken[]): VarRow[] {
+	const seen = new Set<string>();
+	const rows: VarRow[] = [];
+	for (const t of tokens) {
+		const isRef =
+			t.kind === "var" ||
+			t.kind === "unescaped" ||
+			t.kind === "section" ||
+			t.kind === "inverted";
+		if (!isRef) continue;
+		if (t.path === "." || seen.has(t.path)) continue;
+		seen.add(t.path);
+		rows.push({
+			path: t.path,
+			owner: t.field?.owner,
+			name: t.field?.name,
+			type: t.field?.type,
+			required: t.field?.required,
+			href: t.href,
+		});
+	}
+	return rows;
+}
+
+/** Markdown-escape a table cell whose text may contain a `|`. */
+function mdCell(text: string): string {
+	return text.replace(/\|/g, "\\|");
+}
+
+/**
+ * A Markdown table of the unique referenced variables. Resolved variables link
+ * to their field doc (`[owner.name](href)`); unresolved ones are em-dashed and
+ * carry a "not on payload" note in the Type cell. Returns "" when there are no
+ * variables (keeps the page clean).
+ */
+export function renderVariablesTable(tokens: TplToken[]): string {
+	const rows = collectVarRows(tokens);
+	if (rows.length === 0) return "";
+
+	const lines: string[] = [
+		"| Variable | Field | Type | Required |",
+		"| --- | --- | --- | --- |",
+	];
+	for (const r of rows) {
+		const variable = `\`{{${mdCell(r.path)}}}\``;
+		if (r.href && r.owner && r.name) {
+			const field = `[${r.owner}.${r.name}](${r.href})`;
+			const type = r.type ? mdCell(r.type) : "—";
+			const required = r.required ? "yes" : "no";
+			lines.push(`| ${variable} | ${field} | ${type} | ${required} |`);
+		} else {
+			// Unresolved: no field/type/required. Keep the 4-column shape; flag it
+			// "not on payload" in the Field cell, em-dash the rest.
+			lines.push(`| ${variable} | — (not on payload) | — | — |`);
+		}
+	}
+	return lines.join("\n");
+}
+
+// ── 3. Rich linked HTML ────────────────────────────────────────────────────
+
+// Per-kind inline color (self-contained — no external CSS, no classes). Chosen
+// for legibility on both GitHub's light/dark Markdown and a generic docs site.
+const STYLE_VAR = "color:#0969da"; // blue — escaped/unescaped variable
+const STYLE_SECTION = "color:#8250df"; // purple — section / inverted / close
+const STYLE_PARTIAL = "color:#1a7f7a"; // teal — partial reference
+const STYLE_COMMENT = "color:#6e7781;font-style:italic"; // gray italic — comment
+
+/** HTML-escape literal text so `<`, `>`, `&`, `"` in the template don't break
+ *  the surrounding HTML. Quotes are escaped too so token raw is safe in any
+ *  attribute-adjacent position. */
+function escapeHtml(s: string): string {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+}
+
+/** An inline-styled span for a token kind, escaping the inner verbatim text. */
+function styledSpan(style: string, inner: string): string {
+	return `<span style="${style}">${inner}</span>`;
+}
+
+/** A styled span for a token kind, wrapped in a clickable `<a href>` when the
+ *  token resolved to a link (else the bare span). The raw text is HTML-escaped. */
+function linkSpan(
+	style: string,
+	raw: string,
+	href: string | undefined,
+): string {
+	const span = styledSpan(style, escapeHtml(raw));
+	return href ? `<a href="${escapeHtml(href)}">${span}</a>` : span;
+}
+
+/**
+ * The collapsed <details> "Linked view": a <pre> reproducing the template where
+ * each token is an inline-styled <span> (color by kind) and each resolved
+ * variable/section is additionally wrapped in a clickable <a href>. Whitespace
+ * and newlines are preserved inside the <pre>. Collapsed by default (no `open`)
+ * so the plain/agent view stays clean; a human expands it for the clickable vars.
+ */
+export function renderRichLinkedHtml(tokens: TplToken[]): string {
+	let pre = "";
+	for (const t of tokens) {
+		switch (t.kind) {
+			case "text": {
+				// Default color; escape literal text verbatim (preserves newlines).
+				pre += escapeHtml(t.text);
+				break;
+			}
+			case "var":
+			case "unescaped": {
+				pre += linkSpan(STYLE_VAR, t.raw, t.href);
+				break;
+			}
+			case "section":
+			case "inverted":
+			case "close": {
+				// Only open tags (section/inverted) carry an href; close tags don't.
+				const href = "href" in t ? t.href : undefined;
+				pre += linkSpan(STYLE_SECTION, t.raw, href);
+				break;
+			}
+			case "partial": {
+				pre += linkSpan(STYLE_PARTIAL, t.raw, t.href);
+				break;
+			}
+			case "comment": {
+				pre += styledSpan(STYLE_COMMENT, escapeHtml(t.raw));
+				break;
+			}
+		}
+	}
+
+	return (
+		"<details>\n" +
+		"<summary>Linked view</summary>\n\n" +
+		'<pre style="white-space:pre-wrap;word-break:break-word">' +
+		pre +
+		"</pre>\n\n" +
+		"</details>"
+	);
+}