archforge-x 1.0.4 → 1.0.7

package/README.md

@@ -1,190 +1,86 @@
-# ArchForge X
+# ArchForge X - Enterprise Architecture Engine
 
-A configuration-driven architecture engine for generating and enforcing production-grade project structures across multiple languages and frameworks.
-
-## Why This Exists
-
-Modern software development often suffers from two primary issues: **setup fatigue** and **architecture drift**. Developers spend hours configuring boilerplate for logging, caching, and database layers, only for the project's architectural boundaries to erode over time as the team grows.
-
-ArchForge X solves this by moving architecture from "documentation" to "executable configuration." By defining your project's structure and rules in a central `archforge.yaml`, you ensure that every project starts with production-ready defaults and stays compliant throughout its lifecycle.
+ArchForge X is a CLI tool designed to turn software architecture into executable code. It enables teams to scaffold, validate, audit, and visualize project architecture using a configuration-driven approach.
 
 ## Key Features
 
-- **Config-Driven Generation**: Generate entire project skeletons from a single YAML definition.
-- **Architecture Enforcement**: Automatically validate naming conventions and import boundaries.
-- **Production-Ready Defaults**: Built-in support for structured logging, health checks, and global error handling.
-- **Multi-Stack Support**: Consistent patterns across Node.js, Python, and Go.
-- **Zero-Drift Sync**: Re-apply architectural rules to existing projects without losing custom logic.
-
-## Supported Capabilities
-
-- **Architectures**: Clean Architecture (DDD), Layered Architecture, MVC.
-- **Frameworks**: NestJS, Express, FastAPI, Django, Go Gin, Next.js.
-- **ORMs & Databases**: Prisma, SQLAlchemy, GORM, PostgreSQL, MySQL, SQLite, MongoDB.
-- **DevOps**: Automated Dockerfile and Docker Compose generation, GitHub Actions CI/CD workflows.
+*   **Policy-Driven Scaffolding**: Generate production-ready projects (Clean Architecture, DDD, Hexagonal) for Node.js (Express, NestJS).
+*   **Strict Validation**: Enforce dependency rules between layers (e.g., Domain cannot import Infrastructure).
+*   **Automated Audits**: Scan codebase for architectural violations and receive fix suggestions.
+*   **Visualization**: Generate SVG dependency graphs to visualize project structure.
+*   **Configuration as Code**: Define architecture in `archforge.yaml` or `archforge.json`.
 
 ## Installation
 
-Install ArchForge X globally via npm:
-
 ```bash
-npm install -g archforge
+npm install -g archforge-x
 ```
 
-## CLI Commands
-
-### init
+## Quick Start
 
-The `init` command starts an interactive wizard to bootstrap a new project.
+### 1. Initialize a Project
+Start the interactive wizard to create a new project or generate a config for an existing one.
 
 ```bash
 archforge init
 ```
 
