@hasankemaldemirci/aro 1.0.0

package/src/badge.ts

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+import { Branding } from "./constants";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Badge generator for GitHub integration.
+ * Supports --update flag to automatically patch README.md.
+ */
+
+export function run(): void {
+  const args = process.argv.slice(2);
+  const shouldUpdate = args.includes("--update");
+
+  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 = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+  const score = data.score;
+
+  let color = "brightgreen";
+  if (score < 60) color = "red";
+  else if (score < 85) color = "yellow";
+
+  // Using standard 'flat' style to match GitHub native badges exactly
+  const badgeUrl = `https://img.shields.io/badge/ARO_Score-${score}%2F100-${color}`;
+  const markdown = `[![ARO Score](${badgeUrl})](https://github.com/hasankemaldemirci/aro)`;
+
+  if (shouldUpdate) {
+    const readmePath = path.join(projectPath, "README.md");
+    if (fs.existsSync(readmePath)) {
+      let content = fs.readFileSync(readmePath, "utf8");
+      const inlineRegex =
+        /\[\!\[ARO Score\]\(https:\/\/img\.shields\.io\/badge\/ARO_Score-[^)]+\)\]\([^)]+\)/;
+      const refRegex =
+        /^\[aro-badge\]: https:\/\/img\.shields\.io\/badge\/ARO_Score-[^\n]+/m;
+
+      if (inlineRegex.test(content)) {
+        content = content.replace(inlineRegex, markdown);
+        fs.writeFileSync(readmePath, content);
+        console.log(Branding.success("✅ README.md updated (Inline Badge)."));
+      } else if (refRegex.test(content)) {
+        content = content.replace(refRegex, `[aro-badge]: ${badgeUrl}`);
+        fs.writeFileSync(readmePath, content);
+        console.log(
+          Branding.success("✅ README.md updated (Reference Badge)."),
+        );
+      } else {
+        console.log(
+          Branding.warning(
+            "⚠️  ARO Score badge not found in README.md. Skipping auto-update.",
+          ),
+        );
+      }
+    }
+  }
+
+  console.log(Branding.border(""));
+  console.log(Branding.cyan.bold("🛡️  ARO Badge Generator"));
+  console.log(Branding.border(""));
+  console.log(
+    Branding.white("\nUse the following snippet in your README.md:\n"),
+  );
+  console.log(Branding.magenta(markdown));
+  console.log(Branding.border(""));
+}
+
+if (require.main === module) {
+  run();
+}

package/src/constants.ts

@@ -0,0 +1,68 @@
+import chalk from "chalk";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Centralized branding and constants.
+ */
+
+export const Branding = {
+  cyan: chalk.hex("#00f2ff"),
+  magenta: chalk.hex("#ff00ff"),
+  success: chalk.hex("#00ff88"),
+  warning: chalk.hex("#ffbb00"),
+  error: chalk.hex("#ff0044"),
+  gray: chalk.hex("#666666"),
+  white: chalk.hex("#ffffff"),
+  border: (text: string) => chalk.hex("#333333")("─".repeat(text.length || 40)),
+};
+
+export const DEFAULT_IGNORES = [
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "temp_repos",
+  ".agent_context_pro.json",
+  "tests",
+  "__tests__",
+  ".husky",
+];
+
+export const CONFIG_FILES = [
+  "tsconfig.json",
+  "next.config.ts",
+  ".env.example",
+  "package.json",
+  "eslint.config.mjs",
+];
+
+export const SECURITY_KEYWORDS = [
+  "API_" + "KEY",
+  "SEC" + "RET",
+  "PASS" + "WORD",
+  "TO" + "KEN",
+  "PRIVATE_" + "KEY",
+];
+export const DANGEROUS_FUNCS = [
+  "ev" + "al(",
+  "ex" + "ec(",
+  "child_process.ex" + "ec(",
+];
+
+export const TECH_KEYWORDS = [
+  "typescript",
+  "tailwind",
+  "prisma",
+  "mongoose",
+  "jest",
+  "vitest",
+  "express",
+  "fastify",
+  "redux",
+  "axios",
+  "firebase",
+  "supabase",
+  "react",
+  "next",
+  "vue",
+];

package/src/core.ts

