aact 2.1.5 → 3.0.0-beta.3

package/dist/cli/index.mjs

@@ -1,17 +1,65 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 import consola from 'consola';
-import { A as AactConfigSchema, H as loadStructurizrElements, G as loadPlantumlElements, J as mapContainersFromPlantumlElements, q as analyzeArchitecture, E as EXTERNAL_SYSTEM_TYPE, b as CONTAINER_DB_TYPE, r as checkAcl, s as checkAcyclic, t as checkApiGateway, w as checkCrud, x as checkDbPerService, u as checkCohesion, y as checkStableDependencies, v as checkCommonReuse, L as structurizrDslSyntax, D as generateKubernetes, F as generatePlantumlFromModel } from '../shared/aact.CJGFUdeF.mjs';
+import { A as AactConfigSchema, r as knownFormatNames, s as loadFormat, j as canLoad, e as analyzeArchitecture, t as ruleRegistry, h as canFix, g as applyEdits, i as canGenerate } from '../shared/aact.CxegP3pU.mjs';
 import { loadConfig } from 'c12';
+import path, { basename } from 'pathe';
 import * as v from 'valibot';
-import path from 'node:path';
 import fs, { readFile, writeFile } from 'node:fs/promises';
-import pc from 'picocolors';
-import 'yaml';
-import 'plantuml-parser';
+import { colors, box } from 'consola/utils';
 
-const version = "2.1.5";
+const version = "3.0.0-beta.3";
 
