@supacloud/compiler 0.8.0 → 0.10.0

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { resolve as resolve6 } from "node:path";
+import { resolve as resolve7 } from "node:path";
+import { readFile as readFile3 } from "node:fs/promises";
 
 // src/analyze.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -106,6 +107,15 @@ function createDefaultTraitHandlers() {
         return initializer && ts.isCallExpression(initializer) && expressionName(initializer.expression) === "defineModule" ? node.name.text : undefined;
       }
     },
+    {
+      kind: "defineFeatureSlice",
+      detect: (node) => {
+        if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name))
+          return;
+        const initializer = node.initializer;
+        return initializer && ts.isCallExpression(initializer) && expressionName(initializer.expression) === "defineFeatureSlice" ? node.name.text : undefined;
+      }
+    },
     {
       kind: "injectionToken",
       detect: (node) => {
@@ -454,6 +464,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     checker,
     tokensByName: new Map,
     classesByName: new Map,
+    variablesByName: new Map,
     diagnostics: []
   };
   const nativeTraitFiles = new Map;
@@ -488,9 +499,9 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
         });
       }
     }
-    if (!cache || traits?.has("defineModule")) {
+    if (!cache || traits?.has("defineModule") || traits?.has("defineFeatureSlice")) {
       for (const call of descendantsOfKind(sf, ts3.isCallExpression)) {
-        if (nodeText(call.expression) !== "defineModule")
+        if (!["defineModule", "defineFeatureSlice"].includes(nodeText(call.expression)))
           continue;
         const parent = call.parent;
         if (!parent || !ts3.isVariableDeclaration(parent))
@@ -796,6 +807,9 @@ function indexFile(sf, ctx) {
   }
   for (const statement of sf.statements.filter(ts3.isVariableStatement)) {
     for (const decl of statement.declarationList.declarations) {
+      if (ts3.isIdentifier(decl.name) && !ctx.variablesByName.has(decl.name.text)) {
+        ctx.variablesByName.set(decl.name.text, decl);
+      }
       const info = parseTokenVariable(decl, sf.fileName);
       if (info && !ctx.tokensByName.has(info.name)) {
         ctx.tokensByName.set(info.name, info);
@@ -833,6 +847,7 @@ function parseTokenVariable(decl, file) {
 function parseModule(candidate, nameByNode, ctx) {
   const { options, className, file, line } = candidate;
   const name = nameByNode.get(candidate.node) ?? className;
+  const featureSpec = parseFeatureSpec(getProp(options, "spec"), ctx);
   const tags = arrayProp(options, "tags").map((el) => ts3.isStringLiteral(el) ? el.text : nodeText(el).replace(/['"]/g, "")).filter(Boolean);
   const aspects = parseAspectRefs(getProp(options, "aspects"), ctx, `module ${name}`);
   const imports = arrayProp(options, "imports").map((el) => {
@@ -1007,8 +1022,71 @@ function parseModule(candidate, nameByNode, ctx) {
     jobs,
     queries,
     ...aspects.length > 0 ? { aspects } : {},
-    exports
+    exports,
+    ...featureSpec ? { featureSpec } : {}
+  };
+}
+function parseFeatureSpec(input, ctx, seen = new Set) {
+  if (!input)
+    return;
+  if (seen.has(input))
+    return;
+  seen.add(input);
+  if (ts3.isIdentifier(input)) {
+    const local = input.getSourceFile().statements.flatMap((statement) => ts3.isVariableStatement(statement) ? [...statement.declarationList.declarations] : []);
+    const resolved = resolveDeclaration(input, ctx)[0];
+    const decl = (resolved && ts3.isVariableDeclaration(resolved) ? resolved : undefined) ?? ctx.variablesByName.get(input.text) ?? local.find((candidate) => ts3.isIdentifier(candidate.name) && candidate.name.text === input.text) ?? descendantsOfKind(input.getSourceFile(), ts3.isVariableDeclaration).find((candidate) => ts3.isIdentifier(candidate.name) && candidate.name.text === input.text);
+    if (decl && ts3.isVariableDeclaration(decl))
+      return parseFeatureSpec(decl.initializer, ctx, seen);
+  }
+  if (ts3.isCallExpression(input) && nodeText(input.expression) === "defineFeatureSpec") {
+    return parseFeatureSpec(input.arguments[0], ctx, seen);
+  }
+  if (ts3.isAsExpression(input) || ts3.isSatisfiesExpression(input) || ts3.isParenthesizedExpression(input)) {
+    return parseFeatureSpec(input.expression, ctx, seen);
+  }
+  const invalid = () => {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-feature-spec",
+      message: "Feature spec must use static name, states and transition objects.",
+      file: sourcePath(ctx.rootDir, input.getSourceFile().fileName),
+      line: lineOf(input)
+    });
+    return;
   };
+  if (!ts3.isObjectLiteralExpression(input))
+    return invalid();
+  const name = stringLiteralProp(input, "name");
+  const statesExpr = getProp(input, "states");
+  const transitionObject = getProp(input, "transitions");
+  if (!name || !statesExpr || !ts3.isArrayLiteralExpression(statesExpr) || statesExpr.elements.some((state) => !ts3.isStringLiteral(state)) || !transitionObject || !ts3.isObjectLiteralExpression(transitionObject) || input.properties.some((property) => !ts3.isPropertyAssignment(property))) {
+    return invalid();
+  }
+  const states = statesExpr.elements.map((state) => state.text);
+  const transitions = [];
+  for (const property of transitionObject.properties) {
+    if (!ts3.isPropertyAssignment(property) || ts3.isComputedPropertyName(property.name) || !ts3.isObjectLiteralExpression(property.initializer))
+      return invalid();
+    const options = property.initializer;
+    const from = stringLiteralProp(options, "from");
+    const to = stringLiteralProp(options, "to");
+    if (!from || !to || options.properties.some((prop) => !ts3.isPropertyAssignment(prop)) || ["permission", "command", "route", "audit"].some((key) => getProp(options, key) && !stringLiteralProp(options, key)) || ["transaction", "idempotency"].some((key) => getProp(options, key) && !commandModeProp(options, key))) {
+      return invalid();
+    }
+    transitions.push({
+      name: propertyName(property.name),
+      from,
+      to,
+      permission: stringLiteralProp(options, "permission"),
+      command: stringLiteralProp(options, "command"),
+      route: stringLiteralProp(options, "route"),
+      transaction: commandModeProp(options, "transaction"),
+      idempotency: commandModeProp(options, "idempotency"),
+      audit: stringLiteralProp(options, "audit")
+    });
+  }
+  return { name, states, transitions, file: sourcePath(ctx.rootDir, input.getSourceFile().fileName), line: lineOf(input) };
 }
 function commandModeProp(object, name) {
   const value = stringLiteralProp(object, name);
@@ -2186,7 +2264,7 @@ import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
 var HEADER = "// GENERATED BY @supacloud/compiler — do not edit";
 var INTERFACES = `export interface CompiledRoute {
-  method: string;
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
   path: string;
   handler: string;
   body?: unknown;
@@ -2257,7 +2335,7 @@ export type CompiledAspect = (
 export interface CompiledController {
   path: string;
   serviceKey: string;
-  scope: string;
+  scope: "application" | "request" | "job";
   routes: CompiledRoute[];
 }
 
@@ -2871,7 +2949,7 @@ ${indent(item, 2)}`).join(",")}
     switch (provider.kind) {
       case "class": {
         const useClass = this.imports.add(provider.useClass ?? provider.token, provider.importPath, provider.importModule);
-        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const args = provider.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(provider, dep), `ConstructorParameters<typeof ${useClass}>[${index}]`)).join(", ");
         const local = this.localVar(isMulti ? provider.useClass ?? `${provider.token}Item` : provider.token, kind);
         return {
           constLine: `const ${local} = ${this.instantiate(useClass, args, kind, provider.functionalInjects)};`,
@@ -2892,7 +2970,7 @@ ${indent(item, 2)}`).join(",")}
           return { constLine, key, expr: local2 };
         }
         const factory = this.imports.add(provider.useFactoryName ?? "", provider.importPath, provider.importModule);
-        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const args = provider.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(provider, dep), `Parameters<typeof ${factory}>[${index}]`)).join(", ");
         const local = this.localVar(isMulti ? provider.useFactoryName ?? `${provider.token}Item` : provider.token, kind);
         return { constLine: `const ${local} = ${factory}(${args});`, key, expr: local };
       }
@@ -2906,7 +2984,7 @@ ${indent(item, 2)}`).join(",")}
   }
   emitController(controller, kind) {
     const className = this.imports.add(controller.className, controller.importPath);
-    const args = controller.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(controller, dep))).join(", ");
+    const args = controller.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(controller, dep), `ConstructorParameters<typeof ${className}>[${index}]`)).join(", ");
     const key = camelName(controller.className);
     const local = this.localVar(controller.className, kind);
     return {
@@ -2964,6 +3042,13 @@ ${indent(item, 2)}`).join(",")}
       host: "hostDeps" in node ? node.hostDeps?.includes(token) ?? false : false
     };
   }
+  typedDepExpr(token, kind, options, type) {
+    const expression = this.depExpr(token, kind, options);
+    const localProvider = this.module.providers.find((provider) => this.locals[kind].get(provider.token) === expression);
+    if (expression === "undefined" || localProvider && !(localProvider.kind === "factory" && !localProvider.useFactoryName))
+      return expression;
+    return `${expression} as ${type}`;
+  }
   depExpr(token, kind, options = {}) {
     const isOptional = options.optional ?? false;
     const isSelf = options.self ?? false;
@@ -3277,6 +3362,9 @@ function renderPermissions(graph) {
 `);
 }
 
+// src/validate.ts
+import { dirname as dirname2, relative as relative2, sep as sep2 } from "node:path";
+
 // src/profiles.ts
 var MODULAR_MONOLITH_RULES = [
   {
@@ -3444,6 +3532,106 @@ function resolveModuleBoundaries(options) {
   return merged.length > 0 ? merged : undefined;
 }
 
+// src/feature.ts
+function validateFeatureSpec(spec, module) {
+  const diagnostics = [];
+  const error = (code, message) => {
+    diagnostics.push({ severity: "error", code, message, file: spec.file, line: spec.line });
+  };
+  if (!spec.name.trim() || spec.states.length === 0 || spec.states.some((state) => !state.trim()) || new Set(spec.states).size !== spec.states.length) {
+    error("invalid-feature-states", "Feature name and states must be non-empty; states must be unique.");
+  }
+  const names = new Set;
+  for (const transition of spec.transitions) {
+    if (!transition.name.trim() || names.has(transition.name)) {
+      error("duplicate-feature-transition", `Feature ${spec.name} has duplicate/empty transition '${transition.name}'.`);
+    }
+    names.add(transition.name);
+    if (!spec.states.includes(transition.from) || !spec.states.includes(transition.to)) {
+      error("invalid-feature-transition", `Transition ${transition.name} references an undeclared state.`);
+    }
+    if (transition.permission !== undefined && !transition.permission.trim()) {
+      error("feature-governance-drift", `Transition ${transition.name} declares an empty permission.`);
+    }
+    if (!module)
+      continue;
+    const commands = module.commands.filter((command2) => command2.className === transition.command || command2.name === transition.command);
+    const command = commands[0];
+    if (transition.command && commands.length !== 1) {
+      error("feature-command-unresolved", `Transition ${transition.name} must reference exactly one command in module ${module.name}.`);
+    }
+    if (!transition.command && [transition.permission, transition.transaction, transition.idempotency, transition.audit].some((value) => value !== undefined)) {
+      error("feature-command-unresolved", `Transition ${transition.name} declares governance without a command binding.`);
+    }
+    if (command) {
+      for (const key of ["permission", "transaction", "idempotency", "audit"]) {
+        if (transition[key] !== undefined && transition[key] !== command[key]) {
+          error("feature-governance-drift", `Transition ${transition.name} ${key} differs from command ${command.className}.`);
+        }
+      }
+    }
+    if (transition.route) {
+      const routes = module.controllers.flatMap((controller) => controller.routes.filter((route) => `${route.method} ${joinRoutePaths(controller.path, route.path)}` === transition.route));
+      if (routes.length !== 1) {
+        error("feature-route-unresolved", `Transition ${transition.name} must reference exactly one route '${transition.route}' in module ${module.name}.`);
+      } else if (command && routes[0].command !== command.className) {
+        error("feature-route-drift", `Route ${transition.route} is not bound to ${command.className}.`);
+      }
+    }
+  }
+  return diagnostics;
+}
+function generateFeatureSource(spec) {
+  const errors = validateFeatureSpec(spec);
+  if (errors.length)
+    throw new Error(errors.map((error) => error.message).join(`
+`));
+  if (spec.transitions.some((transition) => !transition.permission)) {
+    throw new Error("Spec-to-Code requires an explicit permission for every transition.");
+  }
+  const transitions = spec.transitions.map((transition, index) => ({
+    ...transition,
+    command: `Transition${index + 1}Command`
+  }));
+  if (transitions.some((transition) => transition.route)) {
+    throw new Error("Generate the command slice first; existing HTTP routes require explicit schema and handler implementations.");
+  }
+  const sourceSpec = { name: spec.name, states: spec.states, transitions: Object.fromEntries(transitions.map((transition) => {
+    const { name, ...options } = transition;
+    return [name, options];
+  })) };
+  return [
+    'import { Command, defineFeatureSlice, defineFeatureSpec } from "@supacloud/app";',
+    "",
+    `export const featureSpec = defineFeatureSpec(${JSON.stringify(sourceSpec, null, 2)});`,
+    `export type FeatureState = typeof featureSpec.states[number];`,
+    "",
+    ...transitions.flatMap((transition) => [
+      `@Command(${JSON.stringify({
+        name: `${spec.name}.${transition.name}`,
+        permission: transition.permission,
+        transaction: transition.transaction ?? "none",
+        idempotency: transition.idempotency ?? "none",
+        audit: transition.audit
+      })})`,
+      `export class ${transition.command} {`,
+      `  execute(state: FeatureState): never {`,
+      `    if (state !== ${JSON.stringify(transition.from)}) throw new Error("Invalid transition state");`,
+      `    throw new Error(${JSON.stringify(`Implement ${spec.name}.${transition.name}: persist state ${transition.to}`)});`,
+      "  }",
+      ""
+    ]),
+    "export const FeatureSlice = defineFeatureSlice({",
+    `  name: ${JSON.stringify(spec.name)},`,
+    '  tags: ["type:feature"],',
+    "  spec: featureSpec,",
+    `  providers: [${transitions.map((transition) => transition.command).join(", ")}],`,
+    "});",
+    ""
+  ].join(`
+`);
+}
+
 // src/validate.ts
 var SCOPE_LIFETIME_RANK = {
   application: 0,
@@ -3475,6 +3663,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "invalid-http-method-body": { code: "SC3004", docsUrl: "https://supacloud.dev/errors/SC3004" },
   "unmatched-route-parameter": { code: "SC3005", docsUrl: "https://supacloud.dev/errors/SC3005" },
   "missing-route-parameter-binding": { code: "SC3006", docsUrl: "https://supacloud.dev/errors/SC3006" },
+  "missing-path-param": { code: "SC3006", docsUrl: "https://supacloud.dev/errors/SC3006" },
   "duplicate-route": { code: "SC3007", docsUrl: "https://supacloud.dev/errors/SC3007" },
   "missing-body-schema": { code: "SC3008", docsUrl: "https://supacloud.dev/errors/SC3008" },
   "unused-route-schema": { code: "SC3009", docsUrl: "https://supacloud.dev/errors/SC3009" },
@@ -3485,6 +3674,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "unmatched-path-param-decorator": { code: "SC3014", docsUrl: "https://supacloud.dev/errors/SC3014" },
   "invalid-query-default-type": { code: "SC3015", docsUrl: "https://supacloud.dev/errors/SC3015" },
   "disallowed-body-on-get-delete": { code: "SC3016", docsUrl: "https://supacloud.dev/errors/SC3016" },
+  "invalid-body-binding": { code: "SC3016", docsUrl: "https://supacloud.dev/errors/SC3016" },
   "duplicate-query-param-binding": { code: "SC3017", docsUrl: "https://supacloud.dev/errors/SC3017" },
   "conflicting-route-method": { code: "SC3018", docsUrl: "https://supacloud.dev/errors/SC3018" },
   "missing-param-colon": { code: "SC3019", docsUrl: "https://supacloud.dev/errors/SC3019" },
@@ -3500,7 +3690,15 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "invalid-job-scope": { code: "SC4007", docsUrl: "https://supacloud.dev/errors/SC4007" },
   "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
   "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
-  "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" }
+  "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" },
+  "invalid-feature-states": { code: "SC6001", docsUrl: "https://supacloud.dev/errors/SC6001" },
+  "duplicate-feature-transition": { code: "SC6002", docsUrl: "https://supacloud.dev/errors/SC6002" },
+  "invalid-feature-transition": { code: "SC6003", docsUrl: "https://supacloud.dev/errors/SC6003" },
+  "feature-command-unresolved": { code: "SC6004", docsUrl: "https://supacloud.dev/errors/SC6004" },
+  "feature-governance-drift": { code: "SC6005", docsUrl: "https://supacloud.dev/errors/SC6005" },
+  "feature-route-unresolved": { code: "SC6006", docsUrl: "https://supacloud.dev/errors/SC6006" },
+  "feature-route-drift": { code: "SC6007", docsUrl: "https://supacloud.dev/errors/SC6007" },
+  "invalid-feature-spec": { code: "SC6008", docsUrl: "https://supacloud.dev/errors/SC6008" }
 };
 function validateGraph(graph, options = false) {
   const strict = typeof options === "boolean" ? options : options.strict ?? false;
@@ -3556,7 +3754,7 @@ function validateGraph(graph, options = false) {
     }
     return;
   }
-  const error = (code, message, file, line, suggestion) => {
+  const error = (code, message, file, line, suggestion, fix) => {
     const meta = COMPILER_DIAGNOSTIC_CODES[code];
     diagnostics.push({
       severity: "error",
@@ -3566,10 +3764,11 @@ function validateGraph(graph, options = false) {
       line,
       suggestion,
       errorCode: meta?.code,
-      docsUrl: meta?.docsUrl
+      docsUrl: meta?.docsUrl,
+      fix
     });
   };
-  const warn2 = (code, message, file, line, suggestion) => {
+  const warn2 = (code, message, file, line, suggestion, fix) => {
     const meta = COMPILER_DIAGNOSTIC_CODES[code];
     diagnostics.push({
       severity: strict ? "error" : "warn",
@@ -3579,7 +3778,8 @@ function validateGraph(graph, options = false) {
       line,
       suggestion,
       errorCode: meta?.code,
-      docsUrl: meta?.docsUrl
+      docsUrl: meta?.docsUrl,
+      fix
     });
   };
   const modulesByName = new Map;
@@ -3587,6 +3787,12 @@ function validateGraph(graph, options = false) {
   const routesByKey = new Map;
   const declaredRoutes = [];
   for (const module of graph.modules) {
+    if (module.featureSpec) {
+      for (const diagnostic of validateFeatureSpec(module.featureSpec, module)) {
+        const meta = COMPILER_DIAGNOSTIC_CODES[diagnostic.code];
+        diagnostics.push({ ...diagnostic, errorCode: meta?.code, docsUrl: meta?.docsUrl });
+      }
+    }
     const previousModule = modulesByName.get(module.name);
     if (previousModule) {
       error("duplicate-module", `模块名 ${module.name} 重复（首次声明于 ${previousModule.file}:${previousModule.line}）`, module.file, module.line);
@@ -3679,7 +3885,14 @@ function validateGraph(graph, options = false) {
         if (paramBindings.length > 0) {
           for (const param of pathParams) {
             if (!paramBindings.includes(param)) {
-              warn2("missing-path-param", `Route path '${route.path}' defines parameter ':${param}', but handler ${controller.className}.${route.handler} does not bind it with @Param('${param}').`, controller.file, undefined, `Add @Param('${param}') to ${route.handler} arguments.`);
+              warn2("missing-path-param", `Route path '${route.path}' defines parameter ':${param}', but handler ${controller.className}.${route.handler} does not bind it with @Param('${param}').`, controller.file, undefined, `Add @Param('${param}') to ${route.handler} arguments.`, {
+                type: "add_route_parameter_binding",
+                targetFile: controller.file,
+                controller: controller.className,
+                route: route.handler,
+                parameter: param,
+                binding: "param"
+              });
             }
           }
         }
@@ -3706,10 +3919,20 @@ function validateGraph(graph, options = false) {
           }
         }
         if ((route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS" || route.method === "DELETE") && (route.hasBodyBinding || route.body)) {
-          error("disallowed-body-on-get-delete", `Route handler ${controller.className}.${route.handler} binds @Body() or declares body schema on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`);
+          error("disallowed-body-on-get-delete", `Route handler ${controller.className}.${route.handler} binds @Body() or declares body schema on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`, {
+            type: "remove_route_body_binding",
+            targetFile: controller.file,
+            controller: controller.className,
+            route: route.handler
+          });
         }
         if (route.hasBodyBinding && (route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS")) {
-          error("invalid-body-binding", `Route handler ${controller.className}.${route.handler} binds @Body() on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`);
+          error("invalid-body-binding", `Route handler ${controller.className}.${route.handler} binds @Body() on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`, {
+            type: "remove_route_body_binding",
+            targetFile: controller.file,
+            controller: controller.className,
+            route: route.handler
+          });
         } else if (route.hasBodyBinding && !route.body) {
           warn2("missing-body-schema", `Route handler ${controller.className}.${route.handler} binds @Body() on route '${route.path}', but route definition does not specify a body validation schema.`, controller.file, undefined, `Add schema to route options (e.g. body: Schema) for compile-time and runtime validation.`);
         } else if (route.body && !route.hasBodyBinding && !route.command) {
@@ -3850,23 +4073,51 @@ function validateGraph(graph, options = false) {
               const owner = globalProviders.get(dep);
               if (!owner)
                 continue;
-              error("module-boundary", `模块 ${module.name} 的 provider ${provider.token} 依赖 ${dep}，该 token 由模块 ${owner.module.name} 提供但未被 import`, provider.file, provider.line, `Import module '${owner.module.name}' in '${module.name}', add '${dep}' to '${owner.module.name}' exports, or mark @Injectable({ providedIn: 'root' }).`);
+              error("module-boundary", `模块 ${module.name} 的 provider ${provider.token} 依赖 ${dep}，该 token 由模块 ${owner.module.name} 提供但未被 import`, provider.file, provider.line, `Import module '${owner.module.name}' in '${module.name}', add '${dep}' to '${owner.module.name}' exports, or mark @Injectable({ providedIn: 'root' }).`, {
+                type: "add_module_import",
+                targetFile: module.file,
+                module: owner.module.name,
+                provider: dep,
+                symbol: owner.module.className,
+                targetModule: module.name,
+                importPath: (() => {
+                  const value = relative2(dirname2(module.file), owner.module.file).replace(/\.(tsx?|mts|cts)$/, "").split(sep2).join("/");
+                  return value.startsWith(".") ? value : `./${value}`;
+                })()
+              });
             } else if (dep.includes("TOKEN") || dep.endsWith("Token") || dep.length > 2 && dep === dep.toUpperCase()) {
               error("missing-token-factory", `InjectionToken '${dep}' referenced by provider '${provider.token}' has no provider in module '${module.name}' and no default factory function.`, provider.file, provider.line, `Provide '${dep}' in @Module({ providers: [...] }) or declare it with new InjectionToken('${dep}', { factory: () => ... }).`);
             } else {
-              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line, `Provide '${dep}' in a module, mark constructor parameter @Optional(), or define @Injectable({ providedIn: 'root' }).`);
+              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line, `Provide '${dep}' in a module, mark constructor parameter @Optional(), or define @Injectable({ providedIn: 'root' }).`, {
+                type: "add_provider",
+                targetFile: module.file,
+                token: dep,
+                module: module.name
+              });
             }
           }
           continue;
         }
         if (SCOPE_LIFETIME_RANK[resolved.provider.scope] > SCOPE_LIFETIME_RANK[provider.scope]) {
-          error("scope-violation", `模块 ${module.name} 的 ${provider.scope} provider ${provider.token} 不能依赖 ${resolved.provider.scope} provider ${dep}`, provider.file, provider.line, `Change provider '${provider.token}' scope to '${resolved.provider.scope}', or inject a factory/context instead.`);
+          error("scope-violation", `模块 ${module.name} 的 ${provider.scope} provider ${provider.token} 不能依赖 ${resolved.provider.scope} provider ${dep}`, provider.file, provider.line, `Change provider '${provider.token}' scope to '${resolved.provider.scope}', or inject a factory/context instead.`, {
+            type: "change_provider_scope",
+            targetFile: provider.file,
+            provider: provider.token,
+            from: provider.scope,
+            to: resolved.provider.scope
+          });
         }
       }
     }
     for (const command of module.commands) {
       if (!command.permission) {
-        error("command-missing-permission", `模块 ${module.name} 的 command ${command.name} (${command.className}) 未声明 permission`, module.file, module.line, "Add 'permission: string' to @Command({ ... }) or configure command execution capabilities permission=false.");
+        error("command-missing-permission", `模块 ${module.name} 的 command ${command.name} (${command.className}) 未声明 permission`, module.file, module.line, "Add 'permission: string' to @Command({ ... }) or configure command execution capabilities permission=false.", {
+          type: "add_command_permission",
+          targetFile: module.providers.find((provider) => provider.useClass === command.className || provider.token === command.className)?.file ?? module.file,
+          command: command.className,
+          module: module.name,
+          permission: `${module.name}.${command.name}`
+        });
       }
       if (typeof options === "object" && options.commandCapabilities) {
         const caps = options.commandCapabilities;
@@ -4220,7 +4471,7 @@ import { join as join4 } from "node:path";
 
 // src/type-safety.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join3, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+import { dirname as dirname3, join as join3, relative as relative3, resolve as resolve2, sep as sep3 } from "node:path";
 import * as ts4 from "@typescript/typescript6";
 var DEFAULT_EXCLUDES = [
   "**/*.test.ts",
@@ -4342,7 +4593,7 @@ function readProjectConfig2(configPath) {
   const config = ts4.readConfigFile(configPath, (file) => readFileSync2(file, "utf8"));
   if (config.error)
     return { options: {}, errors: [config.error] };
-  const parsed = ts4.parseJsonConfigFileContent(config.config, ts4.sys, dirname2(configPath));
+  const parsed = ts4.parseJsonConfigFileContent(config.config, ts4.sys, dirname3(configPath));
   return { options: parsed.options, errors: parsed.errors };
 }
 function isProductionSource(rootDir, sourceFile, excludes, outDir) {
@@ -4425,7 +4676,7 @@ function makeDiagnostic(code, message, fileOrSourceFile, node, strict, rootDir)
   };
 }
 function normalizeRelative(rootDir, filePath) {
-  return relative2(rootDir, filePath).split(sep2).join("/").replace(/^\.\//, "");
+  return relative3(rootDir, filePath).split(sep3).join("/").replace(/^\.\//, "");
 }
 function isAnyKeyword(node) {
   return node.kind === ts4.SyntaxKind.AnyKeyword;
@@ -4615,6 +4866,61 @@ function explainGraph(graph, subject) {
   const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
   throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
 }
+function createContextPack(graph, subject) {
+  const subjectModule = graph.modules.find((module) => module.name === subject);
+  if (!subjectModule) {
+    throw new Error(`No module named "${subject}". Context packs require a module name.`);
+  }
+  const byName = new Map(graph.modules.map((module) => [module.name, module]));
+  const selected = new Set([subjectModule.name]);
+  const queue = [subjectModule.name];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current)
+      continue;
+    const module = byName.get(current);
+    if (!module)
+      continue;
+    const neighbors = [
+      ...module.imports,
+      ...graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name)
+    ];
+    for (const neighbor of neighbors) {
+      if (!selected.has(neighbor) && byName.has(neighbor)) {
+        selected.add(neighbor);
+        queue.push(neighbor);
+      }
+    }
+  }
+  const modules = graph.modules.filter((module) => selected.has(module.name));
+  const files = [...new Set(modules.flatMap((module) => [
+    module.file,
+    ...module.providers.map((provider) => provider.file),
+    ...module.controllers.map((controller) => controller.file)
+  ]))].sort();
+  const referencedTokens = new Set;
+  for (const module of modules) {
+    for (const provider of module.providers) {
+      for (const token of provider.deps)
+        referencedTokens.add(token);
+    }
+    for (const controller of module.controllers) {
+      for (const token of controller.deps)
+        referencedTokens.add(token);
+    }
+  }
+  return {
+    version: 1,
+    subject: subjectModule.name,
+    modules,
+    files,
+    externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
+    relatedModules: {
+      imports: subjectModule.imports.filter((name) => selected.has(name)),
+      importedBy: graph.modules.filter((module) => module.imports.includes(subjectModule.name)).map((module) => module.name).sort()
+    }
+  };
+}
 function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
   const checks = [
     {
@@ -4715,12 +5021,12 @@ function exportGraphDot(graph) {
 
 // src/watch.ts
 import { watch } from "node:fs";
-import { relative as relative4, resolve as resolve4 } from "node:path";
+import { relative as relative5, resolve as resolve4 } from "node:path";
 
 // src/incremental.ts
 import { createHash as createHash5 } from "node:crypto";
 import { access as access2, readdir, readFile } from "node:fs/promises";
-import { isAbsolute, relative as relative3, resolve as resolve3, sep as sep3 } from "node:path";
+import { isAbsolute, relative as relative4, resolve as resolve3, sep as sep4 } from "node:path";
 function createDependencyGraphCache() {
   return {
     modules: new Map,
@@ -4799,12 +5105,12 @@ async function updateSnapshot(previous, options, changedPaths) {
   const files = { ...previous.files };
   for (const changedPath of changedPaths) {
     const absolutePath = isAbsolute(changedPath) ? resolve3(changedPath) : resolve3(rootDir, changedPath);
-    const relativeChangedPath = relative3(rootDir, absolutePath);
-    if (relativeChangedPath === ".." || relativeChangedPath.startsWith(`..${sep3}`))
+    const relativeChangedPath = relative4(rootDir, absolutePath);
+    if (relativeChangedPath === ".." || relativeChangedPath.startsWith(`..${sep4}`))
       continue;
     if (absolutePath === outDir || absolutePath.startsWith(`${outDir}/`))
       continue;
-    const relativePath = relative3(rootDir, absolutePath).split(sep3).join("/");
+    const relativePath = relative4(rootDir, absolutePath).split(sep4).join("/");
     try {
       await access2(absolutePath);
       const content = await readFile(absolutePath);
@@ -4822,7 +5128,7 @@ async function createSnapshot(options) {
   const files = {};
   for (const path of paths) {
     const content = await readFile(path);
-    files[relative3(rootDir, path).split(sep3).join("/")] = createHash5("sha256").update(content).digest("hex");
+    files[relative4(rootDir, path).split(sep4).join("/")] = createHash5("sha256").update(content).digest("hex");
   }
   return { files, optionsKey: optionsKeyOf(options) };
 }
@@ -5059,11 +5365,11 @@ function watchProject(options) {
       if (!filename)
         return schedule();
       const changedPath = resolve4(rootDir, filename.toString());
-      const relativePath = relative4(outDir, changedPath);
+      const relativePath = relative5(outDir, changedPath);
       if (!relativePath.startsWith("..") && relativePath !== "")
         return;
       if (/\.(tsx?|mts|cts)$/.test(changedPath))
-        schedule(relative4(rootDir, changedPath));
+        schedule(relative5(rootDir, changedPath));
     });
     if (initialEvent)
       resolveReady(initialEvent);
@@ -5147,6 +5453,196 @@ function compileOptionsFromConfig(config, cwd = process.cwd()) {
   };
 }
 
+// src/fixes.ts
+import { randomUUID } from "node:crypto";
+import { lstat, readFile as readFile2, realpath, rename as rename2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname4, isAbsolute as isAbsolute2, relative as relative6, resolve as resolve6, sep as sep5 } from "node:path";
+import * as ts5 from "@typescript/typescript6";
+async function applyDiagnosticFix(fix, options = {}) {
+  if (!fix || typeof fix.targetFile !== "string")
+    throw new Error("Invalid DiagnosticFix");
+  const root = await realpath(options.rootDir ?? process.cwd());
+  const file = resolve6(root, fix.targetFile);
+  const stat = await lstat(file);
+  const resolved = await realpath(file);
+  const relativePath = relative6(root, resolved);
+  if (stat.isSymbolicLink() || !stat.isFile() || isAbsolute2(relativePath) || relativePath === ".." || relativePath.startsWith(`..${sep5}`)) {
+    throw new Error("Fix target must be a regular file inside rootDir");
+  }
+  const original = await readFile2(file, "utf8");
+  let source = parse(file, original);
+  let content;
+  switch (fix.type) {
+    case "add_module_import": {
+      if (!fix.importPath || !fix.symbol)
+        throw new Error("Module fix requires importPath and symbol");
+      identifier(fix.symbol);
+      const withImport = importSymbol(source, fix.importPath, fix.symbol);
+      source = parse(file, withImport);
+      const object = unique(moduleObjects(source).filter((candidate) => !fix.targetModule || stringProperty(candidate, "name") === fix.targetModule), "target module");
+      const imports = property(object, "imports");
+      if (imports && !ts5.isArrayLiteralExpression(imports.initializer)) {
+        throw new Error("Module imports must be a static array");
+      }
+      const values = imports && ts5.isArrayLiteralExpression(imports.initializer) ? imports.initializer.elements : [];
+      if (values.some(ts5.isSpreadElement))
+        throw new Error("Module imports cannot contain spread elements");
+      content = values.some((value) => ts5.isIdentifier(value) && value.text === fix.symbol) ? withImport : replaceProperty(source, object, "imports", ts5.factory.createArrayLiteralExpression([
+        ...values,
+        ts5.factory.createIdentifier(fix.symbol)
+      ]));
+      break;
+    }
+    case "add_command_permission": {
+      const permission = options.permission ?? fix.permission;
+      if (!permission?.trim()) {
+        throw new Error("Permission fix requires an explicit permission; privileges are never inferred");
+      }
+      const command = findClass(source, fix.command);
+      const object = decoratorObject(command, "Command");
+      const current = property(object, "permission");
+      if (current && (!ts5.isStringLiteral(current.initializer) || current.initializer.text !== permission)) {
+        throw new Error("Command permission already exists with a different value");
+      }
+      content = current ? original : replaceProperty(source, object, "permission", ts5.factory.createStringLiteral(permission));
+      break;
+    }
+    case "add_route_parameter_binding": {
+      const controller = findClass(source, fix.controller);
+      const method = unique(controller.members.filter((member) => ts5.isMethodDeclaration(member) && nameOf(member.name) === fix.route), "route handler");
+      const parameter = unique(method.parameters.filter((candidate) => ts5.isIdentifier(candidate.name) && candidate.name.text === fix.parameter), "same-named route parameter");
+      const binding = fix.binding === "param" ? "Param" : fix.binding === "query" ? "Query" : undefined;
+      if (!binding)
+        throw new Error("Invalid route binding");
+      const decorators = ts5.getDecorators(parameter) ?? [];
+      if (decorators.length > 0)
+        throw new Error("Parameter already has a decorator");
+      const framework = unique(source.statements.filter((statement) => ts5.isImportDeclaration(statement) && statement.importClause?.namedBindings && ts5.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some((element) => ["Controller", "Get", "Post", "Put", "Patch", "Delete", "Head", "Options"].includes(element.name.text))), "framework import");
+      if (!ts5.isImportDeclaration(framework) || !ts5.isStringLiteral(framework.moduleSpecifier)) {
+        throw new Error("Framework import must be static");
+      }
+      const edited = original.slice(0, parameter.getStart(source)) + `@${binding}(${JSON.stringify(fix.parameter)}) ` + original.slice(parameter.getStart(source));
+      content = importSymbol(parse(file, edited), framework.moduleSpecifier.text, binding);
+      break;
+    }
+    default:
+      throw new Error(`Diagnostic fix '${fix.type}' requires a manual semantic decision; no files changed`);
+  }
+  parse(file, content);
+  const result = { file, changed: content !== original, content };
+  if (options.dryRun === false && result.changed) {
+    const temporary = `${file}.supacloud-fix-${randomUUID()}`;
+    try {
+      await writeFile2(temporary, content, { encoding: "utf8", flag: "wx", mode: stat.mode });
+      if (await readFile2(file, "utf8") !== original)
+        throw new Error("Target changed while preparing the fix");
+      await rename2(temporary, file);
+    } finally {
+      await unlink2(temporary).catch(() => {});
+    }
+  }
+  return result;
+}
+function parse(file, text) {
+  const result = ts5.transpileModule(text, {
+    fileName: file,
+    reportDiagnostics: true,
+    compilerOptions: { target: ts5.ScriptTarget.ESNext, experimentalDecorators: true }
+  });
+  if (result.diagnostics?.some((item) => item.category === ts5.DiagnosticCategory.Error)) {
+    throw new Error("Cannot fix syntactically invalid TypeScript");
+  }
+  return ts5.createSourceFile(file, text, ts5.ScriptTarget.Latest, true, ts5.ScriptKind.TS);
+}
+function unique(items, description) {
+  if (items.length !== 1)
+    throw new Error(`Expected exactly one ${description}; found ${items.length}`);
+  return items[0];
+}
+function identifier(value) {
+  if (!/^[A-Za-z_$][\w$]*$/.test(value))
+    throw new Error(`Invalid identifier '${value}'`);
+}
+function nameOf(name) {
+  if (!name)
+    return "";
+  return ts5.isIdentifier(name) || ts5.isStringLiteral(name) || ts5.isNumericLiteral(name) ? name.text : "";
+}
+function property(object, key) {
+  if (object.properties.some((item) => !ts5.isPropertyAssignment(item) || ts5.isComputedPropertyName(item.name))) {
+    throw new Error("Fix requires explicit static object properties");
+  }
+  const values = object.properties.filter((item) => ts5.isPropertyAssignment(item) && nameOf(item.name) === key);
+  if (values.length > 1)
+    throw new Error(`Duplicate '${key}' property`);
+  return values[0];
+}
+function stringProperty(object, key) {
+  const value = property(object, key)?.initializer;
+  return value && ts5.isStringLiteral(value) ? value.text : undefined;
+}
+function replaceProperty(source, object, key, value) {
+  const previous = property(object, key);
+  const replacement = ts5.factory.createPropertyAssignment(key, value);
+  const properties = object.properties.map((item) => item === previous ? replacement : item);
+  if (!previous)
+    properties.push(replacement);
+  const updated = ts5.factory.updateObjectLiteralExpression(object, properties);
+  return source.text.slice(0, object.getStart(source)) + ts5.createPrinter().printNode(ts5.EmitHint.Expression, updated, source) + source.text.slice(object.end);
+}
+function findClass(source, name) {
+  return unique(source.statements.filter((statement) => ts5.isClassDeclaration(statement) && statement.name?.text === name), `class '${name}'`);
+}
+function decoratorObject(node, name) {
+  const decorator = unique((ts5.getDecorators(node) ?? []).filter((item) => ts5.isCallExpression(item.expression) && item.expression.expression.getText() === name), `@${name} decorator`);
+  const argument = ts5.isCallExpression(decorator.expression) ? decorator.expression.arguments[0] : undefined;
+  if (!argument || !ts5.isObjectLiteralExpression(argument))
+    throw new Error(`@${name} requires a static object`);
+  return argument;
+}
+function moduleObjects(source) {
+  const result = [];
+  for (const statement of source.statements) {
+    if (ts5.isClassDeclaration(statement) && (ts5.getDecorators(statement) ?? []).some((item) => ts5.isCallExpression(item.expression) && item.expression.expression.getText() === "Module")) {
+      result.push(decoratorObject(statement, "Module"));
+    }
+    if (ts5.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        const call = declaration.initializer;
+        if (call && ts5.isCallExpression(call) && ["defineModule", "defineFeatureSlice"].includes(call.expression.getText()) && call.arguments[0] && ts5.isObjectLiteralExpression(call.arguments[0])) {
+          result.push(call.arguments[0]);
+        }
+      }
+    }
+  }
+  return result;
+}
+function importSymbol(source, path, symbol) {
+  identifier(symbol);
+  const current = resolve6(source.fileName).replace(/\.(tsx?|mts|cts)$/, "");
+  const target = resolve6(dirname4(source.fileName), path).replace(/\.(tsx?|mts|cts)$/, "");
+  if (current === target)
+    return source.text;
+  const matches = source.statements.filter((item) => ts5.isImportDeclaration(item) && ts5.isStringLiteral(item.moduleSpecifier) && item.moduleSpecifier.text === path);
+  if (matches.length > 1)
+    throw new Error(`Ambiguous imports from '${path}'`);
+  const match = matches[0];
+  if (match && ts5.isImportDeclaration(match) && match.importClause?.namedBindings && ts5.isNamedImports(match.importClause.namedBindings) && !match.importClause.isTypeOnly) {
+    if (match.importClause.namedBindings.elements.some((item) => item.name.text === symbol))
+      return source.text;
+    const bindings = match.importClause.namedBindings;
+    const updated = ts5.factory.updateNamedImports(bindings, [
+      ...bindings.elements,
+      ts5.factory.createImportSpecifier(false, undefined, ts5.factory.createIdentifier(symbol))
+    ]);
+    return source.text.slice(0, bindings.getStart(source)) + ts5.createPrinter().printNode(ts5.EmitHint.Unspecified, updated, source) + source.text.slice(bindings.end);
+  }
+  if (match)
+    throw new Error(`Import from '${path}' is not a named value import`);
+  return `import { ${symbol} } from ${JSON.stringify(path)};
+${source.text}`;
+}
+
 // src/cli.ts
 function isModuleBoundaryPresetName(value) {
   return value === "modular-monolith" || value === "feature-slices" || value === "vertical-slices" || value === "angular-enterprise" || value === "angular" || value === "clean-architecture" || value === "domain-driven";
@@ -5161,7 +5657,9 @@ Usage:
   supacloud-compiler dev     [rootDir] [options]
   supacloud-compiler graph   [rootDir] [options]
   supacloud-compiler explain <name> [rootDir] [options]
+  supacloud-compiler context <module> [rootDir] [options]
   supacloud-compiler doctor  [rootDir] [options]
+  supacloud-compiler fix     <fix.json> [options]
 
 Commands:
   compile             Compile application modules and generate artifacts
@@ -5169,6 +5667,7 @@ Commands:
   dev                 Watch source files and recompile on changes
   graph               Print the discovered application graph
   explain             Explain a module, provider, or external token
+  context             Extract an AI-sized module context pack
   doctor              Run project and generated-artifact health checks
 
 Options:
@@ -5181,7 +5680,9 @@ Options:
   --permissions       Generate typed permissions registry (default)
   --no-permissions    Do not generate permissions.ts
   --debounce <ms>     Debounce source changes in dev mode (default: 100)
-  --json              Print machine-readable output for graph/explain/doctor
+  --json              Print machine-readable output for compile/check/graph/explain/context/doctor
+  --dry-run           Preview a fix without writing the target file
+  --write             Apply a fix to disk (fix is preview-only by default)
   --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
   --help, -h          Show this help
 `);
@@ -5193,7 +5694,7 @@ async function run() {
     process.exit(0);
   }
   const command = args[0];
-  if (!["compile", "check", "dev", "graph", "explain", "doctor"].includes(command)) {
+  if (!["compile", "check", "dev", "graph", "explain", "context", "doctor", "fix"].includes(command)) {
     console.error(`Error: unknown command "${command}"`);
     printUsage();
     process.exit(1);
@@ -5207,6 +5708,7 @@ async function run() {
   let debounceMs = 100;
   let query;
   let json = false;
+  let dryRun = true;
   for (let i = 1;i < args.length; i++) {
     const arg = args[i];
     if (arg === "--root" || arg === "-r") {
@@ -5233,6 +5735,10 @@ async function run() {
       }
     } else if (arg === "--json") {
       json = true;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--write") {
+      dryRun = false;
     } else if (arg === "--preset" || arg === "-p") {
       const presetArg = args[++i];
       if (!isModuleBoundaryPresetName(presetArg)) {
@@ -5241,18 +5747,18 @@ async function run() {
       }
       preset = presetArg;
     } else if (!arg.startsWith("-") && !rootDir) {
-      if (command === "explain" && !query)
+      if ((command === "explain" || command === "context" || command === "fix") && !query)
         query = arg;
       else
         rootDir = arg;
-    } else if (!arg.startsWith("-") && command === "explain" && !query) {
+    } else if (!arg.startsWith("-") && (command === "explain" || command === "context" || command === "fix") && !query) {
       query = arg;
     }
   }
   const loadedConfig = await loadSupacloudConfig(process.cwd());
   const defaults = resolveSupacloudConfig(loadedConfig, process.cwd());
-  const resolvedRoot = rootDir ? resolve6(process.cwd(), rootDir) : defaults.rootDir;
-  const resolvedOut = outDir ? resolve6(process.cwd(), outDir) : defaults.outDir;
+  const resolvedRoot = rootDir ? resolve7(process.cwd(), rootDir) : defaults.rootDir;
+  const resolvedOut = outDir ? resolve7(process.cwd(), outDir) : defaults.outDir;
   const configured = compileOptionsFromConfig({
     ...loadedConfig,
     root: resolvedRoot,
@@ -5265,38 +5771,69 @@ async function run() {
     ...configured,
     moduleBoundaryPreset: preset ?? configured.moduleBoundaryPreset
   };
-  if (command === "compile") {
+  if (command === "fix") {
+    if (!query)
+      throw new Error("fix requires a JSON file containing one DiagnosticFix");
+    const fix = JSON.parse(await readFile3(resolve7(process.cwd(), query), "utf8"));
+    const result = await applyDiagnosticFix(fix, { rootDir: process.cwd(), dryRun });
+    console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+  } else if (command === "compile") {
     const result = await compileProject(compileDefaults);
-    printDiagnostics(result.diagnostics);
     const errors = result.diagnostics.filter((d) => d.severity === "error");
+    if (json) {
+      console.log(JSON.stringify({
+        ok: errors.length === 0,
+        diagnostics: result.diagnostics,
+        written: result.written,
+        stats: result.stats
+      }, null, 2));
+    } else {
+      printDiagnostics(result.diagnostics);
+    }
     if (errors.length > 0) {
-      console.error(`
+      if (!json)
+        console.error(`
 Compilation failed with ${errors.length} error(s).`);
       process.exit(1);
     }
-    console.log(`
+    if (!json) {
+      console.log(`
 Compilation succeeded. Generated artifacts:
 ${result.written.map((f) => `  - ${f}`).join(`
 `)}`);
+    }
   } else if (command === "check") {
     const result = await checkProject(compileDefaults);
-    printDiagnostics(result.diagnostics);
     const errors = result.diagnostics.filter((d) => d.severity === "error");
+    if (json) {
+      console.log(JSON.stringify({
+        ok: errors.length === 0 && result.upToDate,
+        upToDate: result.upToDate,
+        mismatches: result.mismatches,
+        diagnostics: result.diagnostics
+      }, null, 2));
+    } else {
+      printDiagnostics(result.diagnostics);
+    }
     if (errors.length > 0) {
-      console.error(`
+      if (!json)
+        console.error(`
 Governance checks failed with ${errors.length} error(s).`);
       process.exit(1);
     }
     if (!result.upToDate) {
-      console.error(`
+      if (!json) {
+        console.error(`
 Artifact drift detected:`);
-      for (const mismatch of result.mismatches) {
-        console.error(`  - ${mismatch}`);
+        for (const mismatch of result.mismatches) {
+          console.error(`  - ${mismatch}`);
+        }
+        console.error("Run the compile command and commit the updated generated artifacts.");
       }
-      console.error("Run the compile command and commit the updated generated artifacts.");
       process.exit(1);
     }
-    console.log("Artifact check passed: disk files match compiler output with no drift.");
+    if (!json)
+      console.log("Artifact check passed: disk files match compiler output with no drift.");
   } else if (command === "dev") {
     const handle = watchProject({
       ...compileDefaults,
@@ -5350,6 +5887,38 @@ Source change detected; compiling...`);
       console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
       process.exit(1);
     }
+  } else if (command === "context") {
+    if (!query) {
+      console.error("Error: context requires a module name");
+      process.exit(1);
+    }
+    try {
+      const graph = await analyzeProject(resolvedRoot);
+      const pack = createContextPack(graph, query);
+      if (json) {
+        console.log(JSON.stringify(pack, null, 2));
+      } else {
+        console.log([
+          `CONTEXT ${pack.subject}`,
+          `  modules: ${pack.modules.map((module) => module.name).join(", ") || "-"}`,
+          `  files: ${pack.files.join(", ") || "-"}`,
+          `  external tokens: ${pack.externalTokens.join(", ") || "-"}`,
+          `  imports: ${pack.relatedModules.imports.join(", ") || "-"}`,
+          `  imported by: ${pack.relatedModules.importedBy.join(", ") || "-"}`
+        ].join(`
+`));
+      }
+    } catch (error) {
+      if (json) {
+        console.log(JSON.stringify({
+          ok: false,
+          error: error instanceof Error ? error.message : String(error)
+        }, null, 2));
+      } else {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      process.exit(1);
+    }
   } else {
     const result = await checkProject(compileDefaults);
     const doctor = doctorProject(resolvedRoot, resolvedOut, result.graph, result.upToDate, result.diagnostics);