@hasankemaldemirci/aro 1.0.0

package/dist/src/utils.d.ts

@@ -0,0 +1,14 @@
+import { AROMetrics } from "./types";
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Performance Optimized Utilities.
+ * Using fast-glob for high-speed file discovery.
+ */
+export * from "./types";
+export declare function loadIgnoreList(projectPath: string): string[];
+export declare function detectFramework(pkg: any): string;
+export declare function detectTechStack(pkg: any): string[];
+export declare function findEntryPoints(projectPath: string): string[];
+export declare function analyzeMetrics(projectPath: string, ignoreList: string[]): AROMetrics;
+export declare function calculateScore(metrics: AROMetrics): number;
+export declare function getRepoStructure(dir: string, depth: number, ignoreList: string[]): any;

package/dist/src/utils.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadIgnoreList = loadIgnoreList;
+exports.detectFramework = detectFramework;
+exports.detectTechStack = detectTechStack;
+exports.findEntryPoints = findEntryPoints;
+exports.analyzeMetrics = analyzeMetrics;
+exports.calculateScore = calculateScore;
+exports.getRepoStructure = getRepoStructure;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const constants_1 = require("./constants");
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Performance Optimized Utilities.
+ * Using fast-glob for high-speed file discovery.
+ */
+__exportStar(require("./types"), exports);
+function loadIgnoreList(projectPath) {
+    const ignorePath = path_1.default.join(projectPath, ".aroignore");
+    if (fs_1.default.existsSync(ignorePath)) {
+        const content = fs_1.default.readFileSync(ignorePath, "utf8");
+        const userIgnores = content
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l && !l.startsWith("#"));
+        return [...constants_1.DEFAULT_IGNORES, ...userIgnores];
+    }
+    return constants_1.DEFAULT_IGNORES;
+}
+function detectFramework(pkg) {
+    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";
+}
+function detectTechStack(pkg) {
+    const stack = [];
+    const allDeps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+    };
+    Object.keys(allDeps).forEach((dep) => {
+        if (constants_1.TECH_KEYWORDS.some((k) => dep.toLowerCase().includes(k))) {
+            stack.push(dep);
+        }
+    });
+    return stack;
+}
+function findEntryPoints(projectPath) {
+    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_1.default.existsSync(path_1.default.join(projectPath, file)));
+}
+function analyzeMetrics(projectPath, ignoreList) {
+    const metrics = {
+        hasReadme: false,
+        readmeSize: 0,
+        hasSrc: false,
+        hasConfig: 0,
+        largeFiles: 0,
+        securityIssues: 0,
+        blindSpots: [],
+    };
+    const readmePath = path_1.default.join(projectPath, "README.md");
+    if (fs_1.default.existsSync(readmePath)) {
+        metrics.hasReadme = true;
+        metrics.readmeSize = fs_1.default.statSync(readmePath).size;
+    }
+    else {
+        metrics.blindSpots.push("Missing README.md - AI Agents lack project high-level context.");
+    }
+    metrics.hasSrc =
+        fs_1.default.existsSync(path_1.default.join(projectPath, "src")) ||
+            fs_1.default.existsSync(path_1.default.join(projectPath, "app"));
+    if (!metrics.hasSrc)
+        metrics.blindSpots.push("Flat directory structure - Harder for AI to navigate.");
+    constants_1.CONFIG_FILES.forEach((file) => {
+        if (fs_1.default.existsSync(path_1.default.join(projectPath, file)))
+            metrics.hasConfig++;
+    });
+    // PERFORMANCE: Use fast-glob for sub-directory scanning (parallelized)
+    const files = fast_glob_1.default.sync(["**/*.{js,ts,tsx,jsx}"], {
+        cwd: projectPath,
+        ignore: ignoreList.map((i) => `**/${i}/**`),
+        absolute: true,
+        deep: 3,
+    });
+    files.forEach((file) => {
+        const content = fs_1.default.readFileSync(file, "utf8");
+        const lines = content.split("\n");
+        // Size check
+        if (lines.length > 300) {
+            metrics.largeFiles++;
+        }
+        // Security check (Basic detection for AI-gen risks)
+        constants_1.SECURITY_KEYWORDS.forEach((key) => {
+            if (content.includes(key + "=") || content.includes(key + ":")) {
+                metrics.securityIssues++;
+            }
+        });
+        constants_1.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;
+}
+function calculateScore(metrics) {
+    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));
+}
+function getRepoStructure(dir, depth, ignoreList) {
+    if (depth > 2)
+        return "...";
+    const res = {};
+    try {
+        fs_1.default.readdirSync(dir).forEach((file) => {
+            if (!ignoreList.some((ignore) => file === ignore)) {
+                const full = path_1.default.join(dir, file);
+                let stat;
+                try {
+                    stat = fs_1.default.statSync(full);
+                }
+                catch (e) {
+                    return;
+                }
+                if (stat.isDirectory()) {
+                    res[file] = getRepoStructure(full, depth + 1, ignoreList);
+                }
+                else {
+                    res[file] = "file";
+                }
+            }
+        });
+    }
+    catch (e) { }
+    return res;
+}

