@mmapp/react-compiler 0.1.0-alpha.1 → 0.1.0-alpha.4

package/dist/envelope.mjs

@@ -1,9 +1,9 @@
 import {
   buildEnvelope
-} from "./chunk-FX6URXWN.mjs";
+} from "./chunk-R2DD5GTY.mjs";
 import "./chunk-5M7DKKBC.mjs";
-import "./chunk-HLRGCCIL.mjs";
-import "./chunk-Y6FXYEAI.mjs";
+import "./chunk-7T6Q5KAA.mjs";
+import "./chunk-CIESM3BP.mjs";
 export {
   buildEnvelope
 };

package/dist/index-CEKyyazf.d.mts

@@ -0,0 +1,104 @@
+import * as _babel_traverse from '@babel/traverse';
+import { IRActionDefinition, IRFieldDefinition, IRStateDefinition, IRTransitionDefinition, IROnEventSubscription, IRExperienceNode, IRGrammarIsland, CompilerErrorCode } from '@mmapp/player-core';
+
+/**
+ * Change Extractor — extracts useOnChange calls and converts them to field watcher metadata.
+ *
+ * INPUT:
+ *   useOnChange('status', (newVal, oldVal) => {
+ *     console.log(`Status changed from ${oldVal} to ${newVal}`);
+ *   });
+ *
+ * OUTPUT (stored in compilerState metadata.fieldWatchers[]):
+ *   {
+ *     id: "watcher_1",
+ *     field: "status",
+ *     actions: [{ id: "auto_N", type: "log_event", mode: "auto", config: { message: "..." } }]
+ *   }
+ */
+
+interface FieldWatcher {
+    id: string;
+    field: string;
+    actions: IRActionDefinition[];
+}
+
+/**
+ * Transition Effect Extractor — extracts useOnTransition calls.
+ *
+ * INPUT:
+ *   useOnTransition(({ from, to }) => {
+ *     console.log(`Transitioned from ${from} to ${to}`);
+ *   });
+ *
+ * OUTPUT (stored in compilerState metadata.transitionEffects[]):
+ *   {
+ *     id: "transition_effect_1",
+ *     actions: [{ id: "auto_N", type: "log_event", mode: "auto", config: { message: "..." } }]
+ *   }
+ */
+
+interface TransitionEffect {
+    id: string;
+    actions: IRActionDefinition[];
+}
+
+/**
+ * Internal types for the compiler state and extracted data.
+ */
+
+interface ExtractedWorkflow {
+    slug: string;
+    name: string;
+    version: string;
+    description?: string;
+    category: string;
+    fields: IRFieldDefinition[];
+    states: Map<string, IRStateDefinition>;
+    transitions: IRTransitionDefinition[];
+    events: IROnEventSubscription[];
+    experience?: IRExperienceNode;
+    fieldWatchers?: FieldWatcher[];
+    transitionEffects?: TransitionEffect[];
+    grammarIslands?: IRGrammarIsland[];
+    errors?: ReactCompilerError[];
+    warnings?: ReactCompilerError[];
+    /** Extra metadata from model files (runtime, fieldOptions, etc.) */
+    extraMetadata?: Record<string, unknown>;
+}
+interface CompilerState {
+    fields: IRFieldDefinition[];
+    states: Map<string, IRStateDefinition>;
+    transitions: IRTransitionDefinition[];
+    events: IROnEventSubscription[];
+    experience?: IRExperienceNode;
+    actionCounter: number;
+    metadata: {
+        slug?: string;
+        name?: string;
+        version?: string;
+        description?: string;
+        category?: string;
+        [key: string]: unknown;
+    };
+    errors?: ReactCompilerError[];
+    warnings?: ReactCompilerError[];
+}
+interface CompilerOptions {
+    mode?: 'strict' | 'infer';
+    filename?: string;
+}
+interface ReactCompilerError {
+    code: CompilerErrorCode;
+    message: string;
+    line?: number;
+    column?: number;
+    severity: 'error' | 'warning';
+}
+
+declare function babelPlugin(api: any, options?: CompilerOptions): {
+    name: string;
+    visitor: _babel_traverse.Visitor;
+};
+
+export { type CompilerState as C, type ExtractedWorkflow as E, type ReactCompilerError as R, type CompilerOptions as a, babelPlugin as b };

