aact 2.1.5 → 3.0.0-beta.3

package/dist/index.d.ts

@@ -1,48 +1,231 @@
 import * as v from 'valibot';
-import { UMLElement } from 'plantuml-parser';
 
+/**
+ * Self-sufficient C4 Model for aact. Covers full PlantUML / Mermaid C4 /
+ * Structurizr DSL API surface — round-trip без потерь данных для всех
+ * популярных C4-as-code инструментов.
+ *
+ * Scope (намеренно): Solution Architect — C4 Static (L1/L2/L3) + System
+ * Landscape + Dynamic. НЕ покрывается: Deployment view (System Architect /
+ * kube-score territory), ArchiMate, UML, BPMN.
+ *
+ * Performance: Record<string, T> вместо Map<string, T> — на масштабе aact
+ * (30-300 containers) V8 inline cache даёт ~1ns lookup, Map ~50ns. Плюс
+ * JSON.stringify работает нативно, console.log показывает tree.
+ */
+/** C4 element types. Полный stdlib набор. */
+type ContainerKind = "Person" | "System" | "Container" | "ContainerDb" | "ContainerQueue" | "Component" | "ComponentDb" | "ComponentQueue";
+/**
+ * Boundary types сохраняются для round-trip без шумного diff'а в git.
+ * PlantUML автор писал `System_Boundary` / `Container_Boundary` /
+ * `Component_Boundary` / `Enterprise_Boundary` — `aact generate` обязан
+ * вернуть тот же ключ. Generic `Boundary(...)` мапится на "System".
+ */
+type BoundaryKind = "System" | "Container" | "Component" | "Enterprise";
+/**
+ * Foundation для clickable file:line violations в CLI output'е (terminal-link
+ * OSC8). Optional на типе — loader'ы заполняют где могут, test fixtures могут
+ * опустить.
+ */
+interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly column?: number;
+    readonly endLine?: number;
+}
+/**
+ * Связь между двумя контейнерами. `to` — имя целевого контейнера (name-ref),
+ * не объектная ссылка — это рвёт Container↔Relation цикл, делает Model
+ * сериализуемой и упрощает test fixtures (`to: "containerB"` вместо ref'а).
+ */
 interface Relation {
-    readonly to: Container;
+    /** Имя целевого контейнера. Lookup через `model.containers[rel.to]` или helper `targetOf(model, rel)`. */
+    readonly to: string;
+    /** Описание/label. PlantUML `Rel(from, to, label, ...)`, Structurizr `rel.description`. */
+    readonly description?: string;
+    /** Технология. PlantUML `Rel(..., ?techn, ...)`, Structurizr `rel.technology`. */
     readonly technology?: string;
-    readonly tags?: string[];
-}
-
+    /** Tags всегда массив (пустой если нет тегов) — убирает `?.includes()` шум в правилах. */
+    readonly tags: readonly string[];
+    /** Sprite. PlantUML/Mermaid `Rel(..., ?sprite, ...)`. */
+    readonly sprite?: string;
+    /** Sequence number для Dynamic diagrams. PlantUML `$index=Index()`, Structurizr dynamic step. */
+    readonly order?: number;
+    /** $link для clickable diagrams. */
+    readonly link?: string;
+    /** Structurizr relation properties + perspectives (через `perspective.<name>` prefix). */
+    readonly properties?: Readonly<Record<string, string>>;
+    /** Foundation для terminal-link OSC8. Заполняется loader'ом где возможно. */
+    readonly sourceLocation?: SourceLocation;
+}
+/**
+ * C4 element: Person, System, Container или Component. `kind` — typed union,
+ * не stringly. `external` — orthogonal flag (не отдельный `System_Ext` kind),
+ * покрывает все 8 `_Ext` вариантов PlantUML/Mermaid одним полем.
+ */
 interface Container {
+    /** Уникальное имя — ключ в `model.containers`. PlantUML alias / Structurizr `structurizr.dsl.identifier`. */
     readonly name: string;
+    /** Human-readable label. PlantUML `Container(alias, label, ...)`. */
     readonly label: string;
-    readonly type?: string;
-    readonly tags?: string[];
+    /** Типизированный C4 kind. Compile-error на typo. */
+    readonly kind: ContainerKind;
+    /** Внешний контейнер (System_Ext, Container_Ext etc.). Orthogonal к kind. */
+    readonly external: boolean;
     readonly description: string;
-    readonly relations: Relation[];
-}
-
+    /** C4 technology — Structurizr `cont.technology`, PlantUML `Container(alias, label, ?techn, ...)`. */
+    readonly technology?: string;
+    /** Tags всегда массив, не optional — убирает `?.includes()` в правилах. */
+    readonly tags: readonly string[];
+    /** PlantUML/Mermaid `?sprite` — отдельно от tags (раньше попадал в tags). */
+    readonly sprite?: string;
+    /** Исходящие relations. Целевые контейнеры — name-refs (`relation.to`). */
+    readonly relations: readonly Relation[];
+    /** $link для clickable diagrams. */
+    readonly link?: string;
+    /** Structurizr arbitrary properties (включая archetype name + perspectives через `perspective.<name>` prefix). */
+    readonly properties?: Readonly<Record<string, string>>;
+    readonly sourceLocation?: SourceLocation;
+}
+/**
+ * Структурная граница. `containerNames` и `boundaryNames` — name-refs, не
+ * object-refs (как в `Relation.to`) — делает Model сериализуемой и упрощает
+ * test fixtures.
+ */
 interface Boundary {
     readonly name: string;
     readonly label: string;
-    readonly type?: string;
-    boundaries: Boundary[];
-    readonly containers: Container[];
+    readonly kind: BoundaryKind;
+    /** PlantUML Boundary `?descr`, Structurizr softwareSystem.description. */
+    readonly description?: string;
+    readonly tags: readonly string[];
+    /** Имена контейнеров внутри этой границы. Lookup через `model.containers[name]`. */
+    readonly containerNames: readonly string[];
+    /** Имена вложенных boundaries. Lookup через `model.boundaries[name]`. */
+    readonly boundaryNames: readonly string[];
+    readonly link?: string;
+    /** Structurizr softwareSystem properties (archetypes etc.). */
+    readonly properties?: Readonly<Record<string, string>>;
+    readonly sourceLocation?: SourceLocation;
+}
+/**
+ * Корневая Model. Record-based для O(1) lookup'ов на масштабе aact и native
+ * JSON-сериализации. Все поля readonly — после loader-фазы модель immutable.
+ */
+interface Model {
+    readonly containers: Readonly<Record<string, Container>>;
+    readonly boundaries: Readonly<Record<string, Boundary>>;
+    /** Корневые boundaries — top-level в рендере. Все остальные boundary вложены через `boundaryNames`. */
+    readonly rootBoundaryNames: readonly string[];
 }
 
