@aiready/doc-drift 0.1.5 → 0.1.6

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/doc-drift@0.1.5 build /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.1.6 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
@@ -10,7 +10,7 @@
 CJS Build start
 ESM Build start
 
-[2:33:41 PM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
+[10:18:49 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"
@@ -31,7 +31,7 @@
 
 
 
-[2:33:42 PM]  WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]
+[10:18:49 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"
@@ -51,15 +51,15 @@
 
 
 
-CJS dist/index.js 6.50 KB
-CJS dist/cli.js   8.49 KB
-CJS ⚡️ Build success in 2383ms
-ESM dist/cli.mjs            1.36 KB
+ESM dist/cli.mjs            1.39 KB
+ESM dist/chunk-BBGJNBVI.mjs 5.95 KB
 ESM dist/index.mjs          88.00 B
-ESM dist/chunk-TSLAGWBV.mjs 5.71 KB
-ESM ⚡️ Build success in 2526ms
+ESM ⚡️ Build success in 49ms
+CJS dist/cli.js   8.76 KB
+CJS dist/index.js 6.73 KB
+CJS ⚡️ Build success in 51ms
 DTS Build start
-DTS ⚡️ Build success in 72201ms
+DTS ⚡️ Build success in 4363ms
 DTS dist/cli.d.ts    108.00 B
 DTS dist/index.d.ts  950.00 B
 DTS dist/cli.d.mts   108.00 B

package/.turbo/turbo-test.log

@@ -1,16 +1,16 @@
 
 
-> @aiready/doc-drift@0.1.5 test /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.1.6 test /Users/pengcao/projects/aiready/packages/doc-drift
 > vitest run
 
+[?25l
+ RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/doc-drift
 
- RUN  v1.6.1 /Users/pengcao/projects/aiready/packages/doc-drift
-
- ✓ src/__tests__/analyzer.test.ts  (1 test) 777ms
+ ✓ src/__tests__/analyzer.test.ts (1 test) 19ms
 
  Test Files  1 passed (1)
       Tests  1 passed (1)
-   Start at  14:38:44
-   Duration  33.39s (transform 5.68s, setup 0ms, collect 23.73s, tests 777ms, environment 0ms, prepare 4.26s)
+   Start at  22:19:16
+   Duration  1.48s (transform 208ms, setup 0ms, import 1.21s, tests 19ms, environment 0ms)
 
 [?25h

package/README.md

@@ -7,7 +7,7 @@
 
 ## Overview
 
-The **Documentation Drift** analyzer combines AST parsing with git log traversal to identify instances where comments are likely lagging behind actual implementation logic. 
+The **Documentation Drift** analyzer combines AST parsing with git log traversal to identify instances where comments are likely lagging behind actual implementation logic.
 
 ## 🏛️ Architecture
 

package/dist/chunk-BBGJNBVI.mjs

@@ -0,0 +1,189 @@
+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.js

@@ -42,7 +42,14 @@ 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"];
+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 ?? []];
@@ -74,10 +81,13 @@ function collectFiles(dir, options, depth = 0) {
 }
 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 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);
@@ -122,7 +132,9 @@ async function analyzeDocDrift(options) {
         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);
+          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) {
@@ -134,8 +146,12 @@ async function analyzeDocDrift(options) {
             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));
+              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({
@@ -147,8 +163,16 @@ async function analyzeDocDrift(options) {
                 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);
+            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++;
@@ -192,7 +216,13 @@ async function analyzeDocDrift(options) {
 // 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) => {
+  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(),
@@ -201,7 +231,9 @@ function createCommand() {
       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})`);
+    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.`));

package/dist/cli.mjs

@@ -1,13 +1,19 @@
 import {
   __require,
   analyzeDocDrift
-} from "./chunk-TSLAGWBV.mjs";
+} from "./chunk-BBGJNBVI.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) => {
+  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(),
@@ -16,7 +22,9 @@ function createCommand() {
       staleMonths: parseInt(options.staleMonths, 10)
     });
     console.log(pc.bold("Doc Drift Analysis Results:"));