package/dist/tests/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/cli.test.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+describe("ARO CLI E2E", () => {
+    const testDir = path_1.default.join(__dirname, "e2e-dummy-project");
+    const aroBin = path_1.default.join(__dirname, "../dist/bin/aro.js");
+    beforeAll(() => {
+        // Setup dummy project
+        if (!fs_1.default.existsSync(testDir))
+            fs_1.default.mkdirSync(testDir);
+        fs_1.default.writeFileSync(path_1.default.join(testDir, "package.json"), JSON.stringify({
+            name: "e2e-test-project",
+            version: "1.0.0",
+            dependencies: { express: "^4.17.1" },
+        }));
+        fs_1.default.writeFileSync(path_1.default.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_1.default.join(testDir, "src");
+        if (!fs_1.default.existsSync(srcDir))
+            fs_1.default.mkdirSync(srcDir);
+        fs_1.default.writeFileSync(path_1.default.join(srcDir, "app.js"), "console.log('hello world');");
+    });
+    afterAll(() => {
+        // Cleanup
+        if (fs_1.default.existsSync(testDir)) {
+            fs_1.default.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+    test('should run "aro audit" and generate reports', () => {
+        // Ensure build exists
+        if (!fs_1.default.existsSync(aroBin)) {
+            (0, child_process_1.execSync)("npm run build", { cwd: path_1.default.join(__dirname, "..") });
+        }
+        // Execution
+        const output = (0, child_process_1.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_1.default.join(testDir, ".agent_context_pro.json");
+        expect(fs_1.default.existsSync(contextFilePath)).toBe(true);
+        const contextData = JSON.parse(fs_1.default.readFileSync(contextFilePath, "utf8"));
+        expect(contextData.projectName).toBe("e2e-test-project");
+        expect(contextData.framework).toBe("Node.js (Express)");
+    });
+});

package/dist/tests/core.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: This file is monitored for AI-Readability.
+ */
+export {};

package/dist/tests/core.test.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: This file is monitored for AI-Readability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: This file is monitored for AI-Readability.
+ */
+const utils_1 = require("../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((0, utils_1.detectFramework)(pkg)).toBe("Next.js");
+        });
+        test("should detect React", () => {
+            const pkg = { dependencies: { react: "latest" } };
+            expect((0, utils_1.detectFramework)(pkg)).toBe("React");
+        });
+        test("should detect Vue.js from devDependencies", () => {
+            const pkg = { devDependencies: { vue: "latest" } };
+            expect((0, utils_1.detectFramework)(pkg)).toBe("Vue.js");
+        });
+        test("should detect Nuxt.js", () => {
+            const pkg = { dependencies: { nuxt: "latest" } };
+            expect((0, utils_1.detectFramework)(pkg)).toBe("Nuxt.js");
+        });
+        test("should detect Node.js (Express)", () => {
+            const pkg = { dependencies: { express: "latest" } };
+            expect((0, utils_1.detectFramework)(pkg)).toBe("Node.js (Express)");
+        });
+        test("should default to Vanilla Node.js for unknown or empty projects", () => {
+            expect((0, utils_1.detectFramework)({})).toBe("Vanilla Node.js");
+            expect((0, utils_1.detectFramework)({ dependencies: { lodash: "1.0.0" } })).toBe("Vanilla Node.js");
+        });
+        test("should handle null/undefined fields gracefully", () => {
+            expect((0, utils_1.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((0, utils_1.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((0, utils_1.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((0, utils_1.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((0, utils_1.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 = (0, utils_1.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((0, utils_1.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((0, utils_1.calculateScore)(metrics)).toBe(0);
+        });
+    });
+});

package/dist/tests/enterprise.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/enterprise.test.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const enterprise_1 = require("../src/enterprise");
+describe("ARO Enterprise Analytics", () => {
+    test("should calculate $0 debt for a perfect project", () => {
+        const metrics = {
+            hasReadme: true,
+            readmeSize: 1000,
+            hasSrc: true,
+            hasConfig: 4,
+            largeFiles: 0,
+            securityIssues: 0,
+            blindSpots: [],
+        };
+        const debt = (0, enterprise_1.calculateDebt)(metrics);
+        expect(debt.totalDebt).toBe(0);
+        expect(debt.docDebt).toBe(0);
+        expect(debt.truncationDebt).toBe(0);
+        expect(debt.structuralDebt).toBe(0);
+    });
+    test("should calculate maximum debt for a missing documentation", () => {
+        const metrics = {
+            hasReadme: false,
+            readmeSize: 0,
+            hasSrc: true,
+            hasConfig: 4,
+            largeFiles: 0,
+            securityIssues: 0,
+            blindSpots: [],
+        };
+        const debt = (0, enterprise_1.calculateDebt)(metrics);
+        expect(debt.docDebt).toBe(15000);
+        expect(debt.totalDebt).toBe(15000);
+    });
+    test("should scale truncation debt with large files", () => {
+        const metrics = {
+            hasReadme: true,
+            readmeSize: 1000,
+            hasSrc: true,
+            hasConfig: 4,
+            largeFiles: 3,
+            securityIssues: 0,
+            blindSpots: [],
+        };
+        const debt = (0, enterprise_1.calculateDebt)(metrics);
+        expect(debt.truncationDebt).toBe(15000); // 3 * 5000
+    });
+    test("should calculate structural debt for flat projects", () => {
+        const metrics = {
+            hasReadme: true,
+            readmeSize: 1000,
+            hasSrc: false,
+            hasConfig: 0,
+            largeFiles: 0,
+            securityIssues: 0,
+            blindSpots: [],
+        };
+        const debt = (0, enterprise_1.calculateDebt)(metrics);
+        expect(debt.structuralDebt).toBe(20000); // 10000 (no src) + (2 * 5000) (missing 2 configs)
+    });
+    test("should handle partial configurations", () => {
+        const metrics = {
+            hasReadme: true,
+            readmeSize: 1000,
+            hasSrc: true,
+            hasConfig: 2,
+            largeFiles: 0,
+            securityIssues: 0,
+            blindSpots: [],
+        };
+        const debt = (0, enterprise_1.calculateDebt)(metrics);
+        expect(debt.structuralDebt).toBe(0); // Target met with 2 configs
+    });
+});

package/dist/tests/mcp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/mcp.test.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+describe("ARO MCP Server Integration", () => {
+    const mcpPath = path_1.default.join(__dirname, "../dist/src/mcp.js");
+    test("should start and respond to ListTools request over stdio", (done) => {
+        // We run the compiled version
+        const mcp = (0, child_process_1.spawn)("node", [mcpPath]);
+        let output = "";
+        mcp.stdout.on("data", (data) => {
+            output += data.toString();
+            try {
+                // MCP is JSON-RPC. We are looking for the tools definition.
+                if (output.includes("analyze_readability") &&
+                    output.includes("optimize_readability")) {
+                    mcp.kill();
+                    done();
+                }
+            }
+            catch (e) {
+                // Wait for more data
+            }
+        });
+        mcp.stderr.on("data", (data) => {
+            const msg = data.toString();
+            // The server logs "ARO MCP Server running on stdio" to stderr
+            if (msg.includes("ARO MCP Server running on stdio")) {
+                // Send dummy ListTools request
+                const listToolsRequest = {
+                    jsonrpc: "2.0",
+                    id: 1,
+                    method: "tools/list",
+                    params: {},
+                };
+                mcp.stdin.write(JSON.stringify(listToolsRequest) + "\n");
+            }
+        });
+        mcp.on("error", (err) => {
+            done(err);
+        });
+        // Timeout safety
+        setTimeout(() => {
+            if (mcp.killed)
+                return;
+            mcp.kill();
+            done(new Error("MCP Server response timeout or tools not found in output: " + output));
+        }, 5000);
+    });
+    test("should expose current-metrics resource", (done) => {
+        const mcp = (0, child_process_1.spawn)("node", [mcpPath]);
+        let output = "";
+        mcp.stdout.on("data", (data) => {
+            output += data.toString();
+            if (output.includes("aro://current-metrics")) {
+                mcp.kill();
+                done();
+            }
+        });
+        mcp.stderr.on("data", (data) => {
+            if (data.toString().includes("ARO MCP Server running on stdio")) {
+                const listResourcesRequest = {
+                    jsonrpc: "2.0",
+                    id: 2,
+                    method: "resources/list",
+                    params: {},
+                };
+                mcp.stdin.write(JSON.stringify(listResourcesRequest) + "\n");
+            }
+        });
+        setTimeout(() => {
+            if (mcp.killed)
+                return;
+            mcp.kill();
+            done(new Error("MCP Server resource discovery failed"));
+        }, 5000);
+    });
+});

package/eslint.config.mjs

@@ -0,0 +1,9 @@
+/** @aro-context-marker */
+export default [
+  {
+    rules: {
+      "no-unused-vars": "warn",
+      "no-undef": "error",
+    },
+  },
+];

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@hasankemaldemirci/aro",
+  "version": "1.0.0",
+  "description": "Agent Readability Optimizer - Professional SEO for your code.",
+  "main": "dist/src/core.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasankemaldemirci/aro.git"
+  },
+  "bin": {
+    "aro": "dist/bin/aro.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "NODE_ENV=development ts-node bin/aro.ts",
+    "analyze": "ts-node src/enterprise.ts",
+    "mcp": "ts-node src/mcp.ts",
+    "test": "jest",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "ai",
+    "agentic",
+    "debt",
+    "seo",
+    "readability",
+    "optimization",
+    "mcp"
+  ],
+  "author": "Hasan Kemal Demirci",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.1.0",
+    "chalk": "^4.1.2",
+    "fast-glob": "^3.2.11"
+  },
+  "devDependencies": {
+    "@types/chalk": "^2.2.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.13.4",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/temp_repos/",
+      "/dist/"
+    ],
+    "modulePathIgnorePatterns": [
+      "/temp_repos/",
+      "/dist/"
+    ],
+    "moduleNameMapper": {
+      "^@src/(.*)$": "<rootDir>/src/$1"
+    }
+  }
+}