@principal-ai/principal-view-react 0.16.44 → 0.16.46

package/src/subsystem/formatDeclaration.ts

@@ -0,0 +1,116 @@
+/**
+ * Generate a TypeScript declaration string from a SubsystemComponent's detail.
+ *
+ * This is the "source code" that Prettier will format. The output is valid
+ * TypeScript (except for `external`, which is handled separately). The string
+ * is intentionally simple — no indentation, no line breaks — because Prettier
+ * handles all formatting.
+ */
+
+import type { SubsystemComponent } from './model';
+import type { GraphifyComponentDetail } from '../graphify';
+
+export function generateDeclarationString(component: SubsystemComponent): string {
+  const detail = component.detail;
+  const kind = detail?.kind ?? component.kind;
+  const name = component.symbol || component.name || 'untitled';
+
+  switch (kind) {
+    case 'class':
+      return generateClass(name, detail);
+    case 'function':
+      return generateFunction(name, detail);
+    case 'type':
+      return generateType(name, detail);
+    case 'module':
+      return generateModule(detail);
+    case 'external':
+      // Not valid TypeScript — caller should handle formatting.
+      return `external '${detail?.kind === 'external' ? detail.label : name}'`;
+    default:
+      return `${kind} ${name}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Format parameters, synthesising names for unnamed positionals. */
+function formatParams(params: { name?: string; type: string }[]): string {
+  return params
+    .map((p, i) => (p.name ? `${p.name}: ${p.type}` : `arg${i}: ${p.type}`))
+    .join(', ');
+}
+
+// ---------------------------------------------------------------------------
+// Per-kind generators
+// ---------------------------------------------------------------------------
+
+function generateClass(name: string, detail?: GraphifyComponentDetail): string {
+  const cls = detail?.kind === 'class' ? detail : undefined;
+  const parts: string[] = [`class ${name}`];
+
+  if (cls?.extends && cls.extends.length > 0) {
+    parts.push(`extends ${cls.extends.join(', ')}`);
+  }
+  if (cls?.implements && cls.implements.length > 0) {
+    parts.push(`implements ${cls.implements.join(', ')}`);
+  }
+
+  const members: string[] = [];
+
+  for (const m of cls?.methods ?? []) {
+    const ret = m.returnType ? `: ${m.returnType}` : '';
+    members.push(`  ${m.name}(${formatParams(m.parameters ?? [])})${ret};`);
+  }
+
+  for (const prop of cls?.properties ?? []) {
+    const t = prop.type ? `: ${prop.type}` : '';
+    members.push(`  ${prop.name}${t};`);
+  }
+
+  if (members.length > 0) {
+    parts.push(`{\n${members.join('\n')}\n}`);
+  } else {
+    parts.push('{}');
+  }
+
+  return parts.join(' ');
+}
+
+function generateFunction(name: string, detail?: GraphifyComponentDetail): string {
+  const fn = detail?.kind === 'function' ? detail : undefined;
+  const params = formatParams(fn?.parameters ?? []);
+  const ret = fn?.returnType ? `: ${fn.returnType}` : '';
+  return `function ${name}(${params})${ret};`;
+}
+
+function generateType(name: string, detail?: GraphifyComponentDetail): string {
+  const tpe = detail?.kind === 'type' ? detail : undefined;
+  const props = (tpe?.properties ?? [])
+    .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
+    .join('\n');
+
+  if (props) {
+    return `interface ${name} {\n${props}\n}`;
+  }
+  return `interface ${name} {}`;
+}
+
+function generateModule(detail?: GraphifyComponentDetail): string {
+  const mod = detail?.kind === 'module' ? detail : undefined;
+  if (!mod) return 'module {}';
+
+  const parts: string[] = [];
+
+  for (const imp of mod.imports ?? []) {
+    parts.push(`import '${imp.name}';`);
+  }
+
+  if ((mod.exports ?? []).length > 0) {
+    parts.push(`export { ${mod.exports!.join(', ')} };`);
+  }
+
+  return parts.join('\n') || `module {}`;
+}

package/src/subsystem/model.ts

@@ -27,6 +27,24 @@ export type SubsystemComponentKind =
   | 'module'
   | 'external';
 
+// ---------------------------------------------------------------------------
+// Declaration tokens — structured source representation
+// ---------------------------------------------------------------------------
+
+export type SubsystemDeclTokenKind =
+  | 'keyword'
+  | 'name'
+  | 'member'
+  | 'type'
+  | 'punctuation'
+  | 'string'
+  | 'newline';
+
+export interface SubsystemDeclToken {
+  text: string;
+  kind: SubsystemDeclTokenKind;
+}
+
 export type SubsystemEdgeMechanism =
   | 'imports'
   | 'imports_from'
@@ -87,6 +105,12 @@ export interface SubsystemComponent {
    * may claim `verified`.
    */
   detailProvenance?: 'verified' | 'authored';
+  /**
+   * Pre-tokenized declaration for the detail panel. When present, the
+   * renderer skips client-side tokenization. Tokens are language-agnostic;
+   * a different language just needs a different tokenizer and text joiner.
+   */
+  tokens?: SubsystemDeclToken[];
 }
 
 /** A cross-component edge in the subsystem graph. */

package/src/subsystem/tokenizeComponent.ts

@@ -0,0 +1,70 @@
+/**
+ * Tokenize a SubsystemComponent into a flat token stream for the detail panel.
+ *
+ * Pipeline: generate declaration string → format with Prettier → tokenize
+ * with highlight.js. The `component.tokens` field, when present, overrides
+ * the entire pipeline (for pre-tokenized data from graphify).
+ *
+ * This function is async because Prettier's format() is async.
+ */
+
+import type { SubsystemComponent, SubsystemDeclToken } from './model';
+import { generateDeclarationString } from './formatDeclaration';
+import { tokenizeFormatted } from './tokenizeFormatted';
+
+// Lazy-loaded Prettier to avoid startup cost.
+let prettierPromise: Promise<typeof import('prettier/standalone')> | null = null;
+let prettierPluginsPromise: Promise<{
+  typescript: typeof import('prettier/plugins/typescript');
+  estree: typeof import('prettier/plugins/estree');
+}> | null = null;
+
+async function getPrettier() {
+  if (!prettierPromise) {
+    prettierPromise = import('prettier/standalone');
+  }
+  if (!prettierPluginsPromise) {
+    prettierPluginsPromise = Promise.all([
+      import('prettier/plugins/typescript'),
+      import('prettier/plugins/estree'),
+    ]).then(([typescript, estree]) => ({ typescript, estree }));
+  }
+  const [prettier, plugins] = await Promise.all([prettierPromise, prettierPluginsPromise]);
+  return { prettier, plugins };
+}
+
+/**
+ * Tokenize a SubsystemComponent into SubsystemDeclToken[].
+ *
+ * When `component.tokens` is present (pre-tokenized data from the wire),
+ * it's returned as-is. Otherwise the pipeline generates a TypeScript
+ * declaration string, formats it with Prettier, and tokenizes the output.
+ */
+export async function tokenizeComponent(component: SubsystemComponent): Promise<SubsystemDeclToken[]> {
+  // Pre-tokenized tokens from the wire take precedence.
+  if (component.tokens) return component.tokens;
+
+  // External kind — not valid TypeScript, bypass Prettier.
+  const kind = component.detail?.kind ?? component.kind;
+  if (kind === 'external') {
+    const label = component.detail?.kind === 'external' ? component.detail.label : component.name;
+    return [
+      { text: 'external', kind: 'keyword' },
+      { text: ' ', kind: 'punctuation' },
+      { text: "'", kind: 'punctuation' },
+      { text: label, kind: 'string' },
+      { text: "'", kind: 'punctuation' },
+    ];
+  }
+
+  // Generate → format → tokenize
+  const raw = generateDeclarationString(component);
+  const { prettier, plugins } = await getPrettier();
+  const formatted = await prettier.format(raw, {
+    parser: 'typescript',
+    plugins: [plugins.typescript, plugins.estree],
+    printWidth: 80,
+  });
+
+  return tokenizeFormatted(formatted);
+}

package/src/subsystem/tokenizeFormatted.ts

@@ -0,0 +1,92 @@
+/**
+ * Tokenize a formatted TypeScript declaration string into SubsystemDeclToken[]
+ * using highlight.js.
+ *
+ * highlight.js produces HTML with `<span class="hljs-...">` wrappers. This
+ * module parses that output into our token format so the renderer stays
+ * language-agnostic.
+ */
+
+import hljs from 'highlight.js/lib/core';
+import typescript from 'highlight.js/lib/languages/typescript';
+import type { SubsystemDeclToken, SubsystemDeclTokenKind } from './model';
+
+// Register once — safe to call multiple times.
+try {
+  hljs.registerLanguage('typescript', typescript);
+} catch {
+  // Already registered.
+}
+
+// hljs class → our token kind
+const CLASS_MAP: Record<string, SubsystemDeclTokenKind> = {
+  'hljs-keyword': 'keyword',
+  'hljs-title': 'name',
+  'hljs-title.function_': 'name',
+  'hljs-params': 'member',
+  'hljs-type': 'type',
+  'hljs-built_in': 'type',
+  'hljs-string': 'string',
+  'hljs-number': 'string',
+  'hljs-comment': 'punctuation',
+};
+
+/**
+ * Tokenize a formatted TypeScript string into SubsystemDeclToken[].
+ * The input should already be formatted by Prettier (or be valid TS).
+ */
+export function tokenizeFormatted(code: string): SubsystemDeclToken[] {
+  const result = hljs.highlight(code, { language: 'typescript' });
+  return parseHighlightedHtml(result.value);
+}
+
+// ---------------------------------------------------------------------------
+// HTML parser — walks the hljs output and extracts tokens
+// ---------------------------------------------------------------------------
+
+function unescapeHtml(text: string): string {
+  return text
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/&#39;/g, "'");
+}
+
+function parseHighlightedHtml(html: string): SubsystemDeclToken[] {
+  const tokens: SubsystemDeclToken[] = [];
+  // Regex matches either `<span class="hljs-...">`, `</span>`, or text content.
+  const re = /<span class="([^"]+)">|<\/span>|[^<]+/g;
+  const classStack: string[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = re.exec(html)) !== null) {
+    const chunk = match[0];
+
+    if (chunk.startsWith('<span')) {
+      // Opening tag — push class onto stack.
+      classStack.push(match[1]);
+    } else if (chunk === '</span>') {
+      // Closing tag — pop class.
+      classStack.pop();
+    } else {
+      // Text content — emit tokens for each line segment.
+      const currentClass = classStack[classStack.length - 1] ?? '';
+      const kind = CLASS_MAP[currentClass] ?? 'punctuation';
+      const text = chunk;
+
+      // Split on newlines so each line becomes its own token set.
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (i > 0) {
+          tokens.push({ text: '', kind: 'newline' });
+        }
+        if (lines[i]) {
+          tokens.push({ text: unescapeHtml(lines[i]), kind });
+        }
+      }
+    }
+  }
+
+  return tokens;
+}