-    console.log(`Rating: ${report.summary.rating.toUpperCase()} (Score: ${report.summary.score})`);
+    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.`));

package/dist/index.js

@@ -31,7 +31,14 @@ 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"];
+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 ?? []];
@@ -63,10 +70,13 @@ function collectFiles(dir, options, depth = 0) {
 }
 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 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);
@@ -111,7 +121,9 @@ async function analyzeDocDrift(options) {
         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);
+          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) {
@@ -123,8 +135,12 @@ async function analyzeDocDrift(options) {
             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));
+              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({
@@ -136,8 +152,16 @@ async function analyzeDocDrift(options) {
                 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);
+            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++;

package/dist/index.mjs

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

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@aiready/doc-drift",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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",
+    "@typescript-eslint/typescript-estree": "^8.0.0",
+    "commander": "^14.0.0",
+    "glob": "^13.0.0",
     "picocolors": "^1.0.0",
-    "@aiready/core": "0.9.32"
+    "@aiready/core": "0.9.33"
   },
   "devDependencies": {
-    "@types/node": "^20.12.7",
-    "@typescript-eslint/types": "^7.8.0",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/types": "^8.0.0",
     "tsup": "^8.0.2",
     "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "vitest": "^4.0.0"
   },
   "exports": {
     ".": {

package/src/__tests__/analyzer.test.ts

@@ -13,7 +13,9 @@ describe('Doc Drift Analyzer', () => {
 
     // File with signature mismatch
     const file1 = join(tmpDir, 'file1.ts');
-    writeFileSync(file1, `
+    writeFileSync(
+      file1,
+      `
 /**
  * Adds numbers.
  * @param a First number
@@ -21,11 +23,14 @@ describe('Doc Drift Analyzer', () => {
 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, `
+    writeFileSync(
+      file2,
+      `
 export function complexFunction(data: any) {
   let result = 0;
   for (let i = 0; i < 10; i++) {
@@ -51,7 +56,8 @@ export function complexFunction(data: any) {
   }
   return result;
 }
-    `);
+    `
+    );
   });
 
   afterAll(() => {
@@ -72,6 +78,6 @@ export function complexFunction(data: any) {
     expect(report.rawData.undocumentedComplexity).toBe(1);
 
     expect(report.issues.length).toBeGreaterThan(0);
-    expect(report.issues.some(i => i.message.includes('b'))).toBe(true);
+    expect(report.issues.some((i) => i.message.includes('b'))).toBe(true);
   });
 });

package/src/analyzer.ts

@@ -7,24 +7,43 @@ 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[] {
+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 []; }
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
 
   const files: string[] = [];
   for (const entry of entries) {
-    if (excludes.some(ex => entry === ex || entry.includes(ex))) continue;
+    if (excludes.some((ex) => entry === ex || entry.includes(ex))) continue;
     const full = join(dir, entry);
     let stat;
-    try { stat = statSync(full); } catch { continue; }
+    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))) {
+      if (!options.include || options.include.some((p) => full.includes(p))) {
         files.push(full);
       }
     }
@@ -32,13 +51,20 @@ function collectFiles(dir: string, options: DocDriftOptions, depth = 0): string[
   return files;
 }
 
-function getLineRangeLastModified(file: string, startLine: number, endLine: number): number {
+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 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);
@@ -50,7 +76,7 @@ function getLineRangeLastModified(file: string, startLine: number, endLine: numb
 }
 
 export async function analyzeDocDrift(
-  options: DocDriftOptions,
+  options: DocDriftOptions
 ): Promise<DocDriftReport> {
   const rootDir = options.rootDir;
   const files = collectFiles(rootDir, options);
@@ -67,7 +93,11 @@ export async function analyzeDocDrift(
 
   for (const file of files) {
     let code: string;
-    try { code = readFileSync(file, 'utf-8'); } catch { continue; }
+    try {
+      code = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
 
     let ast: TSESTree.Program;
     try {
@@ -76,22 +106,36 @@ export async function analyzeDocDrift(
         loc: true,
         comment: true,
       });
-    } catch { continue; }
+    } catch {
+      continue;
+    }
 
     const comments = ast.comments || [];
 
     for (const node of ast.body) {
-      if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') {
+      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') {
+        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);
+          const jsdocs = comments.filter(
+            (c: any) =>
+              c.type === 'Block' &&
+              c.value.startsWith('*') &&
+              c.loc.end.line === nodeLine - 1
+          );
 
           if (jsdocs.length === 0) {
             uncommentedExports++;
@@ -107,35 +151,52 @@ export async function analyzeDocDrift(
 
             // 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));
+              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 }
+                  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);
+            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) {
+              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 }
+                  location: { file, line: jsdoc.loc.start.line },
                 });
               }
             }
@@ -149,7 +210,7 @@ export async function analyzeDocDrift(
     uncommentedExports,
     totalExports,
     outdatedComments,
-    undocumentedComplexity
+    undocumentedComplexity,
   });
 
   return {

package/src/cli.ts

@@ -4,10 +4,16 @@ import pc from 'picocolors';
 
 export function createCommand() {
   const program = new Command('doc-drift')
-    .description('Scan for documentation drift (outdated comments, mismatched signatures)')
+    .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')
+    .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({
@@ -18,7 +24,9 @@ export function createCommand() {
       });
 
       console.log(pc.bold('Doc Drift Analysis Results:'));
-      console.log(`Rating: ${report.summary.rating.toUpperCase()} (Score: ${report.summary.score})`);
+      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 {
@@ -30,8 +38,10 @@ export function createCommand() {
 }
 
 if (require.main === module) {
-  createCommand().parseAsync(process.argv).catch(err => {
-    console.error(pc.red(err.message));
-    process.exit(1);
-  });
+  createCommand()
+    .parseAsync(process.argv)
+    .catch((err) => {
+      console.error(pc.red(err.message));
+      process.exit(1);
+    });
 }