archforge-x 1.0.2 → 1.0.4

package/README.md

@@ -1,90 +1,190 @@
-# 🛡️ ArchForge X
+# ArchForge X
 
-**Enterprise Architecture Engine** for scaffolding, analyzing, and visualizing software architecture.
+A configuration-driven architecture engine for generating and enforcing production-grade project structures across multiple languages and frameworks.
 
-ArchForge X helps development teams maintain clean, consistent, and scalable codebases by enforcing architectural boundaries and providing intelligent scaffolding.
+## Why This Exists
 
-## 🚀 Features
+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.
 
-- **🏗️ Intelligent Scaffolding**: Generate project structures for TypeScript, JavaScript, Python, and Go using patterns like Clean Architecture, DDD, and Hexagonal Architecture.
-- **🔍 Dependency Analysis**: Detect architectural violations and circular dependencies between layers.
-- **📊 Visual Graphs**: Generate high-resolution SVG dependency graphs to visualize your architecture.
-- **🛡️ Rule Enforcement**: Define custom architectural rules in `archforge.yaml` to ensure your team follows the intended design.
-- **✨ Interactive CLI**: A user-friendly wizard to get you started in seconds.
+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.
 
-## 📦 Installation
+## 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.
+
+## Installation
+
+Install ArchForge X globally via npm:
 
 ```bash
-npm install -g archforge-x
+npm install -g archforge
 ```
 
-## 🛠️ Usage
+## CLI Commands
+
+### init
+
+The `init` command starts an interactive wizard to bootstrap a new project.
 
-### 1. Initialize a Project
-Create a new architecture configuration file:
 ```bash
 archforge init
 ```
 
-### 2. Interactive Wizard (Recommended)
-Scaffold a new project with a guided setup:
+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 interactive
+archforge sync
 ```
 
-### 3. Analyze Dependencies
-Check your project for architectural violations:
+- **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 analyze
+archforge validate
 ```
 
-### 4. Visualize Architecture
-Generate an SVG graph of your project's layers:
+- **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 visualize -o architecture.svg
+archforge upgrade
 ```
 
-### 5. Deep Audit
-Get intelligent fix suggestions based on architectural principles:
+- **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 audit
+archforge generate module user
 ```
 
-## ⚙️ Configuration (`archforge.yaml`)
+- **Usage**: Use this to quickly add new features, layers, or modules that follow the project's established patterns.
+- **Alias**: `create`
+
+### graph
 
-Define your layers and dependency rules:
+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.
 
 ```yaml
-version: "1.0"
-name: "My Project Architecture"
-project:
-  name: "my-app"
-  root: "."
-
-metadata:
-  type: "clean"
-  language: "ts"
-  framework: "express"
-
-layers:
-  - name: "domain"
-    path: "src/domain"
-    description: "Core business logic"
-    forbiddenImports: ["infrastructure", "application"]
-
-  - name: "application"
-    path: "src/application"
-    allowedImports: ["domain"]
-
-  - name: "infrastructure"
-    path: "src/infrastructure"
-    allowedImports: ["domain", "application"]
+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
 ```
 
-## 🤝 Contributing
+## 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
+
+```bash
+# Install dependencies
+npm install
+
+# Start in development mode with hot-reload
+npm run start:dev
+```
+
+### Docker-Based Development
+
+```bash
+# Build and start all services (App, Database, Redis)
+docker-compose up --build
+```
+
+### Environment Variables
+
+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.
+
+## Team & Company Usage
+
+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."
+
+## Design Philosophy
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+- **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.
 
-## 📄 License
+## Contributing & License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+ArchForge X is open-source software licensed under the MIT License. Contributions are welcome via GitHub Pull Requests.

package/dist/cli/commands/sync.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncCommand = syncCommand;
+const validator_1 = require("../../core/architecture/validator");
+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..."));
+    const result = await validator.validate(projectRoot);
+    if (result.success) {
+        console.log(chalk_1.default.green.bold("✅ Architecture is valid and in sync!"));
+    }
+    else {
+        console.log(chalk_1.default.red.bold("❌ Architecture violations found:"));
+        result.errors.forEach(err => console.log(chalk_1.default.red(`   - ${err}`)));
+        process.exit(1);
+    }
+}

package/dist/cli/interactive.js

@@ -52,13 +52,47 @@ async function interactiveCLI() {
             { title: "Hexagonal Architecture", value: "hexagonal" },
         ],
     });
