@aiready/change-amplification 0.1.4

package/.turbo/turbo-build.log

@@ -0,0 +1,108 @@
+
+
+> @aiready/change-amplification@0.1.4 build /Users/pengcao/projects/aiready/packages/change-amplification
+> tsup src/index.ts src/cli.ts --format cjs,esm --dts
+
+CLI Building entry: src/cli.ts, src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2020
+CJS Build start
+ESM Build start
+
+[1:03:47 PM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
+
+    package.json:33:6:
+      33 │       "types": "./dist/index.d.ts"
+         ╵       ~~~~~~~
+
+  The "import" condition comes earlier and will be used for all "import" statements:
+
+    package.json:31:6:
+      31 │       "import": "./dist/index.mjs",
+         ╵       ~~~~~~~~
+
+  The "require" condition comes earlier and will be used for all "require" calls:
+
+    package.json:32:6:
+      32 │       "require": "./dist/index.js",
+         ╵       ~~~~~~~~~
+
+
+
+
+[1:03:47 PM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
+
+    package.json:38:6:
+      38 │       "types": "./dist/cli.d.ts"
+         ╵       ~~~~~~~
+
+  The "import" condition comes earlier and will be used for all "import" statements:
+
+    package.json:36:6:
+      36 │       "import": "./dist/cli.mjs",
+         ╵       ~~~~~~~~
+
+  The "require" condition comes earlier and will be used for all "require" calls:
+
+    package.json:37:6:
+      37 │       "require": "./dist/cli.js",
+         ╵       ~~~~~~~~~
+
+
+
+
+[1:03:47 PM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
+
+    package.json:33:6:
+      33 │       "types": "./dist/index.d.ts"
+         ╵       ~~~~~~~
+
+  The "import" condition comes earlier and will be used for all "import" statements:
+
+    package.json:31:6:
+      31 │       "import": "./dist/index.mjs",
+         ╵       ~~~~~~~~
+
+  The "require" condition comes earlier and will be used for all "require" calls:
+
+    package.json:32:6:
+      32 │       "require": "./dist/index.js",
+         ╵       ~~~~~~~~~
+
+
+
+
+[1:03:47 PM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
+
+    package.json:38:6:
+      38 │       "types": "./dist/cli.d.ts"
+         ╵       ~~~~~~~
+
+  The "import" condition comes earlier and will be used for all "import" statements:
+
+    package.json:36:6:
+      36 │       "import": "./dist/cli.mjs",
+         ╵       ~~~~~~~~
+
+  The "require" condition comes earlier and will be used for all "require" calls:
+
+    package.json:37:6:
+      37 │       "require": "./dist/cli.js",
+         ╵       ~~~~~~~~~
+
+
+
+ESM dist/index.mjs          110.00 B
+ESM dist/cli.mjs            2.72 KB
+ESM dist/chunk-VW57ZQRN.mjs 3.83 KB
+ESM ⚡️ Build success in 66ms
+CJS dist/index.js 5.13 KB
+CJS dist/cli.js   7.94 KB
+CJS ⚡️ Build success in 67ms
+DTS Build start
+DTS ⚡️ Build success in 7604ms
+DTS dist/cli.d.ts    152.00 B
+DTS dist/index.d.ts  1013.00 B
+DTS dist/cli.d.mts   152.00 B
+DTS dist/index.d.mts 1013.00 B

package/.turbo/turbo-test.log

@@ -0,0 +1,16 @@
+
+
+> @aiready/change-amplification@0.1.4 test /Users/pengcao/projects/aiready/packages/change-amplification
+> vitest run
+
+
+ RUN  v1.6.1 /Users/pengcao/projects/aiready/packages/change-amplification
+
+ ✓ src/__tests__/dummy.test.ts  (1 test) 9ms
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+   Start at  13:04:26
+   Duration  2.33s (transform 367ms, setup 0ms, collect 466ms, tests 9ms, environment 0ms, prepare 541ms)
+
+[?25h

package/README.md

@@ -0,0 +1,65 @@
+# @aiready/change-amplification
+
+> AIReady Spoke: Analyzes architectural coupling and graph metrics to predict how code changes "explode" across the codebase.
+
+[![npm version](https://img.shields.io/npm/v/@aiready/change-amplification.svg)](https://npmjs.com/package/@aiready/change-amplification)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+High architectural coupling is one of the leading causes of AI agent failure. When an agent modifies a "bottleneck" file with dozens of dependents, the resulting cascade of breakages often exceeds the agent's context window or reasoning capacity. 
+
+The **Change Amplification** analyzer computes graph metrics (fan-in, fan-out, and centrality) to identify these high-risk areas before they cause an "edit explosion."
+
+## 🏛️ Architecture
+
+```
+                    🎯 USER
+                      │
+                      ▼
+         🎛️  @aiready/cli (orchestrator)
+          │     │     │     │     │     │     │     │     │
+          ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼
+        [PAT] [CTX] [CON] [AMP] [DEP] [DOC] [SIG] [AGT] [TST]
+          │     │     │     │     │     │     │     │     │
+          └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
+                               │
+                               ▼
+                      🏢 @aiready/core
+
+Legend:
+  PAT = pattern-detect        CTX = context-analyzer
+  CON = consistency           AMP = change-amplification ★
+  DEP = deps-health           DOC = doc-drift
+  SIG = ai-signal-clarity     AGT = agent-grounding
+  TST = testability           ★   = YOU ARE HERE
+```
+
+## Features
+
+- **Fan-Out Analysis**: Measures how many dependencies a file has (impact of external changes on this file).
+- **Fan-In Analysis**: Measures how many files depend on this one (impact of changes in this file on the system).
+- **Amplification Factor**: A weighted metric predicting the "blast radius" of a single line change.
+- **Hotspot Detection**: Automatically flags files that should be refactored to reduce system-wide fragility.
+
+## Installation
+
+```bash
+pnpm add @aiready/change-amplification
+```
+
+## Usage
+
+This tool is designed to be run through the unified AIReady CLI.
+
+```bash
+# Scan for change amplification hotspots
+aiready scan . --tools change-amplification
+
+# Get specific results for a directory
+aiready change-amplification ./src
+```
+
+## License
+
+MIT

package/dist/chunk-DS7GBUP2.mjs

@@ -0,0 +1,100 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/analyzer.ts
+import * as fs from "fs";
+import * as path from "path";
+import { globSync } from "glob";
+import { calculateChangeAmplification } from "@aiready/core";
+import { parseDependencies } from "@aiready/core";
+function collectFiles(dir, options) {
+  const includePatterns = options.include && options.include.length > 0 ? options.include : ["**/*.{ts,tsx,js,jsx,py,go}"];
+  const excludePatterns = options.exclude && options.exclude.length > 0 ? options.exclude : ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+  let matchedFiles = [];
+  for (const pattern of includePatterns) {
+    const files = globSync(pattern, { cwd: dir, ignore: excludePatterns, absolute: true });
+    matchedFiles = matchedFiles.concat(files);
+  }
+  return [...new Set(matchedFiles)];
+}
+async function analyzeChangeAmplification(options) {
+  const rootDir = path.resolve(options.rootDir || ".");
+  const files = collectFiles(rootDir, options);
+  const dependencyGraph = /* @__PURE__ */ new Map();
+  const reverseGraph = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    dependencyGraph.set(file, []);
+    reverseGraph.set(file, []);
+  }
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, "utf8");
+      const dependencies = parseDependencies(content);
+      for (const dep of dependencies) {
+        const depDir = path.dirname(file);
+        const resolvedPath = files.find((f) => {
+          if (dep.startsWith(".")) {
+            return f.startsWith(path.resolve(depDir, dep));
+          } else {
+            return f.includes(dep);
+          }
+        });
+        if (resolvedPath) {
+          dependencyGraph.get(file)?.push(resolvedPath);
+          reverseGraph.get(resolvedPath)?.push(file);
+        }
+      }
+    } catch (err) {
+    }
+  }
+  const fileMetrics = files.map((file) => {
+    const fanOut = dependencyGraph.get(file)?.length || 0;
+    const fanIn = reverseGraph.get(file)?.length || 0;
+    return { file, fanOut, fanIn };
+  });
+  const riskResult = calculateChangeAmplification({ files: fileMetrics });
+  const results = [];
+  for (const hotspot of riskResult.hotspots) {
+    const issues = [];
+    if (hotspot.amplificationFactor > 20) {
+      issues.push({
+        type: "change-amplification",
+        severity: hotspot.amplificationFactor > 40 ? "critical" : "major",
+        message: `High change amplification detected (Factor: ${hotspot.amplificationFactor}). Changes here cascade heavily.`,
+        location: { file: hotspot.file, line: 1 },
+        suggestion: `Reduce coupling. Fan-out is ${hotspot.fanOut}, Fan-in is ${hotspot.fanIn}.`
+      });
+    }
+    if (hotspot.amplificationFactor > 5) {
+      results.push({
+        fileName: hotspot.file,
+        issues,
+        metrics: {
+          aiSignalClarityScore: 100 - hotspot.amplificationFactor
+          // Just a rough score
+        }
+      });
+    }
+  }
+  return {
+    summary: {
+      totalFiles: files.length,
+      totalIssues: results.reduce((sum, r) => sum + r.issues.length, 0),
+      criticalIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "critical").length, 0),
+      majorIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "major").length, 0),
+      score: riskResult.score,
+      rating: riskResult.rating,
+      recommendations: riskResult.recommendations
+    },
+    results
+  };
+}
+
+export {
+  __require,
+  analyzeChangeAmplification
+};