-interface ArchitectureModel {
-    readonly boundaries: Boundary[];
-    readonly allContainers: Container[];
-}
+/**
+ * Issue найденный validateModel — проблема в loader output'е, которую
+ * раньше silent drop'ало (Structurizr component relations, PlantUML
+ * dangling Rel'ы, duplicate names при load collision).
+ *
+ * CLI решает severity: dangling/duplicate/cycle — fail, unknown-kind/
+ * self-relation — warn.
+ */
+type ModelIssue = {
+    kind: "dangling-relation";
+    from: string;
+    to: string;
+} | {
+    kind: "container-in-boundary-not-in-model";
+    container: string;
+    boundary: string;
+} | {
+    kind: "boundary-not-in-model";
+    parent: string;
+    child: string;
+} | {
+    kind: "boundary-cycle";
+    path: readonly string[];
+} | {
+    kind: "duplicate-container-name";
+    name: string;
+} | {
+    kind: "duplicate-boundary-name";
+    name: string;
+} | {
+    kind: "self-relation";
+    container: string;
+} | {
+    kind: "unknown-kind";
+    container: string;
+    raw: string;
+};
+/**
+ * Single-pass O(V + E) проверка инвариантов Model. Loader'ы зовут после
+ * построения; CLI surfaces issues пользователю с file:line context (если
+ * SourceLocation заполнен).
+ *
+ * Duplicate names ловятся на loader-side (Record overwrites молча) — loader
+ * должен явно проверять collision перед insertion и добавлять issue, либо
+ * validateModel может опираться на тот факт, что Record не сохранит дубликат.
+ * Здесь мы проверяем по уже-построенной Model — duplicates physically не
+ * могут быть, но мы оставляем тип в union для loader'а / future use.
+ */
+declare const validateModel: (model: Model) => ModelIssue[];
+declare const isDuplicateContainer: (containers: Readonly<Record<string, Container>>, name: string) => boolean;
 