+const matchesPattern = (filePath, pattern) => {
+  if (pattern.startsWith("*")) {
+    return filePath.endsWith(pattern.slice(1));
+  }
+  return basename(filePath) === pattern;
+};
+const validateCustomRules = (entries) => {
+  const validated = [];
+  for (const [i, raw] of entries.entries()) {
+    if (!raw || typeof raw !== "object") {
+      throw new Error(
+        `customRules[${i}]: expected RuleDefinition object (got ${typeof raw})`
+      );
+    }
+    const rule = raw;
+    if (typeof rule.name !== "string" || !rule.name) {
+      throw new Error(
+        `customRules[${i}]: missing "name" (must be non-empty string)`
+      );
+    }
+    if (typeof rule.description !== "string") {
+      throw new TypeError(
+        `customRules[${i}] "${rule.name}": missing "description" string`
+      );
+    }
+    if (typeof rule.check !== "function") {
+      throw new TypeError(
+        `customRules[${i}] "${rule.name}": "check" must be a function`
+      );
+    }
+    if (rule.fix !== void 0 && typeof rule.fix !== "function") {
+      throw new Error(
+        `customRules[${i}] "${rule.name}": "fix" must be a function if provided`
+      );
+    }
+    validated.push(rule);
+  }
+  return validated;
+};
+const inferSourceType = async (filePath) => {
+  for (const name of knownFormatNames()) {
+    const fmt = await loadFormat(name);
+    if (!canLoad(fmt) || !fmt.defaultPattern) continue;
+    if (matchesPattern(filePath, fmt.defaultPattern)) return name;
+  }
+  const known = knownFormatNames().join(", ");
+  throw new Error(
+    `Cannot infer source format from "${filePath}". Add explicit \`source.type\` to aact.config.ts (known: ${known}).`
+  );
+};
 const loadAndValidateConfig = async (configPath) => {
   const { config } = await loadConfig({
     name: "aact",
@@ -20,7 +68,24 @@ const loadAndValidateConfig = async (configPath) => {
   if (!config) {
     throw new Error("No source configured. Create an aact.config.ts file.");
   }
-  return v.parse(AactConfigSchema, config);
+  const parsed = v.parse(AactConfigSchema, config);
+  const rawSource = typeof parsed.source === "string" ? { path: parsed.source } : parsed.source;
+  const type = rawSource.type ?? await inferSourceType(rawSource.path);
+  if (rawSource.type && !knownFormatNames().includes(type)) {
+    throw new Error(
+      `Unknown source.type "${type}" in aact.config.ts (known: ${knownFormatNames().join(", ")}).`
+    );
+  }
+  const customRules = parsed.customRules ? validateCustomRules(parsed.customRules) : void 0;
+  return {
+    ...parsed,
+    customRules,
+    source: {
+      path: rawSource.path,
+      type,
+      ..."writePath" in rawSource && rawSource.writePath !== void 0 ? { writePath: rawSource.writePath } : {}
+    }
+  };
 };
 
 const isFileNotFound = (err) => typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
@@ -32,19 +97,14 @@ const exitWithError = (message, hint) => {
 const loadModel = async (config) => {
   const resolvedPath = path.resolve(config.source.path);
   try {
-    switch (config.source.type) {
-      case "plantuml": {
-        const elements = await loadPlantumlElements(resolvedPath);
-        return mapContainersFromPlantumlElements(elements);
-      }
-      case "structurizr": {
-        return await loadStructurizrElements(resolvedPath);
-      }
-      default: {
-        const sourceType = config.source.type;
-        throw new Error(`Unsupported source type: ${String(sourceType)}`);
-      }
+    const format = await loadFormat(config.source.type);
+    if (!canLoad(format)) {
+      return exitWithError(
+        `Format "${format.name}" doesn't support load`,
+        "Specify a source-capable format (plantuml, structurizr)."
+      );
     }
+    return await format.load(resolvedPath);
   } catch (error) {
     if (isFileNotFound(error)) {
       return exitWithError(
@@ -82,7 +142,7 @@ const analyze = defineCommand({
   },
   async run({ args }) {
     const config = await loadAndValidateConfig(args.config);
-    const model = await loadModel(config);
+    const { model } = await loadModel(config);
     const { report } = analyzeArchitecture(model);
     if (args.format === "json") {
       console.log(JSON.stringify(report, void 0, 2));
@@ -107,511 +167,121 @@ const analyze = defineCommand({
   }
 });
 
-const plantumlSyntax = {
-  containerPattern: (name) => `(${name},`,
-  containerDecl: (name, label, tags) => {
-    const tagsPart = tags ? `, "", "", $tags="${tags}"` : "";
-    return `Container(${name}, "${label}"${tagsPart})`;
-  },
-  relationPattern: (from, to) => `Rel(${from}, ${to}`,
-  relationDecl: (from, to, tech, tags) => {
-    const tagsPart = tags ? `, $tags="${tags}"` : "";
-    return `Rel(${from}, ${to}, "${tech ?? ""}"${tagsPart})`;
-  }
-};
-
-const applyIndent = (content, indent) => content.split("\n").map((line) => line.trim() ? indent + line : line).join("\n");
-const applyEdits = (source, edits) => {
-  const lines = source.split("\n");
-  for (const edit of edits) {
-    const idx = lines.findIndex((line) => line.includes(edit.search));
-    if (idx === -1) {
-      consola.warn(`fix: pattern not found in source \u2014 "${edit.search}"`);
-      continue;
-    }
-    const matchCount = lines.filter(
-      (line) => line.includes(edit.search)
-    ).length;
-    if (matchCount > 1) {
-      consola.warn(
-        `fix: ambiguous pattern "${edit.search}" matches ${matchCount} lines, using first`
+const exitWithViolations = () => process.exit(1);
+const buildEffectiveRules = (customRules) => {
+  if (!customRules || customRules.length === 0) return ruleRegistry;
+  const seen = /* @__PURE__ */ new Map();
+  for (const r of ruleRegistry) seen.set(r.name, "built-in");
+  const merged = [...ruleRegistry];
+  for (const r of customRules) {
+    const existing = seen.get(r.name);
+    if (existing) {
+      throw new Error(
+        `customRules: rule "${r.name}" conflicts with existing ${existing} rule. Rename your custom rule (e.g. prefix with your project name).`
       );
     }
-    const indent = /^(\s*)/.exec(lines[idx])?.[1] ?? "";
-    switch (edit.type) {
-      case "remove": {
-        lines.splice(idx, 1);
-        break;
-      }
-      case "replace": {
-        lines[idx] = applyIndent(edit.content ?? "", indent);
-        break;
-      }
-      case "add": {
-        lines.splice(idx + 1, 0, applyIndent(edit.content ?? "", indent));
-        break;
-      }
-    }
+    seen.set(r.name, "custom");
+    merged.push(r);
   }
-  return lines.join("\n");
+  return merged;
 };
-
-const detectNamingConvention = (model) => {
-  const names = model.allContainers.map((c) => c.name);
-  if (names.length === 0) return "snake";
-  const withUnderscore = names.filter((n) => n.includes("_")).length;
-  const withHyphen = names.filter((n) => n.includes("-")).length;
-  const withCamel = names.filter((n) => /[a-z][A-Z]/.test(n)).length;
-  if (withHyphen > withUnderscore && withHyphen > withCamel) return "kebab";
-  if (withCamel > withUnderscore) return "camel";
-  return "snake";
-};
-const joinName = (base, word, convention) => {
-  switch (convention) {
-    case "camel": {
-      return base + word.charAt(0).toUpperCase() + word.slice(1);
-    }
-    case "kebab": {
-      return `${base}-${word}`;
-    }
-    default: {
-      return `${base}_${word}`;
-    }
-  }
-};
-
-const fixAcl = (model, violations, syntax, options) => {
-  const tag = options?.tag ?? "acl";
-  const convention = detectNamingConvention(model);
-  const externalType = options?.externalType ?? EXTERNAL_SYSTEM_TYPE;
-  const results = [];
-  for (const violation of violations) {
-    const container = model.allContainers.find(
-      (c) => c.name === violation.container
-    );
-    if (!container) continue;
-    const externalRels = container.relations.filter(
-      (r) => r.to.type === externalType
-    );
-    if (externalRels.length === 0) continue;
-    const aclName = joinName(container.name, "acl", convention);
-    if (model.allContainers.some((c) => c.name === aclName)) {
+const warnUnknownRuleNames = (rules, effective) => {
+  if (!rules) return;
+  const known = new Set(effective.map((r) => r.name));
+  for (const key of Object.keys(rules)) {
+    if (!known.has(key)) {
       consola.warn(
-        `fix acl: skipping ${container.name} \u2014 ${aclName} already exists`
+        `Unknown rule "${key}" in config.rules \u2014 ignored. Did you forget to add it to customRules?`
       );
-      continue;
-    }
-    const fix = {
-      rule: "acl",
-      description: `Add ACL layer for ${container.name}`,
-      edits: []
-    };
-    fix.edits.push(
-      // 1. Add ACL container after the violating container
-      {
-        type: "add",
-        search: syntax.containerPattern(container.name),
-        content: syntax.containerDecl(aclName, `${container.label} ACL`, tag)
-      },
-      // 2. Add single Rel(svc, acl) after the ACL container declaration
-      {
-        type: "add",
-        search: syntax.containerPattern(aclName),
-        content: syntax.relationDecl(container.name, aclName)
-      },
-      ...externalRels.map((rel) => ({
-        type: "replace",
-        search: syntax.relationPattern(container.name, rel.to.name),
-        content: syntax.relationDecl(aclName, rel.to.name, rel.technology)
-      }))
-    );
-    results.push(fix);
-  }
-  return results;
-};
-
-const buildContainerBoundaryMap = (model) => {
-  const map = /* @__PURE__ */ new Map();
-  for (const boundary of model.boundaries) {
-    for (const container of boundary.containers) {
-      map.set(container.name, boundary);
     }
   }
-  return map;
 };
-const findPublicApiCandidate = (targetBoundary, dbType, ownerTags, model, containerBoundaryMap) => {
-  const candidates = targetBoundary.containers.filter(
-    (c) => c.type !== dbType && !ownerTags.some((t) => c.tags?.includes(t))
-  );
-  if (candidates.length === 0) return void 0;
-  if (candidates.length === 1) return candidates[0];
-  const candidateNames = new Set(candidates.map((c) => c.name));
-  const inDegree = new Map(candidates.map((c) => [c.name, 0]));
-  for (const container of model.allContainers) {
-    if (containerBoundaryMap.get(container.name) === targetBoundary) continue;
-    for (const rel of container.relations) {
-      if (candidateNames.has(rel.to.name)) {
-        inDegree.set(rel.to.name, (inDegree.get(rel.to.name) ?? 0) + 1);
-      }
-    }
-  }
-  return candidates.toSorted(
-    (a, b) => (inDegree.get(b.name) ?? 0) - (inDegree.get(a.name) ?? 0)
-  )[0];
-};
-const resolveRedirectTarget = (accessor, db, owner, dbType, ownerTags, model, containerBoundaryMap, ruleName) => {
-  const accessorBoundary = containerBoundaryMap.get(accessor.name);
-  const dbBoundary = containerBoundaryMap.get(db.name);
-  const isCrossBoundary = accessorBoundary !== void 0 && dbBoundary !== void 0 && accessorBoundary !== dbBoundary;
-  if (!isCrossBoundary) return owner;
-  const publicApi = findPublicApiCandidate(
-    dbBoundary,
-    dbType,
-    ownerTags,
-    model,
-    containerBoundaryMap
-  );
-  if (!publicApi) {
-    consola.warn(
-      `fix ${ruleName}: boundary "${dbBoundary.name}" has no public API \u2014 cannot auto-redirect "${accessor.name}" away from "${db.name}", fix manually`
-    );
-    return void 0;
-  }
-  if (publicApi === owner) {
-    consola.warn(
-      `fix ${ruleName}: the only public API candidate in "${dbBoundary.name}" is the repo owner \u2014 cross-boundary access from "${accessor.name}" requires manual review`
-    );
-    return void 0;
-  }
-  return publicApi;
-};
-
-const stripDbWord = (name) => {
-  const lower = name.toLowerCase();
-  for (const suffix of [
-    "_database",
-    "-database",
-    "database",
-    "_db",
-    "-db",
-    "db"
-  ]) {
-    if (lower.endsWith(suffix)) {
-      return name.slice(0, -suffix.length);
-    }
-  }
-  return name;
-};
-const deriveRepoName = (dbName, convention) => {
-  const base = stripDbWord(dbName);
-  return joinName(base || dbName, "repo", convention);
-};
-const deriveRepoLabel = (dbName) => {
-  const base = stripDbWord(dbName);
-  const word = base || dbName;
-  return word.charAt(0).toUpperCase() + word.slice(1).replaceAll("_", " ") + " Repo";
-};
-const fixNonRepoAccessesDb = (accessor, model, syntax, dbType, ownerTags, convention) => {
-  const dbRels = accessor.relations.filter((r) => r.to.type === dbType);
-  if (dbRels.length === 0) return void 0;
-  const containerBoundaryMap = buildContainerBoundaryMap(model);
-  const edits = dbRels.flatMap((rel) => {
-    const db = rel.to;
-    const existingRepo = model.allContainers.find(
-      (c) => c !== accessor && c.relations.some((r) => r.to.name === db.name) && ownerTags.some((t) => c.tags?.includes(t))
-    );
-    if (existingRepo) {
-      const redirectTarget = resolveRedirectTarget(
-        accessor,
-        db,
-        existingRepo,
-        dbType,
-        ownerTags,
-        model,
-        containerBoundaryMap,
-        "crud"
-      );
-      if (!redirectTarget) return [];
-      return [
-        {
-          type: "replace",
-          search: syntax.relationPattern(accessor.name, db.name),
-          content: syntax.relationDecl(
-            accessor.name,
-            redirectTarget.name,
-            rel.technology
-          )
-        }
-      ];
-    }
-    const accessorBoundary = containerBoundaryMap.get(accessor.name);
-    const dbBoundary = containerBoundaryMap.get(db.name);
-    if (accessorBoundary !== void 0 && dbBoundary !== void 0 && accessorBoundary !== dbBoundary) {
-      consola.warn(
-        `fix crud: "${accessor.name}" accesses "${db.name}" cross-boundary with no existing repo \u2014 fix manually`
-      );
-      return [];
-    }
-    const repoName = deriveRepoName(db.name, convention);
-    if (model.allContainers.some((c) => c.name === repoName)) {
-      consola.warn(
-        `fix crud: cannot create repo for "${db.name}" \u2014 "${repoName}" already exists`
-      );
-      return [];
-    }
-    return [
-      {
-        type: "add",
-        search: syntax.containerPattern(db.name),
-        content: syntax.containerDecl(
-          repoName,
-          deriveRepoLabel(db.name),
-          ownerTags[0] ?? "repo"
-        )
-      },
-      {
-        type: "add",
-        search: syntax.containerPattern(repoName),
-        content: syntax.relationDecl(repoName, db.name, rel.technology)
-      },
-      {
-        type: "replace",
-        search: syntax.relationPattern(accessor.name, db.name),
-        content: syntax.relationDecl(accessor.name, repoName, rel.technology)
-      }
-    ];
-  });
-  if (edits.length === 0) return void 0;
-  return {
-    rule: "crud",
-    description: `Add repo intermediary for ${accessor.name} \u2192 ${dbRels.map((r) => r.to.name).join(", ")}`,
-    edits
-  };
-};
-const fixRepoWithNonDbDeps = (repo, syntax, dbType) => {
-  const nonDbRels = repo.relations.filter((r) => r.to.type !== dbType);
-  if (nonDbRels.length === 0) return void 0;
-  return {
-    rule: "crud",
-    description: `Remove non-database dependencies from repo ${repo.name}`,
-    edits: nonDbRels.map((rel) => ({
-      type: "remove",
-      search: syntax.relationPattern(repo.name, rel.to.name)
-    }))
-  };
-};
-const fixCrud = (model, violations, syntax, options) => {
-  const dbType = options?.dbType ?? CONTAINER_DB_TYPE;
-  const ownerTags = options?.repoTags ?? ["repo", "relay"];
-  const convention = detectNamingConvention(model);
+const getRuleConfigValue = (rules, ruleName) => rules?.[ruleName];
+const runRules = (model, rules, effective) => {
   const results = [];
-  for (const violation of violations) {
-    const container = model.allContainers.find(
-      (c) => c.name === violation.container
-    );
-    if (!container) continue;
-    const isRepo = ownerTags.some((t) => container.tags?.includes(t));
-    if (isRepo) {
-      const fix = fixRepoWithNonDbDeps(container, syntax, dbType);
-      if (fix) results.push(fix);
-    } else {
-      const fix = fixNonRepoAccessesDb(
-        container,
-        model,
-        syntax,
-        dbType,
-        ownerTags,
-        convention
-      );
-      if (fix) results.push(fix);
-    }
-  }
-  return results;
-};
-
-const resolveOwner = (dbName, accessors, ownerTags) => {
-  const tagged = accessors.filter(
-    (c) => c.tags?.some((t) => ownerTags.includes(t))
-  );
-  if (tagged.length === 0) {
-    consola.warn(
-      `Cannot determine owner of ${dbName}: no ${ownerTags.join("/")} tagged accessor found, using ${accessors[0].name}`
-    );
-    return accessors[0];
-  }
-  if (tagged.length > 1) {
-    consola.warn(
-      `Cannot determine owner of ${dbName}: multiple tagged accessors (${tagged.map((c) => c.name).join(", ")}), using ${tagged[0].name}`
-    );
-  }
-  return tagged[0];
-};
-const fixDbPerService = (model, violations, syntax, options) => {
-  const dbType = options?.dbType ?? CONTAINER_DB_TYPE;
-  const ownerTags = options?.ownerTags ?? ["repo", "relay"];
-  const containerBoundaryMap = buildContainerBoundaryMap(model);
-  const results = [];
-  for (const violation of violations) {
-    const db = model.allContainers.find(
-      (c) => c.name === violation.container && c.type === dbType
-    );
-    if (!db) continue;
-    const accessors = model.allContainers.filter(
-      (c) => c.relations.some((r) => r.to.name === db.name)
-    );
-    if (accessors.length <= 1) continue;
-    const owner = resolveOwner(db.name, accessors, ownerTags);
-    const edits = accessors.filter((c) => c !== owner).flatMap((accessor) => {
-      const rel = accessor.relations.find((r) => r.to.name === db.name);
-      if (!rel) {
-        consola.warn(
-          `fix dbPerService: relation from ${accessor.name} to ${db.name} not found, skipping`
-        );
-        return [];
-      }
-      const redirectTarget = resolveRedirectTarget(
-        accessor,
-        db,
-        owner,
-        dbType,
-        ownerTags,
-        model,
-        containerBoundaryMap,
-        "dbPerService"
-      );
-      if (!redirectTarget) return [];
-      const tags = rel.tags && rel.tags.length > 0 ? rel.tags.join("+") : void 0;
-      return [
-        {
-          type: "replace",
-          search: syntax.relationPattern(accessor.name, db.name),
-          content: syntax.relationDecl(
-            accessor.name,
-            redirectTarget.name,
-            rel.technology ?? "",
-            tags
-          )
-        }
-      ];
-    });
-    if (edits.length === 0) continue;
-    results.push({
-      rule: "dbPerService",
-      description: `Redirect access to ${db.name} through ${owner.name}`,
-      edits
-    });
-  }
-  return results;
-};
-
-const defineRule = (def) => def;
-const ruleRegistry = [
-  defineRule({
-    name: "acl",
-    check: (m, o) => checkAcl(m.allContainers, o),
-    fix: fixAcl
-  }),
-  defineRule({ name: "acyclic", check: (m) => checkAcyclic(m.allContainers) }),
-  defineRule({
-    name: "apiGateway",
-    check: (m, o) => checkApiGateway(m.allContainers, o)
-  }),
-  defineRule({
-    name: "crud",
-    check: (m, o) => checkCrud(m.allContainers, o),
-    fix: fixCrud
-  }),
-  defineRule({
-    name: "dbPerService",
-    check: (m, o) => checkDbPerService(m.allContainers, o),
-    fix: fixDbPerService
-  }),
-  defineRule({
-    name: "cohesion",
-    check: (m, o) => checkCohesion(m, o)
-  }),
-  defineRule({
-    name: "stableDependencies",
-    check: (m, o) => checkStableDependencies(m.allContainers, o)
-  }),
-  defineRule({
-    name: "commonReuse",
-    check: (m) => checkCommonReuse(m)
-  })
-];
-
-const ruleMap = new Map(ruleRegistry.map((r) => [r.name, r]));
-const exitWithViolations = () => process.exit(1);
-const runRules = (model, rules) => {
-  const results = [];
-  for (const rule of ruleRegistry) {
-    const configValue = rules?.[rule.name];
+  for (const rule of effective) {
+    const configValue = getRuleConfigValue(rules, rule.name);
     if (configValue === false) continue;
     const options = typeof configValue === "object" ? configValue : void 0;
     results.push({ name: rule.name, violations: rule.check(model, options) });
   }
   return results;
 };
-const getSyntax = (config) => {
-  if (config.source.type === "plantuml") {
-    return plantumlSyntax;
+const resolveFixCapability = async (config) => {
+  const format = await loadFormat(config.source.type);
+  if (!canFix(format)) {
+    consola.warn(`Format "${format.name}" doesn't support --fix`);
+    return null;
   }
-  if (config.source.type === "structurizr") {
-    if (!config.source.writePath) {
-      consola.warn(
-        "To use --fix with structurizr, add source.writePath pointing to your workspace.dsl"
-      );
-      return null;
-    }
-    return structurizrDslSyntax;
+  if (config.source.type === "structurizr" && !config.source.writePath) {
+    consola.warn(
+      "To use --fix with structurizr, add source.writePath pointing to your workspace.dsl"
+    );
+    return null;
   }
-  return null;
+  return format.fix;
 };
-const generateFixes = (model, results, rules, syntax) => {
+const generateFixes = (model, results, rules, syntax, effective) => {
+  const ruleByName = new Map(effective.map((r) => [r.name, r]));
   const fixes = [];
   for (const result of results) {
     if (result.violations.length === 0) continue;
-    const ruleDef = ruleMap.get(result.name);
+    const ruleDef = ruleByName.get(result.name);
     if (!ruleDef?.fix) continue;
-    const configValue = rules?.[ruleDef.name];
+    const configValue = getRuleConfigValue(rules, ruleDef.name);
     const options = typeof configValue === "object" ? configValue : void 0;
-    fixes.push(...ruleDef.fix(model, result.violations, syntax, options));
+    fixes.push(
+      ...ruleDef.fix?.(model, result.violations, syntax, options) ?? []
+    );
   }
   return fixes;
 };
-const formatText = (results) => {
+const formatText = (results, effective) => {
   const failed = results.filter((r) => r.violations.length > 0);
   const passed = results.filter((r) => r.violations.length === 0);
   for (const result of failed) {
     const count = result.violations.length;
     const label = count === 1 ? "violation" : "violations";
-    const countLabel = pc.red(`${count} ${label}`);
-    console.log(`${pc.bold(pc.red(result.name))}  ${countLabel}`);
+    const countLabel = colors.red(`${count} ${label}`);
+    console.log(`${colors.bold(colors.red(result.name))}  ${countLabel}`);
     const maxLen = Math.max(
       ...result.violations.map((v) => v.container.length)
     );
     for (const v of result.violations) {
-      console.log(`  ${pc.bold(v.container.padEnd(maxLen))}  ${v.message}`);
+      console.log(`  ${colors.bold(v.container.padEnd(maxLen))}  ${v.message}`);
     }
     console.log();
   }
   if (passed.length > 0) {
     console.log(
-      `${pc.dim("Passed")}  ${passed.map((r) => pc.green(r.name)).join(pc.dim(" \xB7 "))}`
+      `${colors.dim("Passed")}  ${passed.map((r) => colors.green(r.name)).join(colors.dim(" \xB7 "))}`
     );
     console.log();
   }
   const total = failed.reduce((n, r) => n + r.violations.length, 0);
   if (total === 0) {
-    console.log(pc.green("No violations found."));
-  } else {
-    const rulesLabel = failed.length === 1 ? "rule" : "rules";
     console.log(
-      pc.red(
-        `Found ${total} ${total === 1 ? "violation" : "violations"} in ${failed.length} ${rulesLabel}`
-      ) + pc.dim("  \u2014  run with --fix to apply suggested fixes")
+      box(colors.green("No violations found."), {
+        title: colors.green("\u2713 check"),
+        style: { borderColor: "green" }
+      })
     );
+    return;
   }
+  const fixableRules = failed.filter(
+    (r) => typeof effective.find((rd) => rd.name === r.name)?.fix === "function"
+  ).length;
+  const violationsLabel = total === 1 ? "violation" : "violations";
+  const rulesLabel = failed.length === 1 ? "rule" : "rules";
+  const fixableHas = fixableRules === 1 ? "rule has auto-fix" : "rules have auto-fix";
+  const fixableLine = fixableRules > 0 ? "\n" + colors.dim(`${fixableRules} ${fixableHas} \u2014 run with --fix`) : "";
+  const headline = colors.red(`${total} ${violationsLabel}`) + " " + colors.dim("in") + " " + colors.red(`${failed.length} ${rulesLabel}`) + fixableLine;
+  console.log(
+    box(headline, {
+      title: colors.red("\u2717 check"),
+      style: { borderColor: "red" }
+    })
+  );
 };
 const formatJson = (results) => {
   const output = {
@@ -633,25 +303,29 @@ const formatGithub = (results) => {
 const prefixContent = (content, first, rest) => content.split("\n").map((line, i) => i === 0 ? first + line : rest + line).join("\n");
 const formatFixes = (fixes) => {
   for (const fix of fixes) {
-    const ruleTag = pc.bold(`[${fix.rule}]`);
+    const ruleTag = colors.bold(`[${fix.rule}]`);
     console.log(`  ${ruleTag}  ${fix.description}`);
     for (const edit of fix.edits) {
       switch (edit.type) {
         case "remove": {
-          console.log(pc.red(prefixContent(edit.search, "    - ", "      ")));
+          console.log(
+            colors.red(prefixContent(edit.search, "    - ", "      "))
+          );
           break;
         }
         case "replace": {
-          console.log(pc.red(prefixContent(edit.search, "    - ", "      ")));
           console.log(
-            pc.green(prefixContent(edit.content ?? "", "    + ", "      "))
+            colors.red(prefixContent(edit.search, "    - ", "      "))
+          );
+          console.log(
+            colors.green(prefixContent(edit.content ?? "", "    + ", "      "))
           );
           break;
         }
         case "add": {
-          console.log(pc.dim(`    (after "${edit.search}")`));
+          console.log(colors.dim(`    (after "${edit.search}")`));
           console.log(
-            pc.green(prefixContent(edit.content ?? "", "    + ", "      "))
+            colors.green(prefixContent(edit.content ?? "", "    + ", "      "))
           );
           break;
         }
@@ -665,7 +339,7 @@ const detectFormat = (format) => {
   if (process.env.GITHUB_ACTIONS) return "github";
   return "text";
 };
-const formatResults = (results, format) => {
+const formatResults = (results, format, effective) => {
   switch (format) {
     case "json": {
       formatJson(results);
@@ -676,11 +350,11 @@ const formatResults = (results, format) => {
       break;
     }
     default: {
-      formatText(results);
+      formatText(results, effective);
     }
   }
 };
-const writeFixes = async (config, fixes) => {
+const writeFixes = async (config, fixes, effective) => {
   const writePath = path.resolve(config.source.writePath ?? config.source.path);
   let source = await readFile(writePath, "utf8");
   for (const fix of fixes) {
@@ -694,43 +368,55 @@ const writeFixes = async (config, fixes) => {
       "DSL updated \u2014 regenerate workspace.json from workspace.dsl before re-checking"
     );
   } else {
-    const reModel = await loadModel(config);
-    const reResults = runRules(reModel, config.rules);
+    const { model: reModel } = await loadModel(config);
+    const reResults = runRules(reModel, config.rules, effective);
     const remaining = reResults.reduce((n, r) => n + r.violations.length, 0);
     consola.success(
       `Applied ${fixes.length} fix(es), wrote ${writePath}` + (remaining > 0 ? ` (${remaining} violation(s) remain)` : "")
     );
   }
 };
-const handleFixMode = async (model, results, config, dryRun) => {
+const handleFixMode = async (model, results, config, dryRun, effective) => {
   const hasViolations = results.some((r) => r.violations.length > 0);
   if (!hasViolations) {
     consola.success("No violations to fix");
     return;
   }
-  const syntax = getSyntax(config);
-  if (!syntax) return exitWithViolations();
-  const fixes = generateFixes(model, results, config.rules, syntax);
+  const fixCapability = await resolveFixCapability(config);
+  if (!fixCapability) return exitWithViolations();
+  const fixes = generateFixes(
+    model,
+    results,
+    config.rules,
+    fixCapability.syntax,
+    effective
+  );
   if (fixes.length === 0) {
     consola.info("No auto-fixes available for these violations");
     exitWithViolations();
   }
   console.log(
-    pc.bold(dryRun ? "Suggested fixes (dry run):" : "Applying fixes:")
+    colors.bold(dryRun ? "Suggested fixes (dry run):" : "Applying fixes:")
   );
   console.log();
   formatFixes(fixes);
   console.log();
   if (!dryRun) {
-    await writeFixes(config, fixes);
+    await writeFixes(config, fixes, effective);
   }
 };
-const suggestFixes = (model, results, config) => {
-  const syntax = getSyntax(config);
-  if (!syntax) return;
-  const fixes = generateFixes(model, results, config.rules, syntax);
+const suggestFixes = async (model, results, config, effective) => {
+  const fixCapability = await resolveFixCapability(config);
+  if (!fixCapability) return;
+  const fixes = generateFixes(
+    model,
+    [...results],
+    config.rules,
+    fixCapability.syntax,
+    effective
+  );
   if (fixes.length > 0) {
-    console.log(pc.bold("Suggested fixes:"));
+    console.log(colors.bold("Suggested fixes:"));
     console.log();
     formatFixes(fixes);
   }
@@ -757,43 +443,32 @@ const check = defineCommand({
   },
   async run({ args }) {
     const config = await loadAndValidateConfig(args.config);
-    const model = await loadModel(config);
-    const results = runRules(model, config.rules);
-    formatResults(results, detectFormat(args.format));
+    const effective = buildEffectiveRules(config.customRules);
+    warnUnknownRuleNames(config.rules, effective);
+    const { model, issues } = await loadModel(config);
+    for (const issue of issues) {
+      consola.warn(`model: ${issue.kind}`, issue);
+    }
+    const results = runRules(model, config.rules, effective);
+    formatResults(results, detectFormat(args.format), effective);
     const hasViolations = results.some((r) => r.violations.length > 0);
     if (args.fix || args["dry-run"]) {
-      await handleFixMode(model, results, config, args["dry-run"] ?? false);
+      await handleFixMode(
+        model,
+        results,
+        config,
+        args["dry-run"] ?? false,
+        effective
+      );
       return;
     }
     if (hasViolations) {
-      suggestFixes(model, results, config);
+      await suggestFixes(model, results, config, effective);
       exitWithViolations();
     }
   }
 });
 
-const runPlantuml = async (model, config, outputPath) => {
-  const puml = generatePlantumlFromModel(model, {
-    boundaryLabel: config.generate?.boundaryLabel
-  });
-  if (outputPath) {
-    await fs.writeFile(outputPath, puml);
-    consola.success(`Written to ${outputPath}`);
-  } else {
-    console.log(puml);
-  }
-};
-const runKubernetes = async (model, config, outputDir) => {
-  const outputs = generateKubernetes(model);
-  const targetDir = outputDir ?? config.generate?.kubernetes?.path ?? "resources/kubernetes/microservices";
-  await fs.mkdir(targetDir, { recursive: true });
-  await Promise.all(
-    outputs.map(
-      (output) => fs.writeFile(path.join(targetDir, output.fileName), output.content)
-    )
-  );
-  consola.success(`Generated ${outputs.length} file(s) in ${targetDir}`);
-};
 const generate = defineCommand({
   meta: { description: "Generate architecture artifacts" },
   args: {
@@ -803,30 +478,44 @@ const generate = defineCommand({
     },
     output: {
       type: "string",
-      description: "Output path (file for plantuml, directory for kubernetes)"
+      description: "Output path (file for single output, directory for multi)"
     },
     format: {
       type: "string",
-      description: "Output format: plantuml, kubernetes"
+      description: "Target format name (plantuml, kubernetes, ...)"
     }
   },
   async run({ args }) {
     const config = await loadAndValidateConfig(args.config);
-    const model = await loadModel(config);
-    const format = args.format ?? "plantuml";
-    switch (format) {
-      case "plantuml": {
-        await runPlantuml(model, config, args.output);
-        break;
-      }
-      case "kubernetes": {
-        await runKubernetes(model, config, args.output);
-        break;
-      }
-      default: {
-        throw new Error(`Unknown format: ${format}`);
+    const { model } = await loadModel(config);
+    const formatName = args.format ?? "plantuml";
+    const format = await loadFormat(formatName);
+    if (!canGenerate(format)) {
+      throw new Error(`Format "${format.name}" doesn't support generate`);
+    }
+    const output = format.generate(model);
+    if (output.files.length === 0) {
+      consola.warn("Generator produced no files");
+      return;
+    }
+    if (output.files.length === 1) {
+      const file = output.files[0];
+      if (args.output) {
+        await fs.writeFile(args.output, file.content);
+        consola.success(`Written to ${args.output}`);
+      } else {
+        console.log(file.content);
       }
+      return;
     }
+    const targetDir = args.output ?? config.generate?.kubernetes?.path ?? "fixtures/kubernetes/microservices";
+    await fs.mkdir(targetDir, { recursive: true });
+    await Promise.all(
+      output.files.map(
+        (f) => fs.writeFile(path.join(targetDir, f.path), f.content)
+      )
+    );
+    consola.success(`Generated ${output.files.length} file(s) in ${targetDir}`);
   }
 });
 
@@ -851,9 +540,35 @@ const config: AactConfig = {
     commonReuse: true, // Reuse all of a context's public API or none
   },
 
+  // -----------------------------------------------------------------------
+  // Project-specific (custom) rules
+  //
+  // After \`npm install aact\` locally, switch from this type-only import to
+  // \`defineConfig\` to register your own checks alongside the built-ins:
+  //
+  //   import { defineConfig } from "aact";
+  //   import { bcIsolationRule } from "./rules/bcIsolation";
+  //
+  //   export default defineConfig({
+  //     source: { type: "plantuml", path: "./architecture.puml" },
+  //
+  //     customRules: [bcIsolationRule],
+  //
+  //     rules: {
+  //       acl: true,
+  //       // Configure custom rules with the same syntax as built-ins.
+  //       // TypeScript autocompletes options based on the rule definition.
+  //       bcIsolation: { apiSuffix: "_api" },
+  //     },
+  //   });
+  //
+  // Worked example with two rules and tests:
+  //   https://github.com/Byndyusoft/aact/tree/main/examples/custom-rules
+  // -----------------------------------------------------------------------
+
   // PlantUML generation from Kubernetes configs (aact generate)
   // generate: {
-  //   kubernetes: { path: "./resources/kubernetes" },
+  //   kubernetes: { path: "./fixtures/kubernetes" },
   //   boundaryLabel: "Our system",
   // },
 };
@@ -912,12 +627,93 @@ const init = defineCommand({
   }
 });
 
+const buildEffectiveSet = async () => {
+  const out = [];
+  let config;
+  try {
+    config = await loadAndValidateConfig();
+  } catch {
+    return ruleRegistry.map((rule2) => ({
+      rule: rule2,
+      source: "built-in",
+      enabled: true
+    }));
+  }
+  const rules = config.rules;
+  const isEnabled = (name) => rules?.[name] !== false;
+  for (const rule2 of ruleRegistry) {
+    out.push({ rule: rule2, source: "built-in", enabled: isEnabled(rule2.name) });
+  }
+  for (const rule2 of config.customRules ?? []) {
+    out.push({ rule: rule2, source: "custom", enabled: isEnabled(rule2.name) });
+  }
+  return out;
+};
+const listAction = defineCommand({
+  meta: { description: "List all effective rules (built-in + custom)" },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Output in JSON format"
+    }
+  },
+  async run({ args }) {
+    const effective = await buildEffectiveSet();
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          effective.map((e) => ({
+            name: e.rule.name,
+            description: e.rule.description,
+            source: e.source,
+            enabled: e.enabled,
+            hasFix: typeof e.rule.fix === "function"
+          })),
+          void 0,
+          2
+        )
+      );
+      return;
+    }
+    const groups = {
+      "built-in": [],
+      custom: []
+    };
+    for (const e of effective) groups[e.source].push(e);
+    const renderGroup = (label, items) => {
+      if (items.length === 0) return;
+      console.log(colors.bold(label));
+      const maxName = Math.max(...items.map((i) => i.rule.name.length));
+      for (const { rule: rule2, enabled: enabled2 } of items) {
+        const status = enabled2 ? colors.green("\u25CF") : colors.dim("\u25CB");
+        const fix = rule2.fix ? colors.dim(" [fix]") : "";
+        const name = enabled2 ? colors.bold(rule2.name.padEnd(maxName)) : colors.dim(rule2.name.padEnd(maxName));
+        console.log(
+          `  ${status}  ${name}  ${colors.dim(rule2.description)}${fix}`
+        );
+      }
+      console.log();
+    };
+    renderGroup("Built-in", groups["built-in"]);
+    renderGroup("Custom", groups.custom);
+    const enabled = effective.filter((e) => e.enabled).length;
+    const total = effective.length;
+    console.log(
+      colors.dim(`${enabled}/${total} rules enabled \xB7 \u25CF enabled \xB7 \u25CB disabled`)
+    );
+  }
+});
+const rule = defineCommand({
+  meta: { description: "Inspect and manage architecture rules" },
+  subCommands: { list: listAction }
+});
+
 const main = defineCommand({
   meta: {
     name: "aact",
     version,
     description: "Architecture analysis and compliance tool"
   },
-  subCommands: { init, check, analyze, generate }
+  subCommands: { init, check, analyze, generate, rule }
 });
 void runMain(main);