@c4a/context-cli 0.5.38 → 0.5.39-beta.2

package/templates/aspect-runtime/aspectRunnerSdk.ts

@@ -1,749 +0,0 @@
-import { readFile, readdir, realpath, stat } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import * as ts from "typescript";
-
-/**
- * Aspect plugin runtime SDK.
- *
- * Product-specific aspects export a lifecycle object through defineAspect().
- * The CLI owns workspace I/O, source_ref encoding, JSONL output, hash
- * calculation, raw bucket publishing, and knowledge writes. Aspect code only
- * reads source files through ctx.source and emits deterministic node/Section
- * rows through ctx.emit.
- */
-
-export interface RunnerRuntimeContext {
-  protocol?: string;
-  helper_module?: string;
-  plugin_module?: string;
-}
-
-export interface CodeIndexPackage {
-  package_name?: string;
-  package_slug: string;
-  node_slug?: string;
-  source_id?: string;
-}
-
-export interface CodeIndexSymbol {
-  export_name?: string;
-  symbol_name?: string;
-  aliases?: string[];
-  package_name?: string;
-  package_slug?: string;
-  node_slug: string;
-  source_id?: string;
-  kind?: string;
-}
-
-export interface CodeIndexContext {
-  packages?: CodeIndexPackage[];
-  symbols?: CodeIndexSymbol[];
-}
-
-export interface AspectHostInput {
-  workspace_root: string;
-  repo_root: string;
-  aspect: string;
-  source_slug: string;
-  source_id: string;
-  snapshot_id: string;
-  runtime?: RunnerRuntimeContext;
-  code_index?: CodeIndexContext;
-}
-
-export interface SourceFileRef {
-  path: string;
-  name: string;
-  extension: string;
-}
-
-export interface SourceGlobOptions {
-  root?: string;
-  extensions?: readonly string[];
-  recursive?: boolean;
-}
-
-export interface SectionProjectionRow {
-  node_slug: string;
-  kind: "description" | "spec" | "warning" | "principle" | "decision" | "incident" | "example" | "changelog" | "comparison" | "faq";
-  summary?: string;
-  content: string;
-  source?: SourceFileRef | string;
-  source_path?: string;
-  artifact: string;
-}
-
-export interface NodeProjectionRow {
-  node_slug: string;
-  title: string;
-  type?: "domain" | "entity" | "action";
-  tags?: readonly string[];
-  summary?: string;
-  parent_slug?: string;
-  code_package?: string;
-  language?: string;
-}
-
-export interface AspectCaptureContext {
-  aspect: {
-    name: string;
-    source_slug: string;
-    source_id: string;
-    snapshot_id: string;
-  };
-  source: {
-    glob(options?: SourceGlobOptions): Promise<SourceFileRef[]>;
-    immediateFiles(root: string, extensions: readonly string[]): Promise<SourceFileRef[]>;
-    exists(source: SourceFileRef | string): Promise<boolean>;
-    readText(source: SourceFileRef | string): Promise<string>;
-  };
-  code: {
-    packages: CodeIndexPackage[];
-    symbols: CodeIndexSymbol[];
-    findPackage(packageSlug: string): CodeIndexPackage | undefined;
-    findSymbol(packageSlug: string, symbolName: string): CodeIndexSymbol | undefined;
-  };
-  emit: {
-    node(row: NodeProjectionRow): void;
-    section(row: SectionProjectionRow): void;
-    warning(message: string, detail?: Record<string, unknown>): void;
-  };
-}
-
-export interface AspectPlugin {
-  setup?(ctx: AspectCaptureContext): void | Promise<void>;
-  capture(ctx: AspectCaptureContext): void | Promise<void>;
-  teardown?(ctx: AspectCaptureContext): void | Promise<void>;
-}
-
-interface RunnerResult {
-  type: "aspect-plugin-result.v1";
-  nodes: PersistedNodeEmit[];
-  sections: PersistedSectionEmit[];
-  warnings: AspectPluginWarning[];
-}
-
-interface PersistedNodeEmit {
-  node_slug: string;
-  title: string;
-  type: "domain" | "entity" | "action";
-  tags: string[];
-  summary?: string;
-  parent_slug?: string;
-  code_package?: string;
-  language?: string;
-}
-
-interface PersistedSectionEmit {
-  node_slug: string;
-  kind: SectionProjectionRow["kind"];
-  summary?: string;
-  content: string;
-  source_path: string;
-  artifact: string;
-}
-
-interface AspectPluginWarning {
-  message: string;
-  detail?: Record<string, unknown>;
-}
-
-export function defineAspect(plugin: AspectPlugin): AspectPlugin {
-  return plugin;
-}
-
-async function readHostInput(): Promise<AspectHostInput> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  const input = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Partial<AspectHostInput>;
-  for (const key of ["workspace_root", "repo_root", "aspect", "source_slug", "source_id", "snapshot_id"] as const) {
-    if (typeof input[key] !== "string" || input[key]!.length === 0) {
-      throw new Error(`aspect host input missing ${key}`);
-    }
-  }
-  return input as AspectHostInput;
-}
-
-async function pathExists(absPath: string): Promise<boolean> {
-  try {
-    await stat(absPath);
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT" || code === "ENOTDIR") return false;
-    throw err;
-  }
-}
-
-function sourceRefFromInput(source: SourceFileRef | string): string {
-  return typeof source === "string" ? source : source.path;
-}
-
-function normalizeSourceRoot(root: string | undefined): string {
-  if (root === undefined || root === "" || root === ".") return "";
-  const normalized = toPosix(path.posix.normalize(toPosix(root)));
-  validateSourcePath(normalized);
-  return normalized;
-}
-
-function sourceFileRef(sourcePath: string): SourceFileRef {
-  validateSourcePath(sourcePath);
-  return {
-    path: sourcePath,
-    name: path.posix.basename(sourcePath),
-    extension: path.posix.extname(sourcePath).toLowerCase(),
-  };
-}
-
-async function resolveRepoPath(repoRoot: string, sourcePath: string): Promise<string> {
-  validateSourcePath(sourcePath);
-  const realRepoRoot = await realpath(repoRoot);
-  const realSource = await realpath(path.resolve(realRepoRoot, sourcePath));
-  const rel = path.relative(realRepoRoot, realSource);
-  if (rel.startsWith("..") || path.isAbsolute(rel)) {
-    throw new Error(`source_path escapes repo_root: ${sourcePath}`);
-  }
-  return realSource;
-}
-
-async function readRepoText(repoRoot: string, source: SourceFileRef | string): Promise<string> {
-  return readFile(await resolveRepoPath(repoRoot, sourceRefFromInput(source)), "utf8");
-}
-
-async function collectRepoFiles(repoRoot: string, rootRel: string, extensions: readonly string[], recursive: boolean): Promise<SourceFileRef[]> {
-  const normalizedRoot = normalizeSourceRoot(rootRel);
-  const realRepoRoot = await realpath(repoRoot);
-  let root: string;
-  try {
-    root = normalizedRoot.length > 0 ? await resolveRepoPath(realRepoRoot, normalizedRoot) : realRepoRoot;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT" || code === "ENOTDIR") return [];
-    throw err;
-  }
-  if (!(await pathExists(root))) return [];
-  const normalizedExtensions = extensions.map((ext) => ext.toLowerCase());
-  const out: SourceFileRef[] = [];
-  async function walk(dir: string): Promise<void> {
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.name.startsWith(".")) continue;
-      const absPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (recursive) await walk(absPath);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      const ext = path.extname(entry.name).toLowerCase();
-      if (normalizedExtensions.length > 0 && !normalizedExtensions.includes(ext)) continue;
-      out.push(sourceFileRef(repoRelative(realRepoRoot, absPath)));
-    }
-  }
-  await walk(root);
-  return out.sort((a, b) => a.path.localeCompare(b.path));
-}
-
-export function toPosix(value: string): string {
-  return value.split(path.sep).join("/");
-}
-
-export function repoRelative(repoRoot: string, absPath: string): string {
-  const rel = toPosix(path.relative(repoRoot, absPath));
-  validateSourcePath(rel);
-  return rel;
-}
-
-export function validateSourcePath(sourcePath: string): void {
-  if (sourcePath.length === 0 || sourcePath.includes("\0") || sourcePath.includes("\\")) {
-    throw new Error(`invalid source_path: ${sourcePath}`);
-  }
-  if (path.posix.isAbsolute(sourcePath)) {
-    throw new Error(`source_path must be relative: ${sourcePath}`);
-  }
-  const parts = sourcePath.split("/");
-  if (parts.some((part) => part.length === 0 || part === "." || part === "..")) {
-    throw new Error(`source_path must be normalized and stay inside repo_root: ${sourcePath}`);
-  }
-}
-
-export function encodeSourcePath(sourcePath: string): string {
-  validateSourcePath(sourcePath);
-  return sourcePath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
-}
-
-export function encodeFragment(fragment: string): string {
-  return encodeURIComponent(fragment);
-}
-
-export function fileSourceRef(sourcePath: string, artifact: string, hash: string): string {
-  return `file:${encodeSourcePath(sourcePath)}#${encodeFragment(artifact)}@${hash}`;
-}
-
-function normalizeSection(row: SectionProjectionRow): PersistedSectionEmit {
-  const sourcePath = row.source_path ?? (row.source !== undefined ? sourceRefFromInput(row.source) : undefined);
-  if (sourcePath === undefined) {
-    throw new Error("ctx.emit.section requires source or source_path");
-  }
-  validateSourcePath(sourcePath);
-  if (row.artifact.trim().length === 0) {
-    throw new Error("ctx.emit.section requires a non-empty artifact");
-  }
-  return {
-    node_slug: row.node_slug,
-    kind: row.kind,
-    ...(row.summary !== undefined && row.summary.length > 0 ? { summary: row.summary } : {}),
-    content: row.content,
-    source_path: sourcePath,
-    artifact: row.artifact,
-  };
-}
-
-function normalizeNode(row: NodeProjectionRow): PersistedNodeEmit {
-  if (row.node_slug.trim().length === 0) {
-    throw new Error("ctx.emit.node requires a non-empty node_slug");
-  }
-  if (row.title.trim().length === 0) {
-    throw new Error("ctx.emit.node requires a non-empty title");
-  }
-  return {
-    node_slug: row.node_slug,
-    title: row.title,
-    type: row.type ?? "entity",
-    tags: [...(row.tags ?? ["module"])],
-    ...(row.summary !== undefined && row.summary.length > 0 ? { summary: row.summary } : {}),
-    ...(row.parent_slug !== undefined && row.parent_slug.length > 0 ? { parent_slug: row.parent_slug } : {}),
-    ...(row.code_package !== undefined && row.code_package.length > 0 ? { code_package: row.code_package } : {}),
-    ...(row.language !== undefined && row.language.length > 0 ? { language: row.language } : {}),
-  };
-}
-
-function findPackage(packages: readonly CodeIndexPackage[], packageSlug: string): CodeIndexPackage | undefined {
-  return packages.find((pkg) => pkg.package_slug === packageSlug);
-}
-
-function findSymbol(symbols: readonly CodeIndexSymbol[], packageSlug: string, symbolName: string): CodeIndexSymbol | undefined {
-  const target = normalizeComponentSlug(symbolName);
-  return symbols.find((symbol) => {
-    if (symbol.package_slug !== undefined && symbol.package_slug !== packageSlug) return false;
-    const nodeLeaf = symbol.node_slug.split("/").at(-1);
-    const names = [symbol.export_name, symbol.symbol_name, ...(symbol.aliases ?? []), nodeLeaf]
-      .filter((name): name is string => typeof name === "string" && name.length > 0);
-    return names.some((name) => normalizeComponentSlug(name) === target || name.toLowerCase() === symbolName.toLowerCase());
-  });
-}
-
-function buildContext(
-  input: AspectHostInput,
-  nodes: PersistedNodeEmit[],
-  sections: PersistedSectionEmit[],
-  warnings: AspectPluginWarning[],
-): AspectCaptureContext {
-  const packages = input.code_index?.packages ?? [];
-  const symbols = input.code_index?.symbols ?? [];
-  return {
-    aspect: {
-      name: input.aspect,
-      source_slug: input.source_slug,
-      source_id: input.source_id,
-      snapshot_id: input.snapshot_id,
-    },
-    source: {
-      glob: (options = {}) => collectRepoFiles(
-        input.repo_root,
-        options.root ?? "",
-        options.extensions ?? [],
-        options.recursive ?? true,
-      ),
-      immediateFiles: (root, extensions) => collectRepoFiles(input.repo_root, root, extensions, false),
-      exists: async (source) => {
-        try {
-          await resolveRepoPath(input.repo_root, sourceRefFromInput(source));
-          return true;
-        } catch (err) {
-          const code = (err as NodeJS.ErrnoException).code;
-          if (code === "ENOENT" || code === "ENOTDIR") return false;
-          return false;
-        }
-      },
-      readText: (source) => readRepoText(input.repo_root, source),
-    },
-    code: {
-      packages,
-      symbols,
-      findPackage: (packageSlug) => findPackage(packages, packageSlug),
-      findSymbol: (packageSlug, symbolName) => findSymbol(symbols, packageSlug, symbolName),
-    },
-    emit: {
-      node: (row) => {
-        nodes.push(normalizeNode(row));
-      },
-      section: (row) => {
-        sections.push(normalizeSection(row));
-      },
-      warning: (message, detail) => {
-        warnings.push({
-          message,
-          ...(detail !== undefined ? { detail } : {}),
-        });
-      },
-    },
-  };
-}
-
-export async function runAspectPluginForHost(pluginModulePath: string, input: AspectHostInput): Promise<RunnerResult> {
-  const nodes: PersistedNodeEmit[] = [];
-  const sections: PersistedSectionEmit[] = [];
-  const warnings: AspectPluginWarning[] = [];
-  const pluginModule = await import(pathToFileURL(pluginModulePath).href) as {
-    default?: AspectPlugin;
-  };
-  const plugin = pluginModule.default;
-  if (plugin === undefined || typeof plugin.capture !== "function") {
-    throw new Error(`${pluginModulePath} must export default defineAspect({ capture(ctx) { ... } })`);
-  }
-  const ctx = buildContext(input, nodes, sections, warnings);
-  await plugin.setup?.(ctx);
-  try {
-    await plugin.capture(ctx);
-  } finally {
-    await plugin.teardown?.(ctx);
-  }
-  return {
-    type: "aspect-plugin-result.v1",
-    nodes,
-    sections,
-    warnings,
-  };
-}
-
-export function slugSegment(raw: string): string {
-  const segment = raw
-    .trim()
-    .replace(/\.[^.]+$/u, "")
-    .replace(/\+$/u, "")
-    .replace(/([a-z0-9])([A-Z])/gu, "$1-$2")
-    .replace(/[^A-Za-z0-9]+/gu, "-")
-    .replace(/^-+|-+$/gu, "")
-    .toLowerCase();
-  return segment.length > 0 ? segment : "untitled";
-}
-
-async function runPlugin(pluginModulePath: string): Promise<RunnerResult> {
-  return runAspectPluginForHost(pluginModulePath, await readHostInput());
-}
-
-async function main(): Promise<void> {
-  const pluginModulePath = process.argv[2];
-  if (pluginModulePath === undefined || pluginModulePath.length === 0) {
-    throw new Error("usage: aspectRunnerSdk.ts <aspect-plugin-module>");
-  }
-  const result = await runPlugin(path.resolve(pluginModulePath));
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-}
-
-if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main().catch((err) => {
-    const message = err instanceof Error ? err.stack ?? err.message : String(err);
-    process.stderr.write(`${message}\n`);
-    process.exitCode = 1;
-  });
-}
-
-export function markdownFence(language: string, body: string): string {
-  const fence = body.includes("```") ? "~~~~" : "```";
-  return `${fence}${language}\n${body.trimEnd()}\n${fence}`;
-}
-
-export function normalizeSymbolSlug(raw: string): string {
-  const cleaned = raw
-    .replace(/\.[^.]+$/u, "")
-    .replace(/\+$/u, "")
-    .replace(/[^A-Za-z0-9]+/gu, "")
-    .toLowerCase();
-  return cleaned.length === 0 ? "unknown" : cleaned;
-}
-
-export function normalizeComponentSlug(raw: string): string {
-  return normalizeSymbolSlug(raw);
-}
-
-export function inferComponentName(source: string, fallback: string): string {
-  const patterns = [
-    /\bimport\s*\{[^}]*\b([A-Z][A-Za-z0-9]+)\b[^}]*\}/u,
-    /<\s*([A-Z][A-Za-z0-9]+)\b/u,
-    /\b([A-Z][A-Za-z0-9]+)\s*\(/u,
-  ];
-  for (const pattern of patterns) {
-    const match = source.match(pattern);
-    if (match?.[1]) return match[1];
-  }
-  return fallback;
-}
-
-export function artifactFromRelPath(sourcePath: string): string {
-  return sourcePath.replace(/\.[^.]+$/u, "");
-}
-
-export function firstMarkdownHeading(markdown: string, fallback: string): string {
-  const heading = markdown.match(/^#{1,6}\s+(.+)$/mu)?.[1]?.trim();
-  return heading && heading.length > 0 ? heading : fallback;
-}
-
-export function compactWhitespace(value: string): string {
-  return value.replace(/[ \t]+/gu, " ").replace(/\n{3,}/gu, "\n\n").trim();
-}
-
-function sourceFileFor(fileName: string, source: string): ts.SourceFile {
-  const ext = path.extname(fileName).toLowerCase();
-  const scriptKind =
-    ext === ".tsx" ? ts.ScriptKind.TSX :
-    ext === ".jsx" ? ts.ScriptKind.JSX :
-    ext === ".js" || ext === ".cjs" || ext === ".mjs" ? ts.ScriptKind.JS :
-    ts.ScriptKind.TS;
-  return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind);
-}
-
-function propertyNameText(name: ts.PropertyName): string | null {
-  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
-  if (
-    ts.isComputedPropertyName(name) &&
-    ts.isStringLiteralLike(name.expression)
-  ) {
-    return name.expression.text;
-  }
-  return null;
-}
-
-function jsxTagNameText(name: ts.JsxTagNameExpression): string | null {
-  if (ts.isIdentifier(name)) return name.text;
-  if (ts.isPropertyAccessExpression(name)) return name.name.text;
-  return null;
-}
-
-function pushUnique(out: string[], seen: Set<string>, value: string | null | undefined): void {
-  if (!value || seen.has(value)) return;
-  seen.add(value);
-  out.push(value);
-}
-
-export function parseTsxComponentNames(source: string, fileName: string): string[] {
-  const sf = sourceFileFor(fileName, source);
-  const names: string[] = [];
-  const seen = new Set<string>();
-  const isComponentName = (value: string): boolean => /^[A-Z][A-Za-z0-9]+$/u.test(value);
-  function visit(node: ts.Node): void {
-    if (ts.isImportDeclaration(node) && node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings)) {
-      for (const specifier of node.importClause.namedBindings.elements) {
-        const imported = specifier.propertyName?.text ?? specifier.name.text;
-        if (isComponentName(imported)) pushUnique(names, seen, imported);
-      }
-    }
-    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
-      const tag = jsxTagNameText(node.tagName);
-      if (tag && isComponentName(tag)) pushUnique(names, seen, tag);
-    }
-    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && isComponentName(node.expression.text)) {
-      pushUnique(names, seen, node.expression.text);
-    }
-    ts.forEachChild(node, visit);
-  }
-  visit(sf);
-  return names;
-}
-
-export function parseJsLikeTokenNames(source: string, fileName: string, category: string): string[] {
-  const sf = sourceFileFor(fileName, source);
-  const names: string[] = [];
-  const seen = new Set<string>();
-  function maybePush(value: string | null | undefined): void {
-    if (!value) return;
-    void category;
-    if (!/^[A-Za-z_$-][A-Za-z0-9_$-]*$/u.test(value)) return;
-    pushUnique(names, seen, value);
-  }
-  function visit(node: ts.Node): void {
-    if (ts.isPropertyAssignment(node)) {
-      const name = propertyNameText(node.name);
-      if (name === "cssVarName" && ts.isStringLiteralLike(node.initializer)) {
-        maybePush(node.initializer.text);
-      } else {
-        maybePush(name);
-      }
-    } else if (ts.isShorthandPropertyAssignment(node)) {
-      maybePush(node.name.text);
-    } else if (ts.isStringLiteralLike(node) && (/^--[A-Za-z0-9_-]+$/u.test(node.text) || /^\$[A-Za-z0-9_-]+$/u.test(node.text))) {
-      maybePush(node.text);
-    }
-    ts.forEachChild(node, visit);
-  }
-  visit(sf);
-  return names.sort((a, b) => a.localeCompare(b));
-}
-
-export function parseScssTokenNames(source: string): string[] {
-  const names = new Set<string>();
-  for (const line of source.split(/\r?\n/u)) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith("//") || trimmed.startsWith("@import") || trimmed.startsWith("@use")) continue;
-    const variable = trimmed.match(/^(\$[A-Za-z0-9_-]+)\s*:/u)?.[1];
-    if (variable) names.add(variable);
-    const cssVar = trimmed.match(/(--[A-Za-z0-9_-]+)\s*:/u)?.[1];
-    if (cssVar) names.add(cssVar);
-    const property = trimmed.match(/^([A-Za-z-]+)\s*:/u)?.[1];
-    if (property && !["if", "for", "each", "include"].includes(property)) names.add(property);
-  }
-  return [...names].sort((a, b) => a.localeCompare(b));
-}
-
-export interface MdxBlock {
-  type: "heading" | "paragraph" | "code";
-  depth?: number;
-  language?: string;
-  text: string;
-}
-
-export interface ParsedMdxDocument {
-  title: string;
-  markdown: string;
-  blocks: MdxBlock[];
-}
-
-function replaceMdxCodeBlockComponents(raw: string): string {
-  return raw.replace(/<CodeBlock\b[\s\S]*?\/>/gu, (match) => {
-    const code = match.match(/code=\{`([\s\S]*?)`\}/u)?.[1];
-    if (!code) return "";
-    return `\n\n\`\`\`tsx\n${code.trim()}\n\`\`\`\n\n`;
-  });
-}
-
-export function parseMdxDocument(raw: string, fallbackTitle: string): ParsedMdxDocument {
-  const source = replaceMdxCodeBlockComponents(raw);
-  const cleanedLines: string[] = [];
-  let inFence = false;
-  let fenceLanguage = "";
-  let inFrontmatter = false;
-  let jsxTag: string | null = null;
-  for (const [idx, line] of source.split(/\r?\n/u).entries()) {
-    const trimmed = line.trim();
-    if (idx === 0 && trimmed === "---") {
-      inFrontmatter = true;
-      continue;
-    }
-    if (inFrontmatter) {
-      if (trimmed === "---") inFrontmatter = false;
-      continue;
-    }
-    const fence = trimmed.match(/^(```|~~~)(.*)$/u);
-    if (fence) {
-      inFence = !inFence;
-      fenceLanguage = inFence ? fence[2].trim() : "";
-      cleanedLines.push(line);
-      continue;
-    }
-    if (!inFence) {
-      if (jsxTag !== null) {
-        if (
-          trimmed.includes(`</${jsxTag}>`) ||
-          trimmed.endsWith("/>") ||
-          trimmed === `</${jsxTag}>`
-        ) {
-          jsxTag = null;
-        }
-        continue;
-      }
-      if (/^import\s/u.test(trimmed) || /^export\s/u.test(trimmed)) continue;
-      if (/^\{[^}]*\}$/u.test(trimmed)) continue;
-      const jsxOpen = trimmed.match(/^<([A-Z][A-Za-z0-9.:-]*|div|span|a|img)\b/u)?.[1];
-      if (jsxOpen) {
-        if (!trimmed.endsWith("/>") && !trimmed.includes(`</${jsxOpen}>`)) jsxTag = jsxOpen;
-        continue;
-      }
-      cleanedLines.push(line
-        .replace(/<\/?[A-Z][A-Za-z0-9.:-]*(?:\s+[^>]*)?>/gu, "")
-        .replace(/\{`([^`]+)`\}/gu, "`$1`")
-        .replace(/\{["'`]([^"'`]+)["'`]\}/gu, "$1"));
-      continue;
-    }
-    void fenceLanguage;
-    cleanedLines.push(line);
-  }
-
-  const markdown = compactWhitespace(cleanedLines.join("\n"));
-  const blocks: MdxBlock[] = [];
-  let paragraph: string[] = [];
-  let code: string[] = [];
-  let codeLanguage = "";
-  let readingCode = false;
-  function flushParagraph(): void {
-    const text = compactWhitespace(paragraph.join("\n"));
-    if (text.length > 0) blocks.push({ type: "paragraph", text });
-    paragraph = [];
-  }
-  for (const line of markdown.split(/\r?\n/u)) {
-    const fence = line.trim().match(/^(```|~~~)(.*)$/u);
-    if (fence) {
-      if (readingCode) {
-        blocks.push({ type: "code", language: codeLanguage, text: code.join("\n") });
-        code = [];
-        codeLanguage = "";
-        readingCode = false;
-      } else {
-        flushParagraph();
-        codeLanguage = fence[2].trim();
-        readingCode = true;
-      }
-      continue;
-    }
-    if (readingCode) {
-      code.push(line);
-      continue;
-    }
-    const heading = line.match(/^(#{1,6})\s+(.+)$/u);
-    if (heading) {
-      flushParagraph();
-      blocks.push({ type: "heading", depth: heading[1].length, text: heading[2].trim() });
-      continue;
-    }
-    if (line.trim().length === 0) {
-      flushParagraph();
-      continue;
-    }
-    paragraph.push(line);
-  }
-  flushParagraph();
-  const title = blocks.find((block) => block.type === "heading")?.text ?? fallbackTitle;
-  return { title, markdown, blocks };
-}
-
-type CodeLookupInput = AspectCaptureContext | { code_index?: CodeIndexContext };
-
-function codePackages(input: CodeLookupInput): readonly CodeIndexPackage[] {
-  return "code" in input ? input.code.packages : input.code_index?.packages ?? [];
-}
-
-function codeSymbols(input: CodeLookupInput): readonly CodeIndexSymbol[] {
-  return "code" in input ? input.code.symbols : input.code_index?.symbols ?? [];
-}
-
-export function resolvePackageNodeSlug(input: CodeLookupInput, packageSlug: string): string {
-  return codePackages(input).find((pkg) => pkg.package_slug === packageSlug)?.node_slug ?? packageSlug;
-}
-
-export function resolveSymbolNodeSlug(input: CodeLookupInput, packageSlug: string, componentName: string): string {
-  const componentSlug = normalizeSymbolSlug(componentName);
-  const normalizedExport = componentName.toLowerCase();
-  const match = codeSymbols(input).find((symbol) => {
-    if (symbol.package_slug !== undefined && symbol.package_slug !== packageSlug) return false;
-    const nodeLeaf = symbol.node_slug.split("/").at(-1);
-    const names = [symbol.export_name, symbol.symbol_name, ...(symbol.aliases ?? []), nodeLeaf]
-      .filter((name): name is string => typeof name === "string" && name.length > 0);
-    return names.some((rawName) =>
-      normalizeSymbolSlug(rawName) === componentSlug || rawName.toLowerCase() === normalizedExport
-    );
-  });
-  return match?.node_slug ?? `${resolvePackageNodeSlug(input, packageSlug)}/symbol/${componentSlug}`;
-}