-declare const EXTERNAL_SYSTEM_TYPE = "System_Ext";
-declare const SYSTEM_TYPE = "System";
-declare const CONTAINER_TYPE = "Container";
-declare const CONTAINER_DB_TYPE = "ContainerDb";
-declare const COMPONENT_TYPE = "Component";
-declare const BOUNDARY_TYPE = "Boundary";
-declare const SYSTEM_BOUNDARY_TYPE = "System_Boundary";
-declare const CONTAINER_BOUNDARY_TYPE = "Container_Boundary";
-declare const PERSON_TYPE = "Person";
+/**
+ * Все loader'ы (PlantUML, Structurizr, Kubernetes, future Mermaid/Compose/
+ * LikeC4) строят Model через эту единственную точку. Гарантии:
+ *
+ *  1. Duplicate name detection — перед insertion'ом в Record. Issue вместо
+ *     silent overwrite (что Record делает по умолчанию).
+ *  2. Final validateModel pass — dangling refs, boundary cycles, unknown
+ *     kinds. Issues аккумулируются с pre-build duplicates.
+ *  3. Immutable Model — Object.freeze на containers/boundaries/root names.
+ *  4. Stable insertion order — sorted by name для deterministic output
+ *     (JSON snapshot тестов, diff-friendly serialization).
+ *
+ * Tests могут конструировать Model вручную через literal, но через
+ * buildModel гарантия проверок одинакова с loader'ами.
+ */
+interface ModelBuildInput {
+    readonly containers: readonly Container[];
+    readonly boundaries: readonly Boundary[];
+    readonly rootBoundaryNames: readonly string[];
+    /** Issues найденные loader'ом до сборки (parse errors etc.) — добавляются к ModelIssue'ам валидации. */
+    readonly preIssues?: readonly ModelIssue[];
+}
+interface ModelBuildResult {
+    readonly model: Model;
+    readonly issues: readonly ModelIssue[];
+}
+declare const buildModel: (input: ModelBuildInput) => ModelBuildResult;
 