@@ -0,0 +1,141 @@
+/**
+ * @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 fs from "fs";
+import path from "path";
+import { AROContext } from "./types";
+import { Branding } from "./constants";
+import {
+  loadIgnoreList,
+  detectFramework,
+  detectTechStack,
+  findEntryPoints,
+  analyzeMetrics,
+  calculateScore,
+  getRepoStructure,
+} from "./utils";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: Orchestration layer for ARO analysis.
+ */
+
+export async function run(): Promise<AROContext | void> {
+  const isSilent = process.argv.includes("--silent");
+
+  if (!isSilent) {
+    console.log(Branding.border(""));
+    console.log(Branding.cyan.bold("🛰️  ARO") + Branding.gray(" | v2.1.0-TS"));
+    console.log(
+      Branding.white('"SEO for your code, optimized for AI Agents."'),
+    );
+    console.log(Branding.border(""));
+  }
+
+  const projectPath = process.cwd();
+  const pkgPath = path.join(projectPath, "package.json");
+
+  if (!fs.existsSync(pkgPath)) {
+    handleError(
+      "package.json not found. Please run this in a Node.js project.",
+    );
+  }
+
+  let pkg: any;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  } catch (e: any) {
+    handleError(`Failed to parse package.json: ${e.message}`);
+  }
+
+  const framework = detectFramework(pkg);
+  const techStack = detectTechStack(pkg);
+  const entryPoints = findEntryPoints(projectPath);
+
+  if (!isSilent) {
+    console.log(
+      Branding.white(`\n🎯 Framework: `) + Branding.magenta.bold(framework),
+    );
+    console.log(
+      Branding.gray(`🛠️  Tech Stack: `) + Branding.cyan(techStack.join(", ")),
+    );
+    console.log(Branding.gray(`📂 Scope: `) + Branding.white(projectPath));
+  }
+
+  const ignoreList = loadIgnoreList(projectPath);
+
+  try {
+    const metrics = analyzeMetrics(projectPath, ignoreList);
+    const score = calculateScore(metrics);
+
+    const contextMap: AROContext = {
+      projectName: pkg.name || "Unknown",
+      version: pkg.version || "0.0.1",
+      framework,
+      techStack,
+      entryPoints,
+      analyzedAt: new Date().toISOString(),
+      metrics,
+      score,
+      blindSpots: metrics.blindSpots,
+      structure: getRepoStructure(projectPath, 0, ignoreList),
+    };
+
+    const contextFilePath = path.join(projectPath, ".agent_context_pro.json");
+    fs.writeFileSync(contextFilePath, JSON.stringify(contextMap, null, 2));
+
+    if (!isSilent) {
+      console.log(
+        Branding.success(`\n✅ Knowledge Map: `) +
+          Branding.white.bold(".agent_context_pro.json"),
+      );
+      displayScore(score);
+
+      if (score < 100 && metrics.blindSpots.length > 0) {
+        console.log(Branding.warning("\n🚩 Blind Spots & Recommendations:"));
+        metrics.blindSpots.forEach((spot) => {
+          console.log(Branding.gray(` • ${spot}`));
+        });
+      }
+    }
+
+    return contextMap;
+  } catch (e: any) {
+    handleError(`Analysis failed: ${e.message}`);
+  }
+}
+
+export function handleError(message: string): never {
+  console.log(Branding.error(`\n❌ Error: ${message}`));
+  process.exit(1);
+}
+
+export function displayScore(score: number): void {
+  const color =
+    score > 80
+      ? Branding.success
+      : score > 60
+        ? Branding.warning
+        : Branding.error;
+  console.log(
+    Branding.white(`📈 Quality Score: `) + color.bold(`${score}/100`),
+  );
+
+  if (score < 80) {
+    console.log(
+      Branding.warning(`\n⚠️  At Risk: High Hallucination Tax detected.`),
+    );
+  }
+}
+
+if (require.main === module) {
+  run().catch((err) => {
+    handleError(err.message);
+  });
+}

package/src/enterprise.ts