-During initialization, you will select:
-- **Architecture Style**: Choose between Clean, Layered, or MVC.
-- **Framework**: Select your preferred backend or frontend framework.
-- **ORM & Database**: Configure your data persistence layer.
-- **Optional Modules**: Add Docker support, CI/CD workflows, Caching (Redis), and more.
-
-### sync
-
-The `sync` command re-applies the architectural rules defined in `archforge.yaml` to your project.
-
-```bash
-archforge sync
-```
-
-- **What it changes**: Updates configuration files, architecture guardrails (e.g., ESLint rules), and missing infrastructure layers.
-- **What it never changes**: Your business logic, use cases, or custom implementation files.
-
-### validate
-
-The `validate` command checks your project against the rules defined in `archforge.yaml`.
-
-```bash
-archforge validate
-```
-
-- **Validation**: Checks naming conventions, directory structure, and restricted import paths.
-- **Usage**: Used locally during development or in CI pipelines to prevent architectural violations.
-- **Behavior**: Returns a non-zero exit code on failure, making it ideal for blocking invalid PRs.
-
-### upgrade
-
-The `upgrade` command adds new production-grade features to an existing ArchForge project.
-
-```bash
-archforge upgrade
-```
-
-- **Purpose**: Safely introduces enhancements like new logging providers or health check endpoints without breaking existing code.
-
-### generate
-
-The `generate` command creates specific architectural components within an existing project.
-
-```bash
-archforge generate module user
-```
-
-- **Usage**: Use this to quickly add new features, layers, or modules that follow the project's established patterns.
-- **Alias**: `create`
-
-### graph
-
-The `graph` command generates a visual representation of your project's architecture.
-
-```bash
-archforge graph
-```
-
-- **Output**: Generates an `architecture-graph.svg` file showing the relationships and dependencies between your project's layers.
-- **Alias**: `visualize`
-
-## Configuration (archforge.yaml)
-
-The `archforge.yaml` file is the single source of truth for your project's architecture. It defines the structure, naming conventions, and enforcement policies.
+### 2. Define Your Architecture
+Create an `archforge.yaml` file to define your layers and rules.
 
 ```yaml
-name: my-production-app
-architecture: clean
-framework: nestjs
-orm: prisma
-database: postgresql
-
-structure:
-  layers:
-    - name: domain
-      path: src/domain
-      canImport: []
-    - name: application
-      path: src/application
-      canImport: [domain]
-    - name: infrastructure
-      path: src/infrastructure
-      canImport: [domain, application]
-    - name: presentation
-      path: src/presentation
-      canImport: [domain, application]
-
-naming:
-  controllers: "{name}.controller.ts"
-  useCases: "{name}.use-case.ts"
-  repositories: "{name}.repository.ts"
-
-enforcement:
-  strictImports: true
-  namingConvention: pascalCase
+version: "1.0"
+project:
+  name: "my-service"
+layers:
+  - name: "domain"
+    path: "src/domain"
+    canImport: []
+  - name: "application"
+    path: "src/application"
+    canImport: ["domain"]
+  - name: "infrastructure"
+    path: "src/infrastructure"
+    canImport: ["domain", "application"]
+rules:
+  enforceLayerBoundaries: true
 ```
 
-## Rule Enforcement & Verification
-
-ArchForge X enforces rules through a combination of static analysis and framework-specific configurations:
-
-1. **Local Enforcement**: During `sync`, ArchForge configures tools like ESLint with `import/no-restricted-paths` to provide real-time feedback in your IDE.
-2. **CI Verification**: Running `archforge validate` in your CI pipeline ensures that no code violating the architecture is merged.
-3. **Fixing Violations**: If a violation is detected (e.g., a Domain entity importing from Infrastructure), the CLI will provide a detailed report pointing to the offending file and rule.
-
-## Running the Project
-
-### Local Development
+### 3. Validate Your Code
+Check if your code adheres to the defined architecture.
 
 ```bash
-# Install dependencies
-npm install
-
-# Start in development mode with hot-reload
-npm run start:dev
+archforge validate
 ```
 
-### Docker-Based Development
+### 4. Visualize Dependencies
+Generate a graph of your project's architecture.
 
 ```bash
-# Build and start all services (App, Database, Redis)
-docker-compose up --build
+archforge graph --output architecture.svg
 ```
 
-### Environment Variables
+## Documentation
 
-ArchForge generates a `.env.example` file. Copy it to `.env` and configure your secrets:
-- `PORT`: Server port (default: 3000)
-- `DATABASE_URL`: Connection string for your database.
-- `REDIS_URL`: Connection string for Redis caching.
+For a deep dive into defining rules and best practices, check out the [Rules & Validation Guide](docs/RULES_GUIDE.md).
 
-## Team & Company Usage
+## CLI Commands
 