-interface Section {
-    readonly name: string;
-    readonly prod_value: string;
-}
+/**
+ * O(1) container lookup. Возвращает undefined для dangling references
+ * (которые validateModel ловит как ModelIssue).
+ */
+declare const getContainer: (m: Model, name: string) => Container | undefined;
+/**
+ * O(1) boundary lookup.
+ */
+declare const getBoundary: (m: Model, name: string) => Boundary | undefined;
+/**
+ * Resolve целевого Container'а по Relation.to (name-ref). Самый частый
+ * pattern в правилах: `targetOf(model, rel)?.kind === "ContainerDb"`.
+ */
+declare const targetOf: (m: Model, rel: Relation) => Container | undefined;
+/**
+ * Все контейнеры в model как массив. Удобно для `.filter()` / `.map()`,
+ * когда нужен flat iteration.
+ */
+declare const allContainers: (m: Model) => Container[];
+/**
+ * Все boundaries в model как массив.
+ */
+declare const allBoundaries: (m: Model) => Boundary[];
+/**
+ * Depth-first iteration всех boundaries — от root'ов вглубь. Visited set
+ * защищает от accidental cycles (validateModel ловит их явно).
+ */
+declare const walkBoundaries: (m: Model) => Generator<Boundary>;
 
 interface CouplingRelation {
     from: string;
@@ -55,6 +238,10 @@ interface BoundaryAnalysis {
     coupling: number;
     couplingRelations: CouplingRelation[];
 }
+interface DatabasesInfo {
+    count: number;
+    consumes: number;
+}
 interface AnalysisReport {
     elementsCount: number;
     syncApiCalls: number;
@@ -63,242 +250,346 @@ interface AnalysisReport {
     boundaries: BoundaryAnalysis[];
 }
 interface AnalyzedArchitecture {
-    model: ArchitectureModel;
+    model: Model;
     report: AnalysisReport;
 }
-interface DatabasesInfo {
-    count: number;
-    consumes: number;
-}
 interface AnalyzeOptions {
-    apiTechnologies?: string[];
-    externalType?: string;
-    dbType?: string;
+    apiTechnologies?: readonly string[];
+}
+declare const analyzeArchitecture: (model: Model, options?: AnalyzeOptions) => AnalyzedArchitecture;
+
+/**
+ * Capability-based Format API. Один Format interface, capabilities
+ * (load / generate / fix) — optional. Каждый формат self-describes что
+ * support'ит. CLI и users-as-library narrowing через type guards.
+ *
+ * Долгосрочно (десятилетия): новые capabilities добавляются как optional
+ * methods в существующем interface, не как новые типы. Никаких
+ * "SourceFormat vs ArtifactFormat" junk types под комбинации фич.
+ */
+/**
+ * Regex-based primitives для in-place editing source files. Используется
+ * fix-функциями правил. Future-ready: AST primitives добавятся как
+ * `ast?: AstPrimitives` в FixCapability — non-breaking.
+ */
+interface SourceSyntax {
+    containerPattern(name: string): string;
+    containerDecl(name: string, label: string, tags?: string): string;
+    relationPattern(from: string, to: string): string;
+    relationDecl(from: string, to: string, tech?: string, tags?: string): string;
 }
-declare const analyzeArchitecture: (model: ArchitectureModel, options?: AnalyzeOptions) => AnalyzedArchitecture;
+interface FixCapability {
+    readonly syntax: SourceSyntax;
+}
+/**
+ * Сериализованный output генератора. Single-file output (PlantUML/Mermaid/
+ * Compose) — массив из одного `GeneratedFile`. Multi-file (k8s manifests
+ * per service) — несколько. Один shape, CLI iterate'ит без discriminated
+ * dispatch'а.
+ */
+interface GeneratedFile {
+    readonly path: string;
+    readonly content: string;
+}
+interface FormatOutput {
+    readonly files: readonly GeneratedFile[];
+}
+/**
+ * Результат load'а — Model + diagnostics. Loader заполняет `issues` через
+ * buildModel (duplicate names, dangling refs, etc.) + post-build
+ * validateModel. CLI решает severity (warn / fail), users-as-library
+ * могут игнорировать или экспозить пользователю.
+ */
+interface LoadResult {
+    readonly model: Model;
+    readonly issues: readonly ModelIssue[];
+}
+/**
+ * Format — единственный contract для всех C4-as-code форматов и IaC
+ * artefactов. Capabilities опциональны:
+ *  - PlantUML / Mermaid / Structurizr: load + generate + fix
+ *  - Kubernetes / Compose: load + generate (no fix — IaC не authored руками)
+ *  - Hypothetical write-only: только generate
+ *  - Hypothetical read-only: только load
+ *
+ * `name` — уникальный идентификатор в Format registry (config.source.type).
+ * `defaultPattern` — glob для CLI `init` шаблонов и автодетекта.
+ *
+ * Structurizr load/write asymmetry (load workspace.json → fix workspace.dsl)
+ * решается через `AactConfig.source.writePath`, не через Format type.
+ */
+interface Format {
+    readonly name: string;
+    readonly defaultPattern?: string;
+    load?(path: string): Promise<LoadResult>;
+    generate?(model: Model): FormatOutput;
+    fix?: FixCapability;
+}
+/** Format с гарантированным load — после canLoad narrow. */
+type LoadableFormat = Format & {
+    load: NonNullable<Format["load"]>;
+};
+/** Format с гарантированным generate — после canGenerate narrow. */
+type GeneratableFormat = Format & {
+    generate: NonNullable<Format["generate"]>;
+};
+/** Format с гарантированным fix — после canFix narrow. */
+type FixableFormat = Format & {
+    fix: NonNullable<Format["fix"]>;
+};
+declare const canLoad: (f: Format) => f is LoadableFormat;
+declare const canGenerate: (f: Format) => f is GeneratableFormat;
+declare const canFix: (f: Format) => f is FixableFormat;
+
+interface Violation {
+    readonly container: string;
+    readonly message: string;
+}
+interface SourceEdit {
+    readonly type: "add" | "remove" | "replace";
+    readonly search: string;
+    readonly content?: string;
+}
+interface FixResult {
+    readonly rule: string;
+    readonly description: string;
+    readonly edits: readonly SourceEdit[];
+}
+/**
+ * Function-type aliases — useful когда user пишет check / fix отдельно от
+ * RuleDefinition объекта. Внутри RuleDefinition объявлены как методы
+ * (bivariant): `RuleDefinition<MyOptions>` assignable to `RuleDefinition<unknown>`,
+ * чтобы typed rules без cast'а попадали в `customRules: readonly RuleDefinition[]`.
+ *
+ * Fix получает `SourceSyntax` (regex primitives). Будущее — `FixCapability`
+ * с AST primitives. Эволюция non-breaking: добавляется новое поле SourceSyntax.
+ */
+type CheckFn<O = unknown> = (model: Model, options?: O) => readonly Violation[];
+type FixFn<O = unknown> = (model: Model, violations: readonly Violation[], syntax: SourceSyntax, options?: O) => readonly FixResult[];
+interface RuleDefinition<O = unknown> {
+    readonly name: string;
+    /** Human-readable description — для CLI `rules list`, docs, CHANGELOG. */
+    readonly description: string;
+    check(model: Model, options?: O): readonly Violation[];
+    fix?(model: Model, violations: readonly Violation[], syntax: SourceSyntax, options?: O): readonly FixResult[];
+}
+/**
+ * Identity helper для inline RuleDefinition declaracий. Generic с `<const T>`
+ * сохраняет literal type для всех полей — particularly `name`, что позволяет
+ * defineConfig'у через mapped type вытащить literal rule name и propagate'нуть
+ * autocomplete в `rules{}`.
+ *
+ * `T extends RuleDefinition` (constraint без widening через `extends`) валидирует
+ * shape без потери literal'ов.
+ *
+ * Built-ins и custom rules используют один и тот же `RuleDefinition<O>` —
+ * defineRule одинаково применим к обоим.
+ */
+declare const defineRule: <const T extends RuleDefinition>(rule: T) => T;
+
+interface AclOptions {
+    /** Tag, который маркирует ACL-контейнер. Default "acl". */
+    readonly tag?: string;
+}
+/**
+ * Anti-corruption Layer: контейнер, который зовёт внешние системы, должен
+ * быть тэгирован как ACL.
+ *
+ * v3: внешние системы определяются через `target.external === true`
+ * (orthogonal flag), не через kind == "System_Ext".
+ */
+declare const aclRule: RuleDefinition<AclOptions>;
+
+interface ApiGatewayOptions {
+    /** Tag, который маркирует ACL-контейнер. Default "acl". */
+    readonly aclTag?: string;
+    /** Regex для определения "это gateway technology". Default /gateway/i. */
+    readonly gatewayPattern?: RegExp;
+}
+/**
+ * API Gateway pattern: ACL-контейнеры, зовущие внешние системы, должны
+ * проходить через API Gateway (technology содержит "gateway").
+ */
+declare const apiGatewayRule: RuleDefinition<ApiGatewayOptions>;
+
+interface CrudOptions {
+    /** Tags маркирующие repo/relay контейнеры. Default ["repo", "relay"]. */
+    readonly repoTags?: readonly string[];
+}
+/**
+ * Database per CRUD-service: containers без repo-tag не должны напрямую
+ * обращаться к databases. Доступ через repo/relay прокси. Repo-контейнеры
+ * наоборот должны только базы трогать (no external deps).
+ */
+declare const crudRule: RuleDefinition<CrudOptions>;
+
+interface DbPerServiceOptions {
+    /** Tags маркирующие repo/relay контейнеры — определяют owner of DB. */
+    readonly ownerTags?: readonly string[];
+}
+/**
+ * Database per Service: одна база — один владелец. Если несколько
+ * контейнеров напрямую обращаются к одной БД, это нарушение принципа.
+ */
+declare const dbPerServiceRule: RuleDefinition<DbPerServiceOptions>;
 
+/**
+ * AactConfig — что пишет пользователь в `aact.config.ts`. Source + rules
+ * (per-rule опции) + customRules (external RuleDefinition[]) + generate.
+ *
+ * v3: убраны legacy options (externalType, dbType, internalType) — kind
+ * и external теперь typed fields на Model, а не configurable. Если нужно
+ * переопределить detection — это сейчас loader-side concern, не rule.
+ *
+ * Source shape — accepts:
+ *   1. String shorthand: `source: "./architecture.puml"` — type inferred from path
+ *   2. Object form: `source: { path, type?, writePath? }` — type optional,
+ *      inferred from path if missing; explicit overrides infer
+ *
+ * Type accepts arbitrary string (validated against runtime format registry at
+ * load time) — добавление нового формата = entry в registry, не breaking-bump.
+ *
+ * Rules — looseObject: typed entries для built-ins (autocomplete +
+ * options валидация), extra keys разрешены для custom rules. Custom rule
+ * options проверяются на check() time через rule.optionsSchema (если есть).
+ *
+ * CustomRules — array of RuleDefinition. Auto-enabled при load'е (не нужно
+ * писать `rules: { myRule: true }`). Чтобы выключить — `rules.<name>: false`.
+ */
 declare const AactConfigSchema: v.StrictObjectSchema<{
-    readonly source: v.StrictObjectSchema<{
-        readonly type: v.PicklistSchema<["plantuml", "structurizr"], undefined>;
+    readonly source: v.UnionSchema<[v.StringSchema<undefined>, v.StrictObjectSchema<{
         readonly path: v.StringSchema<undefined>;
+        /** Optional — infer'ится из `path` через format registry `defaultPattern` если опущен. */
+        readonly type: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        /** Structurizr only: куда писать fix'ы (workspace.dsl). */
         readonly writePath: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    }, undefined>;
-    readonly rules: v.OptionalSchema<v.StrictObjectSchema<{
+    }, undefined>], undefined>;
+    readonly rules: v.OptionalSchema<v.LooseObjectSchema<{
         readonly acl: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.StrictObjectSchema<{
             tag: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            externalType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>], undefined>, undefined>;
         readonly acyclic: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly apiGateway: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.StrictObjectSchema<{
             aclTag: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            externalType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             gatewayPattern: v.OptionalSchema<v.InstanceSchema<RegExpConstructor, undefined>, undefined>;
         }, undefined>], undefined>, undefined>;
         readonly crud: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.StrictObjectSchema<{
             repoTags: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
-            dbType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>], undefined>, undefined>;
         readonly dbPerService: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.StrictObjectSchema<{
-            dbType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             ownerTags: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
         }, undefined>], undefined>, undefined>;
-        readonly cohesion: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.StrictObjectSchema<{
-            externalType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            internalType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        }, undefined>], undefined>, undefined>;
-        readonly stableDependencies: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.StrictObjectSchema<{
-            externalType: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        }, undefined>], undefined>, undefined>;
+        readonly cohesion: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly stableDependencies: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly commonReuse: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly customRules: v.OptionalSchema<v.ArraySchema<v.AnySchema, undefined>, undefined>;
     readonly generate: v.OptionalSchema<v.StrictObjectSchema<{
         readonly kubernetes: v.OptionalSchema<v.StrictObjectSchema<{
             readonly path: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            readonly exclude: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
         }, undefined>, undefined>;
         readonly boundaryLabel: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
 }, undefined>;
-type AactConfig = v.InferOutput<typeof AactConfigSchema>;
-declare const defineConfig: (config: AactConfig) => AactConfig;
-
-interface KubernetesGenerateOptions {
-    defaultPort?: number;
-    dbConnectionTemplate?: string;
-}
-interface KubernetesOutput {
-    fileName: string;
-    content: string;
-}
-declare const generateKubernetes: (model: ArchitectureModel, options?: KubernetesGenerateOptions) => KubernetesOutput[];
-
-interface PlantumlFromModelOptions {
-    boundaryLabel?: string;
-}
-declare const generatePlantumlFromModel: (model: ArchitectureModel, options?: PlantumlFromModelOptions) => string;
-
-interface EnvValue {
-    prod?: string;
-    default?: string;
-}
-interface DeployConfig {
-    name: string;
-    fileName?: string;
-    readonly environment?: Record<string, EnvValue>;
-    sections: Section[];
-}
-
-interface LoadDeployConfigsOptions {
-    path?: string;
-    exclude?: string[];
-}
-declare const loadMicroserviceDeployConfigs: (options?: LoadDeployConfigsOptions) => Promise<DeployConfig[]>;
-
-interface KubernetesMapOptions {
-    envWhitelist?: (string | RegExp)[];
-    envNamePartsToCleanup?: (string | RegExp)[];
-}
-declare const mapFromConfigs: (deployConfigs: DeployConfig[], options?: KubernetesMapOptions) => DeployConfig[];
-
-declare const PLANTUML_CONTAINER = "Container";
-declare const PLANTUML_CONTAINER_DB = "ContainerDb";
-declare const PLANTUML_SYSTEM_EXT = "System_Ext";
-declare const PLANTUML_SYSTEM = "System";
-declare const PLANTUML_PERSON = "Person";
-declare const PLANTUML_COMPONENT = "Component";
-declare const PLANTUML_SYSTEM_BOUNDARY = "System_Boundary";
-declare const PLANTUML_CONTAINER_BOUNDARY = "Container_Boundary";
-declare const PLANTUML_BOUNDARY = "Boundary";
-
-declare const loadPlantumlElements: (filePath: string) => Promise<UMLElement[]>;
-
-declare const mapContainersFromPlantumlElements: (elements: UMLElement[]) => ArchitectureModel;
-
-declare const STRUCTURIZR_LOCATION_EXTERNAL = "External";
-declare const STRUCTURIZR_INTERACTION_ASYNC = "Asynchronous";
-declare const STRUCTURIZR_TAG_ASYNC = "async";
-
-interface StructurizrWorkspace {
-    id?: number;
-    name: string;
-    description?: string;
-    model: StructurizrModel;
-}
-interface StructurizrModel {
-    enterprise?: {
-        name: string;
+/**
+ * Built-in rules config — handcrafted interface (вместо v.InferOutput) чтобы
+ * TS user получал чистые option types в `rules{}` без `[key: string]: unknown`
+ * index-signature leak из looseObject inference.
+ *
+ * Runtime parsing идёт через `AactConfigSchema.rules` looseObject; этот TS-тип
+ * это user-facing surface для autocomplete.
+ */
+interface BuiltinRulesConfig {
+    readonly acl?: boolean | AclOptions;
+    readonly acyclic?: boolean;
+    readonly apiGateway?: boolean | ApiGatewayOptions;
+    readonly crud?: boolean | CrudOptions;
+    readonly dbPerService?: boolean | DbPerServiceOptions;
+    readonly cohesion?: boolean;
+    readonly stableDependencies?: boolean;
+    readonly commonReuse?: boolean;
+}
+/**
+ * Extract'ит options type из RuleDefinition'а через сигнатуру `check(model, options?: O)`.
+ * Используется defineConfig'ом для inference custom rule options types в `rules{}`.
+ */
+type ExtractRuleOptions<R> = R extends RuleDefinition ? Exclude<Parameters<R["check"]>[1], undefined> : never;
+/**
+ * Maps кастомные правила к их config-shape: `{ <rule.name>?: false | options }`.
+ * Через `<const C>` в defineConfig — TS preserves литеральные имена,
+ * R['name'] становится narrow string literal, а не `string`.
+ */
+type CustomRulesConfig<C extends readonly RuleDefinition[]> = {
+    readonly [R in C[number] as R["name"]]?: boolean | ExtractRuleOptions<R>;
+};
+type AactRulesConfig<C extends readonly RuleDefinition[]> = BuiltinRulesConfig & CustomRulesConfig<C>;
+/**
+ * Raw user-facing shape — это что юзер пишет в aact.config.ts. Generic'и
+ * подбираются через `defineConfig<const C>` чтобы дать autocomplete на
+ * custom rule options в `rules{}`.
+ */
+interface AactConfigInput<C extends readonly RuleDefinition[] = readonly RuleDefinition[]> {
+    readonly source: string | {
+        readonly path: string;
+        readonly type?: string;
+        readonly writePath?: string;
     };
-    people?: StructurizrPerson[];
-    softwareSystems?: StructurizrSoftwareSystem[];
-}
-interface StructurizrProperties {
-    "structurizr.dsl.identifier"?: string;
-    [key: string]: string | undefined;
-}
-interface StructurizrPerson {
-    id: string;
-    name: string;
-    description?: string;
-    tags?: string;
-    properties?: StructurizrProperties;
-    relationships?: StructurizrRelationship[];
-}
-interface StructurizrSoftwareSystem {
-    id: string;
-    name: string;
-    description?: string;
-    location?: "External" | "Internal" | "Unspecified";
-    tags?: string;
-    properties?: StructurizrProperties;
-    containers?: StructurizrContainer[];
-    relationships?: StructurizrRelationship[];
-}
-interface StructurizrContainer {
-    id: string;
-    name: string;
-    description?: string;
-    technology?: string;
-    tags?: string;
-    properties?: StructurizrProperties;
-    components?: StructurizrComponent[];
-    relationships?: StructurizrRelationship[];
-}
-interface StructurizrComponent {
-    id: string;
-    name: string;
-    description?: string;
-    technology?: string;
-    tags?: string;
-    properties?: StructurizrProperties;
-    relationships?: StructurizrRelationship[];
-}
-interface StructurizrRelationship {
-    id: string;
-    description?: string;
-    sourceId: string;
-    destinationId: string;
-    technology?: string;
-    interactionStyle?: "Synchronous" | "Asynchronous";
-    tags?: string;
-}
-
-declare const loadStructurizrWorkspace: (filePath: string) => Promise<StructurizrWorkspace>;
-declare const mapContainersFromStructurizr: (workspace: StructurizrWorkspace) => ArchitectureModel;
-declare const loadStructurizrElements: (filePath: string) => Promise<ArchitectureModel>;
-
-interface SourceSyntax {
-    containerPattern(name: string): string;
-    containerDecl(name: string, label: string, tags?: string): string;
-    relationPattern(from: string, to: string): string;
-    relationDecl(from: string, to: string, tech?: string, tags?: string): string;
-}
-
-declare const structurizrDslSyntax: SourceSyntax;
-
-interface Violation {
-    container: string;
-    message: string;
-}
+    readonly rules?: AactRulesConfig<C>;
+    readonly customRules?: C;
+    readonly generate?: v.InferInput<typeof AactConfigSchema>["generate"];
+}
+/** Normalized — то что `loadAndValidateConfig` возвращает. Source всегда object с populated `type`. */
+interface AactConfig {
+    readonly source: {
+        readonly path: string;
+        readonly type: string;
+        readonly writePath?: string;
+    };
+    readonly rules?: BuiltinRulesConfig & Readonly<Record<string, unknown>>;
+    readonly customRules?: readonly RuleDefinition[];
+    readonly generate?: v.InferOutput<typeof AactConfigSchema>["generate"];
+}
+/**
+ * Typed config builder. `<const C>` captures customRules array's literal type
+ * — каждое правило сохраняет свой `name` (literal) и `Parameters<check>[1]`
+ * (options type). Через mapped type `CustomRulesConfig<C>` это даёт user'у
+ * autocomplete + type validation на `rules: { customRuleName: { ←tab } }`.
+ */
+declare const defineConfig: <const C extends readonly RuleDefinition[]>(config: AactConfigInput<C>) => AactConfigInput<C>;
 
-interface AclOptions {
-    tag?: string;
-    externalType?: string;
-}
-declare const checkAcl: (containers: Container[], options?: AclOptions) => Violation[];
+/**
+ * Async lookup формата по name. Throws если name unknown — let caller
+ * surface user-facing error с config context.
+ */
+declare const loadFormat: (name: string) => Promise<Format>;
+/** Все зарегистрированные имена форматов. CLI `init` использует для prompt'а. */
+declare const knownFormatNames: () => readonly string[];
 
-declare const checkAcyclic: (containers: Container[]) => Violation[];
+/**
+ * Acyclic Dependencies Principle: dependency graph не должен иметь циклов.
+ * Per-container DFS, visited set предотвращает infinite loop. Dangling refs
+ * (rel.to не в model.containers) — early return false; validateModel
+ * surface'ит их отдельно.
+ */
+declare const acyclicRule: RuleDefinition;
 
-interface ApiGatewayOptions {
-    aclTag?: string;
-    externalType?: string;
-    gatewayPattern?: RegExp;
-}
-declare const checkApiGateway: (containers: Container[], options?: ApiGatewayOptions) => Violation[];
+declare const cohesionRule: RuleDefinition;
 
-interface CohesionOptions {
-    externalType?: string;
-    internalType?: string;
-}
-declare const checkCohesion: (model: ArchitectureModel, options?: CohesionOptions) => Violation[];
+declare const commonReuseRule: RuleDefinition;
 
-declare const checkCommonReuse: (model: ArchitectureModel) => Violation[];
+declare const applyEdits: (source: string, edits: readonly SourceEdit[]) => string;
 
-interface CrudOptions {
-    repoTags?: string[];
-    dbType?: string;
-}
-declare const checkCrud: (containers: Container[], options?: CrudOptions) => Violation[];
-
-interface DbPerServiceOptions {
-    dbType?: string;
-    ownerTags?: string[];
-}
-declare const checkDbPerService: (containers: Container[], options?: DbPerServiceOptions) => Violation[];
+/**
+ * Все built-in правила. Порядок определяет default order CLI вывода.
+ * Adding new rule: импорт + строчка в массиве, ничего больше не трогать.
+ *
+ * `check` / `fix` объявлены как методы в `RuleDefinition` (bivariant под
+ * strictFunctionTypes), поэтому typed rules упаковываются в `RuleDefinition[]`
+ * без cast'ов. Это тот же контракт что используют customRules.
+ */
+declare const ruleRegistry: readonly RuleDefinition[];
 
-interface StableDependenciesOptions {
-    externalType?: string;
-}
-declare const checkStableDependencies: (containers: Container[], options?: StableDependenciesOptions) => Violation[];
+declare const stableDependenciesRule: RuleDefinition;
 
-export { AactConfigSchema, BOUNDARY_TYPE, COMPONENT_TYPE, CONTAINER_BOUNDARY_TYPE, CONTAINER_DB_TYPE, CONTAINER_TYPE, EXTERNAL_SYSTEM_TYPE, PERSON_TYPE, PLANTUML_BOUNDARY, PLANTUML_COMPONENT, PLANTUML_CONTAINER, PLANTUML_CONTAINER_BOUNDARY, PLANTUML_CONTAINER_DB, PLANTUML_PERSON, PLANTUML_SYSTEM, PLANTUML_SYSTEM_BOUNDARY, PLANTUML_SYSTEM_EXT, STRUCTURIZR_INTERACTION_ASYNC, STRUCTURIZR_LOCATION_EXTERNAL, STRUCTURIZR_TAG_ASYNC, SYSTEM_BOUNDARY_TYPE, SYSTEM_TYPE, analyzeArchitecture, checkAcl, checkAcyclic, checkApiGateway, checkCohesion, checkCommonReuse, checkCrud, checkDbPerService, checkStableDependencies, defineConfig, generateKubernetes, generatePlantumlFromModel, loadMicroserviceDeployConfigs, loadPlantumlElements, loadStructurizrElements, loadStructurizrWorkspace, mapContainersFromPlantumlElements, mapContainersFromStructurizr, mapFromConfigs, structurizrDslSyntax };
-export type { AactConfig, AclOptions, AnalysisReport, AnalyzeOptions, AnalyzedArchitecture, ApiGatewayOptions, ArchitectureModel, Boundary, BoundaryAnalysis, CohesionOptions, Container, CouplingRelation, CrudOptions, DbPerServiceOptions, DeployConfig, EnvValue, KubernetesGenerateOptions, KubernetesMapOptions, KubernetesOutput, LoadDeployConfigsOptions, PlantumlFromModelOptions, Relation, Section, StableDependenciesOptions, StructurizrComponent, StructurizrContainer, StructurizrModel, StructurizrPerson, StructurizrProperties, StructurizrRelationship, StructurizrSoftwareSystem, StructurizrWorkspace, Violation };
+export { AactConfigSchema, aclRule, acyclicRule, allBoundaries, allContainers, analyzeArchitecture, apiGatewayRule, applyEdits, buildModel, canFix, canGenerate, canLoad, cohesionRule, commonReuseRule, crudRule, dbPerServiceRule, defineConfig, defineRule, getBoundary, getContainer, isDuplicateContainer, knownFormatNames, loadFormat, ruleRegistry, stableDependenciesRule, targetOf, validateModel, walkBoundaries };
+export type { AactConfig, AactConfigInput, AactRulesConfig, AclOptions, AnalysisReport, AnalyzeOptions, AnalyzedArchitecture, ApiGatewayOptions, Boundary, BoundaryAnalysis, BoundaryKind, BuiltinRulesConfig, CheckFn, Container, ContainerKind, CouplingRelation, CrudOptions, CustomRulesConfig, DbPerServiceOptions, FixCapability, FixFn, FixResult, Format, FormatOutput, LoadResult, Model, ModelBuildInput, ModelBuildResult, ModelIssue, Relation, RuleDefinition, SourceEdit, SourceLocation, SourceSyntax, Violation };