@supacloud/compiler 0.4.0 → 0.5.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/types.d.ts

@@ -1,6 +1,6 @@
 /**
- * ApplicationGraph：编译器从源码 AST 构建出的静态应用图。
- * 运行期不反射、无容器，所有信息都在该结构与生成代码中显式给出。
+ * 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.
  */
 export type Scope = "application" | "request" | "job";
 export type ProviderKind = "class" | "value" | "factory" | "existing";
@@ -11,9 +11,15 @@ export interface Diagnostic {
     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 名（InjectionToken 变量名或类名）。 */
+    /** Token name (InjectionToken variable name or class name). */
     token: string;
     tokenKind: TokenKind;
     kind: ProviderKind;
@@ -22,14 +28,35 @@ export interface ProviderNode {
     useFactoryName?: string;
     useExisting?: string;
     scope: Scope;
-    /** token 名，构造/工厂参数顺序。 */
+    /** 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[];
+    /** 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;
-    /** useClass/useFactory/useValue 符号的模块相对路径（供生成 import）。 */
+    /** Relative module path of useClass/useFactory/useValue symbol (for import generation). */
     importPath?: 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";
     path: string;
@@ -40,16 +67,56 @@ 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[];
 }
 export interface ControllerNode {
     className: string;
     path: string;
     scope: Scope;
     deps: string[];
+    /** Parameter tokens marked @Optional(). */
+    optionalDeps?: string[];
+    selfDeps?: string[];
+    skipSelfDeps?: string[];
+    /** Automatically registered without manual module declaration (Angular standalone controller style). */
+    standalone?: boolean;
     routes: RouteNode[];
     file: string;
     importPath: string;
-    /** 路由 schema 符号名 → 模块相对路径（供生成 import）。 */
+    /** Route schema symbol name -> relative module path (for import generation). */
     schemaImports?: Record<string, string>;
 }
 export interface CommandNode {
@@ -59,52 +126,59 @@ export interface CommandNode {
     transaction: "required" | "none";
     audit?: string;
     idempotency: "required" | "none";
+    /** Automatically registered without manual module declaration. */
+    standalone?: boolean;
 }
 export interface QueryNode {
     className: string;
     name: string;
 }
 export interface ModuleNode {
-    /** @Module({ name }) 或 defineModule 的 name。 */
+    /** Name from @Module({ name }) or defineModule. */
     name: string;
     className: string;
-    /** 模块标签（如 ['scope:case', 'type:feature']），用于架构边界治理。 */
+    /** Module tags (e.g. ['scope:case', 'type:feature']) for architecture boundary governance. */
     tags?: string[];
     file: string;
     line: number;
-    /** 被 import 模块的 name。 */
+    /** Names of imported modules. */
     imports: string[];
     providers: ProviderNode[];
     controllers: ControllerNode[];
     commands: CommandNode[];
     queries: QueryNode[];
-    /** 导出的 token 名。 */
+    /** Exported token names. */
     exports: string[];
 }
 export interface ApplicationGraph {
     modules: ModuleNode[];
-    /** 被依赖但无任何模块提供的 token 名（平台注入）。 */
+    /** Depended token names provided by platform injection rather than any module. */
     externalTokens: string[];
     /**
-     * 分析阶段产生的诊断（如 missing-deps），由 compileProject 合并进结果。
-     * 不写入 app.manifest.json。
+     * Diagnostics produced during analysis (e.g. missing-deps), merged by compileProject.
+     * Omitted from app.manifest.json.
      */
     diagnostics?: Diagnostic[];
     /**
-     * InjectionToken 变量名 → 字符串 name（如 REQUEST_CONTEXT →
-     * "supacloud.request-context"），供代码生成识别内置上下文 token。
-     * 不写入 app.manifest.json。
+     * InjectionToken variable name -> string name (e.g. REQUEST_CONTEXT ->
+     * "supacloud.request-context"), used during code generation to identify built-in context tokens.
+     * Omitted from app.manifest.json.
      */
     tokenNames?: Record<string, string>;
+    /** Incremental cache statistics (modules reused vs reanalyzed). */
+    cacheStats?: {
+        reusedModules: string[];
+        reanalyzedModules: string[];
+    };
 }
 export interface CompileOptions {
-    /** 项目根（含 tsconfig）。 */
+    /** Project root directory (containing tsconfig). */
     rootDir: string;
-    /** glob，默认 ['**\/*.module.ts', '**\/*.ts']。 */
+    /** Glob patterns, defaults to ['**\/*.module.ts', '**\/*.ts']. */
     include?: string[];
-    /** 生成目录（如 <rootDir>/generated）。 */
+    /** Output directory (e.g. <rootDir>/generated). */
     outDir: string;
-    /** warn 级诊断升级为 error。 */
+    /** Upgrade warn-level diagnostics to error. */
     strict?: boolean;
     /** Built-in architecture boundary preset (for example, 'modular-monolith'). */
     moduleBoundaryPreset?: ModuleBoundaryPresetName;
@@ -118,6 +192,16 @@ 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;
 }
 export interface ModuleBoundaryRule {
     /** Source module tag pattern or tag (for example, 'type:ui', 'scope:case', or '*'). */
@@ -167,6 +251,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 +268,44 @@ 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 AST project for true incremental graph re-analysis. */
+    project?: any;
+    /** Retained module dependency graph tracking imports and reverse dependents. */
+    dependencyGraph?: any;
+    lastStats?: {
+        reusedModules: string[];
+        reanalyzedModules: string[];
+    };
+}

package/dist/util.d.ts

@@ -1,15 +1,19 @@
 /**
- * token 名 → services 对象的 key。
- * CASE_REPOSITORY → caseRepository、LOGGER → logger（常量命名转 camelCase），
- * CaseService → caseService（PascalCase 首字母小写）。
+ * Token name -> key in services object.
+ * CASE_REPOSITORY -> caseRepository, LOGGER -> logger (convert CONSTANT_CASE to camelCase),
+ * CaseService -> caseService (lowercase first letter of PascalCase).
  */
 export declare function camelName(token: string): string;
-/** 计算 from 目录到 to 文件的相对 import 路径（去扩展名，保证 ./ 或 ../ 前缀）。 */
+/** Computes relative import path from fromDir to toFile (stripping extension, ensuring ./ or ../ prefix). */
 export declare function relativeImportPath(fromDir: string, toFile: string): string;
-/** 内置上下文 token 的字符串 name（与 @supacloud/app 的 REQUEST_CONTEXT/JOB_CONTEXT 对齐）。 */
+/** String names of built-in context tokens (aligned with REQUEST_CONTEXT/JOB_CONTEXT in @supacloud/app). */
 export declare const REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context";
 export declare const JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
-/** 判断 token 是否为内置 request 上下文（变量名 REQUEST_CONTEXT 或 token name 匹配）。 */
+/** Determines whether token is built-in request context (variable name REQUEST_CONTEXT or matching token name). */
 export declare function isRequestContextToken(token: string, tokenNames?: Record<string, string>): boolean;
-/** 判断 token 是否为内置 job 上下文。 */
+/** 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,6 +1,10 @@
 import type { ApplicationGraph, Diagnostic, ValidateOptions } from "./types";
+export declare const COMPILER_DIAGNOSTIC_CODES: Record<string, {
+    code: string;
+    docsUrl: string;
+}>;
 /**
- * 校验 ApplicationGraph，产出诊断列表。
- * strict 时 warn 级诊断升级为 error。
+ * Validates ApplicationGraph and produces diagnostics list.
+ * In strict mode, warn-level diagnostics are promoted to error.
  */
 export declare function validateGraph(graph: ApplicationGraph, options?: boolean | ValidateOptions): Diagnostic[];

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.0",
+  "version": "0.5.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",