-ArchForge X is designed for engineering organizations to:
-- **Standardize**: Ensure every microservice or project follows the same structural patterns.
-- **Onboard**: New developers can navigate any project instantly because the structure is predictable.
-- **Scale**: Enforce best practices across hundreds of repositories without manual code reviews for "folder structure."
+| Command | Description |
+| :--- | :--- |
+| `archforge init` | Interactive wizard to setup a project. |
+| `archforge generate` | Scaffold a new project based on the config. |
+| `archforge validate` | Check for architectural violations. |
+| `archforge audit` | Deep scan with auto-fix suggestions. |
+| `archforge graph` | Generate a visual dependency graph (SVG). |
+| `archforge sync` | Sync project structure with the config. |
 
-## Design Philosophy
+## Supported Frameworks
 
-- **Enforcement over Documentation**: Rules that aren't enforced will eventually be broken.
-- **Production-Ready by Default**: Every project starts with the scaffolding needed for a real-world deployment.
-- **Config-Driven Flexibility**: The tool adapts to your team's preferred patterns, not the other way around.
+Currently, ArchForge X specializes in TypeScript backends:
+*   Express.js (Clean Architecture / DDD)
+*   NestJS (Modular / Hexagonal)
 
-## Contributing & License
+## License
 
-ArchForge X is open-source software licensed under the MIT License. Contributions are welcome via GitHub Pull Requests.
+MIT

package/dist/analyzers/dependency.js

@@ -27,36 +27,6 @@ const parseImportsTS = (content, filePath) => {
     });
     return imports;
 };
