@ismaelsoilet/synapsejs 1.8.0 → 1.11.1

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';
 
@@ -51,10 +58,9 @@ import {
   Ok,
   Err,
   MockDatabaseClient,
-  type SessionContext,
-  DataForm,
-  Card
+  type SessionContext
 } from 'synapsejs';
+import { DataForm, type FormField, Card } from 'synapsejs/client';
 
 // ============================================================================
 // 1. CONTRATO DE ENTRADA JIT (TypeBox)
@@ -121,7 +127,7 @@ export interface ${pascal}TriggerProps {
   onSubmitAction?: (payload: unknown) => Promise<${outputTypeName}>;
 }
 
-const FORM_FIELDS = ${formFields};
+const FORM_FIELDS: FormField[] = ${formFields};
 
 export function ${triggerName}({ onSubmitAction }: ${pascal}TriggerProps) {
   const [feedback, setFeedback] = useState<string | null>(null);
@@ -415,7 +421,31 @@ export const sliceTests = {
 `;
 }
 
-export type ScaffoldErrorCode = SlicesDirErrorCode | 'SLICE_EXISTS' | 'WRITE_FAILED';
+export type ScaffoldErrorCode =
+  | SlicesDirErrorCode
+  | 'SLICE_EXISTS'
+  | 'WRITE_FAILED'
+  | 'PARTIAL_WRITE'
+  | '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',
+  PARTIAL_WRITE:
+    'a domain scaffolding operation failed and one or more files could not be removed; candidates lists what remains',
+  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;
@@ -448,6 +478,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,
@@ -461,9 +532,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',
@@ -473,11 +570,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({
@@ -525,11 +623,23 @@ export function scaffoldCrud(
 export function scaffoldShared(name: string, baseDir: string = process.cwd()): Result<string, ScaffoldError> {
   const cleanName = name.replace(/\.ts$/, '');
   const sharedDir = path.resolve(baseDir, 'src', 'shared');
-  if (!fs.existsSync(sharedDir)) {
-    fs.mkdirSync(sharedDir, { recursive: true });
+
+  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',
@@ -563,6 +673,7 @@ export async function executeShared${pascalName}(
 `;
 
   try {
+    fs.mkdirSync(sharedDir, { recursive: true });
     fs.writeFileSync(targetFile, content, 'utf-8');
     return Ok(targetFile);
   } catch (err: unknown) {
@@ -575,6 +686,113 @@ export async function executeShared${pascalName}(
   }
 }
 
+/**
+ * Scaffolds an entire modular domain directory with domain layout (_layout.tsx),
+ * an initial listing slice (listar-<domain>.slice.tsx), and shared module (src/shared/<domain>.ts).
+ */
+export function scaffoldDomain(
+  domain: string,
+  baseDir: string = process.cwd(),
+  fieldsSpec?: string
+): Result<string[], ScaffoldError> {
+  const domainRejection = segmentRejection('domain', domain, 'o domínio');
+  if (domainRejection) return Err(domainRejection);
+
+  const target = resolveScaffoldTarget(baseDir);
+  if (!target.ok) return Err(target.error);
+
+  const domainDir = path.join(target.value, domain);
+  const layoutFile = path.join(domainDir, '_layout.tsx');
+  const domainDirExisted = fs.existsSync(domainDir);
+  const createdFiles: string[] = [];
+
+  const fail = (error: ScaffoldError): Result<string[], ScaffoldError> => {
+    const cleanupFailures: string[] = [];
+
+    for (const file of [...createdFiles].reverse()) {
+      try {
+        fs.rmSync(file, { force: true });
+      } catch {
+        cleanupFailures.push(file);
+      }
+    }
+
+    if (!domainDirExisted) {
+      try {
+        fs.rmdirSync(domainDir);
+      } catch {
+        if (fs.existsSync(domainDir)) {
+          cleanupFailures.push(domainDir);
+        }
+      }
+    }
+
+    if (cleanupFailures.length > 0) {
+      return Err({
+        code: 'PARTIAL_WRITE',
+        message: `${error.code}: ${error.message}; não foi possível remover: ${cleanupFailures.join(', ')}`,
+        candidates: cleanupFailures
+      });
+    }
+
+    return Err(error);
+  };
+
+  try {
+    fs.mkdirSync(domainDir, { recursive: true });
+
+    // 1. Domain layout if not exists
+    if (!fs.existsSync(layoutFile)) {
+      const pascalDomain = toPascalCase(domain);
+      const layoutContent = `import React, { type ReactNode } from 'react';
+
+export default function ${pascalDomain}DomainLayout({ children }: { children: ReactNode; url?: string; session?: any }) {
+  return (
+    <div className="flex flex-col flex-1 w-full min-h-full">
+      <header className="border-b border-slate-800 bg-slate-900/60 backdrop-blur px-6 py-4 flex items-center justify-between">
+        <div>
+          <div className="text-xs uppercase tracking-wider text-cyan-400 font-semibold">Domínio</div>
+          <h2 className="text-xl font-bold text-slate-100 capitalize">${domain}</h2>
+        </div>
+        <nav className="flex gap-4 text-sm font-medium">
+          <a href="/${domain}/listar-${domain}" className="text-slate-300 hover:text-cyan-400 transition-colors">Listagem</a>
+        </nav>
+      </header>
+      <main className="flex-1 p-6 max-w-7xl w-full mx-auto">
+        {children}
+      </main>
+    </div>
+  );
+}
+`;
+      fs.writeFileSync(layoutFile, layoutContent, 'utf-8');
+      createdFiles.push(layoutFile);
+    }
+
+    // 2. Initial List Slice
+    const listSliceRes = scaffoldSlice(domain, `listar-${domain}`, baseDir, 'list', fieldsSpec);
+    if (!listSliceRes.ok) {
+      return fail(listSliceRes.error);
+    }
+    createdFiles.push(listSliceRes.value);
+
+    // 3. Shared module
+    const sharedRes = scaffoldShared(domain, baseDir);
+    if (!sharedRes.ok) {
+      return fail(sharedRes.error);
+    }
+    createdFiles.push(sharedRes.value);
+  } catch (err) {
+    return fail({
+      code: 'WRITE_FAILED',
+      message: err instanceof Error ? err.message : String(err),
+      candidates: [domainDir]
+    });
+  }
+
+  return Ok(createdFiles);
+}
+
 if (import.meta.main) {
   const domain = process.argv[2] || 'core';
   const name = process.argv[3] || 'example-feature';

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));

package/src/compiler/slice-splitter.ts

@@ -40,9 +40,15 @@ export interface SplitArtifact {
 export interface SplitResult {
   sliceName: string;
   artifacts: SplitArtifact[];
+  lineCount?: number;
 }
 
-export type SplitErrorCode = 'SLICE_NOT_FOUND' | 'SLICE_IMPORTS_SLICE' | 'NO_ROOTS' | 'UNPARSED';
+export type SplitErrorCode =
+  | 'SLICE_NOT_FOUND'
+  | 'SLICE_IMPORTS_SLICE'
+  | 'NO_ROOTS'
+  | 'UNPARSED'
+  | 'SERVER_VALUE_IN_CLIENT';
 
 export interface SplitError {
   code: SplitErrorCode;
@@ -67,17 +73,25 @@ export interface SplitVerification {
 const CLIENT_ROOTS = [...COMPONENT_SUFFIXES];
 const TEST_ONLY_NAMES: readonly string[] = [...TEST_ONLY_EXPORTS];
 
-const SERVER_ONLY_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
+/** The expressions that must never survive into a client bundle. Exported so the
+ * linear-time guarantee can be asserted directly against each of them. */
+export const SERVER_ONLY_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
   // `SELECT ... FROM` e não `SELECT` seguido de qualquer palavra: sem o FROM, a
   // tag HTML `<select id="x">` de um formulário casava como vazamento de SQL.
-  { label: 'SELECT statement', pattern: /\bSELECT\s+[\w*"`][\w*"`.,\s]*\bFROM\b/i },
+  // O quantificador é limitado (uma janela fixa, não `*`): um bundle grande com
+  // muitos `SELECT` sem `FROM` fazia o motor retroceder sobre o texto inteiro.
+  { label: 'SELECT statement', pattern: /\bSELECT\s[\w*"`.,\s]{0,4096}?\bFROM\b/i },
   { label: 'INSERT statement', pattern: /\bINSERT\s+INTO\b/i },
   { label: 'UPDATE statement', pattern: /\bUPDATE\s+\w+\s+SET\b/i },
   { label: 'DELETE statement', pattern: /\bDELETE\s+FROM\b/i },
   { label: 'CREATE TABLE statement', pattern: /\bCREATE\s+TABLE\b/i },
   { label: 'ALTER TABLE statement', pattern: /\bALTER\s+TABLE\b/i },
   { label: 'DROP TABLE statement', pattern: /\bDROP\s+TABLE\b/i },
-  { label: 'database call', pattern: /\bdb\s*\.\s*(?:query|findMany|findOne|insert|update|delete|sql|sqlOne)\b/ },
+  {
+    label: 'database call',
+    pattern:
+      /\bdb\s*\.\s*(?:query|queryOne|findMany|findOne|insert|update|delete|sql|sqlOne|aggregate|count|exists|transaction)\b/
+  },
   { label: 'sliceSchema symbol', pattern: /\bsliceSchema\b/ },
   { label: 'test runner import', pattern: /from\s+['"]bun:test['"]/ },
   { label: 'process.env access', pattern: /\bprocess\s*(?:\.\s*env|\[\s*['"]env['"]\s*\])/ },
@@ -507,6 +521,20 @@ function unwrapPromiseType(typeText: string): string {
   return match ? match[1].trim() : `Awaited<${typeText}>`;
 }
 
+/**
+ * A wire stub describes a server *function*. A server-owned value that a component
+ * references has no wire form, so the caller must fail with a diagnostic instead of
+ * emitting a stub that would call the endpoint as if it were an action.
+ */
+function isStubCandidate(entry: DeclEntry): boolean {
+  return (
+    ts.isFunctionDeclaration(entry.node) ||
+    ts.isFunctionExpression(entry.node) ||
+    ts.isArrowFunction(entry.node) ||
+    ts.isMethodDeclaration(entry.node)
+  );
+}
+
 function renderRpcStub(entry: DeclEntry, endpoint: string, sourceFile: ts.SourceFile): string {
   const fn = entry.node as ts.FunctionDeclaration;
   const payload = fn.parameters[0];
@@ -712,6 +740,27 @@ export function splitSlice(sliceFilePath: string, baseDir: string = process.cwd(
   const sliceName = path.basename(sliceFilePath, '.slice.tsx');
   const relativePath = path.relative(baseDir, sliceFilePath);
   const endpoint = `/_synapse/rpc/${sliceName}`;
+
+  const serverValueInClient = stubbedKeys.find((key) => {
+    const entry = entries.get(key);
+
+    return entry ? !isStubCandidate(entry) : false;
+  });
+
+  if (serverValueInClient) {
+    const entry = entries.get(serverValueInClient) as DeclEntry;
+
+    return Err({
+      code: 'SERVER_VALUE_IN_CLIENT',
+      message:
+        `O componente de ${path.basename(sliceFilePath)} referencia '${serverValueInClient}', ` +
+        `que é um valor do servidor (${ts.SyntaxKind[entry.node.kind]}) e não uma action: não existe ` +
+        `forma de transportá-lo pelo endpoint RPC. Mova o valor para um módulo em src/shared/, ` +
+        `importe-o de 'synapsejs/client', ou limite-se a declará-lo no servidor.`,
+      candidates: [serverValueInClient]
+    });
+  }
+
   const artifacts: SplitArtifact[] = [];
   const outDir = artifactDirectory(baseDir, sliceName);
   const sourceDir = path.dirname(sliceFilePath);
@@ -774,7 +823,8 @@ export function splitSlice(sliceFilePath: string, baseDir: string = process.cwd(
     )
   });
 
-  return Ok({ sliceName, artifacts });
+  const lineCount = sourceFile.text.split('\n').length;
+  return Ok({ sliceName, artifacts, lineCount });
 }
 
 export function writeSplitArtifacts(result: SplitResult, outDir: string): string[] {
@@ -855,8 +905,20 @@ export function verifySplit(result: SplitResult, outDir: string): SplitVerificat
     }
   }
 
+  if (result.lineCount && result.lineCount > 500) {
+    diagnostics.push({
+      file: `${result.sliceName}.slice.tsx`,
+      line: 1,
+      column: 1,
+      code: 'WARN_LARGE_SLICE',
+      message: `Fatia excede 500 linhas (${result.lineCount} linhas). Para manter alta densidade sem sobrecarregar agentes de IA e humanos, considere decompor este domínio em sub-fatias de intenção de negócio com <SubSlice> e src/shared/ (consulte docs/arquitetura-sistemas-grandes.pt-BR.md).`
+    });
+  }
+
+  const hasErrors = diagnostics.some((d) => !d.code.startsWith('WARN_'));
+
   return {
-    status: diagnostics.length === 0 && leaks.length === 0 ? 'PASS' : 'FAIL',
+    status: !hasErrors && leaks.length === 0 ? 'PASS' : 'FAIL',
     diagnostics,
     leaks
   };