@1agh/maude 0.15.0

package/plugins/design/dev-server/test/canvas-edit.test.ts

@@ -0,0 +1,139 @@
+// canvas-edit.ts — Phase 3.6 Task 5. AST-aware single-attribute edits on TSX
+// canvases. The same component+jsxIndex bookkeeping as canvas-pipeline.ts
+// computes the target ID; tests round-trip an edit through transpileCanvasSource
+// to confirm the IDs line up.
+
+import { describe, expect, test } from 'bun:test';
+
+import { CanvasEditError, applyEdit, editAttribute } from '../canvas-edit.ts';
+import { transpileCanvasSource } from '../canvas-pipeline.ts';
+
+const CANVAS = '/abs/Canvas.tsx';
+
+function idsOf(source: string): Record<string, string> {
+  // Run the pipeline to learn what data-cd-id each JSX element gets, returning
+  // a map keyed by the element-type name so tests can ask "what id is the
+  // <span>?" without hardcoding the hash.
+  const { withIds } = transpileCanvasSource(CANVAS, source);
+  const out: Record<string, string> = {};
+  for (const m of withIds.matchAll(/<(\w+)([^>]*?)data-cd-id="([0-9a-f]{8})"/g)) {
+    if (!out[m[1] as string]) out[m[1] as string] = m[3] as string;
+  }
+  return out;
+}
+
+describe('canvas-edit / applyEdit', () => {
+  test('swaps an existing className literal value', () => {
+    const src = `function Demo() { return <button className="btn">OK</button>; }`;
+    const ids = idsOf(src);
+    const id = ids.button as string;
+    const out = applyEdit(CANVAS, src, id, 'className', 'btn btn--ghost');
+    expect(out.source).toBe(
+      `function Demo() { return <button className="btn btn--ghost">OK</button>; }`
+    );
+    // "btn" (3 chars) → "btn btn--ghost" (14 chars): +11 bytes inside the
+    // literal; quotes unchanged.
+    expect(out.delta).toBe(11);
+  });
+
+  test('inserts className when missing', () => {
+    const src = 'function Demo() { return <div>x</div>; }';
+    const ids = idsOf(src);
+    const id = ids.div as string;
+    const out = applyEdit(CANVAS, src, id, 'className', 'card');
+    expect(out.source).toBe(`function Demo() { return <div className="card">x</div>; }`);
+  });
+
+  test('rewrites a plain attribute (aria-label)', () => {
+    const src = `function Demo() { return <button aria-label="old">x</button>; }`;
+    const ids = idsOf(src);
+    const id = ids.button as string;
+    const out = applyEdit(CANVAS, src, id, 'aria-label', 'new');
+    expect(out.source).toBe(`function Demo() { return <button aria-label="new">x</button>; }`);
+  });
+
+  test('swaps a single style.<prop> value inside style={{...}}', () => {
+    const src = 'function Demo() { return <div style={{ padding: 8, margin: 4 }}>x</div>; }';
+    const ids = idsOf(src);
+    const id = ids.div as string;
+    const out = applyEdit(CANVAS, src, id, 'style.padding', '14');
+    expect(out.source).toBe(
+      'function Demo() { return <div style={{ padding: 14, margin: 4 }}>x</div>; }'
+    );
+  });
+
+  test('inserts a missing style key into existing style={{...}}', () => {
+    const src = 'function Demo() { return <div style={{ padding: 8 }}>x</div>; }';
+    const ids = idsOf(src);
+    const id = ids.div as string;
+    const out = applyEdit(CANVAS, src, id, 'style.color', '"#facc15"');
+    // The exact spacing of the appended key is implementation-defined; assert
+    // the substring lands without trampling the prior key.
+    expect(out.source).toContain('padding: 8');
+    expect(out.source).toContain('color: "#facc15"');
+  });
+
+  test('inserts a brand-new style={{}} prop when missing', () => {
+    const src = 'function Demo() { return <div>x</div>; }';
+    const ids = idsOf(src);
+    const id = ids.div as string;
+    const out = applyEdit(CANVAS, src, id, 'style.padding', '14');
+    expect(out.source).toContain('<div style={{ padding: 14 }}>x</div>');
+  });
+
+  test('throws CanvasEditError when id is not found', () => {
+    const src = 'function Demo() { return <div>x</div>; }';
+    expect(() => applyEdit(CANVAS, src, 'deadbeef', 'className', 'x')).toThrow(CanvasEditError);
+  });
+
+  test('refuses to edit data-cd-id (owned by pipeline)', () => {
+    const src = 'function Demo() { return <div>x</div>; }';
+    const ids = idsOf(src);
+    const id = ids.div as string;
+    expect(() => applyEdit(CANVAS, src, id, 'data-cd-id', 'beefcafe')).toThrow(CanvasEditError);
+  });
+
+  test('throws on malformed source', () => {
+    const src = 'function Demo() { return <not closing';
+    expect(() => applyEdit(CANVAS, src, 'aaaaaaaa', 'className', 'x')).toThrow();
+  });
+
+  test('targets the right element when multiple share a type', () => {
+    const src =
+      'function Demo() { return (<section>' +
+      `<button className="a">A</button>` +
+      `<button className="b">B</button>` +
+      '</section>); }';
+    // The pipeline visits in pre-order; expose all <button> ids by walking the
+    // withIds output and capturing each match.
+    const { withIds } = transpileCanvasSource(CANVAS, src);
+    const matches = [
+      ...withIds.matchAll(/<button[^>]*data-cd-id="([0-9a-f]{8})"[^>]*className="([ab])"/g),
+    ];
+    expect(matches.length).toBe(2);
+    const idA = matches.find((m) => m[2] === 'a')?.[1] as string;
+    expect(idA).toBeDefined();
+    const out = applyEdit(CANVAS, src, idA, 'className', 'A-edited');
+    expect(out.source).toContain('className="A-edited"');
+    expect(out.source).toContain('className="b"');
+  });
+});
+
+describe('canvas-edit / editAttribute (fs)', () => {
+  test('writes the edit atomically + is a no-op when source unchanged', async () => {
+    const tmp = `/tmp/canvas-edit-${Math.random().toString(36).slice(2)}.tsx`;
+    const src = `function Demo() { return <div className="x">y</div>; }`;
+    await Bun.write(tmp, src);
+    const ids = idsOf(src);
+    const id = ids.div as string;
+
+    const r1 = await editAttribute(tmp, id, 'className', 'longer-value');
+    expect(r1.delta).toBeGreaterThan(0);
+    const after = await Bun.file(tmp).text();
+    expect(after).toContain('className="longer-value"');
+
+    // Second pass with the same value — no-op (the source already has it).
+    const r2 = await editAttribute(tmp, id, 'className', 'longer-value');
+    expect(r2.delta).toBe(0);
+  });
+});

