@supacloud/compiler 0.4.1 → 0.6.0

package/dist/inspect.d.ts

@@ -0,0 +1,21 @@
+import type { ApplicationGraph, Diagnostic } from "./types";
+export interface DoctorResult {
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        detail: string;
+    }>;
+    diagnostics: ApplicationGraph["diagnostics"];
+    errors: number;
+}
+export declare function formatGraph(graph: ApplicationGraph): string;
+export declare function explainGraph(graph: ApplicationGraph, subject: string): string;
+export declare function doctorProject(rootDir: string, outDir: string, graph: ApplicationGraph, upToDate: boolean, diagnostics?: Diagnostic[]): DoctorResult;
+/**
+ * Exports the application module architecture as a Mermaid graph diagram.
+ */
+export declare function exportGraphMermaid(graph: ApplicationGraph): string;
+/**
+ * Exports the application module architecture as a Graphviz DOT script.
+ */
+export declare function exportGraphDot(graph: ApplicationGraph): string;

package/dist/program.d.ts

@@ -0,0 +1,30 @@
+import * as ts from "@typescript/typescript6";
+import { type TraitRecord } from "./traits";
+export interface IncrementalProgramSession {
+    /** The current TypeScript program used as the semantic compilation boundary. */
+    getProgram(): ts.Program;
+    /** The current TypeScript type checker. */
+    getTypeChecker(): ts.TypeChecker;
+    /** Update the program while preserving TypeScript's incremental state. */
+    update(rootNames: string[], changedPaths?: string[]): ProgramUpdate;
+    /** Local Angular-style metadata records compiled from the current Program. */
+    getTraits(): readonly TraitRecord[];
+    /** TypeScript syntactic diagnostics for the current Program. */
+    getDiagnostics(): readonly ts.Diagnostic[];
+    /** Emit the current TypeScript program using the builder's incremental state. */
+    emit(): ts.EmitResult;
+    /** Drop the retained builder and source versions. */
+    reset(): void;
+}
+export interface ProgramUpdate {
+    changedFiles: string[];
+    reusedFiles: string[];
+    program: ts.Program;
+}
+/**
+ * Angular-style semantic boundary around TypeScript's incremental program.
+ *
+ * This deliberately owns only TypeScript program state. SupaCloud metadata
+ * handlers and ApplicationGraph linking remain separate layers.
+ */
+export declare function createIncrementalProgramSession(projectRoot: string): IncrementalProgramSession;

package/dist/traits.d.ts

@@ -0,0 +1,32 @@
+import * as ts from "@typescript/typescript6";
+export type TraitKind = "module" | "injectable" | "controller" | "command" | "query" | "defineModule" | "injectionToken";
+export interface TraitRecord {
+    kind: TraitKind;
+    name: string;
+    file: string;
+    start: number;
+    end: number;
+    fingerprint: string;
+}
+export interface TraitCompilation {
+    byFile: Map<string, TraitRecord[]>;
+    all: TraitRecord[];
+}
+export interface TraitHandler {
+    readonly kind: TraitKind;
+    detect(node: ts.Node): string | undefined;
+}
+export declare class TraitCompiler {
+    private readonly handlers;
+    constructor(handlers?: readonly TraitHandler[]);
+    /**
+     * Angular-style local metadata compiler.
+     *
+     * This pass is intentionally syntax-only. It discovers candidate declarations
+     * cheaply; handlers that need symbols or types run later against the Program's
+     * TypeChecker.
+     */
+    compile(program: ts.Program, previous: TraitCompilation | undefined, changedFiles: Set<string>): TraitCompilation;
+    private compileSourceFile;
+}
+export declare function compileTraits(program: ts.Program, previous: TraitCompilation | undefined, changedFiles: Set<string>): TraitCompilation;

package/dist/type-safety.d.ts

@@ -0,0 +1,9 @@
+import type { Diagnostic, TypeSafetyOptions } from "./types";
+export interface TypeSafetyScanOptions extends TypeSafetyOptions {
+    rootDir: string;
+    include?: string[];
+    outDir?: string;
+    strict?: boolean;
+}
+export declare function scanGeneratedArtifacts(artifacts: Record<string, string | undefined>, strict?: boolean): Diagnostic[];
+export declare function scanProductionSource(options: TypeSafetyScanOptions): Diagnostic[];

package/dist/types.d.ts