package/dist/index-CEKyyazf.d.ts

@@ -0,0 +1,104 @@
+import * as _babel_traverse from '@babel/traverse';
+import { IRActionDefinition, IRFieldDefinition, IRStateDefinition, IRTransitionDefinition, IROnEventSubscription, IRExperienceNode, IRGrammarIsland, CompilerErrorCode } from '@mmapp/player-core';
+
+/**
+ * Change Extractor — extracts useOnChange calls and converts them to field watcher metadata.
+ *
+ * INPUT:
+ *   useOnChange('status', (newVal, oldVal) => {
+ *     console.log(`Status changed from ${oldVal} to ${newVal}`);
+ *   });
+ *
+ * OUTPUT (stored in compilerState metadata.fieldWatchers[]):
+ *   {
+ *     id: "watcher_1",
+ *     field: "status",
+ *     actions: [{ id: "auto_N", type: "log_event", mode: "auto", config: { message: "..." } }]
+ *   }
+ */
+
+interface FieldWatcher {
+    id: string;
+    field: string;
+    actions: IRActionDefinition[];
+}
+
+/**
+ * Transition Effect Extractor — extracts useOnTransition calls.
+ *
+ * INPUT:
+ *   useOnTransition(({ from, to }) => {
+ *     console.log(`Transitioned from ${from} to ${to}`);
+ *   });
+ *
+ * OUTPUT (stored in compilerState metadata.transitionEffects[]):
+ *   {
+ *     id: "transition_effect_1",
+ *     actions: [{ id: "auto_N", type: "log_event", mode: "auto", config: { message: "..." } }]
+ *   }
+ */
+
+interface TransitionEffect {
+    id: string;
+    actions: IRActionDefinition[];
+}
+
+/**
+ * Internal types for the compiler state and extracted data.
+ */
+
+interface ExtractedWorkflow {
+    slug: string;
+    name: string;
+    version: string;
+    description?: string;
+    category: string;
+    fields: IRFieldDefinition[];
+    states: Map<string, IRStateDefinition>;
+    transitions: IRTransitionDefinition[];
+    events: IROnEventSubscription[];
+    experience?: IRExperienceNode;
+    fieldWatchers?: FieldWatcher[];
+    transitionEffects?: TransitionEffect[];
+    grammarIslands?: IRGrammarIsland[];
+    errors?: ReactCompilerError[];
+    warnings?: ReactCompilerError[];
+    /** Extra metadata from model files (runtime, fieldOptions, etc.) */
+    extraMetadata?: Record<string, unknown>;
+}
+interface CompilerState {
+    fields: IRFieldDefinition[];
+    states: Map<string, IRStateDefinition>;
+    transitions: IRTransitionDefinition[];
+    events: IROnEventSubscription[];
+    experience?: IRExperienceNode;
+    actionCounter: number;
+    metadata: {
+        slug?: string;
+        name?: string;
+        version?: string;
+        description?: string;
+        category?: string;
+        [key: string]: unknown;
+    };
+    errors?: ReactCompilerError[];
+    warnings?: ReactCompilerError[];
+}
+interface CompilerOptions {
+    mode?: 'strict' | 'infer';
+    filename?: string;
+}
+interface ReactCompilerError {
+    code: CompilerErrorCode;
+    message: string;
+    line?: number;
+    column?: number;
+    severity: 'error' | 'warning';
+}
+
+declare function babelPlugin(api: any, options?: CompilerOptions): {
+    name: string;
+    visitor: _babel_traverse.Visitor;
+};
+
+export { type CompilerState as C, type ExtractedWorkflow as E, type ReactCompilerError as R, type CompilerOptions as a, babelPlugin as b };

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { E as ExtractedWorkflow, C as CompilerState, a as CompilerOptions } from './index-revho_gS.mjs';
-export { R as ReactCompilerError, b as babelPlugin } from './index-revho_gS.mjs';
+import { E as ExtractedWorkflow, C as CompilerState, a as CompilerOptions } from './index-CEKyyazf.mjs';
+export { R as ReactCompilerError, b as babelPlugin } from './index-CEKyyazf.mjs';
 import { NodePath, Visitor } from '@babel/traverse';
 import * as t from '@babel/types';