package/plugins/design/dev-server/test/canvas-header.test.ts

@@ -0,0 +1,127 @@
+// canvas-header.ts — Phase 3.6 Task 12a. Tests the JSDoc header projector
+// (idempotent replace + ai_context surfacing).
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import {
+  type MetaSidecar,
+  applyHeader,
+  applyHeaderToSource,
+  buildHeader,
+} from '../canvas-header.ts';
+
+const META: MetaSidecar = {
+  title: 'Smoke Canvas',
+  subtitle: 'Single hero with CTA — smoke harness',
+  brief: 'Verify the JSDoc projection round-trips meta.',
+  platform: 'desktop',
+  designSystem: 'project',
+  opt_out_scope: 'palette',
+  css_mode: 'inline',
+  sections: [{ id: 's', artboards: [{ id: 'a1' }, { id: 'a2' }] }],
+};
+
+describe('canvas-header / buildHeader', () => {
+  test('renders all canonical @tags', () => {
+    const out = buildHeader({ name: 'Smoke Canvas', meta: META });
+    expect(out).toContain('@canvas      Smoke Canvas — Single hero with CTA');
+    expect(out).toContain('@ds          project');
+    expect(out).toContain('@platform    desktop');
+    expect(out).toContain('@opt_out     palette');
+    expect(out).toContain('@artboards   a1 | a2');
+    expect(out).toContain('@brief       Verify the JSDoc projection');
+    expect(out).toContain('@stack       React 19 · TSX · Bun.build · css_mode=inline');
+    expect(out).toContain('@history     .design/_history/smoke-canvas/');
+    expect(out).toContain('@handoff     bunx shadcn add file://./Smoke Canvas.registry.json');
+  });
+
+  test('surfaces ai_context fields when present', () => {
+    const meta: MetaSidecar = {
+      ...META,
+      ai_context: {
+        why_this_exists: 'Captures the cold-read contract for future Claude.',
+        pinned_decisions: ['Bun.hash over blake3-wasm (smaller dep tree)'],
+        known_quirks: ['IDs renumber on sibling-insert — documented in DDR-019'],
+      },
+    };
+    const out = buildHeader({ name: 'Smoke', meta });
+    expect(out).toContain('@notes       Captures the cold-read contract');
+    expect(out).toContain('@decision    Bun.hash over blake3-wasm');
+    expect(out).toContain('@quirk       IDs renumber on sibling-insert');
+  });
+
+  test('omits ai_context lines when absent', () => {
+    const out = buildHeader({ name: 'Smoke', meta: META });
+    expect(out).not.toContain('@notes');
+    expect(out).not.toContain('@decision');
+    expect(out).not.toContain('@quirk');
+  });
+});
+
+describe('canvas-header / applyHeaderToSource', () => {
+  test('replaces an existing leading block comment', () => {
+    const source = `/** STALE HEADER */\nimport { useState } from "react";\nexport default function X() { return <div/>; }\n`;
+    const header = '/** NEW HEADER */';
+    const out = applyHeaderToSource(source, header);
+    expect(out.startsWith('/** NEW HEADER */')).toBe(true);
+    expect(out).not.toContain('STALE HEADER');
+    expect(out).toContain('import { useState }');
+  });
+
+  test('prepends when no leading block comment exists', () => {
+    const source = `import { useState } from "react";\nexport default function X() { return <div/>; }\n`;
+    const header = '/** NEW HEADER */';
+    const out = applyHeaderToSource(source, header);
+    expect(out.startsWith('/** NEW HEADER */')).toBe(true);
+    expect(out).toContain('import { useState }');
+  });
+
+  test('idempotent — applying twice yields the same output', () => {
+    const source = `import { useState } from "react";\nexport default function X() { return <div/>; }\n`;
+    const header = '/** A */';
+    const once = applyHeaderToSource(source, header);
+    const twice = applyHeaderToSource(once, header);
+    expect(twice).toBe(once);
+  });
+});
+
+describe('canvas-header / applyHeader (fs)', () => {
+  let dir = '';
+  beforeAll(() => {
+    dir = mkdtempSync(path.join(tmpdir(), 'header-'));
+  });
+  afterAll(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('writes a fresh header + persists meta projection', async () => {
+    const canvas = path.join(dir, 'Demo.tsx');
+    const meta = path.join(dir, 'Demo.meta.json');
+    await Bun.write(
+      canvas,
+      'import { useState } from "react";\nexport default function Demo() { return <div/>; }\n'
+    );
+    await Bun.write(meta, JSON.stringify(META, null, 2));
+    const r = await applyHeader(canvas);
+    expect(r.changed).toBe(true);
+    const out = await Bun.file(canvas).text();
+    expect(out.startsWith('/**')).toBe(true);
+    expect(out).toContain('@canvas      Demo');
+    expect(out).toContain('@ds          project');
+    expect(out).toContain('export default function Demo');
+  });
+
+  test('idempotent — second invocation is no-op', async () => {
+    const canvas = path.join(dir, 'Demo2.tsx');
+    const meta = path.join(dir, 'Demo2.meta.json');
+    await Bun.write(canvas, 'export default function Demo2() { return <div/>; }\n');
+    await Bun.write(meta, JSON.stringify(META, null, 2));
+    const r1 = await applyHeader(canvas);
+    expect(r1.changed).toBe(true);
+    const r2 = await applyHeader(canvas);
+    expect(r2.changed).toBe(false);
+  });
+});

package/plugins/design/dev-server/test/canvas-lib-inline.test.ts

@@ -0,0 +1,146 @@
+// canvas-lib-inline — Phase 3.6.1 Task 9. Inline used canvas-lib exports
+// (+ transitive deps) into a handoff drop.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type LibMap, buildLibMap, inlineUsedExports } from '../canvas-lib-inline.ts';
+
+const LIB_PATH = '/virtual/_lib/canvas-lib.tsx';
+
+const SAMPLE_LIB =
+  `import type { ReactNode } from "react";\n` +
+  '\n' +
+  '/** Root wrapper. */\n' +
+  'export function DesignCanvas({ children }: { children: ReactNode }) {\n' +
+  `  return <div className="dc-canvas">{children}</div>;\n` +
+  '}\n' +
+  '\n' +
+  'export function DCArtboard({ children }: { children: ReactNode }) {\n' +
+  `  return <article className="dc-artboard">{children}</article>;\n` +
+  '}\n' +
+  '\n' +
+  'function internalHelper(name: string): string {\n' +
+  '  return name.toUpperCase();\n' +
+  '}\n' +
+  '\n' +
+  'export function TokenChip({ name }: { name: string }) {\n' +
+  '  return <code>{internalHelper(name)}</code>;\n' +
+  '}\n' +
+  '\n' +
+  'export function ColorSwatch({ token }: { token: string }) {\n' +
+  '  return <div><TokenChip name={token} /></div>;\n' +
+  '}\n';
+
+function map(): LibMap {
+  return buildLibMap(LIB_PATH, SAMPLE_LIB);
+}
+
+describe('canvas-lib-inline / buildLibMap', () => {
+  test('records every named export', () => {
+    const m = map();
+    expect(m.has('DesignCanvas')).toBe(true);
+    expect(m.has('DCArtboard')).toBe(true);
+    expect(m.has('TokenChip')).toBe(true);
+    expect(m.has('ColorSwatch')).toBe(true);
+  });
+
+  test('also records internal helpers (reachable for transitive resolution)', () => {
+    const m = map();
+    expect(m.has('internalHelper')).toBe(true);
+  });
+
+  test('captures dep edges (ColorSwatch → TokenChip)', () => {
+    const m = map();
+    expect(m.get('ColorSwatch')?.deps).toContain('TokenChip');
+  });
+
+  test('captures dep edges (TokenChip → internalHelper)', () => {
+    const m = map();
+    expect(m.get('TokenChip')?.deps).toContain('internalHelper');
+  });
+
+  test('captures leading JSDoc comment', () => {
+    const m = map();
+    expect(m.get('DesignCanvas')?.source).toContain('Root wrapper');
+  });
+
+  test('strips leading `export` token from inlined source', () => {
+    const m = map();
+    expect(m.get('DesignCanvas')?.source).not.toMatch(/^export\s+/);
+  });
+});
+
+describe('canvas-lib-inline / inlineUsedExports', () => {
+  test('no-op when canvas has no @maude/canvas-lib import', () => {
+    const canvas = 'export default function X() { return <button>x</button>; }\n';
+    const r = inlineUsedExports(canvas, map());
+    expect(r.droppedImport).toBe(false);
+    expect(r.content).toBe(canvas);
+    expect(r.inlined).toEqual([]);
+  });
+
+  test('inlines a single export + strips import line', () => {
+    const canvas =
+      `import { DesignCanvas } from "@maude/canvas-lib";\n` +
+      'export default function X() { return <DesignCanvas>hi</DesignCanvas>; }\n';
+    const r = inlineUsedExports(canvas, map());
+    expect(r.droppedImport).toBe(true);
+    expect(r.inlined).toEqual(['DesignCanvas']);
+    expect(r.content).not.toContain('@maude/canvas-lib');
+    expect(r.content).toContain('function DesignCanvas');
+  });
+
+  test('inlines transitive internal deps (ColorSwatch → TokenChip → internalHelper)', () => {
+    const canvas =
+      `import { ColorSwatch } from "@maude/canvas-lib";\n` +
+      `export default function X() { return <ColorSwatch token="--accent" />; }\n`;
+    const r = inlineUsedExports(canvas, map());
+    expect(r.inlined.sort()).toEqual(['ColorSwatch', 'TokenChip', 'internalHelper']);
+    expect(r.content).toContain('function ColorSwatch');
+    expect(r.content).toContain('function TokenChip');
+    expect(r.content).toContain('function internalHelper');
+  });
+
+  test('handles multi-line import with trailing commas', () => {
+    const canvas =
+      `import {\n  DesignCanvas,\n  DCArtboard,\n} from "@maude/canvas-lib";\n` +
+      'export default function X() { return <DesignCanvas><DCArtboard /></DesignCanvas>; }\n';
+    const r = inlineUsedExports(canvas, map());
+    expect(r.inlined.sort()).toEqual(['DCArtboard', 'DesignCanvas']);
+    expect(r.content).not.toMatch(/from\s*["']@maude\/canvas-lib["']/);
+  });
+
+  test('throws when canvas imports an unknown export', () => {
+    const canvas =
+      `import { DoesNotExist } from "@maude/canvas-lib";\n` +
+      'export default function X() { return <DoesNotExist />; }\n';
+    expect(() => inlineUsedExports(canvas, map())).toThrow(/no such export/);
+  });
+
+  test('inlined content keeps the canvas default export at the top', () => {
+    const canvas =
+      `import { DesignCanvas } from "@maude/canvas-lib";\n` +
+      'export default function X() { return <DesignCanvas>x</DesignCanvas>; }\n';
+    const r = inlineUsedExports(canvas, map());
+    const defaultIdx = r.content.indexOf('export default');
+    const helperIdx = r.content.indexOf('function DesignCanvas');
+    expect(defaultIdx).toBeGreaterThan(-1);
+    expect(helperIdx).toBeGreaterThan(defaultIdx);
+  });
+
+  test('zero @maude references remain in output', () => {
+    const canvas =
+      `import { DesignCanvas, ColorSwatch } from "@maude/canvas-lib";\n` +
+      `export default function X() { return <DesignCanvas><ColorSwatch token="--x"/></DesignCanvas>; }\n`;
+    const r = inlineUsedExports(canvas, map());
+    expect(r.content.match(/@maude/g)).toBeNull();
+  });
+
+  test('result is at least as large as the original canvas (helpers added)', () => {
+    const canvas =
+      `import { DesignCanvas } from "@maude/canvas-lib";\n` +
+      'export default function X() { return <DesignCanvas>x</DesignCanvas>; }\n';
+    const r = inlineUsedExports(canvas, map());
+    expect(r.content.length).toBeGreaterThan(canvas.length);
+  });
+});

package/plugins/design/dev-server/test/canvas-lib-resolver.test.ts

@@ -0,0 +1,112 @@
+// canvas-lib-resolver — virtual specifier `@maude/canvas-lib` → the dev-server-
+// bundled canvas-lib (Phase 3.6.1 Task 2; relocated to dev-server in Phase
+// 4.0.5 per DDR-025).
+
+import { existsSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+
+import { buildCanvasModule } from '../canvas-build.ts';
+import {
+  CANVAS_LIB_SPECIFIER,
+  canvasLibPath,
+  readCanvasLibSource,
+} from '../canvas-lib-resolver.ts';
+
+const TMP = `/tmp/canvas-lib-resolver-${Math.random().toString(36).slice(2, 8)}`;
+const DESIGN_ROOT = path.join(TMP, 'designRoot');
+
+beforeAll(async () => {
+  await mkdir(DESIGN_ROOT, { recursive: true });
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe('canvas-lib-resolver / canvasLibPath', () => {
+  test('returns the dev-server-internal canvas-lib.tsx path', () => {
+    const p = canvasLibPath();
+    expect(p.endsWith('plugins/design/dev-server/canvas-lib.tsx')).toBe(true);
+    expect(existsSync(p)).toBe(true);
+  });
+
+  test('ignores the legacy designRoot argument (back-compat shim)', () => {
+    expect(canvasLibPath('/foo/bar')).toBe(canvasLibPath());
+  });
+
+  test('CANVAS_LIB_SPECIFIER is `@maude/canvas-lib`', () => {
+    expect(CANVAS_LIB_SPECIFIER).toBe('@maude/canvas-lib');
+  });
+});
+
+describe('canvas-lib-resolver / canvasLibResolver plugin', () => {
+  test('resolves @maude/canvas-lib through Bun.build', async () => {
+    const canvasPath = path.join(DESIGN_ROOT, 'ui', 'Resolves.tsx');
+    await mkdir(path.dirname(canvasPath), { recursive: true });
+    const canvasSource =
+      `import { DesignCanvas, DCArtboard } from "@maude/canvas-lib";\n` +
+      'export default function Demo() {\n' +
+      '  return <DesignCanvas><DCArtboard>hi</DCArtboard></DesignCanvas>;\n' +
+      '}\n';
+    await writeFile(canvasPath, canvasSource);
+    const r = await buildCanvasModule(canvasPath, canvasSource, {
+      designRoot: DESIGN_ROOT,
+    });
+    // The bundled output should contain the resolved lib's function bodies.
+    expect(r.js).toContain('dc-canvas');
+    expect(r.js).toContain('dc-artboard');
+    // The bare specifier should NOT survive as an import.
+    expect(r.js).not.toMatch(/from\s*["']@maude\/canvas-lib["']/);
+  });
+
+  test('does not interfere with canvases that never import the lib', async () => {
+    const canvasPath = path.join(DESIGN_ROOT, 'ui', 'PlainNoLib.tsx');
+    await mkdir(path.dirname(canvasPath), { recursive: true });
+    const canvasSource = 'export default function Y() { return <button>hi</button>; }\n';
+    await writeFile(canvasPath, canvasSource);
+    const r = await buildCanvasModule(canvasPath, canvasSource, {
+      designRoot: DESIGN_ROOT,
+    });
+    expect(r.js).toContain('button');
+  });
+});
+
+describe('canvas-lib-resolver / readCanvasLibSource', () => {
+  test('reads the dev-server-bundled lib source', async () => {
+    const src = await readCanvasLibSource();
+    // Real bundled lib — assert a stable export name shows up.
+    expect(src).toContain('DesignCanvas');
+  });
+
+  test('ignores the legacy designRoot argument', async () => {
+    const src = await readCanvasLibSource('/non-existent-design-root');
+    expect(src).toContain('DesignCanvas');
+  });
+});
+
+describe('canvas-lib-resolver / legacy deprecation guard', () => {
+  test('legacy <designRoot>/_lib/canvas-lib.tsx is ignored — dev-server bundled lib wins', async () => {
+    const projRoot = path.join(TMP, 'legacy-project');
+    const legacyLibDir = path.join(projRoot, '_lib');
+    await mkdir(legacyLibDir, { recursive: true });
+    // Plant a syntactically-bogus legacy file. If the resolver were still
+    // reading from `<designRoot>/_lib/canvas-lib.tsx` this would explode at
+    // bundle time; with the dev-server-bundled lib it must be a no-op.
+    await writeFile(
+      path.join(legacyLibDir, 'canvas-lib.tsx'),
+      '// LEGACY — should be ignored\nexport const SHOULD_NOT_APPEAR = true;\n'
+    );
+    const canvasPath = path.join(projRoot, 'ui', 'Legacy.tsx');
+    await mkdir(path.dirname(canvasPath), { recursive: true });
+    const canvasSource =
+      `import { DesignCanvas } from "@maude/canvas-lib";\n` +
+      'export default function L() { return <DesignCanvas>hi</DesignCanvas>; }\n';
+    await writeFile(canvasPath, canvasSource);
+    const r = await buildCanvasModule(canvasPath, canvasSource, { designRoot: projRoot });
+    expect(r.js).toContain('dc-canvas');
+    expect(r.js).not.toContain('SHOULD_NOT_APPEAR');
+  });
+});