@svgrid/enterprise 1.2.0 → 2.0.1

package/src/studio/introspect.ts

@@ -0,0 +1,310 @@
+/**
+ * Introspection - turn a data source into an `EntitySchema`. Entry points:
+ *
+ *   - `introspectJson(name, rows)` infers fields + types from sample JSON rows.
+ *   - `introspectDrizzle(source, table?)` parses one Drizzle table (the string
+ *     contents of a `schema.ts`) into an `EntitySchema`, relations and enums
+ *     included.
+ *   - `introspectDrizzleAll(source)` parses **every** table in the file into a
+ *     linked set of schemas (foreign keys become relation fields, so the whole
+ *     app scaffolds with working lookups).
+ *
+ * All are pure and best-effort: the Studio generator (and the AI host) treats
+ * the result as a draft the user can refine in `SvSchemaDesigner` before
+ * scaffolding code. Nothing imports Drizzle - the reader is a text parse, so
+ * there's no dependency and no code execution.
+ */
+import { linkRelationLabels, type EntityField, type EntityFieldType, type EntitySchema } from '../schema.js'
+import { buildEntitySchema, type IntrospectedColumn } from '../sources/schema-from-columns.js'
+import { refineFields } from '../sources/field-inference.js'
+
+/** Infer an entity field type from a runtime JSON value. */
+export function inferType(value: unknown): EntityFieldType {
+  if (typeof value === 'boolean') return 'boolean'
+  if (typeof value === 'number') return 'number'
+  if (value !== null && typeof value === 'object') return 'json'
+  if (typeof value === 'string') {
+    if (/^\d{4}-\d{2}-\d{2}T/.test(value)) return 'datetime'
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return 'dateString'
+    return 'text'
+  }
+  return 'text'
+}
+
+/** Build a schema from sample rows: union of keys, type from the first non-null value. */
+export function introspectJson(
+  name: string,
+  rows: ReadonlyArray<Record<string, unknown>>,
+): EntitySchema {
+  const keys: string[] = []
+  const seen = new Set<string>()
+  for (const row of rows) {
+    for (const k of Object.keys(row)) {
+      if (!seen.has(k)) {
+        seen.add(k)
+        keys.push(k)
+      }
+    }
+  }
+
+  const fields: EntityField[] = keys.map((k) => {
+    let type: EntityFieldType = 'text'
+    for (const row of rows) {
+      const v = row[k]
+      if (v != null) {
+        type = inferType(v)
+        break
+      }
+    }
+    const field: EntityField = { field: k, type }
+    if (k === 'id') {
+      field.primaryKey = true
+      field.readonly = true
+    }
+    return field
+  })
+
+  return refineFields({ name, fields })
+}
+
+/** Drizzle column builder -> entity field type. */
+const DRIZZLE_TYPE_MAP: Record<string, EntityFieldType> = {
+  serial: 'number',
+  bigserial: 'number',
+  smallserial: 'number',
+  integer: 'number',
+  int: 'number',
+  tinyint: 'number',
+  smallint: 'number',
+  bigint: 'number',
+  numeric: 'number',
+  decimal: 'number',
+  real: 'number',
+  double: 'number',
+  doublePrecision: 'number',
+  float: 'number',
+  boolean: 'boolean',
+  text: 'text',
+  varchar: 'text',
+  char: 'text',
+  uuid: 'text',
+  timestamp: 'datetime',
+  datetime: 'datetime',
+  date: 'dateString',
+  time: 'text',
+  json: 'json',
+  jsonb: 'json',
+}
+
+/** A Drizzle table as found in source: variable name, SQL name, columns body, and extra-config text. */
+type DrizzleTable = { varName: string; name: string; body: string; extras: string }
+
+/** Whole-file context needed to resolve a column: table vars and enum values. */
+type DrizzleContext = {
+  /** Table variable (`export const users = ...`) -> SQL table name. */
+  varToTable: Map<string, string>
+  /** Enum variable (`pgEnum('role', [...])`) -> allowed values. */
+  enums: Map<string, string[]>
+}
+
+/** Read string literals out of a `['a', 'b']`-style array fragment. */
+function stringLiterals(fragment: string): string[] {
+  const out: string[] = []
+  const re = /['"]([^'"]+)['"]/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(fragment)) !== null) out.push(m[1]!)
+  return out
+}
+
+/** Find the balanced `{ ... }` body starting at (or after) `from`. Returns body + end index. */
+function balancedObject(source: string, from: number): { body: string; end: number } {
+  const open = source.indexOf('{', from)
+  if (open === -1) return { body: '', end: from }
+  let depth = 0
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i]
+    if (ch === '{') depth++
+    else if (ch === '}' && --depth === 0) return { body: source.slice(open + 1, i), end: i }
+  }
+  return { body: '', end: source.length }
+}
+
+/** Split an object body at top-level commas, ignoring commas nested in (), [], {}, or strings. */
+function splitTopLevel(body: string): string[] {
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  let str: string | null = null
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i]
+    if (str) {
+      if (ch === str && body[i - 1] !== '\\') str = null
+      continue
+    }
+    if (ch === "'" || ch === '"' || ch === '`') str = ch
+    else if (ch === '(' || ch === '[' || ch === '{') depth++
+    else if (ch === ')' || ch === ']' || ch === '}') depth--
+    else if (ch === ',' && depth === 0) {
+      parts.push(body.slice(start, i))
+      start = i + 1
+    }
+  }
+  const last = body.slice(start)
+  if (last.trim()) parts.push(last)
+  return parts
+}
+
+/** Locate every `const <var> = xxxTable('name', { ... })` in the source. */
+function findTables(source: string): DrizzleTable[] {
+  const tables: DrizzleTable[] = []
+  const re = /const\s+(\w+)\s*=\s*(\w*[Tt]able)\(\s*['"]([^'"]+)['"]\s*,/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(source)) !== null) {
+    const { body, end } = balancedObject(source, m.index + m[0].length)
+    if (body) {
+      // Capture the table's second argument (indexes, composite primary key)
+      // by scanning to the matching close paren of the `xxxTable(` call.
+      let depth = 1
+      let str: string | null = null
+      let i = end + 1
+      for (; i < source.length; i++) {
+        const ch = source[i]
+        if (str) {
+          if (ch === str && source[i - 1] !== '\\') str = null
+          continue
+        }
+        if (ch === "'" || ch === '"' || ch === '`') str = ch
+        else if (ch === '(') depth++
+        else if (ch === ')' && --depth === 0) break
+      }
+      tables.push({ varName: m[1]!, name: m[3]!, body, extras: source.slice(end + 1, i) })
+      re.lastIndex = i
+    }
+  }
+  return tables
+}
+
+/** Field names of a Drizzle composite key (`primaryKey({ columns: [t.a, t.b] })`), else empty. */
+function drizzleComposite(extras: string): string[] {
+  const m = extras.match(/primaryKey\(([\s\S]*?)\)/)
+  if (!m) return []
+  return [...m[1]!.matchAll(/\.(\w+)/g)].map((x) => x[1]!)
+}
+
+/** Build the whole-file context (table vars + enum declarations) once. */
+function scanContext(source: string, tables: DrizzleTable[]): DrizzleContext {
+  const varToTable = new Map(tables.map((t) => [t.varName, t.name]))
+  const enums = new Map<string, string[]>()
+  // const roleEnum = pgEnum('role', ['admin', 'user'])   (also mysqlEnum / singlestoreEnum)
+  const re = /const\s+(\w+)\s*=\s*(?:pg|mysql|singlestore)Enum\(\s*['"][^'"]+['"]\s*,\s*\[([^\]]*)\]/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(source)) !== null) enums.set(m[1]!, stringLiterals(m[2]!))
+  return { varToTable, enums }
+}
+
+/** Parse one column entry (`key: builder(args)<modifiers>`) into a neutral column. */
+function parseColumn(entry: string, ctx: DrizzleContext): IntrospectedColumn | null {
+  const head = entry.match(/^\s*["']?(\w+)["']?\s*:\s*(\w+)\s*\(/)
+  if (!head) return null
+  const name = head[1]!
+  const builder = head[2]!
+  // Balanced args of the builder call, then the trailing modifier chain.
+  const argStart = head.index! + head[0].length - 1
+  let depth = 0
+  let argEnd = argStart
+  for (let i = argStart; i < entry.length; i++) {
+    const ch = entry[i]
+    if (ch === '(') depth++
+    else if (ch === ')' && --depth === 0) {
+      argEnd = i
+      break
+    }
+  }
+  const args = entry.slice(argStart + 1, argEnd)
+  const modifiers = entry.slice(argEnd + 1)
+
+  const col: IntrospectedColumn = { name }
+
+  // Capture the DB column name (the builder's first string arg). When it differs
+  // from the property key, record it so SQL adapters use the real column.
+  const dbColumn = stringLiterals(args)[0]
+  if (dbColumn && dbColumn !== name) col.dbColumn = dbColumn
+
+  // Enum: a `pgEnum` builder var, an inline `mysqlEnum('col', ['a','b'])`, or a
+  // `{ enum: ['a','b'] }` option on a text/varchar column.
+  const inlineEnum = args.match(/enum\s*:\s*\[([^\]]*)\]/)
+  if (ctx.enums.has(builder)) col.enumValues = ctx.enums.get(builder)
+  else if (inlineEnum) col.enumValues = stringLiterals(inlineEnum[1]!)
+  else if (/enum$/i.test(builder)) {
+    const arr = args.match(/\[([^\]]*)\]/)
+    if (arr) col.enumValues = stringLiterals(arr[1]!)
+  }
+  if (!col.enumValues) col.type = DRIZZLE_TYPE_MAP[builder] ?? 'text'
+
+  if (/\.primaryKey\s*\(/.test(modifiers)) col.primaryKey = true
+  if (/\.notNull\s*\(/.test(modifiers)) col.required = true
+
+  // Foreign key: `.references(() => otherTable.col)` -> a relation field.
+  const ref = modifiers.match(/\.references\(\s*\(\)\s*=>\s*(\w+)\.(\w+)/)
+  if (ref) {
+    col.references = { table: ctx.varToTable.get(ref[1]!) ?? ref[1]!, column: ref[2]! }
+  }
+  return col
+}
+
+/** Assemble the neutral column list for one table. */
+function columnsFor(table: DrizzleTable, ctx: DrizzleContext): IntrospectedColumn[] {
+  const columns = splitTopLevel(table.body)
+    .map((entry) => parseColumn(entry, ctx))
+    .filter((c): c is IntrospectedColumn => c !== null)
+
+  // Composite key (`primaryKey({ columns: [t.a, t.b] })` in the table's 2nd arg):
+  // flag the members. buildEntitySchema keys off the first (a join table's screen
+  // targets its first key column).
+  const composite = drizzleComposite(table.extras)
+  if (composite.length && !columns.some((c) => c.primaryKey)) {
+    for (const c of columns) if (composite.includes(c.name)) c.primaryKey = true
+  }
+  return columns
+}
+
+/**
+ * Parse one Drizzle table into an `EntitySchema`. Relations (`.references`) and
+ * enums (`pgEnum` / inline) are resolved against the whole file. Best-effort and
+ * text based: exotic column types fall back to `text`, to be corrected in the
+ * designer.
+ */
+export function introspectDrizzle(source: string, table?: string): EntitySchema {
+  const tables = findTables(source)
+  if (tables.length === 0) {
+    throw new Error('introspectDrizzle: no `xxxTable("name", { ... })` definition found in source')
+  }
+  const picked = table ? tables.find((t) => t.name === table || t.varName === table) : tables[0]
+  if (!picked) throw new Error(`introspectDrizzle: table "${table}" not found in source`)
+
+  const ctx = scanContext(source, tables)
+  const columns = columnsFor(picked, ctx)
+  if (columns.length === 0) {
+    throw new Error(`introspectDrizzle: parsed table "${picked.name}" but found no fields`)
+  }
+  return buildEntitySchema(picked.name, columns)
+}
+
+/**
+ * Parse **every** table in a Drizzle schema file into a linked set of schemas.
+ * Foreign keys become relation fields and `linkRelationLabels` resolves each
+ * lookup's display field from the actual related table - so the whole app
+ * scaffolds with working lookups.
+ */
+export function introspectDrizzleAll(source: string): EntitySchema[] {
+  const tables = findTables(source)
+  if (tables.length === 0) {
+    throw new Error('introspectDrizzle: no `xxxTable("name", { ... })` definition found in source')
+  }
+  const ctx = scanContext(source, tables)
+  const schemas = tables
+    .map((t) => ({ t, columns: columnsFor(t, ctx) }))
+    .filter(({ columns }) => columns.length > 0)
+    .map(({ t, columns }) => buildEntitySchema(t.name, columns))
+  return linkRelationLabels(schemas)
+}

package/src/studio/pipeline.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { introspectDrizzle } from './introspect'
+import { scaffold } from './scaffold'
+
+/**
+ * The end-to-end generator flow the MCP tools expose: a Drizzle schema file
+ * becomes an EntitySchema, which becomes runnable SvelteKit files. This proves
+ * introspect output feeds scaffold cleanly.
+ */
+describe('introspect -> scaffold pipeline', () => {
+  const drizzle = `
+    import { pgTable, serial, text, integer, boolean } from 'drizzle-orm/pg-core'
+    export const products = pgTable('products', {
+      id: serial('id').primaryKey(),
+      title: text('title').notNull(),
+      price: integer('price'),
+      inStock: boolean('in_stock').default(true),
+    })
+  `
+
+  it('drizzle source -> schema -> scaffolded files', () => {
+    const schema = introspectDrizzle(drizzle)
+    const { files } = scaffold(schema)
+    const byPath = Object.fromEntries(files.map((f) => [f.path, f]))
+
+    // schema module reflects the parsed table + fields
+    const schemaFile = byPath['src/lib/products.schema.ts']!.contents
+    expect(schemaFile).toContain('export const productsSchema: EntitySchema<ProductsRow>')
+    expect(schemaFile).toContain('title: string')
+    expect(schemaFile).toContain('price: number')
+    expect(schemaFile).toContain('inStock: boolean')
+    expect(schemaFile).toContain('field: "id", type: "number", primaryKey: true, readonly: true')
+
+    // page + server route are wired to the products endpoint
+    expect(byPath['src/routes/products/+page.svelte']!.contents).toContain(
+      "createKitDataSource<ProductsRow>({ endpoint: '/api/products' })",
+    )
+    expect(byPath['src/routes/api/products/+server.ts']!.contents).toContain(
+      'createKitHandlers({ schema: productsSchema, source })',
+    )
+  })
+})

package/src/studio/project-robust.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Robustness suite: the designer must survive extensive, adversarial editing
+ * without throwing or corrupting the model. Two guarantees:
+ *
+ *  1. `validateProject` can legitimately return DUPLICATE messages (two
+ *     unconfigured master-detail blocks on one screen produce identical warnings).
+ *     This is the root cause of the historical `each_key_duplicate` crash - the
+ *     designer must key those lists by index, never by message. We pin the
+ *     behaviour here so a future "dedupe by message" refactor can't silently
+ *     reintroduce the crash surface.
+ *  2. A fuzz driver applies thousands of random ops (including invalid ids /
+ *     out-of-range indices) and asserts the ops never throw and never break the
+ *     model's invariants (unique block ids, unique screen ids, round-trippable).
+ */
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema } from '../schema'
+import {
+  addBlock,
+  addBlockAt,
+  addScreen,
+  addScreenFromTemplate,
+  createProject,
+  isProjectValid,
+  moveBlock,
+  parseProject,
+  removeBlock,
+  removeEntity,
+  removeScreen,
+  reorderBlock,
+  serializeProject,
+  updateBlock,
+  updateScreen,
+  validateProject,
+  type BlockKind,
+  type StudioProject,
+} from './project'
+
+const customers: EntitySchema = {
+  name: 'customers', label: 'Customer', idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true },
+    { field: 'name', type: 'text' },
+    { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }] },
+    { field: 'mrr', type: 'number' },
+  ],
+}
+const orders: EntitySchema = {
+  name: 'orders', label: 'Order', idField: 'id',
+  fields: [{ field: 'id', type: 'text', primaryKey: true }, { field: 'total', type: 'number' }],
+}
+
+describe('validation message duplication (the each_key_duplicate root cause)', () => {
+  it('two unconfigured master-detail blocks yield IDENTICAL warning messages', () => {
+    const sid = 'customers'
+    let p = createProject([customers])
+    p = addBlock(p, sid, 'master-detail')
+    p = addBlock(p, sid, 'master-detail')
+    const warnings = validateProject(p).filter((i) => /Master\/detail/.test(i.message))
+    expect(warnings).toHaveLength(2)
+    expect(warnings[0]!.message).toBe(warnings[1]!.message) // duplicate keys IF keyed by message
+    // The designer must therefore key its issue list by index; this is a contract.
+  })
+
+  it('never throws while validating a project full of duplicate-warning blocks', () => {
+    let p = createProject([customers])
+    for (let i = 0; i < 12; i++) p = addBlock(p, 'customers', 'master-detail')
+    expect(() => validateProject(p)).not.toThrow()
+    expect(validateProject(p).filter((i) => /Master\/detail/.test(i.message))).toHaveLength(12)
+  })
+})
+
+describe('ops are total: invalid targets are no-ops, not throws', () => {
+  const p = createProject([customers, orders])
+  const sid = p.screens[0]!.id
+  const bid = p.screens[0]!.blocks[0]!.id
+
+  it('tolerates unknown screen / block ids', () => {
+    expect(() => addBlock(p, 'nope', 'grid')).not.toThrow()
+    expect(removeBlock(p, sid, 'ghost')).toEqual(p)
+    expect(removeBlock(p, 'ghost', bid)).toEqual(p)
+    expect(moveBlock(p, sid, 'ghost', 1)).toEqual(p)
+    expect(reorderBlock(p, sid, 'ghost', 0)).toEqual(p)
+    expect(updateBlock(p, sid, 'ghost', { span: 2 })).toEqual(p)
+    expect(updateScreen(p, 'ghost', { title: 'x' })).toEqual(p)
+    expect(removeScreen(p, 'ghost')).toEqual(p)
+  })
+
+  it('clamps out-of-range indices instead of tearing the array', () => {
+    expect(addBlockAt(p, sid, 'kpi', -5).screens[0]!.blocks[0]!.config.kind).toBe('kpi')
+    expect(addBlockAt(p, sid, 'kpi', 999).screens[0]!.blocks.at(-1)!.config.kind).toBe('kpi')
+    expect(reorderBlock(p, sid, bid, -10).screens[0]!.blocks[0]!.id).toBe(bid)
+    expect(reorderBlock(p, sid, bid, 999).screens[0]!.blocks.at(-1)!.id).toBe(bid)
+    expect(moveBlock(p, sid, bid, -1)).toEqual(p) // already first
+  })
+
+  it('removing an entity drops its screens and never orphans a screen without validation catching it', () => {
+    const gone = removeEntity(createProject([customers, orders]), 'orders')
+    expect(gone.screens.every((s) => s.entity !== 'orders')).toBe(true)
+    expect(validateProject(gone).some((i) => /missing entity/.test(i.message))).toBe(false)
+  })
+})
+
+// A tiny seeded PRNG so a failing fuzz run is reproducible.
+function lcg(seed: number): () => number {
+  let s = seed >>> 0
+  return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 0xffffffff)
+}
+
+function invariants(p: StudioProject): void {
+  // Screen ids unique.
+  const sids = p.screens.map((s) => s.id)
+  expect(new Set(sids).size).toBe(sids.length)
+  for (const s of p.screens) {
+    // Block ids unique within a screen (the crash-adjacent invariant).
+    const bids = s.blocks.map((b) => b.id)
+    expect(new Set(bids).size).toBe(bids.length)
+    for (const b of s.blocks) expect([1, 2, 3]).toContain(b.span)
+  }
+  // Always serializable + round-trippable.
+  expect(() => parseProject(serializeProject(p))).not.toThrow()
+}
+
+describe('fuzz: thousands of random ops never throw and preserve invariants', () => {
+  const KINDS: BlockKind[] = ['grid', 'form', 'chart', 'dashboard', 'kpi', 'master-detail', 'lookup']
+
+  it.each([1, 7, 42, 1337, 99999])('seed %i', (seed) => {
+    const rnd = lcg(seed)
+    const pick = <T>(xs: readonly T[]): T => xs[Math.floor(rnd() * xs.length)]!
+    let p = createProject([customers, orders], { title: 'Fuzz' })
+
+    for (let step = 0; step < 400; step++) {
+      const screen = p.screens.length ? pick(p.screens) : null
+      // Occasionally target a bogus id to exercise the no-op paths.
+      const sid = !screen || rnd() < 0.1 ? 'ghost-screen' : screen.id
+      const block = screen && screen.blocks.length ? pick(screen.blocks) : null
+      const bid = !block || rnd() < 0.1 ? 'ghost-block' : block.id
+      const op = Math.floor(rnd() * 10)
+      expect(() => {
+        switch (op) {
+          case 0: p = addBlock(p, sid, pick(KINDS)); break
+          case 1: p = addBlockAt(p, sid, pick(KINDS), Math.floor((rnd() - 0.2) * 12)); break
+          case 2: p = removeBlock(p, sid, bid); break
+          case 3: p = moveBlock(p, sid, bid, rnd() < 0.5 ? -1 : 1); break
+          case 4: p = reorderBlock(p, sid, bid, Math.floor((rnd() - 0.2) * 12)); break
+          case 5: p = updateBlock(p, sid, bid, { span: pick([1, 2, 3] as const) }); break
+          case 6: p = addScreen(p, pick(['customers', 'orders', 'ghost'])); break
+          case 7: p = removeScreen(p, sid); break
+          case 8: p = addScreenFromTemplate(p, pick(['customers', 'orders']), pick(['crud', 'dashboard', 'master-detail'] as const)); break
+          case 9: p = updateScreen(p, sid, { title: `T${step}` }); break
+        }
+      }).not.toThrow()
+      expect(() => validateProject(p)).not.toThrow()
+      expect(typeof isProjectValid(p)).toBe('boolean')
+      invariants(p)
+    }
+  })
+})