@aiready/doc-drift 0.13.4 → 0.13.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/doc-drift",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "description": "AI-Readiness: Documentation Drift Detection",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -10,7 +10,7 @@
     "commander": "^14.0.0",
     "glob": "^13.0.0",
     "picocolors": "^1.0.0",
-    "@aiready/core": "0.23.4"
+    "@aiready/core": "0.23.7"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/analyzer.test.ts

@@ -76,6 +76,7 @@ export function complexFunction(data: any) {
     expect(report.rawData.uncommentedExports).toBe(1);
     expect(report.rawData.outdatedComments).toBe(1);
     expect(report.rawData.undocumentedComplexity).toBe(1);
+    expect(report.rawData.actualDrift).toBe(0);
 
     expect(report.issues.length).toBeGreaterThan(0);
     expect(report.issues.some((i) => i.message.includes('b'))).toBe(true);

package/src/__tests__/provider.test.ts

@@ -21,6 +21,7 @@ describe('Doc Drift Provider', () => {
         totalExports: 5,
         outdatedComments: 0,
         undocumentedComplexity: 0,
+        actualDrift: 0,
       },
       recommendations: [],
     });

package/src/__tests__/scoring.test.ts

@@ -17,6 +17,7 @@ describe('Doc Drift Scoring', () => {
       totalExports: 50,
       outdatedComments: 2,
       undocumentedComplexity: 1,
+      actualDrift: 0,
     },
     recommendations: [
       'Update or remove 2 outdated comments that contradict the code.',

package/src/analyzer.ts

@@ -11,21 +11,31 @@ import {
 import type { DocDriftOptions, DocDriftReport, DocDriftIssue } from './types';
 import { readFileSync } from 'fs';
 
+/**
+ * Analyzes documentation drift across a set of files.
+ * This tool detects:
+ * 1. Missing documentation for complex functions/classes.
+ * 2. Signature mismatches (parameters not mentioned in docs).
+ * 3. Temporal drift (logic changed after documentation was last updated).
+ *
+ * @param options - Analysis configuration including include/exclude patterns and drift thresholds.
+ * @returns A comprehensive report with drift scores and specific issues.
+ */
 export async function analyzeDocDrift(
   options: DocDriftOptions
 ): Promise<DocDriftReport> {
   // Use core scanFiles which respects .gitignore recursively
   const files = await scanFiles(options);
   const issues: DocDriftIssue[] = [];
-  const staleMonths = options.staleMonths ?? 6;
-  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
+  // const staleSeconds = staleMonths * 30 * 24 * 60 * 60; // Unused, removed
 
   let uncommentedExports = 0;
   let totalExports = 0;
   let outdatedComments = 0;
   let undocumentedComplexity = 0;
+  let actualDrift = 0;
 
-  const now = Math.floor(Date.now() / 1000);
+  // const now = Math.floor(Date.now() / 1000); // Unused, removed
 
   let processed = 0;
   for (const file of files) {
@@ -76,7 +86,6 @@ export async function analyzeDocDrift(
             if (exp.type === 'function' && exp.parameters) {
               const params = exp.parameters;
               // Check if params mentioned in doc (standard @param or simple mention)
-              // Use regex with word boundaries to avoid partial matches (e.g. 'b' in 'numbers')
               const missingParams = params.filter((p) => {
                 const regex = new RegExp(`\\b${p}\\b`, 'i');
                 return !regex.test(docContent);
@@ -90,36 +99,39 @@ export async function analyzeDocDrift(
                   message: `Documentation mismatch: function parameters (${missingParams.join(', ')}) are not mentioned in the docs.`,
                   location: { file, line: exp.loc?.start.line || 1 },
                 });
-                continue;
               }
             }
 
-            // Timestamp comparison
-            if (exp.loc) {
+            // Timestamp comparison for temporal drift
+            if (exp.loc && doc.loc) {
               if (!fileLineStamps) {
                 fileLineStamps = getFileCommitTimestamps(file);
               }
 
-              // We don't have exact lines for the doc node in ExportInfo yet,
-              // but we know it precedes the export. Using export start as a proxy for drift check.
               const bodyModified = getLineRangeLastModifiedCached(
                 fileLineStamps,
                 exp.loc.start.line,
                 exp.loc.end.line
               );
 
-              if (bodyModified > 0) {
-                // If body was modified much later than the "stale" threshold
-                if (
-                  now - bodyModified < staleSeconds / 4 &&
-                  exp.documentation.isStale === true
-                ) {
-                  // This would require isStale to be set by the parser if it knew history
-                  // For now, we compare body modification vs current time if docs look very old (heuristic)
-                }
+              const docModified = getLineRangeLastModifiedCached(
+                fileLineStamps,
+                doc.loc.start.line,
+                doc.loc.end.line
+              );
 
-                // If the file itself is very old but has no issues, it's fine.
-                // Doc-drift is really about implementation changing without doc updates.
+              if (bodyModified > 0 && docModified > 0) {
+                // If body was modified more than 1 day AFTER the documentation
+                const DRIFT_THRESHOLD_SECONDS = 24 * 60 * 60;
+                if (bodyModified - docModified > DRIFT_THRESHOLD_SECONDS) {
+                  actualDrift++;
+                  issues.push({
+                    type: IssueType.DocDrift,
+                    severity: Severity.Major,
+                    message: `Documentation drift: logic was modified on ${new Date(bodyModified * 1000).toLocaleDateString()} but documentation was last updated on ${new Date(docModified * 1000).toLocaleDateString()}.`,
+                    location: { file, line: doc.loc.start.line },
+                  });
+                }
               }
             }
           }
@@ -136,6 +148,7 @@ export async function analyzeDocDrift(
     totalExports,
     outdatedComments,
     undocumentedComplexity,
+    actualDrift,
   });
 
   return {
@@ -151,6 +164,7 @@ export async function analyzeDocDrift(
       totalExports,
       outdatedComments,
       undocumentedComplexity,
+      actualDrift,
     },
     recommendations: riskResult.recommendations,
   };

package/src/scoring.ts

@@ -3,7 +3,11 @@ import type { ToolScoringOutput } from '@aiready/core';
 import type { DocDriftReport } from './types';
 
 /**
- * Convert doc-drift report into a ToolScoringOutput.
+ * Convert doc-drift report into a standardized ToolScoringOutput.
+ *
+ * @param report - The detailed doc-drift report including raw metrics.
+ * @returns Standardized scoring and risk factor breakdown.
+ * @lastUpdated 2026-03-18
  */
 export function calculateDocDriftScore(
   report: DocDriftReport
@@ -16,28 +20,41 @@ export function calculateDocDriftScore(
     totalExports: rawData.totalExports,
     outdatedComments: rawData.outdatedComments,
     undocumentedComplexity: rawData.undocumentedComplexity,
+    actualDrift: rawData.actualDrift,
   });
 
   const factors: ToolScoringOutput['factors'] = [
     {
-      name: 'Uncommented Exports',
+      name: 'Undocumented Complexity',
       impact: -Math.min(
-        20,
-        (rawData.uncommentedExports / Math.max(1, rawData.totalExports)) *
+        50,
+        (rawData.undocumentedComplexity /
+          Math.max(1, rawData.totalExports) /
+          0.2) *
           100 *
-          0.2
+          0.5
       ),
-      description: `${rawData.uncommentedExports} uncommented exports`,
+      description: `${rawData.undocumentedComplexity} complex functions lack docs (high risk)`,
     },
     {
-      name: 'Outdated Comments',
-      impact: -Math.min(60, rawData.outdatedComments * 15 * 0.6),
-      description: `${rawData.outdatedComments} outdated comments`,
+      name: 'Outdated/Incomplete Comments',
+      impact: -Math.min(
+        30,
+        (rawData.outdatedComments / Math.max(1, rawData.totalExports) / 0.4) *
+          100 *
+          0.3
+      ),
+      description: `${rawData.outdatedComments} functions with parameter-mismatch in docs`,
     },
     {
-      name: 'Undocumented Complexity',
-      impact: -Math.min(20, rawData.undocumentedComplexity * 10 * 0.2),
-      description: `${rawData.undocumentedComplexity} complex functions lack docs`,
+      name: 'Uncommented Exports',
+      impact: -Math.min(
+        20,
+        (rawData.uncommentedExports / Math.max(1, rawData.totalExports) / 0.8) *
+          100 *
+          0.2
+      ),
+      description: `${rawData.uncommentedExports} uncommented exports`,
     },
   ];
 

package/src/types.ts

@@ -50,6 +50,8 @@ export interface DocDriftReport {
     outdatedComments: number;
     /** Count of complex functions without sufficient documentation */
     undocumentedComplexity: number;
+    /** Number of functions where code changed after docs */
+    actualDrift: number;
   };
   /** AI-generated remediation advice */
   recommendations: string[];

package/dist/chunk-5EFFNN6L.mjs

@@ -1,145 +0,0 @@
-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 {
-  scanFiles,
-  calculateDocDrift,
-  getFileCommitTimestamps,
-  getLineRangeLastModifiedCached
-} from "@aiready/core";
-import { readFileSync } from "fs";
-import { parse } from "@typescript-eslint/typescript-estree";
-async function analyzeDocDrift(options) {
-  const rootDir = options.rootDir;
-  const files = await scanFiles(options);
-  const issues = [];
-  const results = [];
-  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 now = Math.floor(Date.now() / 1e3);
-  let processed = 0;
-  for (const file of files) {
-    processed++;
-    options.onProgress?.(processed, files.length, `doc-drift: analyzing 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 || [];
-    let fileLineStamps;
-    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;
-              }
-            }
-            if (!fileLineStamps) {
-              fileLineStamps = getFileCommitTimestamps(file);
-            }
-            const commentModified = getLineRangeLastModifiedCached(
-              fileLineStamps,
-              jsdoc.loc.start.line,
-              jsdoc.loc.end.line
-            );
-            const bodyModified = getLineRangeLastModifiedCached(
-              fileLineStamps,
-              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/chunk-BBGJNBVI.mjs

@@ -1,189 +0,0 @@
-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
-};