@specverse/engines 4.1.30 → 4.2.0

package/libs/instance-factories/applications/templates/react-starter/__tests__/parity-p3-rendered-output.test.ts

@@ -0,0 +1,183 @@
+/**
+ * P3 — Rendered-output equivalence
+ *
+ * Architectural invariant: the same (spec, view, model) must produce
+ * semantically equivalent output in app-demo (runtime React adapter)
+ * and in ReactAppStarter (Factory B emitter). They differ only in
+ * execution model — one renders in the browser, the other emits
+ * static JSX — but the visible structure must match.
+ *
+ * This file tests the LIST VIEW path, where parity is most
+ * tractable because both consumers call the same Tailwind adapter
+ * for the table shell. The test covers:
+ *
+ *   1. Column selection — both use `inferFieldsFromSchema` from
+ *      the canonical pattern engine. Drift in either composer's
+ *      column-filter logic would diverge here.
+ *   2. Table shell HTML — the Tailwind adapter renders the same
+ *      shell for both paths; ensured by Factory B importing
+ *      `createUniversalTailwindAdapter` directly.
+ *   3. Field humanisation — `camelCase` → `Title Case` for headers.
+ *
+ * Not yet covered (future extensions):
+ *   - Detail / form / dashboard views — would need a reference
+ *     React-adapter render path captured as an HTML string, then
+ *     diffed against the Factory B emitted JSX modulo structural
+ *     differences. Doable but bigger test machinery.
+ *   - FK display-name resolution — blocked on Factory B's TODO to
+ *     replace plain-FK inputs with dropdowns.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { inferFieldsFromSchema } from '@specverse/runtime/views/core';
+import { createUniversalTailwindAdapter } from '@specverse/runtime/views/tailwind';
+import { composeListBody } from '../list-body-composer.js';
+import type { EmitContext, ModelSpec } from '../view-emitter.js';
+
+// ───────────────────────────────────────────────────────────────────────
+// Reference model + view-spec setup
+// ───────────────────────────────────────────────────────────────────────
+
+function makeReferenceModel(): ModelSpec {
+  return {
+    name: 'Article',
+    attributes: {
+      id: { type: 'UUID', required: true, auto: 'uuid4' },      // excluded
+      title: { type: 'String', required: true },                // included
+      slug: { type: 'String', required: true, unique: true },   // included
+      content: { type: 'Text', required: false },               // included
+      status: { type: 'String', values: ['draft', 'published'] },// included
+      authorId: { type: 'UUID', required: true },               // included (FK)
+      createdAt: { type: 'DateTime', auto: 'now' },             // excluded (auto)
+      updatedAt: { type: 'DateTime', auto: 'now' },             // excluded (auto)
+    },
+  };
+}
+
+function makeContext(): EmitContext {
+  const model = makeReferenceModel();
+  return {
+    view: { type: 'list', model: 'Article' },
+    viewName: 'ArticleListView',
+    model,
+    modelSchemas: { Article: model },
+    renderBody: composeListBody,
+  };
+}
+
+function humanize(s: string): string {
+  return s.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase()).trim();
+}
+
+// ───────────────────────────────────────────────────────────────────────
+// Parity assertions
+// ───────────────────────────────────────────────────────────────────────
+
+describe('P3 — list view column inference parity', () => {
+  it('runtime inferFieldsFromSchema and Factory B composer see the same columns', () => {
+    const ctx = makeContext();
+    const runtimeColumns = inferFieldsFromSchema(ctx.modelSchemas, ctx.model.name);
+
+    // We can extract Factory B's column choices by looking at what
+    // headers it emits into the rendered output.
+    const body = composeListBody(ctx);
+
+    for (const col of runtimeColumns) {
+      const label = humanize(col);
+      expect(body, `runtime column "${col}" (label: "${label}") must appear in Factory B output`)
+        .toContain(`>${label}<`);
+    }
+
+    // And nothing EXTRA from the model that runtime excludes:
+    const runtimeSet = new Set(runtimeColumns);
+    const allAttrs = Object.keys(ctx.model.attributes);
+    const runtimeExcluded = allAttrs.filter(a => !runtimeSet.has(a));
+    for (const excluded of runtimeExcluded) {
+      const label = humanize(excluded);
+      // Factory B must NOT emit a <th> for this field.
+      const headerPattern = new RegExp(`<th\\b[^>]*>${label}</th>`);
+      expect(body).not.toMatch(headerPattern);
+    }
+  });
+
+  it('matches the expected column set for the reference model', () => {
+    const cols = inferFieldsFromSchema(makeContext().modelSchemas, 'Article');
+    // Canonical expectation for this reference spec.
+    expect(cols).toEqual(['title', 'slug', 'content', 'status', 'authorId']);
+  });
+});
+
+describe('P3 — list view table shell parity', () => {
+  it('emits a table shell byte-identical to a direct Tailwind adapter call', () => {
+    // The composer calls createUniversalTailwindAdapter() + table.render()
+    // with a known columns list and a sentinel in children. If we call
+    // the adapter directly with the same args, we should get the same
+    // shell HTML (modulo the sentinel vs the Factory B JSX injection).
+    const ctx = makeContext();
+    const runtimeColumns = inferFieldsFromSchema(ctx.modelSchemas, ctx.model.name);
+    const headers = runtimeColumns.map(humanize);
+
+    const adapter = createUniversalTailwindAdapter({ darkMode: true });
+    const SENTINEL = 'SENTINEL';
+    const shellHtml = adapter.components.table.render({
+      properties: { columns: headers },
+      children: SENTINEL,
+    });
+
+    // Every column header appears in the shell, in order.
+    let lastIdx = -1;
+    for (const header of headers) {
+      const idx = shellHtml.indexOf(`>${header}</th>`);
+      expect(idx, `header "${header}" must appear in Tailwind adapter output`).toBeGreaterThan(-1);
+      expect(idx, `header "${header}" must appear AFTER the previous header`).toBeGreaterThan(lastIdx);
+      lastIdx = idx;
+    }
+
+    // Factory B's composer output must preserve the same header order.
+    const body = composeListBody(ctx);
+    let lastBodyIdx = -1;
+    for (const header of headers) {
+      const idx = body.indexOf(`>${header}</th>`);
+      expect(idx).toBeGreaterThan(-1);
+      expect(idx).toBeGreaterThan(lastBodyIdx);
+      lastBodyIdx = idx;
+    }
+  });
+
+  it('Factory B output carries Tailwind classes from the canonical adapter shell', () => {
+    const body = composeListBody(makeContext());
+    // A sampling of classes that come from the adapter's table template.
+    // If the adapter changes its classes, both consumers update together.
+    expect(body).toContain('overflow-x-auto');
+    expect(body).toContain('min-w-full');
+    expect(body).toContain('divide-y divide-gray-200');
+    expect(body).toContain('bg-gray-50 dark:bg-gray-800');
+  });
+
+  it('rows are synthesized by Factory B (the adapter emits placeholder for react mount)', () => {
+    const body = composeListBody(makeContext());
+    // The body should contain a real JSX .map() — Factory B's
+    // contribution to the shared shell.
+    expect(body).toContain('filtered.map((item, idx) =>');
+    expect(body).toContain('onClick={() => onSelect?.(item)}');
+  });
+});
+
+describe('P3 — field humanisation parity', () => {
+  it('both paths humanise column names the same way (camelCase → Title Case)', () => {
+    // Factory B's humanize is inlined in the composer. The runtime
+    // adapter humanises via the same-shaped regex in pattern-engine /
+    // react-pattern-adapter. This test documents the contract by
+    // comparing against a fixture.
+    const cases: [string, string][] = [
+      ['title', 'Title'],
+      ['authorId', 'Author Id'],
+      ['createdAt', 'Created At'],
+      ['slugifiedURL', 'Slugified U R L'],
+      ['name', 'Name'],
+    ];
+    for (const [input, expected] of cases) {
+      expect(humanize(input), `humanize("${input}")`).toBe(expected);
+    }
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/regen-safety.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  loadHashManifest,
+  saveHashManifest,
+  reconcileWrites,
+  sha256,
+  HASHES_DIR,
+  HASHES_FILE,
+} from '../regen-safety.js';
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), 'specverse-regen-safety-'));
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+});
+
+describe('hash manifest persistence', () => {
+  it('loadHashManifest returns {} when the file is missing', () => {
+    expect(loadHashManifest(projectRoot)).toEqual({});
+  });
+
+  it('round-trips through save → load', () => {
+    saveHashManifest(projectRoot, { 'src/a.ts': 'abc', 'src/b.ts': 'def' });
+    const loaded = loadHashManifest(projectRoot);
+    expect(loaded).toEqual({ 'src/a.ts': 'abc', 'src/b.ts': 'def' });
+    expect(existsSync(join(projectRoot, HASHES_DIR, HASHES_FILE))).toBe(true);
+  });
+
+  it('tolerates a malformed manifest file by returning {}', () => {
+    const dir = join(projectRoot, HASHES_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, HASHES_FILE), '{ not valid JSON', 'utf8');
+    expect(loadHashManifest(projectRoot)).toEqual({});
+  });
+});
+
+describe('reconcileWrites — pure planning (no I/O writes)', () => {
+  it('approves brand-new files and records their hashes', () => {
+    const proposed = { 'src/views/PostListView.tsx': 'content-a' };
+    const result = reconcileWrites(projectRoot, proposed, {});
+    expect(result.approvedWrites).toEqual(proposed);
+    expect(result.skipped).toEqual([]);
+    expect(existsSync(join(projectRoot, 'src/views/PostListView.tsx'))).toBe(false);
+    expect(result.manifest['src/views/PostListView.tsx']).toBe(sha256('content-a'));
+  });
+
+  it('approves overwriting a pristine file and updates its hash', () => {
+    const path = 'src/a.ts';
+    const absPath = join(projectRoot, path);
+    const originalContent = 'v1';
+    const newContent = 'v2';
+
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(absPath, originalContent, 'utf8');
+    const prevManifest = { [path]: sha256(originalContent) };
+
+    const result = reconcileWrites(projectRoot, { [path]: newContent }, prevManifest);
+
+    expect(result.approvedWrites[path]).toBe(newContent);
+    expect(result.skipped).toEqual([]);
+    // reconcileWrites is pure planning — filesystem unchanged
+    expect(readFileSync(absPath, 'utf8')).toBe(originalContent);
+    expect(result.manifest[path]).toBe(sha256(newContent));
+  });
+
+  it('skips a user-edited file and keeps the old hash record', () => {
+    const path = 'src/edited.ts';
+    const absPath = join(projectRoot, path);
+    const originalContent = 'v1';
+    const editedContent = 'v1 + user edits';
+    const newContent = 'v2';
+
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(absPath, editedContent, 'utf8');
+    const prevManifest = { [path]: sha256(originalContent) };
+
+    const result = reconcileWrites(projectRoot, { [path]: newContent }, prevManifest);
+
+    expect(result.approvedWrites[path]).toBeUndefined();
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0]).toMatchObject({
+      path,
+      reason: expect.stringContaining('edited'),
+    });
+    expect(readFileSync(absPath, 'utf8')).toBe(editedContent);
+    expect(result.manifest[path]).toBe(prevManifest[path]);
+  });
+
+  it('skips files that exist but have no prior hash record', () => {
+    const path = 'src/unknown.ts';
+    const absPath = join(projectRoot, path);
+
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(absPath, 'manually placed', 'utf8');
+
+    const result = reconcileWrites(projectRoot, { [path]: 'would-overwrite' }, {});
+
+    expect(result.approvedWrites[path]).toBeUndefined();
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0].reason).toContain('no prior hash recorded');
+    expect(readFileSync(absPath, 'utf8')).toBe('manually placed');
+  });
+
+  it('does not mutate the input prevManifest', () => {
+    const prev = { 'a.ts': sha256('old') };
+    const prevSnapshot = { ...prev };
+    reconcileWrites(projectRoot, { 'a.ts': 'new', 'b.ts': 'also new' }, prev);
+    expect(prev).toEqual(prevSnapshot);
+  });
+
+  it('handles a batch of mixed outcomes correctly', () => {
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(join(projectRoot, 'src/pristine.ts'), 'v1', 'utf8');
+    writeFileSync(join(projectRoot, 'src/edited.ts'), 'v1 + user edit', 'utf8');
+    const prev = {
+      'src/pristine.ts': sha256('v1'),
+      'src/edited.ts': sha256('v1'),
+    };
+
+    const proposed = {
+      'src/pristine.ts': 'v2',
+      'src/edited.ts': 'v2',
+      'src/new.ts': 'brand new',
+    };
+
+    const result = reconcileWrites(projectRoot, proposed, prev);
+
+    expect(Object.keys(result.approvedWrites).sort()).toEqual(['src/new.ts', 'src/pristine.ts']);
+    expect(result.skipped.map(s => s.path)).toEqual(['src/edited.ts']);
+    // No writes happened
+    expect(readFileSync(join(projectRoot, 'src/pristine.ts'), 'utf8')).toBe('v1');
+    expect(readFileSync(join(projectRoot, 'src/edited.ts'), 'utf8')).toBe('v1 + user edit');
+    expect(result.manifest['src/pristine.ts']).toBe(sha256('v2'));
+    expect(result.manifest['src/edited.ts']).toBe(prev['src/edited.ts']);
+    expect(result.manifest['src/new.ts']).toBe(sha256('brand new'));
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/starter-generators.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import * as ts from 'typescript';
+import { generate as generateAppTsx } from '../app-tsx-generator.js';
+import { generate as generatePackageJson } from '../package-json-generator.js';
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('app-tsx-generator', () => {
+  it('produces valid TSX with one branch per model and view type', async () => {
+    const source = await generateAppTsx({
+      spec: {
+        models: {
+          Post: { name: 'Post', attributes: {} },
+          Author: { name: 'Author', attributes: {} },
+        },
+      },
+    });
+    assertValidTsx(source, 'App.tsx');
+    // One nav section per model
+    expect(source).toContain('Post');
+    expect(source).toContain('Author');
+    // One import per (model, view) pair — 2 models × 4 view types = 8 imports
+    const importLines = source.match(/^import \{ \w+View \} from '\.\/views\//gm) ?? [];
+    expect(importLines.length).toBe(8);
+    // Navigation wiring
+    expect(source).toContain("select('Post', 'list')");
+    expect(source).toContain("select('Author', 'dashboard')");
+  });
+
+  it('handles an empty spec gracefully', async () => {
+    const source = await generateAppTsx({ spec: { models: {}, views: {} } });
+    assertValidTsx(source, 'App.tsx (empty spec)');
+    expect(source).toContain('No models in this spec.');
+    // Still renders a QueryClientProvider
+    expect(source).toContain('QueryClientProvider');
+  });
+
+  it('uses @tanstack/react-query, not @specverse/runtime', async () => {
+    const source = await generateAppTsx({
+      spec: { models: { Post: { name: 'Post', attributes: {} } } },
+    });
+    expect(source).not.toContain('@specverse/runtime');
+    expect(source).toContain('@tanstack/react-query');
+  });
+});
+
+describe('package-json-generator', () => {
+  it('omits @specverse/runtime from dependencies', async () => {
+    const json = await generatePackageJson({ spec: { name: 'test' } });
+    const pkg = JSON.parse(json);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    expect(allDeps['@specverse/runtime']).toBeUndefined();
+    expect(allDeps['@specverse/engines']).toBeUndefined();
+    expect(allDeps['@specverse/types']).toBeUndefined();
+  });
+
+  it('includes the deps the emitted views actually need', async () => {
+    const json = await generatePackageJson({ spec: { name: 'test' } });
+    const pkg = JSON.parse(json);
+    expect(pkg.dependencies).toMatchObject({
+      react: expect.any(String),
+      'react-dom': expect.any(String),
+      '@tanstack/react-query': expect.any(String),
+    });
+    expect(pkg.devDependencies).toMatchObject({
+      typescript: expect.any(String),
+      vite: expect.any(String),
+      tailwindcss: expect.any(String),
+    });
+  });
+
+  it('slugifies the app name', async () => {
+    const json = await generatePackageJson({
+      spec: { metadata: { name: 'My Fancy App!' } },
+    });
+    const pkg = JSON.parse(json);
+    expect(pkg.name).toBe('my-fancy-app');
+  });
+
+  it('falls back to a default name when none is provided', async () => {
+    const json = await generatePackageJson({ spec: {} });
+    const pkg = JSON.parse(json);
+    expect(pkg.name).toBe('specverse-starter-app');
+  });
+
+  it('parses as valid JSON with the expected shape', async () => {
+    const json = await generatePackageJson({ spec: { name: 'test' } });
+    const pkg = JSON.parse(json);
+    expect(pkg.type).toBe('module');
+    expect(pkg.scripts).toMatchObject({
+      dev: 'vite',
+      build: 'tsc && vite build',
+      preview: 'vite preview',
+    });
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/view-emitter.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import * as ts from 'typescript';
+import { emitView, type EmitContext, type ModelSpec, type ViewSpec } from '../view-emitter.js';
+
+/**
+ * Build a minimal context. The `renderBody` is a stub that returns a
+ * fixed Tailwind table — the point of these tests is the emitter
+ * orchestration + substitutions + JSX validity, not the body's content.
+ * Parity with the real Tailwind adapter is covered by Phase 3 (P3).
+ */
+function makeContext(overrides: Partial<EmitContext> = {}): EmitContext {
+  const defaultModel: ModelSpec = {
+    name: 'Post',
+    attributes: {
+      id: { type: 'UUID', required: true },
+      title: { type: 'String', required: true },
+      body: { type: 'Text', required: false },
+    },
+  };
+
+  const defaultView: ViewSpec = {
+    type: 'list',
+    model: 'Post',
+  };
+
+  return {
+    view: defaultView,
+    viewName: 'PostListView',
+    model: defaultModel,
+    modelSchemas: { Post: defaultModel },
+    // renderBody returns JSX-ready source that will be injected verbatim
+    // into {{BODY}}. NOT raw HTML — that's the composer's job.
+    renderBody: () =>
+      '<table className="w-full"><thead><tr><th className="px-4 py-2">Title</th></tr></thead>' +
+      '<tbody><tr><td className="px-4 py-2">Example</td></tr></tbody></table>',
+    ...overrides,
+  };
+}
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse as TSX:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('emitView — list', () => {
+  it('produces TSX that parses cleanly', () => {
+    const context = makeContext();
+    const source = emitView(context);
+    assertValidTsx(source, 'emitted list view');
+  });
+
+  it('substitutes model names into the skeleton', () => {
+    const source = emitView(makeContext());
+    expect(source).toContain('PostListView');                  // component name
+    expect(source).toContain('usePostsQuery');                 // generated hook name
+    expect(source).toContain('useDeletePostMutation');         // generated hook name
+    expect(source).toContain("Search posts…");                 // pluralized lowercase
+    expect(source).toContain('+ New Post');                    // action button label
+    expect(source).toContain('No posts yet.');                 // empty state
+  });
+
+  it('substitutes a non-trivial plural correctly', () => {
+    const m: ModelSpec = { name: 'Category', attributes: {} };
+    const source = emitView(makeContext({
+      model: m,
+      view: { type: 'list', model: 'Category' },
+      viewName: 'CategoryListView',
+      modelSchemas: { Category: m },
+    }));
+    expect(source).toContain('CategoryListView');
+    expect(source).toContain('useCategoriesQuery');     // "Category" → "Categories"
+    expect(source).toContain('Search categories…');
+  });
+
+  it('injects the rendered body at {{BODY}}', () => {
+    const source = emitView(makeContext({
+      renderBody: () => '<table className="my-table"><tbody><tr><td>Custom</td></tr></tbody></table>',
+    }));
+    expect(source).toContain('<table className="my-table">');
+    expect(source).toContain('Custom');
+    // The placeholder itself should be gone.
+    expect(source).not.toContain('{{BODY}}');
+    // All other placeholders should be gone too.
+    expect(source).not.toMatch(/\{\{[A-Z_]+\}\}/);
+  });
+
+  it('throws for an unknown view type', () => {
+    expect(() =>
+      emitView(makeContext({ view: { type: 'unknown-type-xyz' } }))
+    ).toThrow(/No skeleton registered/);
+  });
+});