package/dist/chunk-VW57ZQRN.mjs

@@ -0,0 +1,103 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/analyzer.ts
+import * as fs from "fs";
+import * as path from "path";
+import { globSync } from "glob";
+import { calculateChangeAmplification } from "@aiready/core";
+import { getParser } from "@aiready/core";
+function collectFiles(dir, options) {
+  const includePatterns = options.include && options.include.length > 0 ? options.include : ["**/*.{ts,tsx,js,jsx,py,go}"];
+  const excludePatterns = options.exclude && options.exclude.length > 0 ? options.exclude : ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+  let matchedFiles = [];
+  for (const pattern of includePatterns) {
+    const files = globSync(pattern, { cwd: dir, ignore: excludePatterns, absolute: true });
+    matchedFiles = matchedFiles.concat(files);
+  }
+  return [...new Set(matchedFiles)];
+}
+async function analyzeChangeAmplification(options) {
+  const rootDir = path.resolve(options.rootDir || ".");
+  const files = collectFiles(rootDir, options);
+  const dependencyGraph = /* @__PURE__ */ new Map();
+  const reverseGraph = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    dependencyGraph.set(file, []);
+    reverseGraph.set(file, []);
+  }
+  for (const file of files) {
+    try {
+      const parser = getParser(file);
+      if (!parser) continue;
+      const content = fs.readFileSync(file, "utf8");
+      const parseResult = parser.parse(content, file);
+      const dependencies = parseResult.imports.map((i) => i.source);
+      for (const dep of dependencies) {
+        const depDir = path.dirname(file);
+        const resolvedPath = files.find((f) => {
+          if (dep.startsWith(".")) {
+            return f.startsWith(path.resolve(depDir, dep));
+          } else {
+            return f.includes(dep);
+          }
+        });
+        if (resolvedPath) {
+          dependencyGraph.get(file)?.push(resolvedPath);
+          reverseGraph.get(resolvedPath)?.push(file);
+        }
+      }
+    } catch (err) {
+    }
+  }
+  const fileMetrics = files.map((file) => {
+    const fanOut = dependencyGraph.get(file)?.length || 0;
+    const fanIn = reverseGraph.get(file)?.length || 0;
+    return { file, fanOut, fanIn };
+  });
+  const riskResult = calculateChangeAmplification({ files: fileMetrics });
+  const results = [];
+  for (const hotspot of riskResult.hotspots) {
+    const issues = [];
+    if (hotspot.amplificationFactor > 20) {
+      issues.push({
+        type: "change-amplification",
+        severity: hotspot.amplificationFactor > 40 ? "critical" : "major",
+        message: `High change amplification detected (Factor: ${hotspot.amplificationFactor}). Changes here cascade heavily.`,
+        location: { file: hotspot.file, line: 1 },
+        suggestion: `Reduce coupling. Fan-out is ${hotspot.fanOut}, Fan-in is ${hotspot.fanIn}.`
+      });
+    }
+    if (hotspot.amplificationFactor > 5) {
+      results.push({
+        fileName: hotspot.file,
+        issues,
+        metrics: {
+          aiSignalClarityScore: 100 - hotspot.amplificationFactor
+          // Just a rough score
+        }
+      });
+    }
+  }
+  return {
+    summary: {
+      totalFiles: files.length,
+      totalIssues: results.reduce((sum, r) => sum + r.issues.length, 0),
+      criticalIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "critical").length, 0),
+      majorIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "major").length, 0),
+      score: riskResult.score,
+      rating: riskResult.rating,
+      recommendations: riskResult.recommendations
+    },
+    results
+  };
+}
+
+export {
+  __require,
+  analyzeChangeAmplification
+};

