@specverse/engines 4.1.30 → 4.2.1

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/);
+  });
+});

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

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as ts from 'typescript';
+import { generate, type ExpandedSpec } from '../views-generator.js';
+
+function makeSpec(): ExpandedSpec {
+  return {
+    models: {
+      Post: {
+        name: 'Post',
+        attributes: {
+          id: { type: 'UUID', required: true, auto: 'uuid4' },
+          title: { type: 'String', required: true },
+          body: { type: 'Text', required: false },
+        },
+      },
+      Author: {
+        name: 'Author',
+        attributes: {
+          id: { type: 'UUID', required: true, auto: 'uuid4' },
+          name: { type: 'String', required: true },
+        },
+      },
+    },
+    views: {},
+  };
+}
+
+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('views-generator.generate', () => {
+  it('emits 4 view files per model plus the helpers file', async () => {
+    const files = await generate({ spec: makeSpec() });
+    const paths = Object.keys(files);
+    expect(paths).toContain('src/views/PostListView.tsx');
+    expect(paths).toContain('src/views/PostDetailView.tsx');
+    expect(paths).toContain('src/views/PostFormView.tsx');
+    expect(paths).toContain('src/views/PostDashboardView.tsx');
+    expect(paths).toContain('src/views/AuthorListView.tsx');
+    expect(paths).toContain('src/views/AuthorDetailView.tsx');
+    expect(paths).toContain('src/views/AuthorFormView.tsx');
+    expect(paths).toContain('src/views/AuthorDashboardView.tsx');
+    expect(paths).toContain('src/lib/entity-display.ts');
+    // 2 models × 4 view types + 1 helper = 9 files.
+    expect(paths.length).toBe(9);
+  });
+
+  it('every emitted view file parses as valid TSX', async () => {
+    const files = await generate({ spec: makeSpec() });
+    for (const [path, source] of Object.entries(files)) {
+      if (path.endsWith('.tsx')) assertValidTsx(source, path);
+    }
+  });
+
+  it('uses a user-declared view spec in preference to a synthesized default', async () => {
+    const spec: ExpandedSpec = {
+      models: {
+        Post: {
+          name: 'Post',
+          attributes: {
+            id: { type: 'UUID', auto: 'uuid4' },
+            title: { type: 'String', required: true },
+          },
+        },
+      },
+      views: {
+        PostListView: {
+          type: 'list',
+          model: 'Post',
+          uiComponents: {
+            customTable: {
+              type: 'table',
+              properties: {
+                columns: ['SUPER CUSTOM COLUMN'],
+              },
+            },
+          },
+        },
+      },
+    };
+    const files = await generate({ spec });
+    const out = files['src/views/PostListView.tsx'];
+    // The user's custom column header is not directly visible because
+    // the current composer ignores user uiComponents (it infers
+    // columns from the model). But the view spec flows through — if
+    // we later teach the composer to honour uiComponents, this test
+    // anchors the contract.
+    expect(out).toBeDefined();
+    expect(out).toContain('export function PostListView');
+  });
+
+  it('warns on specialist view types and skips them', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const spec: ExpandedSpec = {
+        models: {
+          Post: { name: 'Post', attributes: { id: { auto: 'uuid4' }, title: {} } },
+        },
+        views: {
+          PostBoardView: { type: 'board', model: 'Post' },
+          PostTimelineView: { type: 'timeline', model: 'Post' },
+        },
+      };
+      const files = await generate({ spec });
+      expect(files['src/views/PostBoardView.tsx']).toBeUndefined();
+      expect(files['src/views/PostTimelineView.tsx']).toBeUndefined();
+      expect(warn).toHaveBeenCalled();
+      const warning = warn.mock.calls[0][0] as string;
+      expect(warning).toContain('Skipped');
+      expect(warning).toContain('board');
+      expect(warning).toContain('timeline');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('handles an empty models map gracefully', async () => {
+    const files = await generate({ spec: { models: {}, views: {} } });
+    // Only the helpers file is emitted; no view files.
+    expect(Object.keys(files)).toEqual(['src/lib/entity-display.ts']);
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/api-types-starter-generator.ts

@@ -0,0 +1,98 @@
+/**
+ * API types generator for ReactAppStarter
+ *
+ * Emits per-model TypeScript interfaces that the starter's view
+ * skeletons import (`import type { Task } from '../types/api'`). The
+ * shape mirrors the model's attributes as declared in the spec. No
+ * runtime-specific types (those live in ReactAppRuntime's api-types
+ * generator).
+ */
+
+export interface ApiTypesStarterContext {
+  spec: {
+    models?: Record<string, any>;
+  };
+  manifest?: unknown;
+}
+
+/**
+ * Map SpecVerse attribute types to TypeScript types.
+ *
+ * Strings vs unions: if the attribute has a `values` enum (e.g.
+ * status: String values=[draft,published]), emit a union type.
+ */
+function mapAttrType(attr: any): string {
+  const t = typeof attr === 'string'
+    ? attr.split(/\s+/)[0]
+    : attr?.type;
+  const values = attr?.values;
+  if (Array.isArray(values) && values.length > 0) {
+    return values.map((v: string) => JSON.stringify(v)).join(' | ');
+  }
+  switch ((t || '').toLowerCase()) {
+    case 'string':
+    case 'text':
+    case 'uuid':
+    case 'email':
+    case 'url':
+      return 'string';
+    case 'int':
+    case 'integer':
+    case 'float':
+    case 'number':
+    case 'decimal':
+      return 'number';
+    case 'boolean':
+    case 'bool':
+      return 'boolean';
+    case 'datetime':
+    case 'date':
+    case 'time':
+    case 'timestamp':
+      return 'string';
+    case 'json':
+      return 'Record<string, unknown>';
+    default:
+      return 'unknown';
+  }
+}
+
+function isRequired(attr: any): boolean {
+  if (typeof attr === 'string') return /\brequired\b/.test(attr);
+  return !!attr?.required;
+}
+
+export async function generate(context: ApiTypesStarterContext): Promise<string> {
+  const models = context.spec.models ?? {};
+  const modelNames = Object.keys(models);
+
+  const header = `/**
+ * API types (ReactAppStarter)
+ *
+ * Per-model interfaces generated from the spec's model definitions.
+ * Safe to edit — extend these when your UI needs more than the spec
+ * describes (e.g. optimistic fields, denormalized joins).
+ */
+`;
+
+  const interfaces = modelNames.map(name => {
+    const model = models[name] || {};
+    const attrs = model.attributes || {};
+    const attrKeys = Object.keys(attrs);
+
+    const fields = attrKeys.map(attrName => {
+      const attr = attrs[attrName];
+      const tsType = mapAttrType(attr);
+      const optional = isRequired(attr) ? '' : '?';
+      return `  ${attrName}${optional}: ${tsType};`;
+    }).join('\n');
+
+    return `export interface ${name} {
+${fields || '  [key: string]: unknown;'}
+}`;
+  }).join('\n\n');
+
+  return header + '\n' + interfaces + '\n';
+}
+
+export default generate;

package/libs/instance-factories/applications/templates/react-starter/app-tsx-generator.ts

@@ -0,0 +1,141 @@
+/**
+ * App.tsx generator for ReactAppStarter
+ *
+ * Generates a simple App shell that routes between the emitted view
+ * components. Not using react-router — the starter output is
+ * deliberately low-magic. Users can add routing when they need
+ * URL-level view selection; for now, internal state drives it.
+ *
+ * Output:
+ *  - sidebar nav listing every (model × view-type)
+ *  - a main area rendering the selected view
+ *  - QueryClientProvider at the root
+ */
+
+import type { ExpandedSpec } from './views-generator.js';
+
+export interface AppGeneratorContext {
+  spec: ExpandedSpec;
+  manifest?: unknown;
+}
+
+export async function generate(context: AppGeneratorContext): Promise<string> {
+  const models = Object.keys(context.spec.models ?? {});
+  const imports = buildImports(models);
+  const navEntries = buildNavEntries(models);
+  const viewSwitch = buildViewSwitch(models);
+
+  return `/**
+ * App.tsx — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing. This is a minimal shell: a sidebar listing every
+ * (model, view-type) plus a main area that renders the selection.
+ * Swap in react-router or your preferred routing library when the
+ * app needs URL-driven navigation.
+ */
+import { useState } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+${imports}
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 5 * 60 * 1000, retry: 1 },
+  },
+});
+
+type Selection = {
+  model: string;
+  view: 'list' | 'detail' | 'form' | 'dashboard';
+  entityId?: string | number;
+};
+
+function Inner() {
+  const [selection, setSelection] = useState<Selection>(${models.length > 0 ? `{ model: '${models[0]}', view: 'list' }` : `{ model: '', view: 'list' }`});
+
+  const select = (model: string, view: Selection['view']) =>
+    setSelection({ model, view });
+
+  return (
+    <div className="min-h-screen flex bg-gray-50 dark:bg-gray-950">
+      <aside className="w-64 shrink-0 border-r border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900">
+        <div className="p-4 border-b border-gray-200 dark:border-gray-800">
+          <h1 className="text-lg font-semibold text-gray-900 dark:text-gray-100">App</h1>
+        </div>
+        <nav className="p-2 space-y-4">
+${navEntries}
+        </nav>
+      </aside>
+
+      <main className="flex-1 overflow-auto">
+${viewSwitch}
+      </main>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Inner />
+    </QueryClientProvider>
+  );
+}
+`;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────
+
+function buildImports(models: string[]): string {
+  return models.flatMap(m => [
+    `import { ${m}ListView } from './views/${m}ListView';`,
+    `import { ${m}DetailView } from './views/${m}DetailView';`,
+    `import { ${m}FormView } from './views/${m}FormView';`,
+    `import { ${m}DashboardView } from './views/${m}DashboardView';`,
+  ]).join('\n');
+}
+
+function buildNavEntries(models: string[]): string {
+  if (models.length === 0) {
+    return '          <p className="text-sm text-gray-400 px-2">No models in this spec.</p>';
+  }
+  return models.map(m => `          <div>
+            <div className="px-2 pb-1 text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400">
+              ${m}
+            </div>
+            <button type="button" onClick={() => select('${m}', 'list')} className="${navButtonCls('list')}">List</button>
+            <button type="button" onClick={() => select('${m}', 'dashboard')} className="${navButtonCls('dashboard')}">Dashboard</button>
+            <button type="button" onClick={() => select('${m}', 'form')} className="${navButtonCls('form')}">Form</button>
+          </div>`).join('\n');
+}
+
+function navButtonCls(_view: string): string {
+  return (
+    'block w-full text-left rounded px-2 py-1 text-sm ' +
+    'text-gray-700 hover:bg-gray-100 ' +
+    'dark:text-gray-300 dark:hover:bg-gray-800'
+  );
+}
+
+function buildViewSwitch(models: string[]): string {
+  if (models.length === 0) {
+    return '        <p className="p-6 text-sm text-gray-400">No models — add one to your .specly file and run <code>spv realize</code>.</p>';
+  }
+  const branches = models.flatMap(m => [
+    `        {selection.model === '${m}' && selection.view === 'list' && (
+          <${m}ListView onSelect={item => setSelection({ model: '${m}', view: 'detail', entityId: (item as any).id })} onCreate={() => setSelection({ model: '${m}', view: 'form' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'detail' && selection.entityId !== undefined && (
+          <${m}DetailView entityId={selection.entityId} onEdit={item => setSelection({ model: '${m}', view: 'form', entityId: (item as any).id })} onBack={() => setSelection({ model: '${m}', view: 'list' })} onDeleted={() => setSelection({ model: '${m}', view: 'list' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'form' && (
+          <${m}FormView mode={selection.entityId ? 'update' : 'create'} entityId={selection.entityId} onSuccess={() => setSelection({ model: '${m}', view: 'list' })} onCancel={() => setSelection({ model: '${m}', view: 'list' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'dashboard' && (
+          <${m}DashboardView onSelect={item => setSelection({ model: '${m}', view: 'detail', entityId: (item as any).id })} />
+        )}`,
+  ]);
+  return branches.join('\n');
+}

package/libs/instance-factories/applications/templates/react-starter/belongs-to.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared helper: extract belongsTo relationships from a model.
+ *
+ * Used by both the form-body composer (emits <select> dropdowns) and
+ * view-emitter (generates the import + hook wiring for those
+ * dropdowns). Keeping this in one place means form JSX and skeleton
+ * substitutions can't drift.
+ *
+ * Supports both shapes a parsed spec can use:
+ *   - Convention string: "belongsTo User cascade"
+ *   - Structured object: { type: "belongsTo", target: "User" }
+ */
+
+import type { ModelSpec } from './view-emitter.js';
+
+export interface BelongsToRel {
+  /** Relationship name — e.g. "owner", "assignee". */
+  name: string;
+  /** Target model name — e.g. "User". */
+  target: string;
+}
+
+export function extractBelongsToTargets(model: ModelSpec): BelongsToRel[] {
+  const rels = (model.relationships ?? {}) as Record<string, unknown>;
+  const out: BelongsToRel[] = [];
+
+  for (const [name, rawDef] of Object.entries(rels)) {
+    const parsed = parseBelongsTo(rawDef);
+    if (parsed) out.push({ name, target: parsed });
+  }
+  return out;
+}
+
+function parseBelongsTo(def: unknown): string | null {
+  // Convention string: "belongsTo User cascade" / "belongsTo User"
+  if (typeof def === 'string') {
+    const parts = def.trim().split(/\s+/);
+    if (parts[0] === 'belongsTo' && parts[1]) return parts[1];
+    return null;
+  }
+  // Structured: { type: "belongsTo", target: "User" } — support all
+  // of the field names the parsed spec can use ("target", "to",
+  // "model", "targetModel"). The normalizer upstream is inconsistent
+  // and normalizing it there is out of scope for this composer.
+  if (def && typeof def === 'object') {
+    const o = def as { type?: string; target?: string; to?: string; model?: string; targetModel?: string };
+    if (o.type === 'belongsTo') {
+      return o.target || o.to || o.model || o.targetModel || null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Minimal English pluralizer, matching view-emitter's and
+ * use-api-hooks-starter-generator's convention. Centralizing it here
+ * keeps the generated hook names (useUsersQuery) aligned with what
+ * the emitter imports.
+ */
+export function pluralize(s: string): string {
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + 'ies';
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + 'es';
+  return s + 's';
+}
+
+/**
+ * Build a map from FK column name → belongsTo relationship. Used by
+ * every view composer (list, detail, dashboard, form) to detect when
+ * an attribute is really a foreign key and should render as a resolved
+ * display name, not a raw UUID.
+ *
+ * Convention: a belongsTo relationship named `owner` pointing at `User`
+ * implies a column `ownerId: UUID` on the owning model. This function
+ * materializes that convention.
+ */
+export function buildFKMap(model: ModelSpec): Map<string, BelongsToRel> {
+  const map = new Map<string, BelongsToRel>();
+  for (const rel of extractBelongsToTargets(model)) {
+    map.set(`${rel.name}Id`, rel);
+  }
+  return map;
+}