archforge-x 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Henok
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# 🛡️ ArchForge X
+
+**Enterprise Architecture Engine** for scaffolding, analyzing, and visualizing software architecture.
+
+ArchForge X helps development teams maintain clean, consistent, and scalable codebases by enforcing architectural boundaries and providing intelligent scaffolding.
+
+## 🚀 Features
+
+- **🏗️ 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.
+
+## 📦 Installation
+
+```bash
+npm install -g archforge-x
+```
+
+## 🛠️ Usage
+
+### 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:
+```bash
+archforge interactive
+```
+
+### 3. Analyze Dependencies
+Check your project for architectural violations:
+```bash
+archforge analyze
+```
+
+### 4. Visualize Architecture
+Generate an SVG graph of your project's layers:
+```bash
+archforge visualize -o architecture.svg
+```
+
+### 5. Deep Audit
+Get intelligent fix suggestions based on architectural principles:
+```bash
+archforge audit
+```
+
+## ⚙️ Configuration (`archforge.yaml`)
+
+Define your layers and dependency rules:
+
+```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"]
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/bin/archforge.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../dist/index.js");

package/dist/analyzers/dependency.js

@@ -0,0 +1,184 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeDependencies = analyzeDependencies;
+exports.reportViolations = reportViolations;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const typescript_1 = __importDefault(require("typescript"));
+const chalk_1 = __importDefault(require("chalk"));
+// --- LANGUAGE PARSERS ---
+const parseImportsTS = (content, filePath) => {
+    const imports = [];
+    const sourceFile = typescript_1.default.createSourceFile(filePath, content, typescript_1.default.ScriptTarget.Latest, true);
+    sourceFile.forEachChild((node) => {
+        if (typescript_1.default.isImportDeclaration(node) && node.moduleSpecifier) {
+            const importPath = node.moduleSpecifier.text;
+            imports.push(importPath);
+        }
+        if (typescript_1.default.isVariableStatement(node)) {
+            const text = node.getText();
+            const match = text.match(/require\(['"](.+)['"]\)/);
+            if (match)
+                imports.push(match[1]);
+        }
+    });
+    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 = [];
+    const projectRoot = path_1.default.resolve(arch.project.root || ".");
+    function getLayerByPath(filePath) {
+        const absoluteFile = path_1.default.resolve(filePath);
+        const sortedLayers = [...arch.layers].sort((a, b) => b.path.length - a.path.length);
+        return sortedLayers.find((layer) => {
+            const layerPath = path_1.default.resolve(projectRoot, layer.path);
+            return absoluteFile.startsWith(layerPath);
+        });
+    }
+    function resolveImportedLayer(currentFilePath, importPath) {
+        let absoluteImportPath = "";
+        if (importPath.startsWith(".")) {
+            absoluteImportPath = path_1.default.resolve(path_1.default.dirname(currentFilePath), importPath);
+        }
+        else {
+            // Check if the import string starts with any layer path (alias/absolute)
+            for (const layer of arch.layers) {
+                const normLayer = layer.path.replace(/\\/g, "/");
+                const normImport = importPath.replace(/\\/g, "/");
+                if (normImport.startsWith(normLayer)) {
+                    return layer;
+                }
+            }
+            return undefined;
+        }
+        return getLayerByPath(absoluteImportPath);
+    }
+    function scanFolder(folderPath) {
+        const absoluteFolderPath = path_1.default.resolve(projectRoot, folderPath);
+        if (!fs_extra_1.default.existsSync(absoluteFolderPath))
+            return;
+        const entries = fs_extra_1.default.readdirSync(absoluteFolderPath);
+        for (const entry of entries) {
+            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))
+                    continue;
+                scanFolder(fullPath);
+            }
+            else if (stat.isFile()) {
+                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)) {
+                    checkFileImports(fullPath, ext);
+                }
+            }
+        }
+    }
+    function checkFileImports(filePath, ext) {
+        const currentLayer = getLayerByPath(filePath);
+        if (!currentLayer)
+            return;
+        const content = fs_extra_1.default.readFileSync(filePath, "utf-8");
+        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)) {
+                violations.push({
+                    file: path_1.default.relative(projectRoot, filePath),
+                    fromLayer: currentLayer.name,
+                    importedLayer: importedLayer.name,
+                    importPath: importStr,
+                    type: "forbidden",
+                    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));
+    return violations;
+}
+function reportViolations(violations, options = {}) {
+    if (violations.length === 0) {
+        console.log(chalk_1.default.green("✅ No architectural violations found. Architecture is clean."));
+        return;
+    }
+    console.log(chalk_1.default.red.bold(`❌ Found ${violations.length} Architecture Violations:`));
+    const grouped = violations.reduce((acc, v) => {
+        const key = `${v.fromLayer} -> ${v.importedLayer}`;
+        if (!acc[key])
+            acc[key] = [];
+        acc[key].push(v);
+        return acc;
+    }, {});
+    Object.keys(grouped).forEach(key => {
+        const group = grouped[key];
+        const v = group[0];
+        const color = v.severity === "error" ? chalk_1.default.red : chalk_1.default.yellow;
+        console.log(color.bold(`\n[${v.type.toUpperCase()}] ${v.fromLayer} depends on ${v.importedLayer}`));
+        group.forEach(item => {
+            console.log(chalk_1.default.gray(`   - ${item.file} imports '${item.importPath}'`));
+        });
+    });
+    if (options.outputFile) {
+        const absoluteOutput = path_1.default.resolve(options.outputFile);
+        const ext = path_1.default.extname(absoluteOutput).toLowerCase();
+        const content = ext === ".json" ? JSON.stringify(violations, null, 2) :
+            violations.map(v => `[${v.severity.toUpperCase()}] ${v.fromLayer} -> ${v.importedLayer} in ${v.file}`).join("\n");
+        fs_extra_1.default.writeFileSync(absoluteOutput, content, "utf-8");
+        console.log(chalk_1.default.blueBright(`\n📄 Detailed report saved to ${absoluteOutput}`));
+    }
+}

package/dist/cli/init.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = void 0;
+const commander_1 = require("commander");
+const fs_1 = __importDefault(require("fs"));
+const chalk_1 = __importDefault(require("chalk"));
+const path_1 = __importDefault(require("path"));
+exports.initCommand = new commander_1.Command("init")
+    .description("Initialize a new architecture configuration file (archforge.yaml)")
+    .action(() => {
+    const configPath = path_1.default.resolve(process.cwd(), "archforge.yaml");
+    // 1. Safety Check: Don't overwrite existing config
+    if (fs_1.default.existsSync(configPath)) {
+        console.log(chalk_1.default.yellow("⚠️  Configuration file 'archforge.yaml' already exists."));
+        console.log(chalk_1.default.gray(`   Path: ${configPath}`));
+        console.log(chalk_1.default.blue("   Run 'archforge analyze' or 'archforge generate' to use it."));
+        return;
+    }
+    const template = `
+version: "1.0"
+name: "Enterprise Architecture Config"
+project:
+  name: "my-awesome-project"
+  root: "."
+
+metadata:
+  type: "clean"        # Options: clean, ddd, hexagonal, layered
+  language: "ts"       # Options: ts, js, py, go
+  framework: "nestjs"  # Options: nestjs, express, django, flask, gin
+  version: "1.0.0"
+  modules:             # Optional modules to scaffold
+    - "auth"
+    - "docker"
+
+# Define your architecture layers and dependency rules here
+layers:
+  - name: "domain"
+    path: "src/domain"
+    description: "Core business logic and entities (Enterprise Rules)"
+    strict: true
+    forbiddenImports: ["infrastructure", "interface", "application"]
+
+  - name: "application"
+    path: "src/application"
+    description: "Use cases and application logic"
+    allowedImports: ["domain"]
+
+  - name: "infrastructure"
+    path: "src/infrastructure"
+    description: "External tools, databases, and third-party services"
+    allowedImports: ["domain", "application"]
+
+  - name: "interface"
+    path: "src/interface"
+    description: "Controllers, API endpoints, and Presenters"
+    allowedImports: ["application"]
+`.trim();
+    // 3. Write the file
+    try {
+        fs_1.default.writeFileSync(configPath, template, "utf-8");
+        console.log(chalk_1.default.green.bold("✅ Successfully initialized 'archforge.yaml'"));
+        console.log(chalk_1.default.white("   You can now customize the layers in the file."));
+        console.log(chalk_1.default.gray("\nNext steps:"));
+        console.log(chalk_1.default.cyan("   1. archforge generate"));
+        console.log(chalk_1.default.cyan("   2. archforge analyze"));
+    }
+    catch (err) {
+        console.error(chalk_1.default.red("❌ Failed to create configuration file:"), err.message);
+        process.exit(1);
+    }
+});

package/dist/cli/interactive.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interactiveCLI = interactiveCLI;
+const prompts_1 = __importDefault(require("prompts"));
+const chalk_1 = __importDefault(require("chalk"));
+const generator_1 = require("../generators/generator");
+async function interactiveCLI() {
+    console.clear();
+    console.log(chalk_1.default.blue.bold("🚀 Welcome to ArchForge X Interactive CLI"));
+    console.log(chalk_1.default.gray("-----------------------------------------"));
+    const langResponse = await (0, prompts_1.default)({
+        type: "select",
+        name: "language",
+        message: "Select programming language:",
+        choices: [
+            { title: "TypeScript (Recommended)", value: "ts" },
+            { title: "JavaScript", value: "js" },
+            { title: "Python", value: "py" },
+            { title: "Go", value: "go" },
+        ],
+    });
+    const frameworkResponse = await (0, prompts_1.default)({
+        type: "select",
+        name: "framework",
+        message: "Select framework:",
+        choices: langResponse.language === "ts" || langResponse.language === "js"
+            ? [
+                { title: "NestJS", value: "nestjs" },
+                { title: "Express", value: "express" },
+            ]
+            : langResponse.language === "py"
+                ? [
+                    { title: "Django", value: "django" },
+                    { title: "Flask", value: "flask" },
+                ]
+                : [
+                    { title: "Gin", value: "gin" },
+                    { title: "Standard Lib", value: "go" },
+                ],
+    });
+    const archResponse = await (0, prompts_1.default)({
+        type: "select",
+        name: "architecture",
+        message: "Select architecture style:",
+        choices: [
+            { title: "Clean Architecture (Recommended)", value: "clean" },
+            { title: "Domain Driven Design", value: "ddd" },
+            { title: "Layered Architecture", value: "layered" },
+            { title: "Hexagonal Architecture", value: "hexagonal" },
+        ],
+    });
+    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" },
+        ],
+        hint: "- Space to select, Enter to confirm",
+    });
+    const projectNameResp = await (0, prompts_1.default)({
+        type: "text",
+        name: "projectName",
+        message: "Enter project name:",
+        initial: "my-app",
+    });
+    console.log(chalk_1.default.yellow("\n🔧 Generating project..."));
+    const options = {
+        mode: 'professional',
+        language: langResponse.language,
+        framework: frameworkResponse.framework,
+        architecture: archResponse.architecture,
+        modules: modulesResponse.modules,
+        projectName: projectNameResp.projectName,
+    };
+    // Create a dummy arch definition for the generator
+    const dummyArch = {
+        version: "1.0",
+        name: "Interactive Project",
+        project: {
+            name: projectNameResp.projectName,
+            root: "."
+        },
+        metadata: {
+            type: archResponse.architecture,
+            language: langResponse.language,
+            framework: frameworkResponse.framework,
+            modules: modulesResponse.modules
+        },
+        layers: []
+    };
+    try {
+        await (0, generator_1.generateProject)(dummyArch, options);
+        console.log(chalk_1.default.blue(`\n👉 Next steps:`));
+        console.log(`   cd ${options.projectName}`);
+        if (options.language === 'ts' || options.language === 'js') {
+            console.log(`   npm install`);
+            console.log(`   npm run start:dev`);
+        }
+        else if (options.language === 'py') {
+            console.log(`   pip install -r requirements.txt`);
+            console.log(`   python run.py`);
+        }
+        else {
+            console.log(`   go mod tidy`);
+            console.log(`   go run cmd/server/main.go`);
+        }
+    }
+    catch (error) {
+        console.error(chalk_1.default.red("\n❌ Error generating project:"), error);
+    }
+}

package/dist/core/architecture/model.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/core/architecture/model.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/architecture/parser.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadArchitecture = loadArchitecture;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+const zod_1 = require("zod");
+const chalk_1 = __importDefault(require("chalk"));
+const schema_1 = require("./schema");
+const template_1 = require("../../utils/template");
+// --- HELPERS ---
+/**
+ * Recursively merges two architecture definitions.
+ * Layers are merged by name: Child overrides Parent.
+ */
+function mergeArchitectures(base, child) {
+    const layerMap = new Map();
+    // Add base layers
+    base.layers.forEach((l) => layerMap.set(l.name, l));
+    // Override/Add child layers
+    child.layers.forEach((l) => {
+        if (layerMap.has(l.name)) {
+            const baseLayer = layerMap.get(l.name);
+            layerMap.set(l.name, {
+                ...baseLayer,
+                ...l,
+                allowedImports: l.allowedImports ?? baseLayer.allowedImports,
+                forbiddenImports: l.forbiddenImports ?? baseLayer.forbiddenImports,
+            });
+        }
+        else {
+            layerMap.set(l.name, l);
+        }
+    });
+    return {
+        ...base,
+        ...child,
+        project: { ...base.project, ...child.project },
+        metadata: { ...base.metadata, ...child.metadata },
+        layers: Array.from(layerMap.values()),
+    };
+}
+// --- MAIN FUNCTIONS ---
+function loadArchitecture(filePath) {
+    const absolutePath = path_1.default.resolve(filePath);
+    if (!fs_1.default.existsSync(absolutePath)) {
+        throw new Error(`Architecture configuration file not found: ${absolutePath}`);
+    }
+    // 1. Read & Env Substitution
+    let rawContent = fs_1.default.readFileSync(absolutePath, "utf-8");
+    rawContent = (0, template_1.substituteEnvVars)(rawContent);
+    // 2. Parse YAML
+    let parsed;
+    try {
+        parsed = yaml_1.default.parse(rawContent);
+    }
+    catch (e) {
+        throw new Error(`YAML syntax error in ${filePath}: ${e.message}`);
+    }
+    // 3. Handle Inheritance (Extends)
+    if (parsed.extends) {
+        const parentPath = path_1.default.resolve(path_1.default.dirname(absolutePath), parsed.extends);
+        console.log(chalk_1.default.gray(`   ↳ Extending configuration from: ${parsed.extends}`));
+        const parentArch = loadArchitecture(parentPath);
+        const { extends: _, ...childConfig } = parsed;
+        parsed = mergeArchitectures(parentArch, childConfig);
+    }
+    // 4. Validate Schema
+    try {
+        const validated = schema_1.architectureSchema.parse(parsed);
+        return processArchitecturePlaceholders(validated);
+    }
+    catch (err) {
+        if (err instanceof zod_1.z.ZodError) {
+            const issues = err.issues.map(i => ` - ${i.path.join('.')}: ${i.message}`).join('\n');
+            throw new Error(`Invalid architecture configuration:\n${issues}`);
+        }
+        throw err;
+    }
+}
+function processArchitecturePlaceholders(arch) {
+    const placeholders = {
+        projectName: arch.project.name || "unnamed-project",
+        root: arch.project.root || ".",
+    };
+    const newLayers = arch.layers.map((layer) => ({
+        ...layer,
+        path: (0, template_1.replacePlaceholders)(layer.path, placeholders),
+    }));
+    return {
+        ...arch,
+        layers: newLayers,
+    };
+}

package/dist/core/architecture/schema.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.architectureSchema = exports.metadataSchema = exports.layerSchema = void 0;
+// src/core/architecture/schema.ts
+const zod_1 = require("zod");
+exports.layerSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    path: zod_1.z.string().min(1),
+    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(),
+    strict: zod_1.z.boolean().optional(),
+});
+exports.metadataSchema = zod_1.z.object({
+    type: zod_1.z.enum(['clean', 'ddd', 'layered', 'hexagonal', 'microservices']),
+    language: zod_1.z.enum(['ts', 'js', 'py', 'go']),
+    framework: zod_1.z.string().optional(),
+    modules: zod_1.z.array(zod_1.z.string()).optional(),
+    version: zod_1.z.string().optional(),
+});
+exports.architectureSchema = zod_1.z.object({
+    version: zod_1.z.string().default("1.0"),
+    name: zod_1.z.string(),
+    extends: zod_1.z.string().optional(),
+    project: zod_1.z.object({
+        name: zod_1.z.string(),
+        root: zod_1.z.string().optional(),
+    }),
+    metadata: exports.metadataSchema,
+    layers: zod_1.z.array(exports.layerSchema),
+    strict: zod_1.z.boolean().optional(),
+});