-import { IRWorkflowDefinition, PureFormWorkflow, IRDataSource, IRExperienceNode as IRExperienceNode$1 } from '@mindmatrix/player-core';
-export { B as BuildOptions, d as BuildResult, a as DevServerInstance, D as DevServerOptions, b as build, c as createDevServer } from './dev-server-Bs_sz2DG.mjs';
-import { F as FileRole } from './envelope-DD7v0v6E.mjs';
-export { B as BuildEnvelopeOptions, c as BuildEnvelopeResult, a as EnvelopeFile, E as EnvelopeManifest, i as EnvelopeMetadata, n as FsTree, o as FsTreeEntry, h as SourceBinding, S as SourceEnvelope, b as buildEnvelope, e as computeEnvelopeId, d as createSourceEnvelope, k as detectFileRole, g as diffEnvelopes, m as diffFsTrees, f as envelopesEqual, l as filterByRole, j as generateFsTree } from './envelope-DD7v0v6E.mjs';
+import { IRWorkflowDefinition, PureFormWorkflow, IRDataSource, IRExperienceNode as IRExperienceNode$1 } from '@mmapp/player-core';
+export { B as BuildOptions, d as BuildResult, a as DevServerInstance, D as DevServerOptions, b as build, c as createDevServer } from './dev-server-CrQ041KP.mjs';
+import { F as FileRole } from './envelope-ChEkuHij.mjs';
+export { B as BuildEnvelopeOptions, c as BuildEnvelopeResult, a as EnvelopeFile, E as EnvelopeManifest, i as EnvelopeMetadata, n as FsTree, o as FsTreeEntry, h as SourceBinding, S as SourceEnvelope, b as buildEnvelope, e as computeEnvelopeId, d as createSourceEnvelope, k as detectFileRole, g as diffEnvelopes, m as diffFsTrees, f as envelopesEqual, l as filterByRole, j as generateFsTree } from './envelope-ChEkuHij.mjs';
 import 'vite';
 
 /**
@@ -425,7 +425,7 @@ declare function decompile(definition: DecompilerInput, options?: DecompileOptio
  *   - useQuery/useMutation data sources
  *   - JSX return tree from experience nodes
  *   - @workflow JSDoc header
- *   - Proper imports from @mindmatrix/react
+ *   - Proper imports from @mmapp/react
  *
  * @param definition - The IR workflow definition (with optional experience tree).
  * @param options - Decompile options (componentName, includeAnnotation, etc.).
@@ -499,7 +499,7 @@ declare function extractComputed(path: NodePath<t.CallExpression>, state: any):
 /**
  * Babel Visitor — main AST traversal logic for extracting workflow definitions.
  *
- * Handles all @mindmatrix/react hooks:
+ * Handles all @mmapp/react hooks:
  * - useState → fields
  * - useOnEnter / useOnExit → state enter/exit actions
  * - useTransition → transitions
@@ -581,6 +581,8 @@ interface DeployOptions {
     dryRun?: boolean;
     /** Write deploy report to this file. */
     reportFile?: string;
+    /** Resolved target name (for display). */
+    targetName?: string;
 }
 interface DeployResult {
     created: string[];
@@ -591,6 +593,11 @@ interface DeployResult {
         slug: string;
         error: string;
     }[];
+    services?: {
+        registered: string[];
+        updated: string[];
+        failed: string[];
+    };
 }
 declare function deploy(options: DeployOptions): Promise<DeployResult>;
 
@@ -962,6 +969,8 @@ interface ResolvedModule {
         icon?: string;
         showInNav?: boolean;
     }>;