@@ -0,0 +1,159 @@
+import fs from "fs";
+import path from "path";
+import { EnterpriseOptions, ARODebt } from "./types";
+import { Branding } from "./constants";
+import { AROMetrics } from "./utils";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: This file is monitored for AI-Readability.
+ */
+
+export function calculateDebt(
+  metrics: AROMetrics,
+  options?: Partial<EnterpriseOptions>,
+): ARODebt {
+  const m = metrics;
+  const rate = options?.rate || 100;
+  const interactions = options?.interactions || 2400;
+
+  let docDebt = 0;
+  if (!m.hasReadme) docDebt = 15000;
+  else if (m.readmeSize < 500) docDebt = 6000;
+
+  const truncationDebt = m.largeFiles * 5000;
+
+  let structuralDebt = 0;
+  if (!m.hasSrc) structuralDebt += 10000;
+  // Align with Score: Score gives max points for 2 config files.
+  const configRequirement = 2;
+  const missingConfigs = Math.max(0, configRequirement - m.hasConfig);
+  structuralDebt += missingConfigs * 5000;
+
+  const tokenWasteDebt = m.largeFiles * interactions * 0.05;
+
+  const totalDebt = docDebt + truncationDebt + structuralDebt + tokenWasteDebt;
+  const wastedHours = totalDebt / rate;
+
+  return {
+    docDebt,
+    truncationDebt,
+    structuralDebt,
+    tokenWasteDebt,
+    totalDebt,
+    wastedHours,
+  };
+}
+
+export function run(): void {
+  const args = process.argv.slice(2);
+
+  const options: EnterpriseOptions = {
+    rate: 120,
+    interactions: 2400,
+  };
+
+  args.forEach((arg) => {
+    if (arg.startsWith("--rate=")) options.rate = parseInt(arg.split("=")[1]);
+    if (arg.startsWith("--interactions="))
+      options.interactions = parseInt(arg.split("=")[1]);
+    if (arg.startsWith("--threshold="))
+      options.threshold = parseInt(arg.split("=")[1]);
+    if (arg.startsWith("--output=")) options.output = arg.split("=")[1];
+  });
+
+  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 analysis first."),
+    );
+    process.exit(1);
+  }
+
+  const context = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+  const debt = calculateDebt(context.metrics, options);
+
+  let reportContent = `
+# ARO AI-Financial Report
+Analyzed At: ${context.analyzedAt}
+Project: ${context.projectName}
+Score: ${context.score}/100
+
+## Business Metrics
+- AI-Onboarding Ready: ${context.score}%
+- Developer Hourly Rate (Avg): $${options.rate}
+- Annual Interactions: ${options.interactions}
+
+## Financial Breakdown (Annual)
+- Documentation Gap: $${Math.round(debt.docDebt).toLocaleString()}
+- Truncation Risk: $${Math.round(debt.truncationDebt).toLocaleString()}
+- Structural Debt: $${Math.round(debt.structuralDebt).toLocaleString()}
+- Token Waste: $${Math.round(debt.tokenWasteDebt).toLocaleString()}
+
+**TOTAL ANNUAL AI DEBT: $${Math.round(debt.totalDebt).toLocaleString()}**
+Monthly Productivity Loss: $${Math.round(debt.totalDebt / 12).toLocaleString()}
+Wasted Billable Hours: ${Math.round(debt.wastedHours)} hrs/year
+`;
+
+  if (options.output) {
+    // SECURITY: Path Traversal Prevention
+    // Ensure output is directed within the project directory or a safe subdirectory
+    // We basename the filename to prevent escaping with ../..
+    const safeFileName = path.basename(options.output);
+    const outputPath = path.join(projectPath, safeFileName);
+
+    fs.writeFileSync(outputPath, reportContent);
+    console.log(
+      Branding.success(`\n💾 Exported (Sanitized): `) +
+        Branding.white.bold(safeFileName),
+    );
+  }
+
+  // Console Output
+  console.log(Branding.border(""));
+  console.log(
+    Branding.magenta.bold("💰 ARO Financial Analyzer") +
+      Branding.gray(" | Enterprise Report"),
+  );
+  console.log(Branding.border(""));
+
+  console.log(Branding.cyan("\n[BUSINESS METRICS]"));
+  console.log(
+    Branding.white(`Score: `) + Branding.success.bold(`${context.score}%`),
+  );
+  console.log(Branding.white(`Rate: `) + Branding.gray(`$${options.rate}/hr`));
+
+  console.log(Branding.error("\n[DANGER ZONE - ANNUAL DEBT]"));
+  console.log(
+    Branding.gray(`Total Debt: `) +
+      Branding.error.bold(`$${Math.round(debt.totalDebt).toLocaleString()}`),
+  );
+  console.log(
+    Branding.gray(`Wasted Hours: `) +
+      Branding.warning.bold(`${Math.round(debt.wastedHours)} hrs/yr`),
+  );
+
+  if (options.threshold !== undefined) {
+    console.log(Branding.border(""));
+    if (context.score < options.threshold) {
+      console.log(
+        Branding.error(
+          `⛔ CI/CD REJECTED: Score ${context.score} < Threshold ${options.threshold}`,
+        ),
+      );
+      process.exit(1);
+    } else {
+      console.log(
+        Branding.success(
+          `✅ CI/CD PASSED: Score ${context.score} >= Threshold ${options.threshold}`,
+        ),
+      );
+    }
+  }
+}
+
+if (require.main === module) {
+  run();
+}

package/src/init.ts

