@ismaelsoilet/synapsejs 1.1.0

package/src/compiler/contract.ts

@@ -0,0 +1,260 @@
+/**
+ * SynapseJS - Machine Contract
+ *
+ * The framework describes itself, in one call, in the shape an agent consumes.
+ * Everything an agent must know to author a slice without guessing lives here:
+ * export names and suffixes the runtime detects, file locations, the Result and
+ * HTTP semantics, session rules, addressing, and the gates it can run.
+ *
+ * This is not documentation for humans — it is the contract the runtime actually
+ * enforces. Tests assert that the suffix lists below are the very constants the
+ * discovery and the splitter use, so the description cannot drift from behavior.
+ */
+
+import {
+  ACTION_SUFFIX,
+  COMPONENT_SUFFIXES,
+  LOADER_SUFFIX,
+  SLICE_DDL_EXPORT,
+  SLICE_ORACLE_EXPORT
+} from '../runtime/discovery-rules';
+import { SLICE_EXTENSION } from './slice-discovery';
+import { SLICE_TEMPLATES } from './slice-templates';
+
+export interface SliceContractExport {
+  name: string;
+  required: boolean;
+  kind: 'schema' | 'ddl' | 'action' | 'ui' | 'loader' | 'oracle';
+  signature: string;
+  notes: string;
+}
+
+export interface MachineContract {
+  framework: string;
+  slice: {
+    location: string;
+    extension: string;
+    namingRule: string;
+    oneFeaturePerFile: string;
+    exports: SliceContractExport[];
+    example: string;
+  };
+  results: {
+    shape: string;
+    errorsAreValues: string;
+    httpStatus: Record<string, string>;
+  };
+  sessions: {
+    headers: string[];
+    signed: string;
+    anonymous: string;
+    login: string;
+  };
+  addressing: {
+    page: string;
+    rpc: string;
+    upload: string;
+    ambiguity: string;
+  };
+  serverRendering: {
+    props: string;
+    hydration: string;
+    isolation: string;
+  };
+  shared: {
+    location: string;
+    rule: string;
+    atomicity: string;
+  };
+  templates: {
+    command: string;
+    available: string[];
+    notes: string;
+  };
+  gates: Array<{ command: string; proves: string }>;
+}
+
+export function machineContract(): MachineContract {
+  return {
+    framework: 'synapsejs',
+    slice: {
+      location: 'src/slices/<domain>/<name>.slice.tsx',
+      extension: SLICE_EXTENSION,
+      namingRule: '<name> is kebab-case; it becomes <Name> in PascalCase for types and components',
+      oneFeaturePerFile:
+        'A feature is one file. Do not split a slice across modules, and do not import one slice from another.',
+      exports: [
+        {
+          name: '<Name>InputSchema',
+          required: true,
+          kind: 'schema',
+          signature: 'Type.Object({...}) validated with Value.Check',
+          notes: 'Any export ending in "Schema" is treated as the input contract.'
+        },
+        {
+          name: SLICE_DDL_EXPORT,
+          required: false,
+          kind: 'ddl',
+          signature: 'string (template literal with SQL statements)',
+          notes:
+            'Each statement runs once and is recorded individually: an ALTER TABLE applies exactly once. Omit it when the table belongs to another slice. Use portable SQL (TIMESTAMP, not DATETIME).'
+        },
+        {
+          name: `<name>${ACTION_SUFFIX}`,
+          required: true,
+          kind: 'action',
+          signature: `(payload: unknown, db?: DatabaseClient, session?: SessionContext) => Promise<Result<T, E>>`,
+          notes:
+            'db is optional so the same call site is valid on both sides: the server passes the connection, the browser gets an RPC stub. Authorize with requireAuth(session, ["role"]) and return Err(auth.error).'
+        },
+        {
+          name: `<Name>${COMPONENT_SUFFIXES[0]}`,
+          required: false,
+          kind: 'ui',
+          signature: 'React component receiving the query string plus whatever the loader returned',
+          notes: `Detected suffixes: ${COMPONENT_SUFFIXES.join(', ')}. The runtime passes onSubmitAction: the real action on the server, the RPC call in the browser.`
+        },
+        {
+          name: `<Name>${LOADER_SUFFIX}`,
+          required: false,
+          kind: 'loader',
+          signature: '(context: { url, params, db, session }) => Promise<Record<string, unknown>>',
+          notes:
+            'Runs on the server on every render. Its result is merged with the query string and passed to the component, then serialized for hydration. A loader that throws is rendered in the page.'
+        },
+        {
+          name: SLICE_ORACLE_EXPORT,
+          required: true,
+          kind: 'oracle',
+          signature: '{ description?: string, cases: Array<{ name: string, run: () => unknown | Promise<unknown> }> }',
+          notes:
+            'Assert domain behavior, not the validation library. Executed by `synapse test` under bun:test; dropped from both runtime bundles by the splitter. When a generator produces floats, pass noNaN: true and noDefaultInfinity: true to fc.double: a NaN that the schema rejects makes a property return false, which is a flake rather than a finding.'
+        }
+      ],
+      example: [
+        "import { Type, Static } from '@sinclair/typebox';",
+        "import { Value } from '@sinclair/typebox/value';",
+        "import { Ok, Err, type DatabaseClient, type Result, type SessionContext, createSession, requireAuth, MockDatabaseClient } from 'synapsejs';",
+        '',
+        'export const ThingInputSchema = Type.Object({ name: Type.String({ minLength: 2 }) });',
+        'export type ThingInput = Static<typeof ThingInputSchema>;',
+        '',
+        'export const sliceSchema = `',
+        '  CREATE TABLE IF NOT EXISTS things (id TEXT PRIMARY KEY, name TEXT NOT NULL);',
+        '`;',
+        '',
+        "export type ThingOutput = Result<{ id: string }, 'INVALID_SCHEMA' | 'NO_DATABASE' | 'UNAUTHORIZED'>;",
+        '',
+        'export async function createThingAction(payload: unknown, db?: DatabaseClient, session?: SessionContext): Promise<ThingOutput> {',
+        "  const auth = requireAuth(session, ['writer']);",
+        '  if (!auth.ok) return Err(auth.error);',
+        "  if (!db) return Err('NO_DATABASE');",
+        "  if (!Value.Check(ThingInputSchema, payload)) return Err('INVALID_SCHEMA');",
+        '  const input = payload as ThingInput;',
+        '  const id = crypto.randomUUID();',
+        '  await db.query(`INSERT INTO things (id, name) VALUES ($1, $2)`, [id, input.name]);',
+        '  return Ok({ id });',
+        '}',
+        '',
+        'export function ThingTrigger({ onSubmitAction }: { onSubmitAction?: (payload: unknown) => Promise<ThingOutput> }) {',
+        '  return <form onSubmit={async (e) => { e.preventDefault(); await onSubmitAction?.({ name: "x" }); }}><button>criar</button></form>;',
+        '}',
+        '',
+        'export const sliceTests = {',
+        '  cases: [',
+        "    { name: 'sem sessão retorna UNAUTHORIZED', run: async () => {",
+        '      const result = await createThingAction({ name: "x" }, new MockDatabaseClient());',
+        "      if (result.ok || result.error !== 'UNAUTHORIZED') throw new Error('esperava UNAUTHORIZED');",
+        '    } }',
+        '  ]',
+        '};'
+      ].join('\n')
+    },
+    results: {
+      shape: 'type Result<T, E> = { ok: true, value: T } | { ok: false, error: E }',
+      errorsAreValues:
+        'Actions never throw for domain failures: they return Err(code). The code is the contract; declare every code in the output type.',
+      httpStatus: {
+        UNAUTHORIZED: '401',
+        FORBIDDEN: '403',
+        '*_NOT_FOUND': '404',
+        'DUPLICATE_*, ALREADY_*': '409',
+        'INVALID_*, MALFORMED*': '422',
+        'NO_DATABASE, PERSISTENCE_FAILED, *_FAILED': '500',
+        'anything else': '400'
+      }
+    },
+    sessions: {
+      headers: ['Authorization: Bearer <token>', 'x-user-id', 'x-user-roles'],
+      signed:
+        'With SYNAPSE_SESSION_SECRET set, a bearer token must be a signed session (signSessionToken) and its claims win: role headers are ignored.',
+      anonymous: 'A request with none of them is anonymous: requireAuth returns Err("UNAUTHORIZED").',
+      login:
+        'There is no built-in login screen and no server-side session state. A login slice (synapse new-slice auth login --template=login) verifies the password with Bun.password.verify, signs the session with signSessionToken and returns the token; the browser stores it with storeSession(token, roles) and logs out with clearSession(). After that the token travels as Authorization: Bearer and the server authorizes from the signature.'
+    },
+    addressing: {
+      page: 'GET /<domain>/<name>',
+      rpc: 'POST /_synapse/rpc/<domain>/<name> with Content-Type: application/json',
+      upload:
+        'POST /_synapse/files/<domain>/<name>?name=arquivo.pdf sends raw bytes (multipart is not needed and not parsed). It requires a session, refuses a name containing a directory, and stops reading past SYNAPSE_MAX_UPLOAD_BYTES (5 MiB by default). It answers { ok, path, bytes } with a path relative to the app root; what the bytes mean is the slice contract to decide.',
+      ambiguity:
+        'A bare name resolves only while it is unique across domains; otherwise the dispatcher answers 409 listing the candidates.'
+    },
+    serverRendering: {
+      props: 'params (query string) merged with the loader result',
+      hydration:
+        'The server builds a browser bundle per slice from the splitter output, hydrates the component and wires onSubmitAction to the RPC endpoint. The same props are serialized into the page.',
+      isolation:
+        'A client bundle never contains SQL, db access, process.env or Bun globals; the splitter gates fail the build if it does.'
+    },
+    shared: {
+      location: 'src/shared/<name>.ts',
+      rule: 'A slice never imports another slice — the splitter fails with SLICE_IMPORTS_SLICE, transitively, and says so. What two features must do together lives in src/shared/, receives the DatabaseClient by parameter and is called from both slices. A shared module may throw; the action that calls it converts the failure into Err, so the no-throw contract of an action survives a transaction.',
+      atomicity:
+        'db.transaction(fn) is the boundary: the statements inside commit together or roll back together. The mock database does not roll back, so atomicity must be proven against a real engine (SQLite in the suite, PostgreSQL via test:postgres) — never with the mock.'
+    },
+    templates: {
+      command: 'synapse new-slice <domain> <name> --template=<template>',
+      available: [...SLICE_TEMPLATES, 'crud'],
+      notes:
+        'create is the default. crud generates create-<name>, list-<name>, update-<name> and delete-<name> for one resource. list paginates (LIMIT/OFFSET plus COUNT) with a parameterized filter; update is partial and builds its SET clause from a column allowlist, never from the payload; delete checks existence first. Every generated file already carries an oracle.'
+    },
+    gates: [
+      {
+        command: 'synapse check [arquivo]',
+        proves: 'types; fails with coordinates, never reports PASS when nothing matched'
+      },
+      { command: 'synapse test', proves: 'every named invariant, under bun:test, with per-case results' },
+      { command: 'synapse migrate', proves: 'each DDL statement applied once, idempotently' },
+      { command: 'synapse skeleton', proves: 'the repo map is regenerated deterministically' },
+      { command: 'synapse split', proves: 'the emitted modules compile and the client leaks no server code' },
+      {
+        command: 'synapse build',
+        proves:
+          'every slice with a UI produces a browser bundle ahead of time, recorded in .synapse/client/manifest.json; a slice that fails to import is reported FAIL with its reason'
+      }
+    ]
+  };
+}
+
+export function renderContractJson(): string {
+  return JSON.stringify(machineContract(), null, 2);
+}
+
+export function renderContractMarkdown(): string {
+  const contract = machineContract();
+  const lines: string[] = ['# SynapseJS machine contract', ''];
+
+  lines.push(`Slice: \`${contract.slice.location}\` — ${contract.slice.oneFeaturePerFile}`, '');
+  lines.push('| export | required | signature | notes |', '|---|---|---|---|');
+  for (const entry of contract.slice.exports) {
+    lines.push(`| \`${entry.name}\` | ${entry.required ? 'yes' : 'no'} | \`${entry.signature}\` | ${entry.notes} |`);
+  }
+
+  lines.push('', '## Gates', '', '| command | proves |', '|---|---|');
+  for (const gate of contract.gates) {
+    lines.push(`| \`${gate.command}\` | ${gate.proves} |`);
+  }
+
+  return lines.join('\n');
+}

