@ismaelsoilet/synapsejs 1.4.0 → 1.9.0

package/src/compiler/migration-runner.ts

@@ -63,14 +63,114 @@ export interface RollbackOptions {
 }
 
 export function parseBidirectionalDdl(rawDdl: string): BidirectionalDdl {
-  const downMarkerRegex = /^[ \t]*--\s*down:?[ \t]*$/im;
-  const match = downMarkerRegex.exec(rawDdl);
-  if (!match) {
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inBlockComment = false;
+  let dollarTag: string | null = null;
+  let splitIndex = -1;
+  let matchLength = 0;
+
+  let i = 0;
+  while (i < rawDdl.length) {
+    const char = rawDdl[i];
+    const next = rawDdl[i + 1] ?? '';
+
+    if (inBlockComment) {
+      if (char === '*' && next === '/') {
+        inBlockComment = false;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    if (inSingleQuote) {
+      if (char === '\\') {
+        i += 2;
+        continue;
+      }
+      if (char === "'") {
+        if (next === "'") {
+          i += 2;
+          continue;
+        }
+        inSingleQuote = false;
+      }
+      i++;
+      continue;
+    }
+
+    if (inDoubleQuote) {
+      if (char === '"') {
+        if (next === '"') {
+          i += 2;
+          continue;
+        }
+        inDoubleQuote = false;
+      }
+      i++;
+      continue;
+    }
+
+    if (dollarTag !== null) {
+      if (char === '$' && rawDdl.startsWith(dollarTag, i)) {
+        i += dollarTag.length;
+        dollarTag = null;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      inBlockComment = true;
+      i += 2;
+      continue;
+    }
+
+    if (char === "'") {
+      inSingleQuote = true;
+      i++;
+      continue;
+    }
+
+    if (char === '"') {
+      inDoubleQuote = true;
+      i++;
+      continue;
+    }
+
+    if (char === '$') {
+      const match = rawDdl.slice(i).match(/^\$[A-Za-z0-9_]*\$/);
+      if (match) {
+        dollarTag = match[0];
+        i += dollarTag.length;
+        continue;
+      }
+    }
+
+    // Check for -- down: marker at beginning of line outside strings/comments
+    const isLineStart = i === 0 || rawDdl[i - 1] === '\n';
+    if (isLineStart) {
+      const lineSlice = rawDdl.slice(i);
+      const match = lineSlice.match(/^[ \t]*--\s*down:?[ \t]*(?:\r?\n|$)/i);
+      if (match) {
+        splitIndex = i;
+        matchLength = match[0].length;
+        break;
+      }
+    }
+
+    i++;
+  }
+
+  if (splitIndex === -1) {
     return { upDdl: rawDdl.trim(), downDdl: null };
   }
-  const splitIndex = match.index;
+
   const upDdl = rawDdl.slice(0, splitIndex).trim();
-  const downDdl = rawDdl.slice(splitIndex + match[0].length).trim();
+  const downDdl = rawDdl.slice(splitIndex + matchLength).trim();
   return {
     upDdl,
     downDdl: downDdl.length > 0 ? downDdl : null
@@ -91,6 +191,7 @@ export function splitStatements(ddl: string): string[] {
   let inLineComment = false;
   let inBlockComment = false;
   let dollarTag: string | null = null;
+  let beginDepth = 0;
 
   let i = 0;
   while (i < ddl.length) {
@@ -207,8 +308,31 @@ export function splitStatements(ddl: string): string[] {
       }
     }
 
-    // Statement terminator outside strings or comments
-    if (char === ';') {
+    // Track BEGIN ... END blocks (e.g. triggers, compound statements)
+    const remaining = ddl.slice(i);
+    const prevChar = i > 0 ? ddl[i - 1] : ' ';
+    const isWordStart = /[\s,;(]/.test(prevChar);
+
+    if (isWordStart) {
+      const beginMatch = remaining.match(/^BEGIN\b/i);
+      if (beginMatch) {
+        beginDepth++;
+        current += beginMatch[0];
+        i += beginMatch[0].length;
+        continue;
+      }
+
+      const endMatch = remaining.match(/^END\b/i);
+      if (endMatch) {
+        if (beginDepth > 0) beginDepth--;
+        current += endMatch[0];
+        i += endMatch[0].length;
+        continue;
+      }
+    }
+
+    // Statement terminator outside strings or comments, but only when not inside a BEGIN...END block
+    if (char === ';' && beginDepth === 0) {
       const trimmed = current.trim();
       if (trimmed.length > 0) {
         statements.push(trimmed);
@@ -261,9 +385,15 @@ export function extractSliceSchema(sourceFile: ts.SourceFile): string | null {
   return ddl;
 }
 
+export interface RunMigrationsOptions {
+  /** Consult the Jev abort gate after a failure (default: disabled). */
+  enableJevGate?: boolean;
+}
+
 export async function runSliceMigrations(
   baseDir: string = process.cwd(),
-  customDb?: DatabaseClient
+  customDb?: DatabaseClient,
+  options: RunMigrationsOptions = {}
 ): Promise<MigrationReport> {
   const db = customDb || getDatabase();
   const isPostgres = db instanceof PostgresDatabaseClient;
@@ -394,20 +524,23 @@ export async function runSliceMigrations(
           status: 'APPLIED',
           statementsApplied: pending.length
         });
-      } catch (err: any) {
+      } catch (err: unknown) {
         hasFailure = true;
+        const errMessage = err instanceof Error ? err.message : String(err);
         migrations.push({
           slice: sliceName,
           filePath: path.relative(baseDir, filePath),
           status: 'FAILED',
           statementsApplied: 0,
-          error: err.message
+          error: errMessage
         });
       }
     }
 
+    // Opt-in (default: disabled): the abort gate consults an external model provider
+    // when one is configured, so a programmatic caller asks for it explicitly.
     let abortSignal: AbortGateResult | undefined;
-    if (hasFailure) {
+    if (hasFailure && options?.enableJevGate === true) {
       try {
         const failureDetails = migrations
           .filter((m) => m.status === 'FAILED')

package/src/compiler/optional-coverage.ts

@@ -0,0 +1,137 @@
+/**
+ * SynapseJS - Optional Contract Item Coverage
+ *
+ * The slice authoring contract has optional items — webhook, background job,
+ * websocket definition, cache definition, metadata generation, broadcast and
+ * subscription. Prose cannot prove they work; a committed slice can. This module
+ * reports which optional item each shipped application exercises and which ones
+ * nothing exercises, so a capability cannot be advertised on a template assertion.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { findSliceFiles, resolveSlicesDir } from './slice-discovery';
+
+export interface OptionalItemCoverage {
+  item: string;
+  /** The committed slice that exercises it, or null when nothing does. */
+  slice: string | null;
+}
+
+export interface OptionalItemReport {
+  status: 'PASS' | 'FAIL';
+  operation: 'OPTIONAL_ITEM_COVERAGE';
+  appDir: string;
+  totalSlices: number;
+  items: OptionalItemCoverage[];
+  /** The optional items no committed slice exercises. Empty is the passing state. */
+  unexercised: string[];
+  /** Present when slice discovery failed. */
+  code?: string;
+  message?: string;
+  candidates?: string[];
+}
+
+interface Detector {
+  item: string;
+  matches: (filePath: string, source: string) => boolean;
+}
+
+function exportsName(source: string, suffix: string): boolean {
+  return new RegExp(`export\\s+(?:async\\s+)?(?:function|const|class|let|var)\\s+\\w*${suffix}\\b`).test(source);
+}
+
+const DETECTORS: Detector[] = [
+  {
+    item: 'webhook',
+    matches: (_file, source) => exportsName(source, 'Webhook')
+  },
+  {
+    item: 'background job',
+    matches: (_file, source) => exportsName(source, 'Job') || /\bdefineJob\s*[<(]/.test(source)
+  },
+  {
+    item: 'websocket definition',
+    matches: (_file, source) => exportsName(source, 'Socket') || /\bdefineSocket\s*[<(]/.test(source)
+  },
+  {
+    item: 'cache definition',
+    matches: (_file, source) => exportsName(source, 'Cache') || /\bdefineCache\s*\(/.test(source)
+  },
+  {
+    item: 'metadata generation',
+    matches: (_file, source) => /\bsliceMeta\b/.test(source) || exportsName(source, 'Meta')
+  },
+  {
+    item: 'broadcast',
+    matches: (_file, source) => /\.broadcast\s*\(/.test(source)
+  },
+  {
+    item: 'subscription',
+    matches: (_file, source) => /\buseSubscription\s*\(/.test(source) || /\bdefineTopic\s*\(/.test(source)
+  }
+];
+
+export function analyzeOptionalItemCoverage(appDir: string = process.cwd()): OptionalItemReport {
+  const resolution = resolveSlicesDir(appDir);
+
+  if (!resolution.ok) {
+    return {
+      status: 'FAIL',
+      operation: 'OPTIONAL_ITEM_COVERAGE',
+      appDir,
+      totalSlices: 0,
+      items: DETECTORS.map((detector) => ({ item: detector.item, slice: null })),
+      unexercised: DETECTORS.map((detector) => detector.item),
+      code: resolution.error.code,
+      message: resolution.error.message,
+      candidates: resolution.error.candidates
+    };
+  }
+
+  const sliceFiles = findSliceFiles(resolution.value.slicesDir);
+  const items: OptionalItemCoverage[] = DETECTORS.map((detector) => {
+    for (const filePath of sliceFiles) {
+      try {
+        const source = fs.readFileSync(filePath, 'utf-8');
+
+        if (detector.matches(filePath, source)) {
+          return { item: detector.item, slice: path.basename(filePath, '.slice.tsx') };
+        }
+      } catch {
+        // Unreadable slice: it cannot be the evidence, and discovery already reported it.
+      }
+    }
+
+    return { item: detector.item, slice: null };
+  });
+
+  const unexercised = items.filter((entry) => entry.slice === null).map((entry) => entry.item);
+
+  return {
+    status: unexercised.length === 0 ? 'PASS' : 'FAIL',
+    operation: 'OPTIONAL_ITEM_COVERAGE',
+    appDir,
+    totalSlices: sliceFiles.length,
+    items,
+    unexercised
+  };
+}
+
+/** The union of optional items covered across several shipped applications. */
+export function unionCoverage(reports: OptionalItemReport[]): { covered: string[]; unexercised: string[] } {
+  const covered = new Set<string>();
+
+  for (const report of reports) {
+    for (const entry of report.items) {
+      if (entry.slice) {
+        covered.add(entry.item);
+      }
+    }
+  }
+
+  return {
+    covered: Array.from(covered),
+    unexercised: DETECTORS.map((detector) => detector.item).filter((item) => !covered.has(item))
+  };
+}

package/src/compiler/oracle-runner.ts

@@ -157,6 +157,11 @@ export interface OracleRunOptions {
   /** Injected by tests: runs a command and returns its exit code and output. */
   spawn?: (args: string[], cwd: string) => Promise<{ exitCode: number; output: string }>;
   /** Enable Jev System One semantic test triage on failures. Default: true */
+  /**
+   * Opt-in (default: disabled). The triage consults an external model provider when
+   * one is configured, so a programmatic caller must ask for it explicitly; the CLI
+   * enables it only when the environment declares the gate.
+   */
   enableJevTriage?: boolean;
 }
 
@@ -246,7 +251,7 @@ export async function runSliceOracles(
 
   if (!fs.existsSync(reportPath)) {
     let triageResult: TestTriageResult | undefined;
-    if (options.enableJevTriage !== false) {
+    if (options.enableJevTriage === true) {
       try {
         triageResult = await triageTestFailure(output.trim() || `O runner Bun test falhou com exit ${exitCode}`);
       } catch {}
@@ -280,7 +285,7 @@ export async function runSliceOracles(
 
   if (totalCases === 0) {
     let triageResult: TestTriageResult | undefined;
-    if (options.enableJevTriage !== false) {
+    if (options.enableJevTriage === true) {
       try {
         triageResult = await triageTestFailure(`Nenhum invariante foi executado em ${results.length} fatia(s).`);
       } catch {}
@@ -301,7 +306,7 @@ export async function runSliceOracles(
 
   const isPass = passedSlices === results.length;
   let triageResult: TestTriageResult | undefined;
-  if (!isPass && options.enableJevTriage !== false) {
+  if (!isPass && options.enableJevTriage === true) {
     try {
       const failedSummaries = results
         .filter((r) => !r.passed)

package/src/compiler/scaffolder.ts

@@ -8,7 +8,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { Err, Ok, type Result } from '../core/machine-types';
-import { generateFormFieldsCode, generateSqlColumns, generateTypeBoxProperties, parseFields } from './fields-parser';
+import { isInsideBase, validatePathSegment } from '../core/path-guard';
+import {
+  generateFormFieldsCode,
+  generateSqlColumns,
+  generateTypeBoxProperties,
+  parseFields,
+  validateFieldNames
+} from './fields-parser';
 import { resolveSlicesDir, type SlicesDirErrorCode } from './slice-discovery';
 import { generateOperationTemplate, type SliceTemplate } from './slice-templates';
 
@@ -71,6 +78,9 @@ export const sliceSchema = \`
 ${sqlCols},
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
+
+  -- down:
+  DROP TABLE IF EXISTS ${tableName};
 \`;
 
 // ============================================================================
@@ -222,6 +232,9 @@ export const sliceSchema = \`
     email TEXT NOT NULL UNIQUE,
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
+
+  -- down:
+  DROP TABLE IF EXISTS ${tableName};
 \`;
 
 // ============================================================================
@@ -409,7 +422,28 @@ export const sliceTests = {
 `;
 }
 
-export type ScaffoldErrorCode = SlicesDirErrorCode | 'SLICE_EXISTS' | 'WRITE_FAILED';
+export type ScaffoldErrorCode =
+  | SlicesDirErrorCode
+  | 'SLICE_EXISTS'
+  | 'WRITE_FAILED'
+  | 'INVALID_PATH_SEGMENT'
+  | 'INVALID_FIELD_NAME';
+
+/**
+ * One description per scaffolding failure code. The `Record` type makes a
+ * missing member a compile error, so the documented set cannot drift from the
+ * union the functions return.
+ */
+export const SCAFFOLD_FAILURE_CODES: Record<ScaffoldErrorCode, string> = {
+  NO_SLICES_DIR: 'no src/slices directory was found; candidates lists every path examined',
+  AMBIGUOUS_SLICES_DIR:
+    'more than one application owns a slices directory; set SYNAPSE_ROOT or run inside the target application',
+  SLICE_EXISTS: 'the target file already exists',
+  WRITE_FAILED: 'the filesystem refused the write',
+  INVALID_PATH_SEGMENT:
+    'a domain, slice name, shared-module name or project directory is not a single safe path segment',
+  INVALID_FIELD_NAME: 'a field name or enum value in --fields is not a plain identifier'
+};
 
 export interface ScaffoldError {
   code: ScaffoldErrorCode;
@@ -442,6 +476,47 @@ function resolveScaffoldTarget(baseDir: string): Result<string, ScaffoldError> {
   return Ok(path.join(path.resolve(baseDir), 'src', 'slices'));
 }
 
+function segmentRejection(
+  kind: 'domain' | 'name',
+  value: string | undefined,
+  targetKind: string
+): ScaffoldError | null {
+  const validated = validatePathSegment(value);
+
+  if (validated.ok) {
+    return null;
+  }
+
+  return {
+    code: 'INVALID_PATH_SEGMENT',
+    message: `O ${kind === 'domain' ? 'domínio' : 'nome'} informado ('${value ?? ''}') não é um segmento de caminho válido para ${targetKind}. Use apenas letras, números, '-', '_' e '.', sem barras e sem '..'.`,
+    candidates: []
+  };
+}
+
+/**
+ * Field names are interpolated into generated DDL and generated TypeScript, so
+ * they are validated before a single byte is written: the migration runner is
+ * never handed a schema derived from an unchecked name.
+ */
+function fieldRejection(fieldsSpec: string | undefined): ScaffoldError | null {
+  if (!fieldsSpec?.trim()) {
+    return null;
+  }
+
+  const validation = validateFieldNames(parseFields(fieldsSpec));
+
+  if (validation.ok) {
+    return null;
+  }
+
+  return {
+    code: 'INVALID_FIELD_NAME',
+    message: `O nome de campo '${validation.error}' não é um identificador válido. Campos devem casar com [A-Za-z_][A-Za-z0-9_]*.`,
+    candidates: []
+  };
+}
+
 export function scaffoldSlice(
   domain: string,
   sliceName: string,
@@ -455,9 +530,35 @@ export function scaffoldSlice(
     return target;
   }
 
+  const domainRejection = segmentRejection('domain', domain, 'a fatia');
+
+  if (domainRejection) {
+    return Err(domainRejection);
+  }
+
+  const nameRejection = segmentRejection('name', sliceName, 'a fatia');
+
+  if (nameRejection) {
+    return Err(nameRejection);
+  }
+
+  const fieldsRejection = fieldRejection(fieldsSpec);
+
+  if (fieldsRejection) {
+    return Err(fieldsRejection);
+  }
+
   const targetDir = path.join(target.value, domain);
   const targetFile = path.join(targetDir, `${sliceName}.slice.tsx`);
 
+  if (!isInsideBase(target.value, targetFile)) {
+    return Err({
+      code: 'INVALID_PATH_SEGMENT',
+      message: `O caminho resolvido para a fatia '${sliceName}' sai do diretório de fatias da aplicação.`,
+      candidates: [targetFile]
+    });
+  }
+
   if (fs.existsSync(targetFile)) {
     return Err({
       code: 'SLICE_EXISTS',
@@ -467,11 +568,12 @@ export function scaffoldSlice(
   }
 
   try {
-    fs.mkdirSync(targetDir, { recursive: true });
     const content =
       template === 'create'
         ? generateSliceTemplate(domain, sliceName, fieldsSpec)
         : generateOperationTemplate(domain, sliceName, template, fieldsSpec);
+
+    fs.mkdirSync(targetDir, { recursive: true });
     fs.writeFileSync(targetFile, content, 'utf-8');
   } catch (err) {
     return Err({
@@ -513,6 +615,75 @@ export function scaffoldCrud(
   return Ok(created);
 }
 
+/**
+ * Scaffolds a safe shared domain module in `src/shared/<name>.ts`.
+ */
+export function scaffoldShared(name: string, baseDir: string = process.cwd()): Result<string, ScaffoldError> {
+  const cleanName = name.replace(/\.ts$/, '');
+  const sharedDir = path.resolve(baseDir, 'src', 'shared');
+
+  const nameRejection = segmentRejection('name', cleanName, 'o módulo compartilhado');
+
+  if (nameRejection) {
+    return Err(nameRejection);
+  }
+
+  const targetFile = path.join(sharedDir, `${cleanName}.ts`);
+
+  if (!isInsideBase(sharedDir, targetFile)) {
+    return Err({
+      code: 'INVALID_PATH_SEGMENT',
+      message: `O caminho resolvido para o módulo compartilhado '${cleanName}' sai do diretório src/shared da aplicação.`,
+      candidates: [targetFile]
+    });
+  }
+
+  if (fs.existsSync(targetFile)) {
+    return Err({
+      code: 'SLICE_EXISTS',
+      message: `O módulo compartilhado "${cleanName}.ts" já existe em ${sharedDir}.`,
+      candidates: [targetFile]
+    });
+  }
+
+  const pascalName = toPascalCase(cleanName);
+  const content = `import type { DatabaseClient, Result } from 'synapsejs';
+import { Ok, Err } from 'synapsejs';
+
+/**
+ * Módulo compartilhado para o domínio ${cleanName}.
+ * Fatias não importam fatias — regras que envolvem múltiplas fatias ou transações cruzadas
+ * residem em src/shared/, recebem o DatabaseClient por parâmetro e abrem db.transaction().
+ */
+export async function executeShared${pascalName}(
+  db: DatabaseClient,
+  params: Record<string, unknown> = {}
+): Promise<Result<{ success: boolean; data?: unknown }, string>> {
+  if (!db) {
+    return Err('NO_DATABASE');
+  }
+
+  return await db.transaction(async (tx) => {
+    // Implemente a lógica transacional entre fatias aqui usando tx
+    return Ok({ success: true, data: params });
+  });
+}
+`;
+
+  try {
+    fs.mkdirSync(sharedDir, { recursive: true });
+    fs.writeFileSync(targetFile, content, 'utf-8');
+    return Ok(targetFile);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return Err({
+      code: 'WRITE_FAILED',
+      message: `Falha ao escrever módulo compartilhado: ${message}`,
+      candidates: [targetFile]
+    });
+  }
+}
+
 if (import.meta.main) {
   const domain = process.argv[2] || 'core';
   const name = process.argv[3] || 'example-feature';

package/src/compiler/schema-dag.ts

@@ -96,9 +96,12 @@ export function orderSlicesByDag(sliceFiles: string[]): string[] {
     for (const refTable of meta.tablesReferenced) {
       const parentFilePath = tableToSlice.get(refTable);
       if (parentFilePath && parentFilePath !== filePath) {
-        // parentFilePath must run before filePath
-        graph.get(parentFilePath)?.push(filePath);
-        inDegree.set(filePath, (inDegree.get(filePath) || 0) + 1);
+        // parentFilePath must run before filePath (prevent duplicate edge)
+        const neighbors = graph.get(parentFilePath);
+        if (neighbors && !neighbors.includes(filePath)) {
+          neighbors.push(filePath);
+          inDegree.set(filePath, (inDegree.get(filePath) || 0) + 1);
+        }
       }
     }
   }

package/src/compiler/slice-discovery.ts

@@ -38,7 +38,14 @@ export function findSliceFiles(dir: string): string[] {
   }
 
   const results: string[] = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+  // `readdirSync` order is filesystem-dependent: on a fresh checkout it can differ from
+  // the developer's machine, which made generated artifacts (repo map, schema catalog,
+  // split order) drift between the two. Sorting makes every generated file reproducible.
+  const entries = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...findSliceFiles(full));