package/dist/cli.d.mts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare const changeAmplificationAction: (directory: string, options: any) => Promise<void>;
+
+export { changeAmplificationAction };

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare const changeAmplificationAction: (directory: string, options: any) => Promise<void>;
+
+export { changeAmplificationAction };

package/dist/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  changeAmplificationAction: () => changeAmplificationAction
+});
+module.exports = __toCommonJS(cli_exports);
+var import_commander = require("commander");
+var import_chalk = __toESM(require("chalk"));
+var path2 = __toESM(require("path"));
+var fs2 = __toESM(require("fs"));
+
+// src/analyzer.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_glob = require("glob");
+var import_core = require("@aiready/core");
+var import_core2 = require("@aiready/core");
+function collectFiles(dir, options) {
+  const includePatterns = options.include && options.include.length > 0 ? options.include : ["**/*.{ts,tsx,js,jsx,py,go}"];
+  const excludePatterns = options.exclude && options.exclude.length > 0 ? options.exclude : ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+  let matchedFiles = [];
+  for (const pattern of includePatterns) {
+    const files = (0, import_glob.globSync)(pattern, { cwd: dir, ignore: excludePatterns, absolute: true });
+    matchedFiles = matchedFiles.concat(files);
+  }
+  return [...new Set(matchedFiles)];
+}
+async function analyzeChangeAmplification(options) {
+  const rootDir = path.resolve(options.rootDir || ".");
+  const files = collectFiles(rootDir, options);
+  const dependencyGraph = /* @__PURE__ */ new Map();
+  const reverseGraph = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    dependencyGraph.set(file, []);
+    reverseGraph.set(file, []);
+  }
+  for (const file of files) {
+    try {
+      const parser = (0, import_core2.getParser)(file);
+      if (!parser) continue;
+      const content = fs.readFileSync(file, "utf8");
+      const parseResult = parser.parse(content, file);
+      const dependencies = parseResult.imports.map((i) => i.source);
+      for (const dep of dependencies) {
+        const depDir = path.dirname(file);
+        const resolvedPath = files.find((f) => {
+          if (dep.startsWith(".")) {
+            return f.startsWith(path.resolve(depDir, dep));
+          } else {
+            return f.includes(dep);
+          }
+        });
+        if (resolvedPath) {
+          dependencyGraph.get(file)?.push(resolvedPath);
+          reverseGraph.get(resolvedPath)?.push(file);
+        }
+      }
+    } catch (err) {
+    }
+  }
+  const fileMetrics = files.map((file) => {
+    const fanOut = dependencyGraph.get(file)?.length || 0;
+    const fanIn = reverseGraph.get(file)?.length || 0;
+    return { file, fanOut, fanIn };
+  });
+  const riskResult = (0, import_core.calculateChangeAmplification)({ files: fileMetrics });
+  const results = [];
+  for (const hotspot of riskResult.hotspots) {
+    const issues = [];
+    if (hotspot.amplificationFactor > 20) {
+      issues.push({
+        type: "change-amplification",
+        severity: hotspot.amplificationFactor > 40 ? "critical" : "major",
+        message: `High change amplification detected (Factor: ${hotspot.amplificationFactor}). Changes here cascade heavily.`,
+        location: { file: hotspot.file, line: 1 },
+        suggestion: `Reduce coupling. Fan-out is ${hotspot.fanOut}, Fan-in is ${hotspot.fanIn}.`
+      });
+    }
+    if (hotspot.amplificationFactor > 5) {
+      results.push({
+        fileName: hotspot.file,
+        issues,
+        metrics: {
+          aiSignalClarityScore: 100 - hotspot.amplificationFactor
+          // Just a rough score
+        }
+      });
+    }
+  }
+  return {
+    summary: {
+      totalFiles: files.length,
+      totalIssues: results.reduce((sum, r) => sum + r.issues.length, 0),
+      criticalIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "critical").length, 0),
+      majorIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "major").length, 0),
+      score: riskResult.score,
+      rating: riskResult.rating,
+      recommendations: riskResult.recommendations
+    },
+    results
+  };
+}
+
+// src/cli.ts
+var changeAmplificationAction = async (directory, options) => {
+  try {
+    const resolvedDir = path2.resolve(process.cwd(), directory);
+    const finalOptions = {
+      rootDir: resolvedDir,
+      include: options.include ? options.include.split(",") : void 0,
+      exclude: options.exclude ? options.exclude.split(",") : void 0
+    };
+    const report = await analyzeChangeAmplification(finalOptions);
+    if (options.output === "json") {
+      const outputPath = options.outputFile || `change-amplification-report-${Date.now()}.json`;
+      fs2.writeFileSync(outputPath, JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(import_chalk.default.bold("\n\u{1F310} Change Amplification Analysis\n"));
+    console.log(`Rating: ${import_chalk.default.bold(report.summary.rating)}`);
+    console.log(`Score: ${Math.round(report.summary.score)}/100`);
+    console.log(`Critical Issues: ${report.summary.criticalIssues}`);
+    console.log(`Major Issues: ${report.summary.majorIssues}`);
+    if (report.summary.recommendations.length > 0) {
+      console.log(import_chalk.default.bold("\nRecommendations:"));
+      for (const rec of report.summary.recommendations) {
+        console.log(import_chalk.default.cyan(`\u2022 ${rec}`));
+      }
+    }
+    if (report.results.length > 0) {
+      console.log(import_chalk.default.bold("\nHotspots:"));
+      for (const result of report.results) {
+        console.log(`
+\u{1F4C4} ${import_chalk.default.cyan(result.fileName)}`);
+        for (const issue of result.issues) {
+          const color = issue.severity === "critical" ? import_chalk.default.red : import_chalk.default.yellow;
+          console.log(`  ${color("\u25A0")} ${issue.message}`);
+          console.log(`    ${import_chalk.default.dim("Suggestion: " + issue.suggestion)}`);
+        }
+      }
+    } else {
+      console.log(import_chalk.default.green("\n\u2728 No change amplification issues found. Architecture is well contained."));
+    }
+  } catch (error) {
+    console.error(import_chalk.default.red("Error during change amplification analysis:"), error);
+    process.exit(1);
+  }
+};
+var program = new import_commander.Command();
+program.name("aiready-change-amplification").description("Analyze graph metrics for change amplification").argument("[directory]", "Directory to analyze", ".").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").action(changeAmplificationAction);
+if (require.main === module) {
+  program.parse();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  changeAmplificationAction
+});

package/dist/cli.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import {
+  __require,
+  analyzeChangeAmplification
+} from "./chunk-VW57ZQRN.mjs";
+
+// src/cli.ts
+import { Command } from "commander";
+import chalk from "chalk";
+import * as path from "path";
+import * as fs from "fs";
+var changeAmplificationAction = async (directory, options) => {
+  try {
+    const resolvedDir = path.resolve(process.cwd(), directory);
+    const finalOptions = {
+      rootDir: resolvedDir,
+      include: options.include ? options.include.split(",") : void 0,
+      exclude: options.exclude ? options.exclude.split(",") : void 0
+    };
+    const report = await analyzeChangeAmplification(finalOptions);
+    if (options.output === "json") {
+      const outputPath = options.outputFile || `change-amplification-report-${Date.now()}.json`;
+      fs.writeFileSync(outputPath, JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(chalk.bold("\n\u{1F310} Change Amplification Analysis\n"));
+    console.log(`Rating: ${chalk.bold(report.summary.rating)}`);
+    console.log(`Score: ${Math.round(report.summary.score)}/100`);
+    console.log(`Critical Issues: ${report.summary.criticalIssues}`);
+    console.log(`Major Issues: ${report.summary.majorIssues}`);
+    if (report.summary.recommendations.length > 0) {
+      console.log(chalk.bold("\nRecommendations:"));
+      for (const rec of report.summary.recommendations) {
+        console.log(chalk.cyan(`\u2022 ${rec}`));
+      }
+    }
+    if (report.results.length > 0) {
+      console.log(chalk.bold("\nHotspots:"));
+      for (const result of report.results) {
+        console.log(`
+\u{1F4C4} ${chalk.cyan(result.fileName)}`);
+        for (const issue of result.issues) {
+          const color = issue.severity === "critical" ? chalk.red : chalk.yellow;
+          console.log(`  ${color("\u25A0")} ${issue.message}`);
+          console.log(`    ${chalk.dim("Suggestion: " + issue.suggestion)}`);
+        }
+      }
+    } else {
+      console.log(chalk.green("\n\u2728 No change amplification issues found. Architecture is well contained."));
+    }
+  } catch (error) {
+    console.error(chalk.red("Error during change amplification analysis:"), error);
+    process.exit(1);
+  }
+};
+var program = new Command();
+program.name("aiready-change-amplification").description("Analyze graph metrics for change amplification").argument("[directory]", "Directory to analyze", ".").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").action(changeAmplificationAction);
+if (__require.main === module) {
+  program.parse();
+}
+export {
+  changeAmplificationAction
+};

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+import { Issue, ScanOptions } from '@aiready/core';
+
+interface ChangeAmplificationOptions extends ScanOptions {
+}
+interface ChangeAmplificationIssue extends Issue {
+    type: 'change-amplification';
+}
+interface FileChangeAmplificationResult {
+    fileName: string;
+    issues: ChangeAmplificationIssue[];
+    metrics: {
+        aiSignalClarityScore?: number;
+    };
+}
+interface ChangeAmplificationReport {
+    summary: {
+        totalFiles: number;
+        totalIssues: number;
+        criticalIssues: number;
+        majorIssues: number;
+        score: number;
+        rating: 'isolated' | 'contained' | 'amplified' | 'explosive';
+        recommendations: string[];
+    };
+    results: FileChangeAmplificationResult[];
+}
+
+declare function analyzeChangeAmplification(options: ChangeAmplificationOptions): Promise<ChangeAmplificationReport>;
+
+export { type ChangeAmplificationIssue, type ChangeAmplificationOptions, type ChangeAmplificationReport, type FileChangeAmplificationResult, analyzeChangeAmplification };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { Issue, ScanOptions } from '@aiready/core';
+
+interface ChangeAmplificationOptions extends ScanOptions {
+}
+interface ChangeAmplificationIssue extends Issue {
+    type: 'change-amplification';
+}
+interface FileChangeAmplificationResult {
+    fileName: string;
+    issues: ChangeAmplificationIssue[];
+    metrics: {
+        aiSignalClarityScore?: number;
+    };
+}
+interface ChangeAmplificationReport {
+    summary: {
+        totalFiles: number;
+        totalIssues: number;
+        criticalIssues: number;
+        majorIssues: number;
+        score: number;
+        rating: 'isolated' | 'contained' | 'amplified' | 'explosive';
+        recommendations: string[];
+    };
+    results: FileChangeAmplificationResult[];
+}
+
+declare function analyzeChangeAmplification(options: ChangeAmplificationOptions): Promise<ChangeAmplificationReport>;
+
+export { type ChangeAmplificationIssue, type ChangeAmplificationOptions, type ChangeAmplificationReport, type FileChangeAmplificationResult, analyzeChangeAmplification };

package/dist/index.js

@@ -0,0 +1,131 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  analyzeChangeAmplification: () => analyzeChangeAmplification
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/analyzer.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_glob = require("glob");
+var import_core = require("@aiready/core");
+var import_core2 = require("@aiready/core");
+function collectFiles(dir, options) {
+  const includePatterns = options.include && options.include.length > 0 ? options.include : ["**/*.{ts,tsx,js,jsx,py,go}"];
+  const excludePatterns = options.exclude && options.exclude.length > 0 ? options.exclude : ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+  let matchedFiles = [];
+  for (const pattern of includePatterns) {
+    const files = (0, import_glob.globSync)(pattern, { cwd: dir, ignore: excludePatterns, absolute: true });
+    matchedFiles = matchedFiles.concat(files);
+  }
+  return [...new Set(matchedFiles)];
+}
+async function analyzeChangeAmplification(options) {
+  const rootDir = path.resolve(options.rootDir || ".");
+  const files = collectFiles(rootDir, options);
+  const dependencyGraph = /* @__PURE__ */ new Map();
+  const reverseGraph = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    dependencyGraph.set(file, []);
+    reverseGraph.set(file, []);
+  }
+  for (const file of files) {
+    try {
+      const parser = (0, import_core2.getParser)(file);
+      if (!parser) continue;
+      const content = fs.readFileSync(file, "utf8");
+      const parseResult = parser.parse(content, file);
+      const dependencies = parseResult.imports.map((i) => i.source);
+      for (const dep of dependencies) {
+        const depDir = path.dirname(file);
+        const resolvedPath = files.find((f) => {
+          if (dep.startsWith(".")) {
+            return f.startsWith(path.resolve(depDir, dep));
+          } else {
+            return f.includes(dep);
+          }
+        });
+        if (resolvedPath) {
+          dependencyGraph.get(file)?.push(resolvedPath);
+          reverseGraph.get(resolvedPath)?.push(file);
+        }
+      }
+    } catch (err) {
+    }
+  }
+  const fileMetrics = files.map((file) => {
+    const fanOut = dependencyGraph.get(file)?.length || 0;
+    const fanIn = reverseGraph.get(file)?.length || 0;
+    return { file, fanOut, fanIn };
+  });
+  const riskResult = (0, import_core.calculateChangeAmplification)({ files: fileMetrics });
+  const results = [];
+  for (const hotspot of riskResult.hotspots) {
+    const issues = [];
+    if (hotspot.amplificationFactor > 20) {
+      issues.push({
+        type: "change-amplification",
+        severity: hotspot.amplificationFactor > 40 ? "critical" : "major",
+        message: `High change amplification detected (Factor: ${hotspot.amplificationFactor}). Changes here cascade heavily.`,
+        location: { file: hotspot.file, line: 1 },
+        suggestion: `Reduce coupling. Fan-out is ${hotspot.fanOut}, Fan-in is ${hotspot.fanIn}.`
+      });
+    }
+    if (hotspot.amplificationFactor > 5) {
+      results.push({
+        fileName: hotspot.file,
+        issues,
+        metrics: {
+          aiSignalClarityScore: 100 - hotspot.amplificationFactor
+          // Just a rough score
+        }
+      });
+    }
+  }
+  return {
+    summary: {
+      totalFiles: files.length,
+      totalIssues: results.reduce((sum, r) => sum + r.issues.length, 0),
+      criticalIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "critical").length, 0),
+      majorIssues: results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "major").length, 0),
+      score: riskResult.score,
+      rating: riskResult.rating,
+      recommendations: riskResult.recommendations
+    },
+    results
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analyzeChangeAmplification
+});

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import {
+  analyzeChangeAmplification
+} from "./chunk-VW57ZQRN.mjs";
+export {
+  analyzeChangeAmplification
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aiready/change-amplification",
+  "version": "0.1.4",
+  "description": "AI-Readiness: Change Amplification Detection",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@typescript-eslint/typescript-estree": "^7.8.0",
+    "commander": "^12.0.0",
+    "glob": "^10.3.12",
+    "chalk": "^5.3.0",
+    "@aiready/core": "0.9.31"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@typescript-eslint/types": "^7.8.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.mjs",
+      "require": "./dist/cli.js",
+      "types": "./dist/cli.d.ts"
+    },
+    "./dist/cli.js": {
+      "require": "./dist/cli.js",
+      "import": "./dist/cli.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts"
+  }
+}