+    const ormResponse = await (0, prompts_1.default)({
+        type: "select",
+        name: "orm",
+        message: "Select ORM:",
+        choices: langResponse.language === "ts" || langResponse.language === "js"
+            ? [
+                { title: "Prisma", value: "prisma" },
+                { title: "TypeORM", value: "typeorm" },
+                { title: "Sequelize", value: "sequelize" },
+                { title: "Drizzle", value: "drizzle" },
+                { title: "None", value: "none" },
+            ]
+            : langResponse.language === "py"
+                ? [
+                    { title: "SQLAlchemy", value: "sqlalchemy" },
+                    { title: "Django ORM", value: "django" },
+                    { title: "None", value: "none" },
+                ]
+                : [
+                    { title: "GORM", value: "gorm" },
+                    { title: "SQLC", value: "sqlc" },
+                    { title: "None", value: "none" },
+                ],
+    });
+    const dbResponse = await (0, prompts_1.default)({
+        type: ormResponse.orm === "none" ? null : "select",
+        name: "database",
+        message: "Select Database:",
+        choices: [
+            { title: "PostgreSQL", value: "postgresql" },
+            { title: "MySQL", value: "mysql" },
+            { title: "SQLite", value: "sqlite" },
+            { title: "MongoDB", value: "mongodb" },
+        ],
+    });
     const modulesResponse = await (0, prompts_1.default)({
         type: "multiselect",
         name: "modules",
         message: "Select optional modules:",
         choices: [
             { title: "Authentication (JWT)", value: "auth" },
-            { title: "Database (ORM setup)", value: "db" },
             { title: "Caching (Redis)", value: "cache" },
             { title: "Docker Support", value: "docker" },
             { title: "CI/CD (GitHub Actions)", value: "ci" },
@@ -73,12 +107,14 @@ async function interactiveCLI() {
     });
     console.log(chalk_1.default.yellow("\n🔧 Generating project..."));
     const options = {
-        mode: 'professional',
+        // mode: 'professional',
         language: langResponse.language,
         framework: frameworkResponse.framework,
         architecture: archResponse.architecture,
         modules: modulesResponse.modules,
         projectName: projectNameResp.projectName,
+        orm: ormResponse.orm,
+        database: dbResponse.database,
     };
     // Create a dummy arch definition for the generator
     const dummyArch = {
@@ -92,7 +128,9 @@ async function interactiveCLI() {
             type: archResponse.architecture,
             language: langResponse.language,
             framework: frameworkResponse.framework,
-            modules: modulesResponse.modules
+            modules: modulesResponse.modules,
+            orm: ormResponse.orm,
+            database: dbResponse.database
         },
         layers: []
     };

package/dist/core/architecture/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.architectureSchema = exports.metadataSchema = exports.layerSchema = void 0;
+exports.architectureSchema = exports.customStructureSchema = exports.rulesSchema = exports.namingSchema = exports.metadataSchema = exports.layerSchema = void 0;
 // src/core/architecture/schema.ts
 const zod_1 = require("zod");
 exports.layerSchema = zod_1.z.object({
@@ -9,15 +9,33 @@ exports.layerSchema = zod_1.z.object({
     description: zod_1.z.string().optional(),
     allowedImports: zod_1.z.array(zod_1.z.string()).optional(),
     forbiddenImports: zod_1.z.array(zod_1.z.string()).optional(),
+    canImport: zod_1.z.array(zod_1.z.string()).optional(),
     strict: zod_1.z.boolean().optional(),
 });
 exports.metadataSchema = zod_1.z.object({
-    type: zod_1.z.enum(['clean', 'ddd', 'layered', 'hexagonal', 'microservices']),
+    type: zod_1.z.enum(['clean', 'ddd', 'layered', 'hexagonal', 'microservices', 'mvc']),
     language: zod_1.z.enum(['ts', 'js', 'py', 'go']),
     framework: zod_1.z.string().optional(),
+    orm: zod_1.z.string().optional(),
+    database: zod_1.z.string().optional(),
     modules: zod_1.z.array(zod_1.z.string()).optional(),
     version: zod_1.z.string().optional(),
 });
+exports.namingSchema = zod_1.z.object({
+    services: zod_1.z.string().optional(),
+    repositories: zod_1.z.string().optional(),
+    controllers: zod_1.z.string().optional(),
+    entities: zod_1.z.string().optional(),
+});
+exports.rulesSchema = zod_1.z.object({
+    forbidDirectDbAccess: zod_1.z.boolean().optional(),
+    forbidFrameworkInDomain: zod_1.z.boolean().optional(),
+    enforceLayerBoundaries: zod_1.z.boolean().optional(),
+});
+exports.customStructureSchema = zod_1.z.object({
+    enabled: zod_1.z.boolean(),
+    folders: zod_1.z.array(zod_1.z.object({ path: zod_1.z.string() })),
+});
 exports.architectureSchema = zod_1.z.object({
     version: zod_1.z.string().default("1.0"),
     name: zod_1.z.string(),
@@ -28,5 +46,8 @@ exports.architectureSchema = zod_1.z.object({
     }),
     metadata: exports.metadataSchema,
     layers: zod_1.z.array(exports.layerSchema),
+    naming: exports.namingSchema.optional(),
+    rules: exports.rulesSchema.optional(),
+    customStructure: exports.customStructureSchema.optional(),
     strict: zod_1.z.boolean().optional(),
 });

package/dist/core/architecture/validator.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchitectureValidator = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+class ArchitectureValidator {
+    async validate(projectRoot) {
+        const configPath = path_1.default.join(projectRoot, "archforge.yaml");
+        if (!fs_extra_1.default.existsSync(configPath)) {
+            return { success: false, errors: ["archforge.yaml not found"], warnings: [] };
+        }
+        const config = js_yaml_1.default.load(fs_extra_1.default.readFileSync(configPath, "utf8"));
+        const errors = [];
+        const warnings = [];
+        // 1. Validate Folder Structure
+        if (config.layers) {
+            for (const [name, layer] of Object.entries(config.layers)) {
+                const layerPath = path_1.default.join(projectRoot, layer.path);
+                if (!fs_extra_1.default.existsSync(layerPath)) {
+                    errors.push(`Layer "${name}" path not found: ${layer.path}`);
+                }
+            }
+        }
+        // 2. Validate Custom Folders
+        if (config.customStructure?.enabled && config.customStructure.folders) {
+            for (const folder of config.customStructure.folders) {
+                const folderPath = path_1.default.join(projectRoot, folder.path);
+                if (!fs_extra_1.default.existsSync(folderPath)) {
+                    errors.push(`Custom folder not found: ${folder.path}`);
+                }
+            }
+        }
+        // 3. Validate Naming Conventions
+        if (config.naming) {
+            this.validateNamingConventions(projectRoot, config.naming, errors);
+        }
+        // 4. Validate Layer Imports (Basic check for forbidden imports in files)
+        if (config.layers && config.rules?.enforceLayerBoundaries) {
+            this.validateLayerImports(projectRoot, config.layers, errors);
+        }
+        return {
+            success: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    validateNamingConventions(root, naming, errors) {
+        // Simple check: scan src and verify file suffixes
+        const scanDir = (dir) => {
+            if (!fs_extra_1.default.existsSync(dir))
+                return;
+            const files = fs_extra_1.default.readdirSync(dir);
+            for (const file of files) {
+                const fullPath = path_1.default.join(dir, file);
+                if (fs_extra_1.default.statSync(fullPath).isDirectory()) {
+                    scanDir(fullPath);
+                }
+                else {
+                    const lowerFile = file.toLowerCase();
+                    if (dir.includes("services") && naming.services) {
+                        const pattern = naming.services.replace("*", "").toLowerCase();
+                        if (!lowerFile.includes(pattern)) {
+                            errors.push(`Naming violation: Service file "${file}" does not match pattern "${naming.services}"`);
+                        }
+                    }
+                    if (dir.includes("repositories") && naming.repositories) {
+                        const pattern = naming.repositories.replace("*", "").toLowerCase();
+                        if (!lowerFile.includes(pattern)) {
+                            errors.push(`Naming violation: Repository file "${file}" does not match pattern "${naming.repositories}"`);
+                        }
+                    }
+                }
+            }
+        };
+        scanDir(path_1.default.join(root, "src"));
+    }
+    validateLayerImports(root, layers, errors) {
+        // This is a complex task for a simple validator, but we can do a basic grep-like check
+        // for forbidden layer paths in files of other layers.
+        for (const [name, layer] of Object.entries(layers)) {
+            const layerPath = path_1.default.join(root, layer.path);
+            if (!fs_extra_1.default.existsSync(layerPath))
+                continue;
+            const canImport = layer.canImport || [];
+            const forbiddenLayers = Object.keys(layers).filter(l => l !== name && !canImport.includes(l));
+            const scanFiles = (dir) => {
+                const files = fs_extra_1.default.readdirSync(dir);
+                for (const file of files) {
+                    const fullPath = path_1.default.join(dir, file);
+                    if (fs_extra_1.default.statSync(fullPath).isDirectory()) {
+                        scanFiles(fullPath);
+                    }
+                    else if (file.endsWith(".ts") || file.endsWith(".py") || file.endsWith(".go")) {
+                        const content = fs_extra_1.default.readFileSync(fullPath, "utf8");
+                        for (const forbidden of forbiddenLayers) {
+                            const forbiddenPath = layers[forbidden].path.replace("src/", "");
+                            if (content.includes(forbiddenPath) && !content.includes(`from .`)) {
+                                errors.push(`Architecture violation: Layer "${name}" (${file}) imports from forbidden layer "${forbidden}"`);
+                            }
+                        }
+                    }
+                }
+            };
+            scanFiles(layerPath);
+        }
+    }
+}
+exports.ArchitectureValidator = ArchitectureValidator;