architect-ai 1.1.0

package/README.md

@@ -0,0 +1,182 @@
+# 🛡️ ArchitectAI: The AI-Powered Code Guardian
+
+> **Your 24/7 Virtual Technical Lead.**  
+> High-performance CLI tool to automate code reviews, enforce architectural patterns, and maintain clean code at scale using Generative AI.
+
+[![NPM Version](https://img.shields.io/badge/npm-v1.1.0-blue?style=flat-square)](https://www.npmjs.com/)
+[![Build Status](https://img.shields.io/badge/build-passing-green?style=flat-square)](https://github.com/minhnn/architect-ai)
+[![Powered By](https://img.shields.io/badge/AI-Gemini%20Pro-purple?style=flat-square)](https://deepmind.google/technologies/gemini/)
+[![License](https://img.shields.io/badge/license-MIT-gray?style=flat-square)]()
+
+---
+
+## 🚀 Why ArchitectAI?
+
+Traditional tools like **ESLint** or **Prettier** are great for syntax and formatting, but they miss the bigger picture. They can't tell you if your logic is flawed or if you're breaking the project's architecture.
+
+**ArchitectAI fills that gap.** v1.1.0 introduces a high-performance, concurrent engine that audits your code in parallel.
+
+* ❌ **No Architectural Violations:** (e.g., calling Database directly from a Controller).
+* ❌ **No Anti-Patterns:** (e.g., using `useEffect` for data fetching instead of `useQuery`).
+* ✅ **Clean Code Enforcement:** Checks for readability, SOLID principles, and proper code splitting.
+* ⚡ **High Performance:** Concurrent file auditing and ESM-native architecture.
+
+---
+
+## 📦 Installation
+
+```bash
+# Run once without installing
+npx @minhnn/architect-ai
+
+# Or install globally
+npm install -g @minhnn/architect-ai
+
+# Or add as dev dependency (recommended)
+npm install -D @minhnn/architect-ai
+# pnpm add -D @minhnn/architect-ai
+# yarn add -D @minhnn/architect-ai
+```
+
+## �️ CLI Usage
+
+```bash
+# Default: Audit commit message + changed files
+architect-ai
+
+# Audit only changed files (skip commit check)
+architect-ai --skip-commit
+
+# Audit specific files
+architect-ai src/main.ts src/utils.ts
+
+# Set max concurrency (default: 5)
+architect-ai --concurrency 10
+
+# Diff against a specific branch
+architect-ai --target-branch develop
+```
+
+### Options Reference
+
+| Option | Shorthand | Description | Default |
+|--------|-----------|-------------|---------|
+| `--help` | `-h` | Show help message | - |
+| `--version` | `-v` | Show version number | - |
+| `--skip-commit`| - | Skip commit message validation | `false` |
+| `--skip-files` | - | Skip file auditing | `false` |
+| `--target-branch`| `-b` | Target branch for git diff | `origin/main` |
+| `--concurrency` | `-c` | Max concurrent file audits | `5` |
+| `--verbose` | - | Enable verbose logging | `false` |
+
+---
+
+## ⚙️ Configuration (`.architectrc.json`)
+
+Create a `.architectrc.json` in your project root to customize rules and performance.
+
+```json
+{
+  "techStack": "React 19, Next.js (App Router), TanStack Query v5",
+  "rules": [
+    "CRITICAL: Never use 'useEffect' for data fetching. Suggest 'useQuery'.",
+    "STYLE: All components must use Arrow Functions.",
+    "PERFORMANCE: Split components exceeding 200 lines.",
+    "ARCHITECTURE: Business logic must stay in Services, not Controllers."
+  ],
+  "bypassKeyword": "skip:",
+  "maxConcurrency": 5
+}
+```
+
+### � Environment Variables
+
+```bash
+# Required: Get your key at https://aistudio.google.com/
+GEMINI_API_KEY=your_api_key_here
+
+# Optional: Set default target branch
+TARGET_BRANCH=origin/main
+```
+
+---
+
+## 📚 Programmatic API
+
+ArchitectAI can be used as a library in your own Node.js scripts.
+
+```typescript
+import { auditFilesWithConcurrency, loadProjectConfig } from '@minhnn/architect-ai';
+
+const config = await loadProjectConfig();
+const results = await auditFilesWithConcurrency(
+  [{ path: 'src/index.ts', content: '...' }],
+  config
+);
+```
+
+---
+
+## 🤖 CI/CD Integration
+
+### GitHub Actions (`.github/workflows/audit.yml`)
+
+```yaml
+name: ArchitectAI Code Guard
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Run ArchitectAI
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          TARGET_BRANCH: origin/${{ github.base_ref }}
+        run: npx @minhnn/architect-ai
+
+### GitLab CI (`.gitlab-ci.yml`)
+
+```yaml
+audit:
+  image: node:20
+  stage: test
+  cache:
+    paths:
+      - .npm/
+  before_script:
+    - npm ci --cache .npm --prefer-offline
+    - git fetch origin main
+  script:
+    - export TARGET_BRANCH="origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-main}"
+    - npx @minhnn/architect-ai --target-branch $TARGET_BRANCH
+  variables:
+    GEMINI_API_KEY: $GEMINI_API_KEY
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+```
+
+---
+
+## 💡 How it Works
+
+1. **Smart Diff**: Detects only relevant code changes against your target branch.
+2. **Concurrent Audit**: Files are processed in parallel batches for maximum speed.
+3. **AI Reasoning**: Your code + project rules are analyzed by Gemini 1.5 Pro.
+4. **Actionable Reports**: Styled console output with line-specific suggestions.
+5. **Exit Codes**: Returns `1` on CRITICAL issues to block bad PRs.
+
+---
+
+## 🛡️ License
+Copyright © 2026 MinhNN. All rights reserved.  
+Distributed under the MIT License.