@hasankemaldemirci/aro 1.0.0

package/src/refactor.ts

@@ -0,0 +1,122 @@
+import fs from "fs";
+import path from "path";
+import fg from "fast-glob";
+import { Branding } from "./constants";
+import { loadIgnoreList } from "./utils";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Performance Optimized Refactor Module.
+ * Using fast-glob for rapid complexity detection.
+ */
+
+export async function run() {
+  const projectPath = process.cwd();
+  const contextPath = path.join(projectPath, ".agent_context_pro.json");
+  const ignoreList = loadIgnoreList(projectPath);
+
+  if (!fs.existsSync(contextPath)) {
+    console.log(
+      Branding.error(
+        "❌ Error: No .agent_context_pro.json found. Run analysis first.",
+      ),
+    );
+    process.exit(1);
+  }
+
+  const data = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+  const metrics = data.metrics;
+
+  console.log(
+    Branding.magenta.bold(
+      "\n🛠️  ARO Auto-Refactor: Commencing Optimization...",
+    ),
+  );
+
+  // 1. Documentation Optimization
+  if (!metrics.hasReadme) {
+    console.log(Branding.warning("📝 Generating missing README.md..."));
+    const baseReadme = `# ${data.projectName}\n\n## Overview\nThis project is a ${data.framework} application.\n\n## Architecture\n*(Auto-generated by ARO)*\nThis project uses a standard ${data.framework} structure.`;
+    fs.writeFileSync(path.join(projectPath, "README.md"), baseReadme);
+    console.log(Branding.success("✅ README.md created."));
+  }
+
+  // 2. Configuration Recovery
+  const requiredConfigs: Record<string, string> = {
+    ".env.example":
+      "# Environment variables template\nPORT=3000\nAPI_" + "KEY=your_key_here",
+    "tsconfig.json":
+      '{\n  "compilerOptions": {\n    "target": "es5",\n    "module": "commonjs",\n    "strict": true\n  }\n}',
+    ".gitignore": "node_modules\n.DS_Store\n.env\n.agent_context_pro.json",
+  };
+
+  for (const [file, content] of Object.entries(requiredConfigs)) {
+    if (!fs.existsSync(path.join(projectPath, file))) {
+      console.log(
+        Branding.warning(`🛠️  Recovering missing config: ${file}...`),
+      );
+      fs.writeFileSync(path.join(projectPath, file), content);
+      console.log(Branding.success(`✅ ${file} generated.`));
+    }
+  }
+
+  // 3. Complexity Optimization: AI-SEO Markers (Optimized Scan)
+  const filesToOptimize = fg.sync(["**/*.{js,ts,tsx,jsx}"], {
+    cwd: projectPath,
+    ignore: ignoreList.map((i) => `**/${i}/**`),
+    absolute: true,
+    deep: 5,
+  });
+
+  for (const file of filesToOptimize) {
+    const content = fs.readFileSync(file, "utf8");
+    if (content.split("\n").length > 100) {
+      optimizeFile(file);
+    }
+  }
+
+  console.log(
+    Branding.success(
+      "\n✨ Refactoring Pass Complete. Run ARO again to see updated scores!",
+    ),
+  );
+}
+
+function optimizeFile(filePath: string) {
+  try {
+    let content = fs.readFileSync(filePath, "utf8");
+    if (content.includes("@aro-context-marker")) return;
+
+    const lines = content.split("\n");
+    let extraNote = "";
+
+    if (lines.length > 300) {
+      extraNote =
+        "\n * CRITICAL: This file exceeds 300 lines. AI Agents may experience context truncation.\n * ACTION: Consider refactoring core logic into smaller sub-modules.";
+      console.log(
+        Branding.warning(
+          `⚠️  Self-Healing: Detected high-complexity in ${path.basename(filePath)} (${lines.length} lines). Applying advisory markers.`,
+        ),
+      );
+    } else {
+      console.log(
+        Branding.gray(
+          `📌 Adding AI-SEO markers to: ${path.basename(filePath)}`,
+        ),
+      );
+    }
+
+    const marker = `/**\n * @aro-context-marker\n * AI READABILITY NOTE: This file is monitored for AI-Readability.${extraNote}\n */\n`;
+
+    if (lines[0].startsWith("#!")) {
+      lines.splice(1, 0, marker);
+      fs.writeFileSync(filePath, lines.join("\n"));
+    } else {
+      fs.writeFileSync(filePath, marker + content);
+    }
+  } catch (e) {}
+}
+
+if (require.main === module) {
+  run();
+}