-const parseImportsPython = (content) => {
-    const imports = [];
-    const lines = content.split("\n");
-    for (const line of lines) {
-        const trimmed = line.trim();
-        const fromMatch = trimmed.match(/^from\s+([\w\.]+)\s+import/);
-        if (fromMatch)
-            imports.push(fromMatch[1].replace(/\./g, "/"));
-        const importMatch = trimmed.match(/^import\s+([\w\.]+)/);
-        if (importMatch)
-            imports.push(importMatch[1].replace(/\./g, "/"));
-    }
-    return imports;
-};
-const parseImportsGo = (content) => {
-    const imports = [];
-    const singleMatch = content.matchAll(/import\s+"(.+)"/g);
-    for (const m of singleMatch)
-        imports.push(m[1]);
-    const multiBlock = content.match(/import\s+\(([\s\S]*?)\)/);
-    if (multiBlock) {
-        const lines = multiBlock[1].split("\n");
-        for (const line of lines) {
-            const clean = line.trim().replace(/"/g, "");
-            if (clean)
-                imports.push(clean);
-        }
-    }
-    return imports;
-};
 // --- CORE ANALYZER ---
 function analyzeDependencies(arch, options = {}) {
     const violations = [];
@@ -96,15 +66,15 @@ function analyzeDependencies(arch, options = {}) {
             const fullPath = path_1.default.join(absoluteFolderPath, entry);
             const stat = fs_extra_1.default.statSync(fullPath);
             if (stat.isDirectory()) {
-                if (["node_modules", "__pycache__", ".git", "dist"].includes(entry))
+                if (["node_modules", ".git", "dist"].includes(entry))
                     continue;
                 scanFolder(fullPath);
             }
             else if (stat.isFile()) {
-                if (options.ignoreTests && (entry.includes(".spec") || entry.includes("_test")))
+                if (options.ignoreTests && (entry.includes(".spec") || entry.includes(".test")))
                     continue;
                 const ext = path_1.default.extname(entry);
-                if ([".ts", ".js", ".py", ".go", ".tsx", ".jsx"].includes(ext)) {
+                if ([".ts", ".js", ".tsx", ".jsx"].includes(ext)) {
                     checkFileImports(fullPath, ext);
                 }
             }
@@ -118,15 +88,12 @@ function analyzeDependencies(arch, options = {}) {
         let imports = [];
         if ([".ts", ".tsx", ".js", ".jsx"].includes(ext))
             imports = parseImportsTS(content, filePath);
-        else if (ext === ".py")
-            imports = parseImportsPython(content);
-        else if (ext === ".go")
-            imports = parseImportsGo(content);
         for (const importStr of imports) {
             const importedLayer = resolveImportedLayer(filePath, importStr);
             if (!importedLayer || importedLayer.name === currentLayer.name)
                 continue;
-            if (currentLayer.forbiddenImports?.includes(importedLayer.name)) {
+            const canImport = currentLayer.canImport || currentLayer.allowedImports || [];
+            if (!canImport.includes(importedLayer.name)) {
                 violations.push({
                     file: path_1.default.relative(projectRoot, filePath),
                     fromLayer: currentLayer.name,
@@ -136,16 +103,6 @@ function analyzeDependencies(arch, options = {}) {
                     severity: "error"
                 });
             }
-            if (currentLayer.allowedImports && !currentLayer.allowedImports.includes(importedLayer.name)) {
-                violations.push({
-                    file: path_1.default.relative(projectRoot, filePath),
-                    fromLayer: currentLayer.name,
-                    importedLayer: importedLayer.name,
-                    importPath: importStr,
-                    type: "allowed",
-                    severity: "warning"
-                });
-            }
         }
     }
     arch.layers.forEach((layer) => scanFolder(layer.path));

package/dist/api/routes/user.routes.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const user_service_1 = require("../../services/user.service");
+const memory_cache_1 = require("../../infrastructure/cache/memory.cache");
+const http_status_codes_1 = require("http-status-codes");
+const router = (0, express_1.Router)();
+const cache = new memory_cache_1.MemoryCache();
+const userService = new user_service_1.UserService(cache);
+router.post("/", async (req, res) => {
+    const user = await userService.create(req.body.name, req.body.email);
+    res.status(http_status_codes_1.StatusCodes.CREATED).json(user);
+});
+router.get("/:id", async (req, res) => {
+    const user = await userService.getById(req.params.id);
+    res.status(http_status_codes_1.StatusCodes.OK).json(user);
+});
+exports.default = router;

package/dist/cli/commands/init-template.js

@@ -0,0 +1,105 @@
+"use strict";
+// src/cli/commands/init-template.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initTemplateCommand = initTemplateCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const path_1 = __importDefault(require("path"));
+const resolver_1 = require("../../discovery/resolver");
+const fetcher_1 = require("../../orchestration/fetcher");
+const configurator_1 = require("../../orchestration/configurator");
+const installer_1 = require("../../orchestration/installer");
+const compatibility_1 = require("../../validation/compatibility");
+async function initTemplateCommand(options) {
+    try {
+        console.log(chalk_1.default.blue.bold('\n🚀 ArchForge X - Template Initialization\n'));
+        // Step 1: Resolve template
+        console.log(chalk_1.default.cyan('📋 Step 1: Resolving template...'));
+        const resolver = new resolver_1.TemplateResolver();
+        const resolved = await resolver.resolve({
+            language: options.language,
+            framework: options.framework,
+            architecture: options.architecture,
+            orm: options.orm,
+            database: options.database,
+            templateId: options.templateId,
+            templateUrl: options.templateUrl,
+            version: options.version,
+        });
+        // Step 2: Fetch template
+        console.log(chalk_1.default.cyan('\n📥 Step 2: Fetching template...'));
+        const fetcher = new fetcher_1.TemplateFetcher();
+        const { templatePath, metadata } = await fetcher.fetch(resolved, {
+            cache: true,
+            shallow: true,
+        });
+        // Step 3: Check compatibility
+        console.log(chalk_1.default.cyan('\n🔍 Step 3: Checking compatibility...'));
+        const checker = new compatibility_1.CompatibilityChecker();
+        const compatibility = await checker.checkCompatibility(metadata, { strict: false });
+        checker.displayReport(compatibility, metadata);
+        if (!compatibility.compatible) {
+            console.log(chalk_1.default.red('\n❌ Compatibility check failed. Use --skip-compatibility to proceed anyway.'));
+            if (!options.skipInstall) {
+                process.exit(1);
+            }
+        }
+        // Step 4: Configure template
+        console.log(chalk_1.default.cyan('\n🔧 Step 4: Configuring template...'));
+        const configurator = new configurator_1.TemplateConfigurator();
+        const projectName = options.projectName || 'my-project';
+        const projectConfig = {
+            projectName,
+            language: options.language,
+            framework: options.framework,
+            architecture: options.architecture,
+            orm: options.orm,
+            database: options.database,
+            modules: options.modules,
+            authorName: options.authorName,
+            authorEmail: options.authorEmail,
+            license: options.license,
+        };
+        const { configuredPath } = await configurator.configure(templatePath, projectConfig, path_1.default.resolve(projectName));
+        // Step 5: Install dependencies
+        if (!options.skipInstall) {
+            console.log(chalk_1.default.cyan('\n📦 Step 5: Installing dependencies...'));
+            const installer = new installer_1.DependencyInstaller();
+            const installResult = await installer.install(configuredPath, metadata, {
+                packageManager: options.packageManager,
+                production: false,
+                skipPostInstall: options.skipPostInstall,
+            });
+            if (!installResult.success) {
+                console.log(chalk_1.default.yellow('\n⚠️  Dependency installation had issues. You may need to install manually.'));
+            }
+            // Display post-install instructions
+            installer.displayInstructions(metadata);
+        }
+        else {
+            console.log(chalk_1.default.yellow('\n⏭️  Skipping dependency installation'));
+        }
+        // Success message
+        console.log(chalk_1.default.green.bold(`\n✅ Project "${projectName}" created successfully!`));
+        console.log(chalk_1.default.blue('\n📁 Location:'), path_1.default.resolve(configuredPath));
+        console.log(chalk_1.default.blue('\n📝 Next steps:'));
+        console.log(chalk_1.default.gray(`   cd ${projectName}`));
+        if (options.skipInstall) {
+            console.log(chalk_1.default.gray(`   npm install`));
+        }
+        // Get start command from template or use default
+        const startCommand = metadata.postInstall?.scripts?.find((s) => s.includes('start')) || 'npm run start:dev';
+        console.log(chalk_1.default.gray(`   ${startCommand}`));
+        console.log(chalk_1.default.blue('\n💡 Tip: Run "archforge validate" to check your project architecture\n'));
+    }
+    catch (error) {
+        console.error(chalk_1.default.red.bold('\n❌ Initialization failed:'));
+        console.error(chalk_1.default.red(error.message));
+        if (error.stack) {
+            console.error(chalk_1.default.gray(error.stack));
+        }
+        process.exit(1);
+    }
+}

package/dist/cli/commands/sync.js

@@ -9,14 +9,22 @@ const chalk_1 = __importDefault(require("chalk"));
 async function syncCommand() {
     const projectRoot = process.cwd();
     const validator = new validator_1.ArchitectureValidator();
-    console.log(chalk_1.default.blue("🔄 Syncing architecture with archforge.yaml..."));
+    console.log(chalk_1.default.blue("🔄 Syncing architecture with architecture-rules.json..."));
     const result = await validator.validate(projectRoot);
+    if (result.warnings.length > 0) {
+        console.log(chalk_1.default.yellow("\n⚠️  Warnings:"));
+        result.warnings.forEach(warn => console.log(chalk_1.default.yellow(`   - ${warn}`)));
+    }
     if (result.success) {
-        console.log(chalk_1.default.green.bold("✅ Architecture is valid and in sync!"));
+        console.log(chalk_1.default.green.bold("\n✅ Architecture is valid and in sync!"));
+        if (result.warnings.length > 0) {
+            console.log(chalk_1.default.gray("   (Some warnings were found but do not block sync)"));
+        }
     }
     else {
-        console.log(chalk_1.default.red.bold("❌ Architecture violations found:"));
+        console.log(chalk_1.default.red.bold("\n❌ Architecture violations found:"));
         result.errors.forEach(err => console.log(chalk_1.default.red(`   - ${err}`)));
+        console.log(chalk_1.default.yellow("\n💡 Tip: Fix these violations to ensure architectural compliance."));
         process.exit(1);
     }
 }