@@ -2,15 +2,46 @@
  * ApplicationGraph: Static application graph built by the compiler from source AST.
  * No runtime reflection or container; all metadata is explicitly represented here and in generated code.
  */
+import type { IncrementalProgramSession } from "./program";
 export type Scope = "application" | "request" | "job";
 export type ProviderKind = "class" | "value" | "factory" | "existing";
 export type TokenKind = "injection-token" | "class";
+export interface FunctionalInjectNode {
+    /** Logical token name used by the application graph. */
+    token: string;
+    /** Source expression used to identify the runtime token. */
+    expression: string;
+    /** Relative source module path for the token expression. */
+    importPath?: string;
+    /** Package module specifier for a library token. */
+    importModule?: string;
+    optional?: boolean;
+    self?: boolean;
+    skipSelf?: boolean;
+    host?: boolean;
+}
+export interface AspectRefNode {
+    /** Exported symbol name used in the generated static import. */
+    name: string;
+    /** Source expression retained for diagnostics and manifest inspection. */
+    expression: string;
+    /** Relative source module path for a project-local aspect. */
+    importPath?: string;
+    /** Package module specifier for a library aspect. */
+    importModule?: string;
+}
 export interface Diagnostic {
     severity: "error" | "warn";
     code: string;
     message: string;
     file?: string;
     line?: number;
+    /** Actionable Angular Ivy-style remediation hint. */
+    suggestion?: string;
+    /** Standardized compiler diagnostic code (e.g. SC1001) modeled after Angular ngtsc error codes. */
+    errorCode?: string;
+    /** Documentation URL for this diagnostic. */
+    docsUrl?: string;
 }
 export interface ProviderNode {
     /** Token name (InjectionToken variable name or class name). */
@@ -24,11 +55,36 @@ export interface ProviderNode {
     scope: Scope;
     /** Token names in constructor/factory parameter order. */
     deps: string[];
+    /** Parameter tokens that are marked @Optional() (receive undefined if unresolved). */
+    optionalDeps?: string[];
+    /** Parameter tokens marked @Self() (must be resolved from current module's own providers). */
+    selfDeps?: string[];
+    /** Parameter tokens marked @SkipSelf() (must NOT be resolved from current module's own providers). */
+    skipSelfDeps?: string[];
+    /** Parameter tokens marked @Host(). */
+    hostDeps?: string[];
+    /** Property-level Angular functional inject() calls compiled into a static context. */
+    functionalInjects?: FunctionalInjectNode[];
+    /** When true, multiple providers can contribute to this token as an array of instances (Angular multi-providers). */
+    multi?: boolean;
+    /** Automatically provided in the root injector context without manual module declaration (Angular-style). */
+    providedIn?: "root";
+    /** Class implements OnDestroy interface or onDestroy method. */
+    hasOnDestroy?: boolean;
     exported: boolean;
     file: string;
     line: number;
     /** Relative module path of useClass/useFactory/useValue symbol (for import generation). */
     importPath?: string;
+    /** Package module specifier for providers supplied by a library. */
+    importModule?: string;
+}
+export interface HandlerParamNode {
+    name: string;
+    kind: "param" | "query" | "body" | "headers" | "context" | "unknown";
+    bindingName?: string;
+    transform?: "number" | "boolean" | "string";
+    default?: unknown;
 }
 export interface RouteNode {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
@@ -40,12 +96,60 @@ export interface RouteNode {
     response?: string;
     /** @Command-decorated class explicitly bound by the route. */
     command?: string;
+    /** Route guards executed before handler (Angular CanActivateFn style). */
+    guards?: string[];
+    /** Route matching guards executed before route activation (Angular CanMatchFn style). */
+    canMatch?: string[];
+    /** Route deactivation guards executed before leaving route (Angular CanDeactivateFn style). */
+    canDeactivate?: string[];
+    /** Route resolvers executed before handler (Angular ResolveFn style). */
+    resolvers?: Record<string, string>;
+    /** Route redirect target (Angular Router style). */
+    redirectTo?: string;
+    /** Route redirect matching rule (Angular Router style). */
+    pathMatch?: "full" | "prefix";
+    /** Path parameters parsed from route path (e.g. :id -> 'id'). */
+    pathParams?: string[];
+    /** Handler method parameter bindings declared via @Param('name'). */
+    paramBindings?: string[];
+    /** Handler method query bindings declared via @Query('name'). */
+    queryBindings?: string[];
+    /** Handler method has @Body() binding. */
+    hasBodyBinding?: boolean;
+    /** Parameter transforms declared via @Param({ transform: ... }) */
+    paramTransforms?: Record<string, "number" | "boolean" | "string">;
+    /** Parameter defaults declared via @Param({ default: ... }) */
+    paramDefaults?: Record<string, unknown>;
+    /** Query transforms declared via @Query({ transform: ... }) */
+    queryTransforms?: Record<string, "number" | "boolean" | "string">;
+    /** Query defaults declared via @Query({ default: ... }) */
+    queryDefaults?: Record<string, unknown>;
+    /** Route title (Angular Route.title style). */
+    title?: string;
+    /** Route static metadata dictionary (Angular Route.data style). */
+    data?: Record<string, unknown>;
+    /** Detailed method parameter metadata for compile-time typed invoker generation. */
+    handlerParams?: HandlerParamNode[];
+    /** Explicit aspects applied around this route. */
+    aspects?: AspectRefNode[];
 }
 export interface ControllerNode {
     className: string;
     path: string;
     scope: Scope;
     deps: string[];
+    /** Class implements OnDestroy interface or onDestroy method. */
+    hasOnDestroy?: boolean;
+    /** Parameter tokens marked @Optional(). */
+    optionalDeps?: string[];
+    selfDeps?: string[];
+    skipSelfDeps?: string[];
+    /** Parameter tokens marked @Host(). */
+    hostDeps?: string[];
+    /** Property-level Angular functional inject() calls compiled into a static context. */
+    functionalInjects?: FunctionalInjectNode[];
+    /** Automatically registered without manual module declaration (Angular standalone controller style). */
+    standalone?: boolean;
     routes: RouteNode[];
     file: string;
     importPath: string;
@@ -59,6 +163,16 @@ export interface CommandNode {
     transaction: "required" | "none";
     audit?: string;
     idempotency: "required" | "none";
+    /** Automatically registered without manual module declaration. */
+    standalone?: boolean;
+    /** Explicit aspects applied around this command. */
+    aspects?: AspectRefNode[];
+}
+export interface JobNode {
+    className: string;
+    name: string;
+    scope: Scope;
+    aspects?: AspectRefNode[];
 }
 export interface QueryNode {
     className: string;
@@ -77,7 +191,10 @@ export interface ModuleNode {
     providers: ProviderNode[];
     controllers: ControllerNode[];
     commands: CommandNode[];
+    jobs?: JobNode[];
     queries: QueryNode[];
+    /** Explicit aspects applied to all routes and commands in this module. */
+    aspects?: AspectRefNode[];
     /** Exported token names. */
     exports: string[];
 }
@@ -96,6 +213,11 @@ export interface ApplicationGraph {
      * Omitted from app.manifest.json.
      */
     tokenNames?: Record<string, string>;
+    /** Incremental cache statistics (modules reused vs reanalyzed). */
+    cacheStats?: {
+        reusedModules: string[];
+        reanalyzedModules: string[];
+    };
 }
 export interface CompileOptions {
     /** Project root directory (containing tsconfig). */
@@ -118,6 +240,31 @@ export interface CompileOptions {
     disallowControllerDirectDb?: boolean;
     /** Detect modules declared in the project that are unreachable from any root module. */
     detectOrphanModules?: boolean;
+    /** Write generated artifacts even when error-level diagnostics exist (default: true). */
+    writeOnError?: boolean;
+    /** Generate typed API client in client.ts (default: false). */
+    generateClient?: boolean;
+    /** Generate typed permissions registry in permissions.ts (default: false). */
+    generatePermissions?: boolean;
+    /** Prune unused root providers from compiled output (Angular Ivy AOT tree-shaking). */
+    treeShakeUnusedProviders?: boolean;
+    /** Incremental dependency graph cache. */
+    cache?: DependencyGraphCache;
+    /**
+     * Changed source paths supplied by the watch/incremental driver.
+     * This is an implementation hint and does not change the public graph shape.
+     */
+    changedPaths?: string[];
+    /** Type-safety gates for generated artifacts and production source. */
+    typeSafety?: TypeSafetyOptions;
+}
+export interface TypeSafetyOptions {
+    /** Reject the `any` keyword in generated TypeScript artifacts. */
+    noAnyInGenerated?: boolean;
+    /** Scan non-test production source for unsafe type escapes and widening. */
+    scanProductionSource?: boolean;
+    /** Additional relative glob patterns excluded from the production-source scan. */
+    exclude?: string[];
 }
 export interface ModuleBoundaryRule {
     /** Source module tag pattern or tag (for example, 'type:ui', 'scope:case', or '*'). */
@@ -167,6 +314,14 @@ export interface CompileResult {
     diagnostics: Diagnostic[];
     graph: ApplicationGraph;
     written: string[];
+    stats?: CompileStats;
+}
+export interface CompileStats {
+    cacheHit: boolean;
+    changedFiles: string[];
+    affectedModules: string[];
+    reanalyzedModules?: string[];
+    reusedModules?: string[];
 }
 export interface CheckProjectResult {
     /** Whether generated artifacts exactly match the files on disk. */
@@ -176,3 +331,49 @@ export interface CheckProjectResult {
     diagnostics: Diagnostic[];
     graph: ApplicationGraph;
 }
+export interface WatchEvent {
+    type: "compile-start" | "compiled" | "compile-error";
+    initial: boolean;
+    durationMs: number;
+    diagnostics: Diagnostic[];
+    written: string[];
+    stats?: CompileStats;
+}
+export interface WatchOptions extends CompileOptions {
+    /** Debounce source changes before starting a compile (default: 100ms). */
+    debounceMs?: number;
+    onEvent?: (event: WatchEvent) => void;
+}
+export interface WatchHandle {
+    /** Resolves after the initial compile has completed. */
+    ready: Promise<WatchEvent>;
+    close(): Promise<void>;
+}
+export interface CachedModuleEntry {
+    module: ModuleNode;
+    /** Files owned by this module (normalized relative paths). */
+    ownedFiles: string[];
+    /** File hash mapping for owned files. */
+    fileHashes: Record<string, string>;
+    /** Diagnostics captured during this module's analysis. */
+    diagnostics?: Diagnostic[];
+}
+export interface DependencyGraphCache {
+    /** Cached modules by module name. */
+    modules: Map<string, CachedModuleEntry>;
+    /** Global file hashes by relative file path. */
+    fileHashes: Map<string, string>;
+    /** Retained native TypeScript BuilderProgram session. */
+    programSession?: IncrementalProgramSession;
+    /** Retained module dependency graph tracking imports and reverse dependents. */
+    dependencyGraph?: DependencyGraphIndex;
+    /** Content hashes for generated artifacts, used by the incremental emitter. */
+    generatedHashes?: Map<string, string>;
+    lastStats?: {
+        reusedModules: string[];
+        reanalyzedModules: string[];
+    };
+}
+export interface DependencyGraphIndex {
+    getAffectedModules(changedFiles: string[]): string[];
+}

package/dist/util.d.ts

@@ -13,3 +13,7 @@ export declare const JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
 export declare function isRequestContextToken(token: string, tokenNames?: Record<string, string>): boolean;
 /** Determines whether token is built-in job context. */
 export declare function isJobContextToken(token: string, tokenNames?: Record<string, string>): boolean;
+/** Normalizes and combines controller path and route path. */
+export declare function joinRoutePaths(prefix: string, path: string): string;
+/** Finds the closest match from a list of candidate strings (case/delimiter-insensitive). */
+export declare function findClosestMatch(target: string, candidates: string[]): string | undefined;

package/dist/validate.d.ts

@@ -1,4 +1,8 @@
 import type { ApplicationGraph, Diagnostic, ValidateOptions } from "./types";
+export declare const COMPILER_DIAGNOSTIC_CODES: Record<string, {
+    code: string;
+    docsUrl: string;
+}>;
 /**
  * Validates ApplicationGraph and produces diagnostics list.
  * In strict mode, warn-level diagnostics are promoted to error.

package/dist/watch.d.ts

@@ -0,0 +1,3 @@
+import type { WatchHandle, WatchOptions } from "./types";
+/** Watch a project and keep the last successful generated artifacts active on errors. */
+export declare function watchProject(options: WatchOptions): WatchHandle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
   ],
   "scripts": {
     "build": "bun run clean && bun run build:js && bun run build:types",
-    "build:js": "bun build src/index.ts src/cli.ts --outdir dist --target node --external ts-morph",
+    "build:js": "bun build src/index.ts src/cli.ts --outdir dist --target node --external @typescript/typescript6",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build",
@@ -44,7 +44,7 @@
     "directory": "packages/compiler"
   },
   "dependencies": {
-    "ts-morph": "^28.0.0"
+    "@typescript/typescript6": "^6.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.4.0",