+    /** The module's server actions (merged into parent with namespace prefix). */
+    serverActions?: ServerActionEntry[];
 }
 interface ProjectCompilerOptions {
     /** Compilation mode: strict or infer. Default: 'infer'. */
@@ -1001,6 +1010,8 @@ interface ProjectCompilationResult {
     actionResult?: ActionCompilationResult;
     /** Phase 2: Route extraction result (if usePhase2Modules enabled). */
     routeResult?: RouteExtractionResult;
+    /** Generated .d.ts type stubs for module dependencies, keyed by relative path. */
+    typeStubs?: Record<string, string>;
 }
 interface ProjectCompilationError {
     file: string;
@@ -1096,4 +1107,152 @@ declare class IncrementalProjectCompiler {
     } & IncrementalStats;
 }
 
-export { type ActionCompilationResult, type ActionCompilerOptions, CompilerOptions, CompilerState, type ComputedFieldExtraction, type DecompileOptions, type DecompileProjectOptions, type DecompileProjectResult, type DecompileResult, type DecompilerInput, type DependencyEdge, type DeployOptions, type DeployResult, type DirtyFileSet, ExtractedWorkflow, type FileHash, FileRole, type FrontendDataSource, type FrontendExperienceNode, type ImportLink, IncrementalCache, IncrementalProjectCompiler, type IncrementalStats, type LayoutEntry, type ModelCompilationResult, type ModelCompilerOptions, type ProjectCompilationError, type ProjectCompilationResult, type ProjectCompilerOptions, type ProjectFile, type RoundTripDiff, type RoundTripResult, type RouteEntry, type RouteExtractionResult, type RouteExtractorOptions, type RouteTableEntry, type ServerActionEntry, type ServerActionRegistration, buildDependencyGraph, compileActions, compileModel, compileModels, compileProject, compileSource, compilerStateToWorkflow, computeTransitiveDirtySet, createVisitor, decompile, decompileProject, decompileToTSX, deploy, emitCanonical, emitCompiledOutput, emitIR, emitPureForm, extractComponents, extractComputed, extractEffects, extractEvents, extractImports, extractRoutes, extractStates, extractTransitions, hashContent, normalizeDecompilerInput, resolveActionReferences, resolveImport, shouldDecompileAsProject, topologicalSort, transformToFrontend, validateRoundTrip, validateSourceRoundTrip };
+/**
+ * Diagnostic System — structured error/warning/info/hint collection and formatting.
+ *
+ * Provides a DiagnosticCollector that accumulates diagnostics during compilation,
+ * categorized by severity and tagged with machine-readable codes.
+ *
+ * Diagnostic codes are namespaced by extractor:
+ *   FLOW001-099  — Flow (imperative workflow) extractor
+ *   MDLW001-099  — Middleware extractor
+ *   CNST001-099  — Constraint extractor
+ *   ACTR001-099  — Actor extractor
+ *   HOOK001-099  — Hook-based visitor diagnostics
+ *   MODL001-099  — Model extractor
+ *   EMIT001-099  — Emitter diagnostics
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';
+interface DiagnosticLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+}
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+}
+/**
+ * All known diagnostic codes with their default messages.
+ * Extractors reference these codes when reporting issues.
+ */
+declare const DIAGNOSTIC_CODES: {
+    readonly FLOW001: "No default export async function found";
+    readonly FLOW002: "Workflow function has no typed parameter";
+    readonly FLOW003: "Interface not found for parameter type";
+    readonly FLOW004: "Unknown function call in workflow body";
+    readonly FLOW005: "userAction() without a following state (cannot resolve transition target)";
+    readonly FLOW006: "Import could not be resolved as a service";
+    readonly FLOW007: "validate() with unparseable condition";
+    readonly MDLW001: "defineMiddleware() missing required 'name' field";
+    readonly MDLW002: "Invalid match pattern format";
+    readonly MDLW003: "No before/after/around handler defined";
+    readonly CNST001: "Unknown built-in constraint name";
+    readonly CNST002: "Empty constraint list";
+    readonly ACTR001: "Invalid supervision strategy";
+    readonly ACTR002: "spawnActor() called outside workflow function";
+    readonly HOOK001: "Forbidden hook in strict mode";
+    readonly HOOK002: "Raw useEffect in infer mode (component becomes opaque)";
+    readonly HOOK003: "Forbidden import in strict mode";
+    readonly MODL001: "defineModel() missing required fields";
+    readonly MODL002: "Unknown field type in model definition";
+    readonly EMIT001: "Empty workflow — no states, fields, or experience extracted";
+};
+type DiagnosticCode = keyof typeof DIAGNOSTIC_CODES;
+declare class DiagnosticCollector {
+    private diagnostics;
+    /**
+     * Record an error diagnostic.
+     */
+    error(code: string, message: string, location?: DiagnosticLocation, suggestion?: string): void;
+    /**
+     * Record a warning diagnostic.
+     */
+    warning(code: string, message: string, location?: DiagnosticLocation, suggestion?: string): void;
+    /**
+     * Record an informational diagnostic.
+     */
+    info(code: string, message: string): void;
+    /**
+     * Record a hint diagnostic (always includes a suggestion).
+     */
+    hint(code: string, message: string, suggestion: string): void;
+    /**
+     * Whether any error-level diagnostics have been recorded.
+     */
+    hasErrors(): boolean;
+    /**
+     * Whether any warning-level diagnostics have been recorded.
+     */
+    hasWarnings(): boolean;
+    /**
+     * Total number of diagnostics collected.
+     */
+    get count(): number;
+    /**
+     * Return all collected diagnostics.
+     */
+    getAll(): Diagnostic[];
+    /**
+     * Return only error-severity diagnostics.
+     */
+    getErrors(): Diagnostic[];
+    /**
+     * Return only warning-severity diagnostics.
+     */
+    getWarnings(): Diagnostic[];
+    /**
+     * Return only info-severity diagnostics.
+     */
+    getInfos(): Diagnostic[];
+    /**
+     * Return only hint-severity diagnostics.
+     */
+    getHints(): Diagnostic[];
+    /**
+     * Merge diagnostics from another collector into this one.
+     */
+    merge(other: DiagnosticCollector): void;
+    /**
+     * Clear all collected diagnostics.
+     */
+    clear(): void;
+    /**
+     * Pretty-print all diagnostics for terminal output.
+     *
+     * Format:
+     *   error[FLOW001]: No default export async function found
+     *     --> models/task.ts
+     *     = hint: Add `export default async function taskWorkflow(task: Task) { ... }`
+     *
+     *   warning[FLOW004]: Unknown function 'processData' in workflow body
+     *     --> models/order.ts:15:5
+     *     = note: Not a local async function, not imported, and not a stdlib function
+     *     = hint: Did you mean to import it?
+     */
+    format(): string;
+    /**
+     * Machine-readable JSON representation.
+     */
+    toJSON(): {
+        diagnostics: Diagnostic[];
+        summary: {
+            errors: number;
+            warnings: number;
+            infos: number;
+            hints: number;
+            total: number;
+        };
+    };
+}
+/**
+ * Create a fresh DiagnosticCollector instance.
+ */
+declare function createDiagnosticCollector(): DiagnosticCollector;
+
+export { type ActionCompilationResult, type ActionCompilerOptions, CompilerOptions, CompilerState, type ComputedFieldExtraction, DIAGNOSTIC_CODES, type DecompileOptions, type DecompileProjectOptions, type DecompileProjectResult, type DecompileResult, type DecompilerInput, type DependencyEdge, type DeployOptions, type DeployResult, type Diagnostic, type DiagnosticCode, DiagnosticCollector, type DiagnosticLocation, type DiagnosticSeverity, type DirtyFileSet, ExtractedWorkflow, type FileHash, FileRole, type FrontendDataSource, type FrontendExperienceNode, type ImportLink, IncrementalCache, IncrementalProjectCompiler, type IncrementalStats, type LayoutEntry, type ModelCompilationResult, type ModelCompilerOptions, type ProjectCompilationError, type ProjectCompilationResult, type ProjectCompilerOptions, type ProjectFile, type RoundTripDiff, type RoundTripResult, type RouteEntry, type RouteExtractionResult, type RouteExtractorOptions, type RouteTableEntry, type ServerActionEntry, type ServerActionRegistration, buildDependencyGraph, compileActions, compileModel, compileModels, compileProject, compileSource, compilerStateToWorkflow, computeTransitiveDirtySet, createDiagnosticCollector, createVisitor, decompile, decompileProject, decompileToTSX, deploy, emitCanonical, emitCompiledOutput, emitIR, emitPureForm, extractComponents, extractComputed, extractEffects, extractEvents, extractImports, extractRoutes, extractStates, extractTransitions, hashContent, normalizeDecompilerInput, resolveActionReferences, resolveImport, shouldDecompileAsProject, topologicalSort, transformToFrontend, validateRoundTrip, validateSourceRoundTrip };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { E as ExtractedWorkflow, C as CompilerState, a as CompilerOptions } from './index-revho_gS.js';
-export { R as ReactCompilerError, b as babelPlugin } from './index-revho_gS.js';
+import { E as ExtractedWorkflow, C as CompilerState, a as CompilerOptions } from './index-CEKyyazf.js';
+export { R as ReactCompilerError, b as babelPlugin } from './index-CEKyyazf.js';
 import { NodePath, Visitor } from '@babel/traverse';
 import * as t from '@babel/types';
-import { IRWorkflowDefinition, PureFormWorkflow, IRDataSource, IRExperienceNode as IRExperienceNode$1 } from '@mindmatrix/player-core';
-export { B as BuildOptions, d as BuildResult, a as DevServerInstance, D as DevServerOptions, b as build, c as createDevServer } from './dev-server-Bs_sz2DG.js';
-import { F as FileRole } from './envelope-DD7v0v6E.js';
-export { B as BuildEnvelopeOptions, c as BuildEnvelopeResult, a as EnvelopeFile, E as EnvelopeManifest, i as EnvelopeMetadata, n as FsTree, o as FsTreeEntry, h as SourceBinding, S as SourceEnvelope, b as buildEnvelope, e as computeEnvelopeId, d as createSourceEnvelope, k as detectFileRole, g as diffEnvelopes, m as diffFsTrees, f as envelopesEqual, l as filterByRole, j as generateFsTree } from './envelope-DD7v0v6E.js';
+import { IRWorkflowDefinition, PureFormWorkflow, IRDataSource, IRExperienceNode as IRExperienceNode$1 } from '@mmapp/player-core';
+export { B as BuildOptions, d as BuildResult, a as DevServerInstance, D as DevServerOptions, b as build, c as createDevServer } from './dev-server-CrQ041KP.js';
+import { F as FileRole } from './envelope-ChEkuHij.js';
+export { B as BuildEnvelopeOptions, c as BuildEnvelopeResult, a as EnvelopeFile, E as EnvelopeManifest, i as EnvelopeMetadata, n as FsTree, o as FsTreeEntry, h as SourceBinding, S as SourceEnvelope, b as buildEnvelope, e as computeEnvelopeId, d as createSourceEnvelope, k as detectFileRole, g as diffEnvelopes, m as diffFsTrees, f as envelopesEqual, l as filterByRole, j as generateFsTree } from './envelope-ChEkuHij.js';
 import 'vite';
 
 /**
@@ -425,7 +425,7 @@ declare function decompile(definition: DecompilerInput, options?: DecompileOptio
  *   - useQuery/useMutation data sources
  *   - JSX return tree from experience nodes
  *   - @workflow JSDoc header
- *   - Proper imports from @mindmatrix/react
+ *   - Proper imports from @mmapp/react
  *
  * @param definition - The IR workflow definition (with optional experience tree).
  * @param options - Decompile options (componentName, includeAnnotation, etc.).
@@ -499,7 +499,7 @@ declare function extractComputed(path: NodePath<t.CallExpression>, state: any):
 /**
  * Babel Visitor — main AST traversal logic for extracting workflow definitions.
  *
- * Handles all @mindmatrix/react hooks:
+ * Handles all @mmapp/react hooks:
  * - useState → fields
  * - useOnEnter / useOnExit → state enter/exit actions
  * - useTransition → transitions
@@ -581,6 +581,8 @@ interface DeployOptions {
     dryRun?: boolean;
     /** Write deploy report to this file. */
     reportFile?: string;
+    /** Resolved target name (for display). */
+    targetName?: string;
 }
 interface DeployResult {
     created: string[];
@@ -591,6 +593,11 @@ interface DeployResult {
         slug: string;
         error: string;
     }[];
+    services?: {
+        registered: string[];
+        updated: string[];
+        failed: string[];
+    };
 }
 declare function deploy(options: DeployOptions): Promise<DeployResult>;
 