package/src/compiler/db-schema-generator.ts

@@ -0,0 +1,306 @@
+/**
+ * SynapseJS - Centralized Database Schema Generator
+ *
+ * Inspects all sliceSchema DDL contracts across the project, parses table definitions,
+ * column types, primary keys and foreign keys, and generates a clean, compilable
+ * TypeScript declaration catalog at `.codebase/db-schema.d.ts`.
+ *
+ * This provides 100% type visibility to both AI agents and human developers
+ * without requiring heavy ORMs or external database connections.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ts from 'typescript';
+import { extractSliceSchema } from './migration-runner';
+import { orderSlicesByDag } from './schema-dag';
+import { findSliceFiles, resolveSlicesDir } from './slice-discovery';
+
+export interface ColumnDefinition {
+  name: string;
+  sqlType: string;
+  tsType: string;
+  isNullable: boolean;
+  isPrimaryKey: boolean;
+  isUnique: boolean;
+  references?: { table: string; column: string };
+}
+
+export interface TableDefinition {
+  name: string;
+  interfaceName: string;
+  columns: ColumnDefinition[];
+  sourceSlice?: string;
+}
+
+export interface DatabaseCatalog {
+  tables: TableDefinition[];
+  totalTables: number;
+  totalColumns: number;
+}
+
+/** Converts snake_case or kebab-case to PascalCase */
+export function toPascalCase(str: string): string {
+  return str.replace(/[-_](\w)/g, (_, c) => c.toUpperCase()).replace(/^(\w)/, (_, c) => c.toUpperCase());
+}
+
+/** Maps SQL column types to strict TypeScript types */
+export function mapSqlTypeToTs(sqlType: string): string {
+  const upper = sqlType.toUpperCase().trim();
+
+  if (
+    upper.startsWith('TEXT') ||
+    upper.startsWith('VARCHAR') ||
+    upper.startsWith('CHAR') ||
+    upper.startsWith('UUID') ||
+    upper.startsWith('STRING')
+  ) {
+    return 'string';
+  }
+
+  if (
+    upper.startsWith('INT') ||
+    upper.startsWith('BIGINT') ||
+    upper.startsWith('SMALLINT') ||
+    upper.startsWith('SERIAL') ||
+    upper.startsWith('REAL') ||
+    upper.startsWith('FLOAT') ||
+    upper.startsWith('DOUBLE') ||
+    upper.startsWith('NUMERIC') ||
+    upper.startsWith('DECIMAL')
+  ) {
+    return 'number';
+  }
+
+  if (upper.startsWith('BOOL')) {
+    return 'boolean';
+  }
+
+  if (
+    upper.startsWith('TIMESTAMP') ||
+    upper.startsWith('DATETIME') ||
+    upper.startsWith('DATE') ||
+    upper.startsWith('TIME')
+  ) {
+    return 'string';
+  }
+
+  if (upper.startsWith('JSON')) {
+    return 'Record<string, unknown> | unknown[]';
+  }
+
+  if (upper.startsWith('BLOB') || upper.startsWith('BYTEA')) {
+    return 'Uint8Array';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Splits column definitions inside CREATE TABLE (...) accounting for nested parentheses.
+ */
+function splitColumnDefinitions(body: string): string[] {
+  const defs: string[] = [];
+  let depth = 0;
+  let current = '';
+
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+    if (char === '(') {
+      depth++;
+      current += char;
+    } else if (char === ')') {
+      depth--;
+      current += char;
+    } else if (char === ',' && depth === 0) {
+      if (current.trim().length > 0) {
+        defs.push(current.trim());
+      }
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.trim().length > 0) {
+    defs.push(current.trim());
+  }
+
+  return defs;
+}
+
+/**
+ * Parses DDL string to extract all table and column definitions.
+ */
+export function parseDdlToCatalog(ddl: string, sourceSlice?: string): TableDefinition[] {
+  const tables: TableDefinition[] = [];
+
+  // Match CREATE TABLE [IF NOT EXISTS] <name> (<columns>)
+  const createTableRegex =
+    /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?([a-zA-Z0-9_]+)["'`]?\s*\(([\s\S]*?)\)(?:\s*;|\s*$)/gi;
+
+  let match: RegExpExecArray | null = createTableRegex.exec(ddl);
+  while (match !== null) {
+    const tableName = match[1].toLowerCase();
+    const body = match[2];
+    const rawDefs = splitColumnDefinitions(body);
+    const columns: ColumnDefinition[] = [];
+
+    for (const def of rawDefs) {
+      const cleanDef = def.replace(/\s+/g, ' ').trim();
+      const upperDef = cleanDef.toUpperCase();
+
+      // Skip table-level constraints like PRIMARY KEY (a, b) or FOREIGN KEY (...)
+      if (
+        upperDef.startsWith('PRIMARY KEY') ||
+        upperDef.startsWith('FOREIGN KEY') ||
+        upperDef.startsWith('CONSTRAINT') ||
+        upperDef.startsWith('CHECK') ||
+        upperDef.startsWith('UNIQUE')
+      ) {
+        continue;
+      }
+
+      // First token is column name, second token is type
+      const tokens = cleanDef.split(' ');
+      if (tokens.length < 2) continue;
+
+      const colName = tokens[0].replace(/["'`]/g, '');
+      const sqlType = tokens[1].replace(/["'`]/g, '');
+      const tsType = mapSqlTypeToTs(sqlType);
+
+      const isPrimaryKey = upperDef.includes('PRIMARY KEY');
+      const isNotNull = upperDef.includes('NOT NULL') || isPrimaryKey;
+      const isUnique = upperDef.includes('UNIQUE') || isPrimaryKey;
+
+      let references: { table: string; column: string } | undefined;
+      const refMatch = /REFERENCES\s+["'`]?([a-zA-Z0-9_]+)["'`]?\s*(?:\(["'`]?([a-zA-Z0-9_]+)["'`]?\))?/i.exec(
+        cleanDef
+      );
+      if (refMatch) {
+        references = {
+          table: refMatch[1].toLowerCase(),
+          column: refMatch[2] ? refMatch[2].toLowerCase() : 'id'
+        };
+      }
+
+      columns.push({
+        name: colName,
+        sqlType,
+        tsType,
+        isNullable: !isNotNull,
+        isPrimaryKey,
+        isUnique,
+        references
+      });
+    }
+
+    tables.push({
+      name: tableName,
+      interfaceName: `Db${toPascalCase(tableName)}`,
+      columns,
+      sourceSlice
+    });
+
+    match = createTableRegex.exec(ddl);
+  }
+
+  return tables;
+}
+
+/**
+ * Scans a project directory, parses all slice schemas, and generates .codebase/db-schema.d.ts
+ */
+export function generateDatabaseSchemaCatalog(rootDir: string, outputFile?: string): DatabaseCatalog {
+  const targetOutput = outputFile || path.join(rootDir, '.codebase/db-schema.d.ts');
+  const allTables: Map<string, TableDefinition> = new Map();
+
+  const slicesRes = resolveSlicesDir(rootDir);
+  if (slicesRes.ok) {
+    const sliceFiles = findSliceFiles(slicesRes.value.slicesDir);
+    const sortedFiles = orderSlicesByDag(sliceFiles);
+
+    for (const filePath of sortedFiles) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+        const ddl = extractSliceSchema(sourceFile);
+        if (ddl) {
+          const sliceName = path.basename(filePath, '.slice.tsx');
+          const tables = parseDdlToCatalog(ddl, sliceName);
+          for (const table of tables) {
+            // Merge or set table
+            if (!allTables.has(table.name)) {
+              allTables.set(table.name, table);
+            } else {
+              // Merge columns if table defined across slices
+              const existing = allTables.get(table.name);
+              if (existing) {
+                for (const col of table.columns) {
+                  if (!existing.columns.some((c) => c.name === col.name)) {
+                    existing.columns.push(col);
+                  }
+                }
+              }
+            }
+          }
+        }
+      } catch {
+        // Skip unreadable slices gracefully
+      }
+    }
+  }
+
+  const tablesArray = Array.from(allTables.values());
+  let totalColumns = 0;
+  for (const t of tablesArray) {
+    totalColumns += t.columns.length;
+  }
+
+  // Generate TypeScript declaration code
+  let dtsContent = `/**\n`;
+  dtsContent += ` * [SYNAPSE-JS AUTO-GENERATED DATABASE SCHEMA CATALOG]\n`;
+  dtsContent += ` * Provides 100% type-safe table and column definitions extracted directly from slice DDLs.\n`;
+  dtsContent += ` * Regenerate with 'synapse skeleton' or 'synapse db-schema'. DO NOT EDIT MANUALLY.\n`;
+  dtsContent += ` */\n\n`;
+
+  for (const table of tablesArray) {
+    dtsContent += `export interface ${table.interfaceName} {\n`;
+    for (const col of table.columns) {
+      const opt = col.isNullable ? '?' : '';
+      const nullType = col.isNullable ? ' | null' : '';
+      const comment = col.isPrimaryKey
+        ? ' /** Primary Key */'
+        : col.references
+          ? ` /** Foreign Key -> ${col.references.table}.${col.references.column} */`
+          : '';
+      dtsContent += `  ${col.name}${opt}: ${col.tsType}${nullType};${comment}\n`;
+    }
+    dtsContent += `}\n\n`;
+  }
+
+  dtsContent += `export interface DatabaseSchema {\n`;
+  for (const table of tablesArray) {
+    dtsContent += `  ${table.name}: ${table.interfaceName};\n`;
+  }
+  dtsContent += `}\n\n`;
+
+  dtsContent += `export type TableName = keyof DatabaseSchema;\n`;
+  dtsContent += `export type Row<T extends TableName> = DatabaseSchema[T];\n`;
+
+  // Write output file
+  const outDir = path.dirname(targetOutput);
+  if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  fs.writeFileSync(targetOutput, dtsContent, 'utf-8');
+
+  return {
+    tables: tablesArray,
+    totalTables: tablesArray.length,
+    totalColumns
+  };
+}
+
+export const generateDbSchemaCatalog = generateDatabaseSchemaCatalog;