package/src/rules.ts

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+import { Branding } from "./constants";
+import { AROContext } from "./types";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Rules generator for AI Agents (Cursor/Windsurf).
+ * Creates a .cursorrules file based on the local project context.
+ */
+
+export function run(): void {
+  const projectPath = process.cwd();
+  const contextPath = path.join(projectPath, ".agent_context_pro.json");
+
+  if (!fs.existsSync(contextPath)) {
+    console.log(
+      Branding.error("❌ Knowledge Map not found. Run 'aro audit' first."),
+    );
+    process.exit(1);
+  }
+
+  const data: AROContext = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+
+  const rulesContent = `
+# ARO: AI Agent Constitutional Rules 🛰️
+Version: ${data.version} | Framework: ${data.framework}
+
+## Core Directives for the AI Agent
+You are working in a codebase optimized by **ARO**. To maintain a 100/100 Readiness Score:
+
+1. **Modular Consistency:** NEVER create or expand files beyond 300 lines. If logic grows, refactor into smaller sub-modules immediately.
+2. **Context Retention:** Always refer to \`.agent_context_pro.json\` for the latest project structure and tech stack.
+3. **Deep Context Awareness:**
+   - Framework: ${data.framework}
+   - Tech Stack: ${data.techStack.join(", ")}
+   - Active Entry Points: ${data.entryPoints.join(", ")}
+
+4. **SEO Markers:** Always include \`@aro-context-marker\` in the headers of complex or core files to ensure context mapping persistence.
+5. **No Placeholders:** When generating code, provide complete, production-ready implementations.
+
+## Refactoring Protocol
+- Prioritize modularity over monolithic functions.
+- Ensure all new features are reflected in the documentation.
+- Maintain a clear directory hierarchy as defined in the structural audit.
+
+---
+*Optimized by ARO - "SEO for your code, optimized for AI Agents."*
+`.trim();
+
+  try {
+    const rulesFiles = [".cursorrules", ".windsurfrules", "AI-CONSTITUTION.md"];
+
+    rulesFiles.forEach((file) => {
+      fs.writeFileSync(path.join(projectPath, file), rulesContent);
+    });
+
+    console.log(Branding.border(""));
+    console.log(Branding.cyan.bold("👑 ARO Multi-Agent Constitution"));
+    console.log(Branding.border(""));
+    console.log(
+      Branding.success("\n✅ Rules deployed to: ") +
+        Branding.white(rulesFiles.join(", ")),
+    );
+    console.log(
+      Branding.gray(
+        "\nTargeting: Cursor, Windsurf, Devin, and any ARO-compatible AI Agent.",
+      ),
+    );
+    console.log(Branding.border(""));
+  } catch (e: any) {
+    console.log(Branding.error(`\n❌ Failed to deploy AI rules: ${e.message}`));
+  }
+}
+
+if (require.main === module) {
+  run();
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Centralized type definitions.
+ */
+
+export interface AROMetrics {
+  hasReadme: boolean;
+  readmeSize: number;
+  hasSrc: boolean;
+  hasConfig: number;
+  largeFiles: number;
+  securityIssues: number;
+  blindSpots: string[];
+}
+
+export interface AROContext {
+  projectName: string;
+  version: string;
+  framework: string;
+  techStack: string[];
+  entryPoints: string[];
+  analyzedAt: string;
+  metrics: AROMetrics;
+  score: number;
+  blindSpots: string[];
+  structure: any;
+}
+
+export interface EnterpriseOptions {
+  rate: number;
+  interactions: number;
+  threshold?: number;
+  output?: string;
+}
+
+export interface ARODebt {
+  docDebt: number;
+  truncationDebt: number;
+  structuralDebt: number;
+  tokenWasteDebt: number;
+  totalDebt: number;
+  wastedHours: number;
+}

package/src/utils.ts

@@ -0,0 +1,199 @@
+import fs from "fs";
+import path from "path";
+import fg from "fast-glob";
+import { AROMetrics } from "./types";
+import {
+  DEFAULT_IGNORES,
+  CONFIG_FILES,
+  TECH_KEYWORDS,
+  SECURITY_KEYWORDS,
+  DANGEROUS_FUNCS,
+} from "./constants";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Performance Optimized Utilities.
+ * Using fast-glob for high-speed file discovery.
+ */
+
+export * from "./types";
+
+export function loadIgnoreList(projectPath: string): string[] {
+  const ignorePath = path.join(projectPath, ".aroignore");
+  if (fs.existsSync(ignorePath)) {
+    const content = fs.readFileSync(ignorePath, "utf8");
+    const userIgnores = content
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#"));
+    return [...DEFAULT_IGNORES, ...userIgnores];
+  }
+  return DEFAULT_IGNORES;
+}
+
+export function detectFramework(pkg: any): string {
+  const allDeps = {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+  };
+  if (allDeps["next"]) return "Next.js";
+  if (allDeps["nuxt"]) return "Nuxt.js";
+  if (allDeps["vue"]) return "Vue.js";
+  if (allDeps["react"]) return "React";
+  if (allDeps["express"]) return "Node.js (Express)";
+  return "Vanilla Node.js";
+}
+
+export function detectTechStack(pkg: any): string[] {
+  const stack: string[] = [];
+  const allDeps = {
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+  };
+  Object.keys(allDeps).forEach((dep) => {
+    if (TECH_KEYWORDS.some((k) => dep.toLowerCase().includes(k))) {
+      stack.push(dep);
+    }
+  });
+  return stack;
+}
+
+export function findEntryPoints(projectPath: string): string[] {
+  const common = [
+    "src/index.ts",
+    "src/main.ts",
+    "src/app.ts",
+    "bin/aro.ts",
+    "src/index.js",
+    "server.js",
+    "app.js",
+    "index.js",
+  ];
+  return common.filter((file) => fs.existsSync(path.join(projectPath, file)));
+}
+
+export function analyzeMetrics(
+  projectPath: string,
+  ignoreList: string[],
+): AROMetrics {
+  const metrics: AROMetrics = {
+    hasReadme: false,
+    readmeSize: 0,
+    hasSrc: false,
+    hasConfig: 0,
+    largeFiles: 0,
+    securityIssues: 0,
+    blindSpots: [],
+  };
+
+  const readmePath = path.join(projectPath, "README.md");
+  if (fs.existsSync(readmePath)) {
+    metrics.hasReadme = true;
+    metrics.readmeSize = fs.statSync(readmePath).size;
+  } else {
+    metrics.blindSpots.push(
+      "Missing README.md - AI Agents lack project high-level context.",
+    );
+  }
+
+  metrics.hasSrc =
+    fs.existsSync(path.join(projectPath, "src")) ||
+    fs.existsSync(path.join(projectPath, "app"));
+  if (!metrics.hasSrc)
+    metrics.blindSpots.push(
+      "Flat directory structure - Harder for AI to navigate.",
+    );
+
+  CONFIG_FILES.forEach((file) => {
+    if (fs.existsSync(path.join(projectPath, file))) metrics.hasConfig++;
+  });
+
+  // PERFORMANCE: Use fast-glob for sub-directory scanning (parallelized)
+  const files = fg.sync(["**/*.{js,ts,tsx,jsx}"], {
+    cwd: projectPath,
+    ignore: ignoreList.map((i) => `**/${i}/**`),
+    absolute: true,
+    deep: 3,
+  });
+
+  files.forEach((file) => {
+    const content = fs.readFileSync(file, "utf8");
+    const lines = content.split("\n");
+
+    // Size check
+    if (lines.length > 300) {
+      metrics.largeFiles++;
+    }
+
+    // Security check (Basic detection for AI-gen risks)
+    SECURITY_KEYWORDS.forEach((key) => {
+      if (content.includes(key + "=") || content.includes(key + ":")) {
+        metrics.securityIssues++;
+      }
+    });
+
+    DANGEROUS_FUNCS.forEach((func) => {
+      if (content.includes(func)) {
+        metrics.securityIssues++;
+      }
+    });
+  });
+
+  if (metrics.largeFiles > 0) {
+    metrics.blindSpots.push(
+      `${metrics.largeFiles} large files detected - Causes 'Context Truncation'.`,
+    );
+  }
+
+  if (metrics.securityIssues > 0) {
+    metrics.blindSpots.push(
+      `${metrics.securityIssues} potential security/hallucination risks (hardcoded keys or dangerous functions) detected.`,
+    );
+  }
+
+  return metrics;
+}
+
+export function calculateScore(metrics: AROMetrics): number {
+  let score = 0;
+  if (metrics.hasReadme) {
+    score += 15;
+    if (metrics.readmeSize >= 500) score += 15;
+  }
+  if (metrics.hasSrc) score += 20;
+  score += Math.min(metrics.hasConfig * 10, 20);
+  score += Math.max(30 - metrics.largeFiles * 5, 0);
+
+  // Security Penalty: -5 per issue, caps at 20
+  score -= Math.min(metrics.securityIssues * 5, 20);
+
+  return Math.max(0, Math.min(score, 100));
+}
+
+export function getRepoStructure(
+  dir: string,
+  depth: number,
+  ignoreList: string[],
+): any {
+  if (depth > 2) return "...";
+  const res: any = {};
+  try {
+    fs.readdirSync(dir).forEach((file) => {
+      if (!ignoreList.some((ignore) => file === ignore)) {
+        const full = path.join(dir, file);
+        let stat;
+        try {
+          stat = fs.statSync(full);
+        } catch (e) {
+          return;
+        }
+        if (stat.isDirectory()) {
+          res[file] = getRepoStructure(full, depth + 1, ignoreList);
+        } else {
+          res[file] = "file";
+        }
+      }
+    });
+  } catch (e) {}
+  return res;
+}

package/tests/cli.test.ts

@@ -0,0 +1,71 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+describe("ARO CLI E2E", () => {
+  const testDir = path.join(__dirname, "e2e-dummy-project");
+  const aroBin = path.join(__dirname, "../dist/bin/aro.js");
+
+  beforeAll(() => {
+    // Setup dummy project
+    if (!fs.existsSync(testDir)) fs.mkdirSync(testDir);
+
+    fs.writeFileSync(
+      path.join(testDir, "package.json"),
+      JSON.stringify({
+        name: "e2e-test-project",
+        version: "1.0.0",
+        dependencies: { express: "^4.17.1" },
+      }),
+    );
+
+    fs.writeFileSync(
+      path.join(testDir, "README.md"),
+      "# Test Project\nThis is a test project for ARO E2E. It needs to be long enough to pass some size checks if necessary.".repeat(
+        10,
+      ),
+    );
+
+    const srcDir = path.join(testDir, "src");
+    if (!fs.existsSync(srcDir)) fs.mkdirSync(srcDir);
+    fs.writeFileSync(
+      path.join(srcDir, "app.js"),
+      "console.log('hello world');",
+    );
+  });
+
+  afterAll(() => {
+    // Cleanup
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  test('should run "aro audit" and generate reports', () => {
+    // Ensure build exists
+    if (!fs.existsSync(aroBin)) {
+      execSync("npm run build", { cwd: path.join(__dirname, "..") });
+    }
+
+    // Execution
+    const output = execSync(`node ${aroBin} audit`, {
+      cwd: testDir,
+    }).toString();
+
+    // Verifications (Updated strings to match new Branding and modular output)
+    expect(output).toContain("ARO");
+    expect(output).toContain("Framework");
+    expect(output).toContain("Node.js (Express)");
+    expect(output).toContain("Quality Score");
+    expect(output).toContain("Financial Analyzer");
+    expect(output).toContain("ANNUAL DEBT"); // Updated from "TOTAL ANNUAL AI DEBT"
+
+    // Check if artifact was created
+    const contextFilePath = path.join(testDir, ".agent_context_pro.json");
+    expect(fs.existsSync(contextFilePath)).toBe(true);
+
+    const contextData = JSON.parse(fs.readFileSync(contextFilePath, "utf8"));
+    expect(contextData.projectName).toBe("e2e-test-project");
+    expect(contextData.framework).toBe("Node.js (Express)");
+  });
+});

package/tests/core.test.ts

@@ -0,0 +1,146 @@
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: This file is monitored for AI-Readability.
+ */
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: This file is monitored for AI-Readability.
+ */
+import { detectFramework, calculateScore } from "../src/utils";
+
+describe("ARO Core Engine", () => {
+  describe("detectFramework - Precision & Edge Cases", () => {
+    test("should detect Next.js (Priority Case)", () => {
+      const pkg = { dependencies: { next: "latest", react: "latest" } };
+      expect(detectFramework(pkg)).toBe("Next.js");
+    });
+
+    test("should detect React", () => {
+      const pkg = { dependencies: { react: "latest" } };
+      expect(detectFramework(pkg)).toBe("React");
+    });
+
+    test("should detect Vue.js from devDependencies", () => {
+      const pkg = { devDependencies: { vue: "latest" } };
+      expect(detectFramework(pkg)).toBe("Vue.js");
+    });
+
+    test("should detect Nuxt.js", () => {
+      const pkg = { dependencies: { nuxt: "latest" } };
+      expect(detectFramework(pkg)).toBe("Nuxt.js");
+    });
+
+    test("should detect Node.js (Express)", () => {
+      const pkg = { dependencies: { express: "latest" } };
+      expect(detectFramework(pkg)).toBe("Node.js (Express)");
+    });
+
+    test("should default to Vanilla Node.js for unknown or empty projects", () => {
+      expect(detectFramework({})).toBe("Vanilla Node.js");
+      expect(detectFramework({ dependencies: { lodash: "1.0.0" } })).toBe(
+        "Vanilla Node.js",
+      );
+    });
+
+    test("should handle null/undefined fields gracefully", () => {
+      expect(detectFramework({ dependencies: undefined })).toBe(
+        "Vanilla Node.js",
+      );
+    });
+  });
+
+  describe("calculateScore - Logic Boundaries", () => {
+    test("should give 100 for a perfect, well-documented project", () => {
+      const metrics = {
+        hasReadme: true,
+        readmeSize: 1000,
+        hasSrc: true,
+        hasConfig: 4,
+        largeFiles: 0,
+        securityIssues: 0,
+        blindSpots: [],
+      };
+      expect(calculateScore(metrics)).toBe(100);
+    });
+
+    test("should penalize for missing README", () => {
+      const metrics = {
+        hasReadme: false,
+        readmeSize: 0,
+        hasSrc: true,
+        hasConfig: 4,
+        largeFiles: 0,
+        securityIssues: 0,
+        blindSpots: [],
+      };
+      expect(calculateScore(metrics)).toBe(70);
+    });
+
+    test("should penalize for small README (<500 chars)", () => {
+      const metrics = {
+        hasReadme: true,
+        readmeSize: 100,
+        hasSrc: true,
+        hasConfig: 4,
+        largeFiles: 0,
+        securityIssues: 0,
+        blindSpots: [],
+      };
+      expect(calculateScore(metrics)).toBe(85);
+    });
+
+    test("should penalize heavily for flat directory structure", () => {
+      const metrics = {
+        hasReadme: true,
+        readmeSize: 1000,
+        hasSrc: false,
+        hasConfig: 4,
+        largeFiles: 0,
+        securityIssues: 0,
+        blindSpots: [],
+      };
+      expect(calculateScore(metrics)).toBe(80);
+    });
+
+    test("should penalize for large files (truncation debt)", () => {
+      const metrics = {
+        hasReadme: true,
+        readmeSize: 1000,
+        hasSrc: true,
+        hasConfig: 4,
+        largeFiles: 5,
+        securityIssues: 0,
+        blindSpots: [],
+      };
+      const score = calculateScore(metrics);
+      expect(score).toBe(75);
+    });
+
+    test("should penalize for security issues", () => {
+      const metrics = {
+        hasReadme: true,
+        readmeSize: 1000,
+        hasSrc: true,
+        hasConfig: 4,
+        largeFiles: 0,
+        securityIssues: 2,
+        blindSpots: [],
+      };
+      expect(calculateScore(metrics)).toBe(90); // 100 - (2 * 5)
+    });
+
+    test("should not go below 0", () => {
+      const metrics = {
+        hasReadme: false,
+        readmeSize: 0,
+        hasSrc: false,
+        hasConfig: 0,
+        largeFiles: 20,
+        securityIssues: 10,
+        blindSpots: [],
+      };
+      expect(calculateScore(metrics)).toBe(0);
+    });
+  });
+});