@@ -962,6 +969,8 @@ interface ResolvedModule {
         icon?: string;
         showInNav?: boolean;
     }>;
+    /** The module's server actions (merged into parent with namespace prefix). */
+    serverActions?: ServerActionEntry[];
 }
 interface ProjectCompilerOptions {
     /** Compilation mode: strict or infer. Default: 'infer'. */
@@ -1001,6 +1010,8 @@ interface ProjectCompilationResult {
     actionResult?: ActionCompilationResult;
     /** Phase 2: Route extraction result (if usePhase2Modules enabled). */
     routeResult?: RouteExtractionResult;
+    /** Generated .d.ts type stubs for module dependencies, keyed by relative path. */
+    typeStubs?: Record<string, string>;
 }
 interface ProjectCompilationError {
     file: string;
@@ -1096,4 +1107,152 @@ declare class IncrementalProjectCompiler {
     } & IncrementalStats;
 }
 
-export { type ActionCompilationResult, type ActionCompilerOptions, CompilerOptions, CompilerState, type ComputedFieldExtraction, type DecompileOptions, type DecompileProjectOptions, type DecompileProjectResult, type DecompileResult, type DecompilerInput, type DependencyEdge, type DeployOptions, type DeployResult, type DirtyFileSet, ExtractedWorkflow, type FileHash, FileRole, type FrontendDataSource, type FrontendExperienceNode, type ImportLink, IncrementalCache, IncrementalProjectCompiler, type IncrementalStats, type LayoutEntry, type ModelCompilationResult, type ModelCompilerOptions, type ProjectCompilationError, type ProjectCompilationResult, type ProjectCompilerOptions, type ProjectFile, type RoundTripDiff, type RoundTripResult, type RouteEntry, type RouteExtractionResult, type RouteExtractorOptions, type RouteTableEntry, type ServerActionEntry, type ServerActionRegistration, buildDependencyGraph, compileActions, compileModel, compileModels, compileProject, compileSource, compilerStateToWorkflow, computeTransitiveDirtySet, createVisitor, decompile, decompileProject, decompileToTSX, deploy, emitCanonical, emitCompiledOutput, emitIR, emitPureForm, extractComponents, extractComputed, extractEffects, extractEvents, extractImports, extractRoutes, extractStates, extractTransitions, hashContent, normalizeDecompilerInput, resolveActionReferences, resolveImport, shouldDecompileAsProject, topologicalSort, transformToFrontend, validateRoundTrip, validateSourceRoundTrip };
+/**
+ * Diagnostic System — structured error/warning/info/hint collection and formatting.
+ *
+ * Provides a DiagnosticCollector that accumulates diagnostics during compilation,
+ * categorized by severity and tagged with machine-readable codes.
+ *
+ * Diagnostic codes are namespaced by extractor:
+ *   FLOW001-099  — Flow (imperative workflow) extractor
+ *   MDLW001-099  — Middleware extractor
+ *   CNST001-099  — Constraint extractor
+ *   ACTR001-099  — Actor extractor
+ *   HOOK001-099  — Hook-based visitor diagnostics
+ *   MODL001-099  — Model extractor
+ *   EMIT001-099  — Emitter diagnostics
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';
+interface DiagnosticLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+}
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+}
+/**
+ * All known diagnostic codes with their default messages.
+ * Extractors reference these codes when reporting issues.
+ */
+declare const DIAGNOSTIC_CODES: {
+    readonly FLOW001: "No default export async function found";
+    readonly FLOW002: "Workflow function has no typed parameter";
+    readonly FLOW003: "Interface not found for parameter type";
+    readonly FLOW004: "Unknown function call in workflow body";
+    readonly FLOW005: "userAction() without a following state (cannot resolve transition target)";
+    readonly FLOW006: "Import could not be resolved as a service";
+    readonly FLOW007: "validate() with unparseable condition";
+    readonly MDLW001: "defineMiddleware() missing required 'name' field";
+    readonly MDLW002: "Invalid match pattern format";
+    readonly MDLW003: "No before/after/around handler defined";
+    readonly CNST001: "Unknown built-in constraint name";
+    readonly CNST002: "Empty constraint list";
+    readonly ACTR001: "Invalid supervision strategy";
+    readonly ACTR002: "spawnActor() called outside workflow function";
+    readonly HOOK001: "Forbidden hook in strict mode";
+    readonly HOOK002: "Raw useEffect in infer mode (component becomes opaque)";
+    readonly HOOK003: "Forbidden import in strict mode";
+    readonly MODL001: "defineModel() missing required fields";
+    readonly MODL002: "Unknown field type in model definition";
+    readonly EMIT001: "Empty workflow — no states, fields, or experience extracted";
+};
+type DiagnosticCode = keyof typeof DIAGNOSTIC_CODES;
+declare class DiagnosticCollector {
+    private diagnostics;
+    /**
+     * Record an error diagnostic.
+     */
+    error(code: string, message: string, location?: DiagnosticLocation, suggestion?: string): void;
+    /**
+     * Record a warning diagnostic.
+     */
+    warning(code: string, message: string, location?: DiagnosticLocation, suggestion?: string): void;
+    /**
+     * Record an informational diagnostic.
+     */
+    info(code: string, message: string): void;
+    /**
+     * Record a hint diagnostic (always includes a suggestion).
+     */
+    hint(code: string, message: string, suggestion: string): void;
+    /**
+     * Whether any error-level diagnostics have been recorded.
+     */
+    hasErrors(): boolean;
+    /**
+     * Whether any warning-level diagnostics have been recorded.
+     */
+    hasWarnings(): boolean;
+    /**
+     * Total number of diagnostics collected.
+     */
+    get count(): number;
+    /**
+     * Return all collected diagnostics.
+     */
+    getAll(): Diagnostic[];
+    /**
+     * Return only error-severity diagnostics.
+     */
+    getErrors(): Diagnostic[];
+    /**
+     * Return only warning-severity diagnostics.
+     */
+    getWarnings(): Diagnostic[];
+    /**
+     * Return only info-severity diagnostics.
+     */
+    getInfos(): Diagnostic[];
+    /**
+     * Return only hint-severity diagnostics.
+     */
+    getHints(): Diagnostic[];
+    /**
+     * Merge diagnostics from another collector into this one.
+     */
+    merge(other: DiagnosticCollector): void;
+    /**
+     * Clear all collected diagnostics.
+     */
+    clear(): void;
+    /**
+     * Pretty-print all diagnostics for terminal output.
+     *
+     * Format:
+     *   error[FLOW001]: No default export async function found
+     *     --> models/task.ts
+     *     = hint: Add `export default async function taskWorkflow(task: Task) { ... }`
+     *
+     *   warning[FLOW004]: Unknown function 'processData' in workflow body
+     *     --> models/order.ts:15:5
+     *     = note: Not a local async function, not imported, and not a stdlib function
+     *     = hint: Did you mean to import it?
+     */
+    format(): string;
+    /**
+     * Machine-readable JSON representation.
+     */
+    toJSON(): {
+        diagnostics: Diagnostic[];
+        summary: {
+            errors: number;
+            warnings: number;
+            infos: number;
+            hints: number;
+            total: number;
+        };
+    };
+}
+/**
+ * Create a fresh DiagnosticCollector instance.
+ */
+declare function createDiagnosticCollector(): DiagnosticCollector;
+
+export { type ActionCompilationResult, type ActionCompilerOptions, CompilerOptions, CompilerState, type ComputedFieldExtraction, DIAGNOSTIC_CODES, type DecompileOptions, type DecompileProjectOptions, type DecompileProjectResult, type DecompileResult, type DecompilerInput, type DependencyEdge, type DeployOptions, type DeployResult, type Diagnostic, type DiagnosticCode, DiagnosticCollector, type DiagnosticLocation, type DiagnosticSeverity, type DirtyFileSet, ExtractedWorkflow, type FileHash, FileRole, type FrontendDataSource, type FrontendExperienceNode, type ImportLink, IncrementalCache, IncrementalProjectCompiler, type IncrementalStats, type LayoutEntry, type ModelCompilationResult, type ModelCompilerOptions, type ProjectCompilationError, type ProjectCompilationResult, type ProjectCompilerOptions, type ProjectFile, type RoundTripDiff, type RoundTripResult, type RouteEntry, type RouteExtractionResult, type RouteExtractorOptions, type RouteTableEntry, type ServerActionEntry, type ServerActionRegistration, buildDependencyGraph, compileActions, compileModel, compileModels, compileProject, compileSource, compilerStateToWorkflow, computeTransitiveDirtySet, createDiagnosticCollector, createVisitor, decompile, decompileProject, decompileToTSX, deploy, emitCanonical, emitCompiledOutput, emitIR, emitPureForm, extractComponents, extractComputed, extractEffects, extractEvents, extractImports, extractRoutes, extractStates, extractTransitions, hashContent, normalizeDecompilerInput, resolveActionReferences, resolveImport, shouldDecompileAsProject, topologicalSort, transformToFrontend, validateRoundTrip, validateSourceRoundTrip };