package/src/__tests__/dummy.test.ts

@@ -0,0 +1,7 @@
+import { describe, it, expect } from 'vitest';
+
+describe('Change Amplification Analyzer', () => {
+  it('should initialize successfully', () => {
+    expect(true).toBe(true);
+  });
+});

package/src/analyzer.ts

@@ -0,0 +1,116 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { globSync } from 'glob';
+import { calculateChangeAmplification } from '@aiready/core';
+import type { ChangeAmplificationOptions, ChangeAmplificationReport, FileChangeAmplificationResult, ChangeAmplificationIssue } from './types';
+import { getParser } from '@aiready/core';
+
+function collectFiles(dir: string, options: ChangeAmplificationOptions): string[] {
+  const includePatterns = options.include && options.include.length > 0 ? options.include : ['**/*.{ts,tsx,js,jsx,py,go}'];
+  const excludePatterns = options.exclude && options.exclude.length > 0 ? options.exclude : ['**/node_modules/**', '**/dist/**', '**/.git/**'];
+
+  let matchedFiles: string[] = [];
+  for (const pattern of includePatterns) {
+    const files = globSync(pattern, { cwd: dir, ignore: excludePatterns, absolute: true });
+    matchedFiles = matchedFiles.concat(files);
+  }
+  return [...new Set(matchedFiles)];
+}
+
+export async function analyzeChangeAmplification(
+  options: ChangeAmplificationOptions,
+): Promise<ChangeAmplificationReport> {
+  const rootDir = path.resolve(options.rootDir || '.');
+  const files = collectFiles(rootDir, options);
+
+  // Compute graph metrics: fanIn and fanOut
+  const dependencyGraph = new Map<string, string[]>(); // key: file, value: imported files
+  const reverseGraph = new Map<string, string[]>();    // key: file, value: files that import it
+
+  // Initialize graph
+  for (const file of files) {
+    dependencyGraph.set(file, []);
+    reverseGraph.set(file, []);
+  }
+
+  // Parse files to build dependency graph
+  for (const file of files) {
+    try {
+      const parser = getParser(file);
+      if (!parser) continue;
+
+      const content = fs.readFileSync(file, 'utf8');
+      const parseResult = parser.parse(content, file);
+      const dependencies = parseResult.imports.map(i => i.source);
+
+      for (const dep of dependencies) {
+        // Resolve simple relative or absolute imports for the graph
+        // This is a simplified resolution for demonstration purposes
+        const depDir = path.dirname(file);
+
+        // Find if this dependency resolves to one of our mapped files
+        const resolvedPath = files.find(f => {
+          if (dep.startsWith('.')) {
+            return f.startsWith(path.resolve(depDir, dep));
+          } else {
+            return f.includes(dep);
+          }
+        });
+
+        if (resolvedPath) {
+          dependencyGraph.get(file)?.push(resolvedPath);
+          reverseGraph.get(resolvedPath)?.push(file);
+        }
+      }
+    } catch (err) {
+      // Ignore parse errors silently
+    }
+  }
+
+  const fileMetrics = files.map(file => {
+    const fanOut = dependencyGraph.get(file)?.length || 0;
+    const fanIn = reverseGraph.get(file)?.length || 0;
+    return { file, fanOut, fanIn };
+  });
+
+  const riskResult = calculateChangeAmplification({ files: fileMetrics });
+
+  const results: FileChangeAmplificationResult[] = [];
+
+  for (const hotspot of riskResult.hotspots) {
+    const issues: ChangeAmplificationIssue[] = [];
+    if (hotspot.amplificationFactor > 20) {
+      issues.push({
+        type: 'change-amplification',
+        severity: hotspot.amplificationFactor > 40 ? 'critical' : 'major',
+        message: `High change amplification detected (Factor: ${hotspot.amplificationFactor}). Changes here cascade heavily.`,
+        location: { file: hotspot.file, line: 1 },
+        suggestion: `Reduce coupling. Fan-out is ${hotspot.fanOut}, Fan-in is ${hotspot.fanIn}.`
+      });
+    }
+
+    // We only push results for files that have either high fan-in or fan-out
+    if (hotspot.amplificationFactor > 5) {
+      results.push({
+        fileName: hotspot.file,
+        issues,
+        metrics: {
+          aiSignalClarityScore: 100 - hotspot.amplificationFactor, // Just a rough score
+        }
+      });
+    }
+  }
+
+  return {
+    summary: {
+      totalFiles: files.length,
+      totalIssues: results.reduce((sum, r) => sum + r.issues.length, 0),
+      criticalIssues: results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'critical').length, 0),
+      majorIssues: results.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'major').length, 0),
+      score: riskResult.score,
+      rating: riskResult.rating,
+      recommendations: riskResult.recommendations,
+    },
+    results,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import * as path from 'path';
+import * as fs from 'fs';
+import { analyzeChangeAmplification } from './analyzer';
+import type { ChangeAmplificationOptions } from './types';
+
+export const changeAmplificationAction = async (directory: string, options: any) => {
+  try {
+    const resolvedDir = path.resolve(process.cwd(), directory);
+    const finalOptions: ChangeAmplificationOptions = {
+      rootDir: resolvedDir,
+      include: options.include ? options.include.split(',') : undefined,
+      exclude: options.exclude ? options.exclude.split(',') : undefined,
+    };
+
+    const report = await analyzeChangeAmplification(finalOptions);
+
+    if (options.output === 'json') {
+      const outputPath = options.outputFile || `change-amplification-report-${Date.now()}.json`;
+      fs.writeFileSync(outputPath, JSON.stringify(report, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold('\n🌐 Change Amplification Analysis\n'));
+    console.log(`Rating: ${chalk.bold(report.summary.rating)}`);
+    console.log(`Score: ${Math.round(report.summary.score)}/100`);
+    console.log(`Critical Issues: ${report.summary.criticalIssues}`);
+    console.log(`Major Issues: ${report.summary.majorIssues}`);
+
+    if (report.summary.recommendations.length > 0) {
+      console.log(chalk.bold('\nRecommendations:'));
+      for (const rec of report.summary.recommendations) {
+        console.log(chalk.cyan(`• ${rec}`));
+      }
+    }
+
+    if (report.results.length > 0) {
+      console.log(chalk.bold('\nHotspots:'));
+      for (const result of report.results) {
+        console.log(`\n📄 ${chalk.cyan(result.fileName)}`);
+        for (const issue of result.issues) {
+          const color = issue.severity === 'critical' ? chalk.red : chalk.yellow;
+          console.log(`  ${color('■')} ${issue.message}`);
+          console.log(`    ${chalk.dim('Suggestion: ' + issue.suggestion)}`);
+        }
+      }
+    } else {
+      console.log(chalk.green('\n✨ No change amplification issues found. Architecture is well contained.'));
+    }
+  } catch (error) {
+    console.error(chalk.red('Error during change amplification analysis:'), error);
+    process.exit(1);
+  }
+};
+
+const program = new Command();
+program
+  .name('aiready-change-amplification')
+  .description('Analyze graph metrics for change amplification')
+  .argument('[directory]', 'Directory to analyze', '.')
+  .option('--include <patterns>', 'File patterns to include (comma-separated)')
+  .option('--exclude <patterns>', 'File patterns to exclude (comma-separated)')
+  .option('-o, --output <format>', 'Output format: console, json', 'console')
+  .option('--output-file <path>', 'Output file path (for json)')
+  .action(changeAmplificationAction);
+
+if (require.main === module) {
+  program.parse();
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { analyzeChangeAmplification } from './analyzer';
+export type {
+  ChangeAmplificationOptions,
+  ChangeAmplificationReport,
+  ChangeAmplificationIssue,
+  FileChangeAmplificationResult,
+} from './types';

package/src/types.ts

@@ -0,0 +1,30 @@
+import type { ScanOptions, Issue } from '@aiready/core';
+
+export interface ChangeAmplificationOptions extends ScanOptions {
+  // Add any specific configurations needed for change amplification here
+}
+
+export interface ChangeAmplificationIssue extends Issue {
+  type: 'change-amplification';
+}
+
+export interface FileChangeAmplificationResult {
+  fileName: string;
+  issues: ChangeAmplificationIssue[];
+  metrics: {
+    aiSignalClarityScore?: number;
+  };
+}
+
+export interface ChangeAmplificationReport {
+  summary: {
+    totalFiles: number;
+    totalIssues: number;
+    criticalIssues: number;
+    majorIssues: number;
+    score: number;
+    rating: 'isolated' | 'contained' | 'amplified' | 'explosive';
+    recommendations: string[];
+  };
+  results: FileChangeAmplificationResult[];
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}