aact 2.1.2 → 2.1.4

package/README.md

@@ -3,7 +3,7 @@
 # Architecture As Code Tools (aact)
 
 [![npm version](https://img.shields.io/npm/v/aact)](https://www.npmjs.com/package/aact)
-[![test workflow](https://github.com/razonrus/ArchAsCode_Tests/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/razonrus/ArchAsCode_Tests/actions/workflows/test.yaml)
+[![test workflow](https://github.com/Byndyusoft/aact/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/Byndyusoft/aact/actions/workflows/test.yaml)
 
 CLI и библиотека для валидации, анализа и генерации архитектуры микросервисных систем, описанной "as Code" (PlantUML C4, Structurizr).
 
@@ -19,31 +19,57 @@ CLI и библиотека для валидации, анализа и ген
 
 <img src="https://github.com/Byndyusoft/aact/assets/1096954/a3c3b3b0-a09b-4da7-aca4-5538159b371c" width="15"/> Телеграм-канал: [Архитектура распределённых систем](https://t.me/rsa_enc)
 
+aact можно использовать двумя способами: как **CLI** (`npx aact check`, авто-фикс, генерация артефактов) или как **библиотеку** (импортировать `checkAcl`, `analyzeArchitecture` и пр. в свои тесты на vitest/jest). CLI — ниже, library-режим — в [соответствующем разделе](#использование-как-библиотеки).
+
 ## Quick Start (CLI)
 
+В пустой папке:
+
 ```bash
-# Инициализация конфига
+# Создаёт aact.config.ts и стартовый architecture.puml с одним
+# умышленным нарушением, чтобы было что чинить
 npx aact init
 
-# Проверка правил архитектуры
+# Покажет 1 нарушение CRUD-правила (orders → orders_db напрямую)
 npx aact check
 
-# Анализ метрик
-npx aact analyze
+# Применит auto-fix: добавит orders_repo как посредника к БД
+npx aact check --fix
+
+# Снова чисто
+npx aact check
+```
+
+После этого правь `architecture.puml` под свою систему — синтаксис
+[C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML).
+
+### Остальные команды
 
-# Генерация артефактов
-npx aact generate --format plantuml
+```bash
+npx aact check --dry-run             # preview auto-fix без записи
+npx aact analyze                     # coupling/cohesion метрики
+npx aact generate --format plantuml  # сгенерировать .puml из источника
 npx aact generate --format kubernetes
 ```
 
-### Конфигурация
+> Для `structurizr` укажите `source.writePath` в `aact.config.ts` —
+> путь к `workspace.dsl`, в который пишутся правки от `--fix`.
+
+### Что создаёт `aact init`
 
-`aact init` создаст файл `aact.config.ts`:
+Два файла рядом:
+
+- **`aact.config.ts`** — настройки источника и набор включённых правил.
+  Использует `import type { AactConfig }` — рантайм-резолва пакета не
+  происходит, поэтому `npx aact check` работает без `npm install aact`.
+- **`architecture.puml`** — стартовая C4-схема с одним сервисом,
+  одной БД и умышленным нарушением CRUD-правила. Замени на свою.
 
 ```ts
-import { defineConfig } from "aact";
+// aact.config.ts (фрагмент)
+import type { AactConfig } from "aact";
 
-export default defineConfig({
+const config: AactConfig = {
   source: {
     type: "plantuml", // "plantuml" | "structurizr"
     path: "./architecture.puml",
@@ -51,11 +77,16 @@ export default defineConfig({
   rules: {
     acl: true,
     acyclic: true,
+    apiGateway: true,
     crud: true,
     dbPerService: true,
     cohesion: true,
+    stableDependencies: true,
+    commonReuse: true,
   },
-});
+};
+
+export default config;
 ```
 
 ## Использование как библиотеки
@@ -84,8 +115,14 @@ console.log(`Elements: ${report.elementsCount}`);
 
 ## Примеры
 
-- [Banking (PlantUML)](examples/banking-plantuml/) — проверка правил, CCR-анализ, генерация K8s-конфигов
-- [Microservices (Structurizr)](examples/microservices-structurizr/) — полный цикл: правила, анализ, генерация
+Запускаемые из коробки (склонируй репо, `cd examples/<name>`, `npx aact check`):
+
+- [`examples/ecommerce-structurizr/`](examples/ecommerce-structurizr/) — Structurizr-источник с `workspace.json` + `workspace.dsl`, полный цикл правил и auto-fix.
+- [`examples/violations-demo/`](examples/violations-demo/) — мини-набор умышленных нарушений по каждому правилу — чтобы посмотреть, как выглядит вывод и какие правки предлагает `--fix`.
+
+Тестовые сценарии (для разработчиков пакета, запускаются через `vitest`):
+
+- [`examples/banking-plantuml/`](examples/banking-plantuml/) и [`examples/microservices-structurizr/`](examples/microservices-structurizr/) — интеграционные тесты архитектуры из `resources/`.
 
 ## Документация
 

package/dist/cli/index.mjs

@@ -1,7 +1,7 @@
 #!/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.Cpfuzz1A.mjs';
+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.BzhD7c9t.mjs';
 import { loadConfig } from 'c12';
 import * as v from 'valibot';
 import path from 'node:path';
@@ -10,6 +10,8 @@ import pc from 'picocolors';
 import 'yaml';
 import 'plantuml-parser';
 
+const version = "2.1.4";
+
 const loadAndValidateConfig = async (configPath) => {
   const { config } = await loadConfig({
     name: "aact",
@@ -21,20 +23,48 @@ const loadAndValidateConfig = async (configPath) => {
   return v.parse(AactConfigSchema, config);
 };
 
+const isFileNotFound = (err) => typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+const exitWithError = (message, hint) => {
+  consola.error(message);
+  if (hint) consola.info(hint);
+  return process.exit(1);
+};
 const loadModel = async (config) => {
   const resolvedPath = path.resolve(config.source.path);
-  switch (config.source.type) {
-    case "plantuml": {
-      const elements = await loadPlantumlElements(resolvedPath);
-      return mapContainersFromPlantumlElements(elements);
+  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)}`);
+      }
     }
-    case "structurizr": {
-      return loadStructurizrElements(resolvedPath);
+  } catch (error) {
+    if (isFileNotFound(error)) {
+      return exitWithError(
+        `Architecture file not found: ${config.source.path}`,
+        "Update source.path in aact.config.ts or create the file (`aact init` scaffolds a starter)."
+      );
     }
-    default: {
-      const sourceType = config.source.type;
-      throw new Error(`Unsupported source type: ${String(sourceType)}`);
+    if (error instanceof SyntaxError && config.source.type === "structurizr") {
+      return exitWithError(
+        `Cannot parse Structurizr workspace: ${config.source.path}`,
+        `${error.message}. Check that the file is valid JSON.`
+      );
+    }
+    if (error instanceof TypeError && config.source.type === "structurizr" && /softwareSystems|model|people/.test(error.message)) {
+      return exitWithError(
+        `Invalid Structurizr workspace: ${config.source.path}`,
+        'Expected a top-level "model" object with "softwareSystems". See examples/ecommerce-structurizr/ for a working sample.'
+      );
     }
+    throw error;
   }
 };
 
@@ -685,7 +715,12 @@ const handleFixMode = async (model, results, config, dryRun) => {
     consola.info("No auto-fixes available for these violations");
     exitWithViolations();
   }
+  console.log(
+    pc.bold(dryRun ? "Suggested fixes (dry run):" : "Applying fixes:")
+  );
+  console.log();
   formatFixes(fixes);
+  console.log();
   if (!dryRun) {
     await writeFixes(config, fixes);
   }
@@ -795,61 +830,92 @@ const generate = defineCommand({
   }
 });
 
-const template = `import { defineConfig } from "aact";
+const configTemplate = `import type { AactConfig } from "aact";
 
-export default defineConfig({
+const config: AactConfig = {
   // Source of architecture description
   source: {
-    type: "structurizr", // "plantuml" | "structurizr"
-    path: "./workspace.json",
+    type: "plantuml", // "plantuml" | "structurizr"
+    path: "./architecture.puml",
   },
 
   // Validation rules (true = enabled with defaults, false = disabled)
   rules: {
     acl: true, // Anti-Corruption Layer: only tagged containers depend on externals
-    // acl: { tag: "acl", externalType: "System_Ext" },
-
     acyclic: true, // No circular dependencies
-
+    apiGateway: true, // External calls go through an API gateway
     crud: true, // Only repo/relay containers access databases
-    // crud: { repoTags: ["repo", "relay"], dbType: "ContainerDb" },
-
-    dbPerService: true, // Each database accessed by single service
-    // dbPerService: { dbType: "ContainerDb" },
-
+    dbPerService: true, // Each database accessed by a single service
     cohesion: true, // Boundary cohesion > coupling
-    // cohesion: { externalType: "System_Ext", internalType: "Container" },
+    stableDependencies: true, // Depend on more stable components
+    commonReuse: true, // Reuse all of a context's public API or none
   },
 
   // PlantUML generation from Kubernetes configs (aact generate)
   // generate: {
-  //   kubernetes: {
-  //     path: "resources/kubernetes/microservices",
-  //   },
+  //   kubernetes: { path: "./resources/kubernetes" },
   //   boundaryLabel: "Our system",
   // },
-});
+};
+
+export default config;
+`;
+const architectureTemplate = `@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+' Starter architecture. Replace with your own.
+' One intentional CRUD violation: \`orders\` accesses \`orders_db\` directly.
+' Run \`aact check\` to see it, then \`aact check --fix\` to auto-add a repo.
+
+System_Boundary(checkout, "Checkout") {
+  Container(orders, "Orders Service")
+  ContainerDb(orders_db, "Orders DB")
+}
+
+Rel(orders, orders_db, "PostgreSQL")
+@enduml
 `;
 const configFileName = "aact.config.ts";
+const architectureFileName = "architecture.puml";
+const writeIfNew = async (filePath, content, label) => {
+  try {
+    await fs.access(filePath);
+    consola.warn(`${label} already exists. Skipping.`);
+    return false;
+  } catch {
+    await fs.writeFile(filePath, content);
+    consola.success(`Created ${label}`);
+    return true;
+  }
+};
 const init = defineCommand({
-  meta: { description: "Create aact.config.ts with default settings" },
+  meta: {
+    description: "Create aact.config.ts and a starter architecture file"
+  },
   async run() {
-    const configPath = path.resolve(process.cwd(), configFileName);
-    try {
-      await fs.access(configPath);
-      consola.warn(`${configFileName} already exists. Skipping.`);
-      return;
-    } catch {
+    const cwd = process.cwd();
+    const configCreated = await writeIfNew(
+      path.resolve(cwd, configFileName),
+      configTemplate,
+      configFileName
+    );
+    const archCreated = await writeIfNew(
+      path.resolve(cwd, architectureFileName),
+      architectureTemplate,
+      architectureFileName
+    );
+    if (configCreated || archCreated) {
+      consola.info(
+        "Next: run `aact check` to see violations, then `aact check --fix` to auto-fix."
+      );
     }
-    await fs.writeFile(configPath, template);
-    consola.success(`Created ${configFileName}`);
   }
 });
 
 const main = defineCommand({
   meta: {
     name: "aact",
-    version: "2.0.2",
+    version,
     description: "Architecture analysis and compliance tool"
   },
   subCommands: { init, check, analyze, generate }

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { A as AactConfigSchema, B as BOUNDARY_TYPE, C as COMPONENT_TYPE, a as CONTAINER_BOUNDARY_TYPE, b as CONTAINER_DB_TYPE, c as CONTAINER_TYPE, E as EXTERNAL_SYSTEM_TYPE, P as PERSON_TYPE, d as PLANTUML_BOUNDARY, e as PLANTUML_COMPONENT, f as PLANTUML_CONTAINER, g as PLANTUML_CONTAINER_BOUNDARY, h as PLANTUML_CONTAINER_DB, i as PLANTUML_PERSON, j as PLANTUML_SYSTEM, k as PLANTUML_SYSTEM_BOUNDARY, l as PLANTUML_SYSTEM_EXT, S as STRUCTURIZR_INTERACTION_ASYNC, m as STRUCTURIZR_LOCATION_EXTERNAL, n as STRUCTURIZR_TAG_ASYNC, o as SYSTEM_BOUNDARY_TYPE, p as SYSTEM_TYPE, q as analyzeArchitecture, r as checkAcl, s as checkAcyclic, t as checkApiGateway, u as checkCohesion, v as checkCommonReuse, w as checkCrud, x as checkDbPerService, y as checkStableDependencies, z as defineConfig, D as generateKubernetes, F as generatePlantumlFromModel, G as loadPlantumlElements, H as loadStructurizrElements, I as loadStructurizrWorkspace, J as mapContainersFromPlantumlElements, K as mapContainersFromStructurizr, L as structurizrDslSyntax } from './shared/aact.Cpfuzz1A.mjs';
+export { A as AactConfigSchema, B as BOUNDARY_TYPE, C as COMPONENT_TYPE, a as CONTAINER_BOUNDARY_TYPE, b as CONTAINER_DB_TYPE, c as CONTAINER_TYPE, E as EXTERNAL_SYSTEM_TYPE, P as PERSON_TYPE, d as PLANTUML_BOUNDARY, e as PLANTUML_COMPONENT, f as PLANTUML_CONTAINER, g as PLANTUML_CONTAINER_BOUNDARY, h as PLANTUML_CONTAINER_DB, i as PLANTUML_PERSON, j as PLANTUML_SYSTEM, k as PLANTUML_SYSTEM_BOUNDARY, l as PLANTUML_SYSTEM_EXT, S as STRUCTURIZR_INTERACTION_ASYNC, m as STRUCTURIZR_LOCATION_EXTERNAL, n as STRUCTURIZR_TAG_ASYNC, o as SYSTEM_BOUNDARY_TYPE, p as SYSTEM_TYPE, q as analyzeArchitecture, r as checkAcl, s as checkAcyclic, t as checkApiGateway, u as checkCohesion, v as checkCommonReuse, w as checkCrud, x as checkDbPerService, y as checkStableDependencies, z as defineConfig, D as generateKubernetes, F as generatePlantumlFromModel, G as loadPlantumlElements, H as loadStructurizrElements, I as loadStructurizrWorkspace, J as mapContainersFromPlantumlElements, K as mapContainersFromStructurizr, L as structurizrDslSyntax } from './shared/aact.BzhD7c9t.mjs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import YAML from 'yaml';

package/dist/shared/{aact.Cpfuzz1A.mjs → aact.BzhD7c9t.mjs}

@@ -221,7 +221,7 @@ const generateKubernetes = (model, options) => {
   const dbConnectionTemplate = options?.dbConnectionTemplate ?? "postgresql://{name}:pass-{name}@postgresql:5432/{name}";
   const resolvedOptions = { defaultPort, dbConnectionTemplate };
   const containers = model.allContainers.filter(
-    (c) => c.type !== CONTAINER_DB_TYPE && c.type !== EXTERNAL_SYSTEM_TYPE
+    (c) => c.type !== CONTAINER_DB_TYPE && c.type !== EXTERNAL_SYSTEM_TYPE && c.type !== PERSON_TYPE
   );
   return containers.map((container) => {
     const kebabName = toKebab(container.name);
@@ -803,7 +803,7 @@ const checkCrud = (containers, options) => {
         message: `directly accesses database ${dbRelations.map((r) => r.to.name).join(", ")} \u2014 add a repo or relay`
       });
     }
-    if (container.tags?.includes("repo") && container.relations.some((r) => r.to.type !== dbType)) {
+    if (isRepo && container.relations.some((r) => r.to.type !== dbType)) {
       violations.push({
         container: container.name,
         message: `repo has non-database dependencies: ${container.relations.filter((r) => r.to.type !== dbType).map((r) => r.to.name).join(", ")} \u2014 repos should only access databases`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aact",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "type": "module",
   "description": "Architecture analysis and compliance tool",
   "keywords": [
@@ -47,11 +47,10 @@
   "scripts": {
     "build": "unbuild",
     "test": "vitest run",
-    "lint": "npm run lint:eslint && npm run lint:markdown && npm run lint:prettier",
+    "lint": "npm run lint:eslint && npm run lint:prettier",
     "lint:eslint": "eslint .",
-    "lint:markdown": "markdownlint --ignore-path ./.markdownlintignore \"./**/*.md\"",
     "lint:prettier": "prettier --ignore-path ./.gitignore --check \"./**/*.{ts,js,json,yaml,yml,md}\"",
-    "prepare": "husky"
+    "prepare": "husky || true"
   },
   "lint-staged": {
     "*.{ts,js}": [
@@ -74,7 +73,6 @@
     "globals": "^17.3.0",
     "husky": "9.1.7",
     "lint-staged": "16.2.7",
-    "markdownlint-cli": "0.31.1",
     "prettier": "3.8.1",
     "prettier-plugin-packagejson": "3.0.0",
     "typescript": "5.9.3",