@aiready/doc-drift 0.1.1

package/.turbo/turbo-build.log

@@ -0,0 +1,66 @@
+
+
+> @aiready/doc-drift@0.1.1 build /Users/pengcao/projects/aiready/packages/doc-drift
+> 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
+
+[9:41:37 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",
+         ╵       ~~~~~~~~~
+
+
+
+
+[9:41:37 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",
+         ╵       ~~~~~~~~~
+
+
+
+CJS dist/cli.js   8.49 KB
+CJS dist/index.js 6.50 KB
+CJS ⚡️ Build success in 180ms
+ESM dist/chunk-TSLAGWBV.mjs 5.71 KB
+ESM dist/cli.mjs            1.36 KB
+ESM dist/index.mjs          88.00 B
+ESM ⚡️ Build success in 200ms
+DTS Build start
+DTS ⚡️ Build success in 3656ms
+DTS dist/cli.d.ts    108.00 B
+DTS dist/index.d.ts  950.00 B
+DTS dist/cli.d.mts   108.00 B
+DTS dist/index.d.mts 950.00 B

package/.turbo/turbo-test.log

@@ -0,0 +1,16 @@
+
+
+> @aiready/doc-drift@0.1.1 test /Users/pengcao/projects/aiready/packages/doc-drift
+> vitest run
+
+
+ RUN  v1.6.1 /Users/pengcao/projects/aiready/packages/doc-drift
+
+ ✓ src/__tests__/analyzer.test.ts  (1 test) 19ms
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+   Start at  21:42:03
+   Duration  2.17s (transform 267ms, setup 0ms, collect 1.29s, tests 19ms, environment 0ms, prepare 239ms)
+
+[?25h

package/README.md

@@ -0,0 +1,44 @@
+# @aiready/doc-drift
+
+> AIReady Spoke: Tracks documentation freshness versus code churn to pinpoint outdated comments that confuse AI models.
+
+[![npm version](https://img.shields.io/npm/v/@aiready/doc-drift.svg)](https://npmjs.com/package/@aiready/doc-drift)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+AI models rely heavily on inline documentation and function signatures. When code changes but comments don't, AI models often hallucinate based on the stale documentation. The **Documentation Drift** analyzer combines AST parsing with git log traversal to identify instances where comments are likely lagging behind actual implementation logic. 
+
+## Features
+
+- **Drift Detection**: Detects documentation older than the code it describes based on git history timestamps.
+- **Signature Mismatches**: Finds missing documented `@param` tags when new arguments are added to functions.
+- **Complexity Guardrails**: Identifies long or complex functions that completely lack documentation.
+
+## Installation
+
+```bash
+npm install -g @aiready/cli @aiready/doc-drift
+```
+
+## Usage
+
+This tool is designed to be run through the unified AIReady CLI.
+
+```bash
+# Scan a codebase for documentation drift
+aiready scan . --tools doc-drift
+
+# Output detailed JSON report
+aiready scan . --tools doc-drift --output json
+```
+
+## How It Works
+
+1. Parses your codebase into an Abstract Syntax Tree (AST).
+2. Uses `git log` to find the last modified timestamp for the code body limits vs the associated comment block.
+3. Calculates a freshness ratio. If the comment trails the code body by several months (`--stale-months`), it flags the function as having a high risk of documentary drift.
+
+## License
+
+MIT

package/dist/chunk-TSLAGWBV.mjs

@@ -0,0 +1,165 @@
+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 { calculateDocDrift } from "@aiready/core";
+import { readdirSync, statSync, readFileSync } from "fs";
+import { join, extname } from "path";
+import { parse } from "@typescript-eslint/typescript-estree";
+import { execSync } from "child_process";
+var SRC_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+var DEFAULT_EXCLUDES = ["node_modules", "dist", ".git", "coverage", ".turbo", "build"];
+function collectFiles(dir, options, depth = 0) {
+  if (depth > 20) return [];
+  const excludes = [...DEFAULT_EXCLUDES, ...options.exclude ?? []];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (excludes.some((ex) => entry === ex || entry.includes(ex))) continue;
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      files.push(...collectFiles(full, options, depth + 1));
+    } else if (stat.isFile() && SRC_EXTENSIONS.has(extname(full))) {
+      if (!options.include || options.include.some((p) => full.includes(p))) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+function getLineRangeLastModified(file, startLine, endLine) {
+  try {
+    const output = execSync(`git log -1 --format=%ct -L ${startLine},${endLine}:"${file}"`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const match = output.trim().split("\n")[0];
+    if (match && !isNaN(parseInt(match, 10))) {
+      return parseInt(match, 10);
+    }
+  } catch {
+  }
+  return 0;
+}
+async function analyzeDocDrift(options) {
+  const rootDir = options.rootDir;
+  const files = collectFiles(rootDir, options);
+  const staleMonths = options.staleMonths ?? 6;
+  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexity = 0;
+  const issues = [];
+  const now = Math.floor(Date.now() / 1e3);
+  for (const file of files) {
+    let code;
+    try {
+      code = readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = parse(code, {
+        jsx: file.endsWith(".tsx") || file.endsWith(".jsx"),
+        loc: true,
+        comment: true
+      });
+    } catch {
+      continue;
+    }
+    const comments = ast.comments || [];
+    for (const node of ast.body) {
+      if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") {
+        const decl = node.declaration;
+        if (!decl) continue;
+        if (decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration" || decl.type === "VariableDeclaration") {
+          totalExports++;
+          const nodeLine = node.loc.start.line;
+          const jsdocs = comments.filter((c) => c.type === "Block" && c.value.startsWith("*") && c.loc.end.line === nodeLine - 1);
+          if (jsdocs.length === 0) {
+            uncommentedExports++;
+            if (decl.type === "FunctionDeclaration" && decl.body?.loc) {
+              const lines = decl.body.loc.end.line - decl.body.loc.start.line;
+              if (lines > 20) undocumentedComplexity++;
+            }
+          } else {
+            const jsdoc = jsdocs[0];
+            const jsdocText = jsdoc.value;
+            if (decl.type === "FunctionDeclaration") {
+              const params = decl.params.map((p) => p.name || p.left && p.left.name).filter(Boolean);
+              const paramTags = Array.from(jsdocText.matchAll(/@param\s+(?:\{[^}]+\}\s+)?([a-zA-Z0-9_]+)/g)).map((m) => m[1]);
+              const missingParams = params.filter((p) => !paramTags.includes(p));
+              if (missingParams.length > 0) {
+                outdatedComments++;
+                issues.push({
+                  type: "doc-drift",
+                  severity: "major",
+                  message: `JSDoc @param mismatch: function has parameters (${missingParams.join(", ")}) not documented in JSDoc.`,
+                  location: { file, line: nodeLine }
+                });
+                continue;
+              }
+            }
+            const commentModified = getLineRangeLastModified(file, jsdoc.loc.start.line, jsdoc.loc.end.line);
+            const bodyModified = getLineRangeLastModified(file, decl.loc.start.line, decl.loc.end.line);
+            if (commentModified > 0 && bodyModified > 0) {
+              if (now - commentModified > staleSeconds && bodyModified - commentModified > staleSeconds / 2) {
+                outdatedComments++;
+                issues.push({
+                  type: "doc-drift",
+                  severity: "minor",
+                  message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
+                  location: { file, line: jsdoc.loc.start.line }
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  const riskResult = calculateDocDrift({
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity
+  });
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity
+    },
+    recommendations: riskResult.recommendations
+  };
+}
+
+export {
+  __require,
+  analyzeDocDrift
+};

package/dist/cli.d.mts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+
+declare function createCommand(): Command;
+
+export { createCommand };

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+
+declare function createCommand(): Command;
+
+export { createCommand };

package/dist/cli.js

@@ -0,0 +1,223 @@
+"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, {
+  createCommand: () => createCommand
+});
+module.exports = __toCommonJS(cli_exports);
+var import_commander = require("commander");
+
+// src/analyzer.ts
+var import_core = require("@aiready/core");
+var import_fs = require("fs");
+var import_path = require("path");
+var import_typescript_estree = require("@typescript-eslint/typescript-estree");
+var import_child_process = require("child_process");
+var SRC_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+var DEFAULT_EXCLUDES = ["node_modules", "dist", ".git", "coverage", ".turbo", "build"];
+function collectFiles(dir, options, depth = 0) {
+  if (depth > 20) return [];
+  const excludes = [...DEFAULT_EXCLUDES, ...options.exclude ?? []];
+  let entries;
+  try {
+    entries = (0, import_fs.readdirSync)(dir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (excludes.some((ex) => entry === ex || entry.includes(ex))) continue;
+    const full = (0, import_path.join)(dir, entry);
+    let stat;
+    try {
+      stat = (0, import_fs.statSync)(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      files.push(...collectFiles(full, options, depth + 1));
+    } else if (stat.isFile() && SRC_EXTENSIONS.has((0, import_path.extname)(full))) {
+      if (!options.include || options.include.some((p) => full.includes(p))) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+function getLineRangeLastModified(file, startLine, endLine) {
+  try {
+    const output = (0, import_child_process.execSync)(`git log -1 --format=%ct -L ${startLine},${endLine}:"${file}"`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const match = output.trim().split("\n")[0];
+    if (match && !isNaN(parseInt(match, 10))) {
+      return parseInt(match, 10);
+    }
+  } catch {
+  }
+  return 0;
+}
+async function analyzeDocDrift(options) {
+  const rootDir = options.rootDir;
+  const files = collectFiles(rootDir, options);
+  const staleMonths = options.staleMonths ?? 6;
+  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexity = 0;
+  const issues = [];
+  const now = Math.floor(Date.now() / 1e3);
+  for (const file of files) {
+    let code;
+    try {
+      code = (0, import_fs.readFileSync)(file, "utf-8");
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = (0, import_typescript_estree.parse)(code, {
+        jsx: file.endsWith(".tsx") || file.endsWith(".jsx"),
+        loc: true,
+        comment: true
+      });
+    } catch {
+      continue;
+    }
+    const comments = ast.comments || [];
+    for (const node of ast.body) {
+      if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") {
+        const decl = node.declaration;
+        if (!decl) continue;
+        if (decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration" || decl.type === "VariableDeclaration") {
+          totalExports++;
+          const nodeLine = node.loc.start.line;
+          const jsdocs = comments.filter((c) => c.type === "Block" && c.value.startsWith("*") && c.loc.end.line === nodeLine - 1);
+          if (jsdocs.length === 0) {
+            uncommentedExports++;
+            if (decl.type === "FunctionDeclaration" && decl.body?.loc) {
+              const lines = decl.body.loc.end.line - decl.body.loc.start.line;
+              if (lines > 20) undocumentedComplexity++;
+            }
+          } else {
+            const jsdoc = jsdocs[0];
+            const jsdocText = jsdoc.value;
+            if (decl.type === "FunctionDeclaration") {
+              const params = decl.params.map((p) => p.name || p.left && p.left.name).filter(Boolean);
+              const paramTags = Array.from(jsdocText.matchAll(/@param\s+(?:\{[^}]+\}\s+)?([a-zA-Z0-9_]+)/g)).map((m) => m[1]);
+              const missingParams = params.filter((p) => !paramTags.includes(p));
+              if (missingParams.length > 0) {
+                outdatedComments++;
+                issues.push({
+                  type: "doc-drift",
+                  severity: "major",
+                  message: `JSDoc @param mismatch: function has parameters (${missingParams.join(", ")}) not documented in JSDoc.`,
+                  location: { file, line: nodeLine }
+                });
+                continue;
+              }
+            }
+            const commentModified = getLineRangeLastModified(file, jsdoc.loc.start.line, jsdoc.loc.end.line);
+            const bodyModified = getLineRangeLastModified(file, decl.loc.start.line, decl.loc.end.line);
+            if (commentModified > 0 && bodyModified > 0) {
+              if (now - commentModified > staleSeconds && bodyModified - commentModified > staleSeconds / 2) {
+                outdatedComments++;
+                issues.push({
+                  type: "doc-drift",
+                  severity: "minor",
+                  message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
+                  location: { file, line: jsdoc.loc.start.line }
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  const riskResult = (0, import_core.calculateDocDrift)({
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity
+  });
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity
+    },
+    recommendations: riskResult.recommendations
+  };
+}
+
+// src/cli.ts
+var import_picocolors = __toESM(require("picocolors"));
+function createCommand() {
+  const program = new import_commander.Command("doc-drift").description("Scan for documentation drift (outdated comments, mismatched signatures)").option("--include <patterns...>", "File patterns to include").option("--exclude <patterns...>", "File patterns to exclude").option("--stale-months <number>", "Months before a comment is considered potentially outdated", "6").action(async (options) => {
+    console.log(import_picocolors.default.cyan("Analyzing documentation drift..."));
+    const report = await analyzeDocDrift({
+      rootDir: process.cwd(),
+      include: options.include,
+      exclude: options.exclude,
+      staleMonths: parseInt(options.staleMonths, 10)
+    });
+    console.log(import_picocolors.default.bold("Doc Drift Analysis Results:"));
+    console.log(`Rating: ${report.summary.rating.toUpperCase()} (Score: ${report.summary.score})`);
+    if (report.issues.length > 0) {
+      console.log(import_picocolors.default.red(`
+Found ${report.issues.length} drift issues.`));
+    } else {
+      console.log(import_picocolors.default.green("\nNo documentation drift detected."));
+    }
+  });
+  return program;
+}
+if (require.main === module) {
+  createCommand().parseAsync(process.argv).catch((err) => {
+    console.error(import_picocolors.default.red(err.message));
+    process.exit(1);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCommand
+});

package/dist/cli.mjs

@@ -0,0 +1,37 @@
+import {
+  __require,
+  analyzeDocDrift
+} from "./chunk-TSLAGWBV.mjs";
+
+// src/cli.ts
+import { Command } from "commander";
+import pc from "picocolors";
+function createCommand() {
+  const program = new Command("doc-drift").description("Scan for documentation drift (outdated comments, mismatched signatures)").option("--include <patterns...>", "File patterns to include").option("--exclude <patterns...>", "File patterns to exclude").option("--stale-months <number>", "Months before a comment is considered potentially outdated", "6").action(async (options) => {
+    console.log(pc.cyan("Analyzing documentation drift..."));
+    const report = await analyzeDocDrift({
+      rootDir: process.cwd(),
+      include: options.include,
+      exclude: options.exclude,
+      staleMonths: parseInt(options.staleMonths, 10)
+    });
+    console.log(pc.bold("Doc Drift Analysis Results:"));
+    console.log(`Rating: ${report.summary.rating.toUpperCase()} (Score: ${report.summary.score})`);
+    if (report.issues.length > 0) {
+      console.log(pc.red(`
+Found ${report.issues.length} drift issues.`));
+    } else {
+      console.log(pc.green("\nNo documentation drift detected."));
+    }
+  });
+  return program;
+}
+if (__require.main === module) {
+  createCommand().parseAsync(process.argv).catch((err) => {
+    console.error(pc.red(err.message));
+    process.exit(1);
+  });
+}
+export {
+  createCommand
+};

package/dist/index.d.mts

@@ -0,0 +1,31 @@
+import { Issue, ScanOptions } from '@aiready/core';
+
+interface DocDriftOptions extends ScanOptions {
+    /** Maximum commit distance to check for drift */
+    maxCommits?: number;
+    /** Consider comments older than this many months as outdated */
+    staleMonths?: number;
+}
+interface DocDriftIssue extends Issue {
+    type: 'doc-drift';
+}
+interface DocDriftReport {
+    summary: {
+        filesAnalyzed: number;
+        functionsAnalyzed: number;
+        score: number;
+        rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    };
+    issues: DocDriftIssue[];
+    rawData: {
+        uncommentedExports: number;
+        totalExports: number;
+        outdatedComments: number;
+        undocumentedComplexity: number;
+    };
+    recommendations: string[];
+}
+
+declare function analyzeDocDrift(options: DocDriftOptions): Promise<DocDriftReport>;
+
+export { type DocDriftIssue, type DocDriftOptions, type DocDriftReport, analyzeDocDrift };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { Issue, ScanOptions } from '@aiready/core';
+
+interface DocDriftOptions extends ScanOptions {
+    /** Maximum commit distance to check for drift */
+    maxCommits?: number;
+    /** Consider comments older than this many months as outdated */
+    staleMonths?: number;
+}
+interface DocDriftIssue extends Issue {
+    type: 'doc-drift';
+}
+interface DocDriftReport {
+    summary: {
+        filesAnalyzed: number;
+        functionsAnalyzed: number;
+        score: number;
+        rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+    };
+    issues: DocDriftIssue[];
+    rawData: {
+        uncommentedExports: number;
+        totalExports: number;
+        outdatedComments: number;
+        undocumentedComplexity: number;
+    };
+    recommendations: string[];
+}
+
+declare function analyzeDocDrift(options: DocDriftOptions): Promise<DocDriftReport>;
+
+export { type DocDriftIssue, type DocDriftOptions, type DocDriftReport, analyzeDocDrift };

package/dist/index.js

@@ -0,0 +1,183 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  analyzeDocDrift: () => analyzeDocDrift
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/analyzer.ts
+var import_core = require("@aiready/core");
+var import_fs = require("fs");
+var import_path = require("path");
+var import_typescript_estree = require("@typescript-eslint/typescript-estree");
+var import_child_process = require("child_process");
+var SRC_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+var DEFAULT_EXCLUDES = ["node_modules", "dist", ".git", "coverage", ".turbo", "build"];
+function collectFiles(dir, options, depth = 0) {
+  if (depth > 20) return [];
+  const excludes = [...DEFAULT_EXCLUDES, ...options.exclude ?? []];
+  let entries;
+  try {
+    entries = (0, import_fs.readdirSync)(dir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (excludes.some((ex) => entry === ex || entry.includes(ex))) continue;
+    const full = (0, import_path.join)(dir, entry);
+    let stat;
+    try {
+      stat = (0, import_fs.statSync)(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      files.push(...collectFiles(full, options, depth + 1));
+    } else if (stat.isFile() && SRC_EXTENSIONS.has((0, import_path.extname)(full))) {
+      if (!options.include || options.include.some((p) => full.includes(p))) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+function getLineRangeLastModified(file, startLine, endLine) {
+  try {
+    const output = (0, import_child_process.execSync)(`git log -1 --format=%ct -L ${startLine},${endLine}:"${file}"`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const match = output.trim().split("\n")[0];
+    if (match && !isNaN(parseInt(match, 10))) {
+      return parseInt(match, 10);
+    }
+  } catch {
+  }
+  return 0;
+}
+async function analyzeDocDrift(options) {
+  const rootDir = options.rootDir;
+  const files = collectFiles(rootDir, options);
+  const staleMonths = options.staleMonths ?? 6;
+  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexity = 0;
+  const issues = [];
+  const now = Math.floor(Date.now() / 1e3);
+  for (const file of files) {
+    let code;
+    try {
+      code = (0, import_fs.readFileSync)(file, "utf-8");
+    } catch {
+      continue;
+    }
+    let ast;
+    try {
+      ast = (0, import_typescript_estree.parse)(code, {
+        jsx: file.endsWith(".tsx") || file.endsWith(".jsx"),
+        loc: true,
+        comment: true
+      });
+    } catch {
+      continue;
+    }
+    const comments = ast.comments || [];
+    for (const node of ast.body) {
+      if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") {
+        const decl = node.declaration;
+        if (!decl) continue;
+        if (decl.type === "FunctionDeclaration" || decl.type === "ClassDeclaration" || decl.type === "VariableDeclaration") {
+          totalExports++;
+          const nodeLine = node.loc.start.line;
+          const jsdocs = comments.filter((c) => c.type === "Block" && c.value.startsWith("*") && c.loc.end.line === nodeLine - 1);
+          if (jsdocs.length === 0) {
+            uncommentedExports++;
+            if (decl.type === "FunctionDeclaration" && decl.body?.loc) {
+              const lines = decl.body.loc.end.line - decl.body.loc.start.line;
+              if (lines > 20) undocumentedComplexity++;
+            }
+          } else {
+            const jsdoc = jsdocs[0];
+            const jsdocText = jsdoc.value;
+            if (decl.type === "FunctionDeclaration") {
+              const params = decl.params.map((p) => p.name || p.left && p.left.name).filter(Boolean);
+              const paramTags = Array.from(jsdocText.matchAll(/@param\s+(?:\{[^}]+\}\s+)?([a-zA-Z0-9_]+)/g)).map((m) => m[1]);
+              const missingParams = params.filter((p) => !paramTags.includes(p));
+              if (missingParams.length > 0) {
+                outdatedComments++;
+                issues.push({
+                  type: "doc-drift",
+                  severity: "major",
+                  message: `JSDoc @param mismatch: function has parameters (${missingParams.join(", ")}) not documented in JSDoc.`,
+                  location: { file, line: nodeLine }
+                });
+                continue;
+              }
+            }
+            const commentModified = getLineRangeLastModified(file, jsdoc.loc.start.line, jsdoc.loc.end.line);
+            const bodyModified = getLineRangeLastModified(file, decl.loc.start.line, decl.loc.end.line);
+            if (commentModified > 0 && bodyModified > 0) {
+              if (now - commentModified > staleSeconds && bodyModified - commentModified > staleSeconds / 2) {
+                outdatedComments++;
+                issues.push({
+                  type: "doc-drift",
+                  severity: "minor",
+                  message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
+                  location: { file, line: jsdoc.loc.start.line }
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  const riskResult = (0, import_core.calculateDocDrift)({
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity
+  });
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity
+    },
+    recommendations: riskResult.recommendations
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analyzeDocDrift
+});

package/dist/index.mjs

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aiready/doc-drift",
+  "version": "0.1.1",
+  "description": "AI-Readiness: Documentation Drift 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",
+    "picocolors": "^1.0.0",
+    "@aiready/core": "0.9.28"
+  },
+  "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"
+    }
+  },
+  "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__/analyzer.test.ts

@@ -0,0 +1,77 @@
+import { analyzeDocDrift } from '../analyzer';
+import { join } from 'path';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+describe('Doc Drift Analyzer', () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = join(tmpdir(), `doc-drift-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+
+    // File with signature mismatch
+    const file1 = join(tmpDir, 'file1.ts');
+    writeFileSync(file1, `
+/**
+ * Adds numbers.
+ * @param a First number
+ */
+export function add(a: number, b: number) {
+  return a + b;
+}
+    `);
+
+    // File with undocumented complexity (simulated by lines > 20)
+    const file2 = join(tmpDir, 'file2.ts');
+    writeFileSync(file2, `
+export function complexFunction(data: any) {
+  let result = 0;
+  for (let i = 0; i < 10; i++) {
+    if (data && data.includes(i)) result += i;
+  }
+  for (let j = 0; j < 15; j++) {
+    result -= j;
+  }
+  for (let j = 0; j < 15; j++) {
+    result -= j;
+  }
+  for (let j = 0; j < 15; j++) {
+    result -= j;
+  }
+  for (let j = 0; j < 15; j++) {
+    result -= j;
+  }
+  for (let j = 0; j < 15; j++) {
+    result -= j;
+  }
+  for (let k = 0; k < 5; k++) {
+    result += k;
+  }
+  return result;
+}
+    `);
+  });
+
+  afterAll(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('detects missing param documentation and uncommented complexity', async () => {
+    const report = await analyzeDocDrift({
+      rootDir: tmpDir,
+    });
+
+    // totalExports = 2 (add, complexFunction)
+    expect(report.summary.functionsAnalyzed).toBe(2);
+
+    // "add" has a JSDoc, but missing "b" param. "complexFunction" has NO JSDoc.
+    expect(report.rawData.uncommentedExports).toBe(1);
+    expect(report.rawData.outdatedComments).toBe(1);
+    expect(report.rawData.undocumentedComplexity).toBe(1);
+
+    expect(report.issues.length).toBeGreaterThan(0);
+    expect(report.issues.some(i => i.message.includes('b'))).toBe(true);
+  });
+});

package/src/analyzer.ts

@@ -0,0 +1,171 @@
+import { calculateDocDrift } from '@aiready/core';
+import type { DocDriftOptions, DocDriftReport, DocDriftIssue } from './types';
+import { readdirSync, statSync, readFileSync } from 'fs';
+import { join, extname } from 'path';
+import { parse } from '@typescript-eslint/typescript-estree';
+import type { TSESTree } from '@typescript-eslint/types';
+import { execSync } from 'child_process';
+
+const SRC_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+const DEFAULT_EXCLUDES = ['node_modules', 'dist', '.git', 'coverage', '.turbo', 'build'];
+
+function collectFiles(dir: string, options: DocDriftOptions, depth = 0): string[] {
+  if (depth > 20) return [];
+  const excludes = [...DEFAULT_EXCLUDES, ...(options.exclude ?? [])];
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return []; }
+
+  const files: string[] = [];
+  for (const entry of entries) {
+    if (excludes.some(ex => entry === ex || entry.includes(ex))) continue;
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+    if (stat.isDirectory()) {
+      files.push(...collectFiles(full, options, depth + 1));
+    } else if (stat.isFile() && SRC_EXTENSIONS.has(extname(full))) {
+      if (!options.include || options.include.some(p => full.includes(p))) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+
+function getLineRangeLastModified(file: string, startLine: number, endLine: number): number {
+  try {
+    // format %ct is committer date, UNIX timestamp
+    const output = execSync(`git log -1 --format=%ct -L ${startLine},${endLine}:"${file}"`, {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    const match = output.trim().split('\n')[0];
+    if (match && !isNaN(parseInt(match, 10))) {
+      return parseInt(match, 10);
+    }
+  } catch {
+    // Ignore errors (file untracked, new file, etc)
+  }
+  return 0; // Unknown or not committed
+}
+
+export async function analyzeDocDrift(
+  options: DocDriftOptions,
+): Promise<DocDriftReport> {
+  const rootDir = options.rootDir;
+  const files = collectFiles(rootDir, options);
+  const staleMonths = options.staleMonths ?? 6;
+  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
+
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexity = 0;
+
+  const issues: DocDriftIssue[] = [];
+  const now = Math.floor(Date.now() / 1000);
+
+  for (const file of files) {
+    let code: string;
+    try { code = readFileSync(file, 'utf-8'); } catch { continue; }
+
+    let ast: TSESTree.Program;
+    try {
+      ast = parse(code, {
+        jsx: file.endsWith('.tsx') || file.endsWith('.jsx'),
+        loc: true,
+        comment: true,
+      });
+    } catch { continue; }
+
+    const comments = ast.comments || [];
+
+    for (const node of ast.body) {
+      if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') {
+        const decl = (node as any).declaration;
+        if (!decl) continue;
+
+        // Count exports
+        if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration' || decl.type === 'VariableDeclaration') {
+          totalExports++;
+
+          // Find associated JSDoc comment (immediately preceding the export)
+          const nodeLine = node.loc.start.line;
+          const jsdocs = comments.filter((c: any) => c.type === 'Block' && c.value.startsWith('*') && c.loc.end.line === nodeLine - 1);
+
+          if (jsdocs.length === 0) {
+            uncommentedExports++;
+
+            // Check for undocumented complexity (e.g., function body > 20 lines)
+            if (decl.type === 'FunctionDeclaration' && decl.body?.loc) {
+              const lines = decl.body.loc.end.line - decl.body.loc.start.line;
+              if (lines > 20) undocumentedComplexity++;
+            }
+          } else {
+            const jsdoc = jsdocs[0];
+            const jsdocText = jsdoc.value;
+
+            // Signature mismatch detection
+            if (decl.type === 'FunctionDeclaration') {
+              const params = decl.params.map((p: any) => p.name || (p.left && p.left.name)).filter(Boolean);
+              const paramTags = Array.from(jsdocText.matchAll(/@param\s+(?:\{[^}]+\}\s+)?([a-zA-Z0-9_]+)/g)).map((m: any) => m[1]);
+
+              const missingParams = params.filter((p: string) => !paramTags.includes(p));
+              if (missingParams.length > 0) {
+                outdatedComments++;
+                issues.push({
+                  type: 'doc-drift',
+                  severity: 'major',
+                  message: `JSDoc @param mismatch: function has parameters (${missingParams.join(', ')}) not documented in JSDoc.`,
+                  location: { file, line: nodeLine }
+                });
+                continue; // already counted as outdated
+              }
+            }
+
+            // Timestamp comparison
+            const commentModified = getLineRangeLastModified(file, jsdoc.loc.start.line, jsdoc.loc.end.line);
+            const bodyModified = getLineRangeLastModified(file, decl.loc.start.line, decl.loc.end.line);
+
+            if (commentModified > 0 && bodyModified > 0) {
+              // If body was modified much later than the comment, and comment is older than staleMonths
+              if (now - commentModified > staleSeconds && bodyModified - commentModified > staleSeconds / 2) {
+                outdatedComments++;
+                issues.push({
+                  type: 'doc-drift',
+                  severity: 'minor',
+                  message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
+                  location: { file, line: jsdoc.loc.start.line }
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const riskResult = calculateDocDrift({
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity
+  });
+
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating,
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity,
+    },
+    recommendations: riskResult.recommendations,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,37 @@
+import { Command } from 'commander';
+import { analyzeDocDrift } from './analyzer';
+import pc from 'picocolors';
+
+export function createCommand() {
+  const program = new Command('doc-drift')
+    .description('Scan for documentation drift (outdated comments, mismatched signatures)')
+    .option('--include <patterns...>', 'File patterns to include')
+    .option('--exclude <patterns...>', 'File patterns to exclude')
+    .option('--stale-months <number>', 'Months before a comment is considered potentially outdated', '6')
+    .action(async (options) => {
+      console.log(pc.cyan('Analyzing documentation drift...'));
+      const report = await analyzeDocDrift({
+        rootDir: process.cwd(),
+        include: options.include,
+        exclude: options.exclude,
+        staleMonths: parseInt(options.staleMonths, 10),
+      });
+
+      console.log(pc.bold('Doc Drift Analysis Results:'));
+      console.log(`Rating: ${report.summary.rating.toUpperCase()} (Score: ${report.summary.score})`);
+      if (report.issues.length > 0) {
+        console.log(pc.red(`\nFound ${report.issues.length} drift issues.`));
+      } else {
+        console.log(pc.green('\nNo documentation drift detected.'));
+      }
+    });
+
+  return program;
+}
+
+if (require.main === module) {
+  createCommand().parseAsync(process.argv).catch(err => {
+    console.error(pc.red(err.message));
+    process.exit(1);
+  });
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './analyzer';

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { ScanOptions, Issue } from '@aiready/core';
+
+export interface DocDriftOptions extends ScanOptions {
+  /** Maximum commit distance to check for drift */
+  maxCommits?: number;
+  /** Consider comments older than this many months as outdated */
+  staleMonths?: number;
+}
+
+export interface DocDriftIssue extends Issue {
+  type: 'doc-drift';
+}
+
+export interface DocDriftReport {
+  summary: {
+    filesAnalyzed: number;
+    functionsAnalyzed: number;
+    score: number;
+    rating: 'minimal' | 'low' | 'moderate' | 'high' | 'severe';
+  };
+  issues: DocDriftIssue[];
+  rawData: {
+    uncommentedExports: number;
+    totalExports: number;
+    outdatedComments: number;
+    undocumentedComplexity: number;
+  };
+  recommendations: string[];
+}

package/tsconfig.json

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