@@ -0,0 +1,75 @@
+import fs from "fs";
+import path from "path";
+import { Branding } from "./constants";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: CI/CD Initializer for ARO.
+ * Sets up GitHub Actions workflows to automate readability audits.
+ */
+
+const GITHUB_WORKFLOW_YAML = `name: ARO Audit
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - name: Run ARO Audit
+        run: npx @hasankemaldemirci/aro audit --threshold=80
+`;
+
+export function run(): void {
+  const projectPath = process.cwd();
+  const workflowDir = path.join(projectPath, ".github", "workflows");
+  const workflowPath = path.join(workflowDir, "aro.yml");
+
+  console.log(Branding.border(""));
+  console.log(Branding.cyan.bold("🤖 ARO CI/CD Initializer"));
+  console.log(Branding.border(""));
+
+  if (!fs.existsSync(workflowDir)) {
+    fs.mkdirSync(workflowDir, { recursive: true });
+  }
+
+  if (fs.existsSync(workflowPath)) {
+    console.log(
+      Branding.warning(
+        "⚠️  GitHub Action already exists at .github/workflows/aro.yml",
+      ),
+    );
+    return;
+  }
+
+  try {
+    fs.writeFileSync(workflowPath, GITHUB_WORKFLOW_YAML);
+    console.log(
+      Branding.success("\n✅ Created GitHub Action: ") +
+        Branding.white(".github/workflows/aro.yml"),
+    );
+    console.log(
+      Branding.gray(
+        "\nYour project will now be automatically audited on every push.",
+      ),
+    );
+  } catch (e: any) {
+    console.log(Branding.error(`\n❌ Failed to create workflow: ${e.message}`));
+  }
+  console.log(Branding.border(""));
+}
+
+if (require.main === module) {
+  run();
+}

package/src/mcp.ts

@@ -0,0 +1,158 @@
+
+/**
+ * @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 { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+/**
+ * @aro-context-marker
+ * AI READABILITY NOTE: MCP Server in TypeScript.
+ * Provides tools for AI models to self-audit and optimize context.
+ */
+
+const SRC_PATH = __dirname;
+
+const server = new Server(
+  {
+    name: "aro-ai-readability",
+    version: "2.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  },
+);
+
+// --- Resources ---
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: "aro://current-metrics",
+      name: "ARO AI-Readability Metrics",
+      description: "The latest analysis results and AI debt report.",
+      mimeType: "application/json",
+    },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === "aro://current-metrics") {
+    const contextPath = path.join(process.cwd(), ".agent_context_pro.json");
+    if (!fs.existsSync(contextPath)) {
+      throw new Error("No analysis data found. Run analyze_readability first.");
+    }
+    return {
+      contents: [
+        {
+          uri: request.params.uri,
+          mimeType: "application/json",
+          text: fs.readFileSync(contextPath, "utf8"),
+        },
+      ],
+    };
+  }
+  throw new Error("Resource not found");
+});
+
+// --- Tools ---
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "analyze_readability",
+      description:
+        "Performs a deep audit of the codebase to calculate AI-Readiness score and Hallucination Tax.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "optimize_readability",
+      description:
+        "Automatically applies AI-SEO markers and generates missing configurations to improve AI context retention.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          applyFixes: {
+            type: "boolean",
+            description: "Whether to apply automated fixes.",
+            default: true,
+          },
+        },
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name } = request.params;
+
+  try {
+    if (name === "analyze_readability") {
+      execSync(`node ${path.join(SRC_PATH, "core.js")}`);
+      const contextPath = path.join(process.cwd(), ".agent_context_pro.json");
+      const data = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Analysis complete.\nScore: ${data.score}/100\nFramework: ${data.framework}\nBlind Spots: ${data.blindSpots.join(", ")}`,
+          },
+        ],
+      };
+    }
+
+    if (name === "optimize_readability") {
+      execSync(`node ${path.join(SRC_PATH, "refactor.js")}`);
+      execSync(`node ${path.join(SRC_PATH, "core.js")}`);
+      const contextPath = path.join(process.cwd(), ".agent_context_pro.json");
+      const data = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Optimizations applied successfully.\nNew AI-Readiness Score: ${data.score}/100`,
+          },
+        ],
+      };
+    }
+
+    throw new Error(`Tool not found: ${name}`);
+  } catch (error: any) {
+    return {
+      isError: true,
+      content: [
+        { type: "text", text: `Error executing ARO tool: ${error.message}` },
+      ],
+    };
+  }
+});
+
+// --- Start Server ---
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("ARO MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error starting ARO MCP server:", error);
+  process.exit(1);
+});