@aiready/doc-drift 0.13.4 → 0.13.5

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/doc-drift@0.13.4 build /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.13.5 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
@@ -9,16 +9,16 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/chunk-5BGWZWHD.mjs 3.81 KB
-ESM dist/index.mjs          2.37 KB
+CJS dist/cli.js   7.25 KB
+CJS dist/index.js 7.85 KB
+CJS ⚡️ Build success in 122ms
+ESM dist/index.mjs          2.59 KB
 ESM dist/cli.mjs            1.39 KB
-ESM ⚡️ Build success in 200ms
-CJS dist/index.js 6.86 KB
-CJS dist/cli.js   6.48 KB
-CJS ⚡️ Build success in 200ms
+ESM dist/chunk-P74XAVQ3.mjs 4.54 KB
+ESM ⚡️ Build success in 124ms
 DTS Build start
-DTS ⚡️ Build success in 3500ms
+DTS ⚡️ Build success in 5302ms
 DTS dist/cli.d.ts    108.00 B
-DTS dist/index.d.ts  2.12 KB
+DTS dist/index.d.ts  2.66 KB
 DTS dist/cli.d.mts   108.00 B
-DTS dist/index.d.mts 2.12 KB
+DTS dist/index.d.mts 2.66 KB

package/dist/{chunk-5BGWZWHD.mjs → chunk-P74XAVQ3.mjs}

@@ -26,6 +26,7 @@ async function analyzeDocDrift(options) {
   let totalExports = 0;
   let outdatedComments = 0;
   let undocumentedComplexity = 0;
+  let actualDrift = 0;
   const now = Math.floor(Date.now() / 1e3);
   let processed = 0;
   for (const file of files) {
@@ -75,10 +76,9 @@ async function analyzeDocDrift(options) {
                   message: `Documentation mismatch: function parameters (${missingParams.join(", ")}) are not mentioned in the docs.`,
                   location: { file, line: exp.loc?.start.line || 1 }
                 });
-                continue;
               }
             }
-            if (exp.loc) {
+            if (exp.loc && doc.loc) {
               if (!fileLineStamps) {
                 fileLineStamps = getFileCommitTimestamps(file);
               }
@@ -87,8 +87,21 @@ async function analyzeDocDrift(options) {
                 exp.loc.start.line,
                 exp.loc.end.line
               );
-              if (bodyModified > 0) {
-                if (now - bodyModified < staleSeconds / 4 && exp.documentation.isStale === true) {
+              const docModified = getLineRangeLastModifiedCached(
+                fileLineStamps,
+                doc.loc.start.line,
+                doc.loc.end.line
+              );
+              if (bodyModified > 0 && docModified > 0) {
+                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 * 1e3).toLocaleDateString()} but documentation was last updated on ${new Date(docModified * 1e3).toLocaleDateString()}.`,
+                    location: { file, line: doc.loc.start.line }
+                  });
                 }
               }
             }
@@ -104,7 +117,8 @@ async function analyzeDocDrift(options) {
     uncommentedExports,
     totalExports,
     outdatedComments,
-    undocumentedComplexity
+    undocumentedComplexity,
+    actualDrift
   });
   return {
     summary: {
@@ -118,7 +132,8 @@ async function analyzeDocDrift(options) {
       uncommentedExports,
       totalExports,
       outdatedComments,
-      undocumentedComplexity
+      undocumentedComplexity,
+      actualDrift
     },
     recommendations: riskResult.recommendations
   };

package/dist/cli.js

@@ -47,6 +47,7 @@ async function analyzeDocDrift(options) {
   let totalExports = 0;
   let outdatedComments = 0;
   let undocumentedComplexity = 0;
+  let actualDrift = 0;
   const now = Math.floor(Date.now() / 1e3);
   let processed = 0;
   for (const file of files) {
@@ -96,10 +97,9 @@ async function analyzeDocDrift(options) {
                   message: `Documentation mismatch: function parameters (${missingParams.join(", ")}) are not mentioned in the docs.`,
                   location: { file, line: exp.loc?.start.line || 1 }
                 });
-                continue;
               }
             }
-            if (exp.loc) {
+            if (exp.loc && doc.loc) {
               if (!fileLineStamps) {
                 fileLineStamps = (0, import_core.getFileCommitTimestamps)(file);
               }
@@ -108,8 +108,21 @@ async function analyzeDocDrift(options) {
                 exp.loc.start.line,
                 exp.loc.end.line
               );
-              if (bodyModified > 0) {
-                if (now - bodyModified < staleSeconds / 4 && exp.documentation.isStale === true) {
+              const docModified = (0, import_core.getLineRangeLastModifiedCached)(
+                fileLineStamps,
+                doc.loc.start.line,
+                doc.loc.end.line
+              );
+              if (bodyModified > 0 && docModified > 0) {
+                const DRIFT_THRESHOLD_SECONDS = 24 * 60 * 60;
+                if (bodyModified - docModified > DRIFT_THRESHOLD_SECONDS) {
+                  actualDrift++;
+                  issues.push({
+                    type: import_core.IssueType.DocDrift,
+                    severity: import_core.Severity.Major,
+                    message: `Documentation drift: logic was modified on ${new Date(bodyModified * 1e3).toLocaleDateString()} but documentation was last updated on ${new Date(docModified * 1e3).toLocaleDateString()}.`,
+                    location: { file, line: doc.loc.start.line }
+                  });
                 }
               }
             }
@@ -125,7 +138,8 @@ async function analyzeDocDrift(options) {
     uncommentedExports,
     totalExports,
     outdatedComments,
-    undocumentedComplexity
+    undocumentedComplexity,
+    actualDrift
   });
   return {
     summary: {
@@ -139,7 +153,8 @@ async function analyzeDocDrift(options) {
       uncommentedExports,
       totalExports,
       outdatedComments,
-      undocumentedComplexity
+      undocumentedComplexity,
+      actualDrift
     },
     recommendations: riskResult.recommendations
   };

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 import {
   __require,
   analyzeDocDrift
-} from "./chunk-5BGWZWHD.mjs";
+} from "./chunk-P74XAVQ3.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.d.mts

@@ -49,11 +49,23 @@ 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[];
 }
 
+/**
+ * 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.
+ */
 declare function analyzeDocDrift(options: DocDriftOptions): Promise<DocDriftReport>;
 
 /**

package/dist/index.d.ts

@@ -49,11 +49,23 @@ 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[];
 }
 
+/**
+ * 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.
+ */
 declare function analyzeDocDrift(options: DocDriftOptions): Promise<DocDriftReport>;
 
 /**

package/dist/index.js

@@ -42,6 +42,7 @@ async function analyzeDocDrift(options) {
   let totalExports = 0;
   let outdatedComments = 0;
   let undocumentedComplexity = 0;
+  let actualDrift = 0;
   const now = Math.floor(Date.now() / 1e3);
   let processed = 0;
   for (const file of files) {
@@ -91,10 +92,9 @@ async function analyzeDocDrift(options) {
                   message: `Documentation mismatch: function parameters (${missingParams.join(", ")}) are not mentioned in the docs.`,
                   location: { file, line: exp.loc?.start.line || 1 }
                 });
-                continue;
               }
             }
-            if (exp.loc) {
+            if (exp.loc && doc.loc) {
               if (!fileLineStamps) {
                 fileLineStamps = (0, import_core.getFileCommitTimestamps)(file);
               }
@@ -103,8 +103,21 @@ async function analyzeDocDrift(options) {
                 exp.loc.start.line,
                 exp.loc.end.line
               );
-              if (bodyModified > 0) {
-                if (now - bodyModified < staleSeconds / 4 && exp.documentation.isStale === true) {
+              const docModified = (0, import_core.getLineRangeLastModifiedCached)(
+                fileLineStamps,
+                doc.loc.start.line,
+                doc.loc.end.line
+              );
+              if (bodyModified > 0 && docModified > 0) {
+                const DRIFT_THRESHOLD_SECONDS = 24 * 60 * 60;
+                if (bodyModified - docModified > DRIFT_THRESHOLD_SECONDS) {
+                  actualDrift++;
+                  issues.push({
+                    type: import_core.IssueType.DocDrift,
+                    severity: import_core.Severity.Major,
+                    message: `Documentation drift: logic was modified on ${new Date(bodyModified * 1e3).toLocaleDateString()} but documentation was last updated on ${new Date(docModified * 1e3).toLocaleDateString()}.`,
+                    location: { file, line: doc.loc.start.line }
+                  });
                 }
               }
             }
@@ -120,7 +133,8 @@ async function analyzeDocDrift(options) {
     uncommentedExports,
     totalExports,
     outdatedComments,
-    undocumentedComplexity
+    undocumentedComplexity,
+    actualDrift
   });
   return {
     summary: {
@@ -134,7 +148,8 @@ async function analyzeDocDrift(options) {
       uncommentedExports,
       totalExports,
       outdatedComments,
-      undocumentedComplexity
+      undocumentedComplexity,
+      actualDrift
     },
     recommendations: riskResult.recommendations
   };
@@ -173,26 +188,33 @@ function calculateDocDriftScore(report) {
     uncommentedExports: rawData.uncommentedExports,
     totalExports: rawData.totalExports,
     outdatedComments: rawData.outdatedComments,
-    undocumentedComplexity: rawData.undocumentedComplexity
+    undocumentedComplexity: rawData.undocumentedComplexity,
+    actualDrift: rawData.actualDrift
   });
   const factors = [
     {
-      name: "Uncommented Exports",
+      name: "Undocumented Complexity",
       impact: -Math.min(
-        20,
-        rawData.uncommentedExports / Math.max(1, rawData.totalExports) * 100 * 0.2
+        50,
+        rawData.undocumentedComplexity / Math.max(1, rawData.totalExports) / 0.2 * 100 * 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`
     }
   ];
   const recommendations = riskResult.recommendations.map((rec) => ({

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   analyzeDocDrift
-} from "./chunk-5BGWZWHD.mjs";
+} from "./chunk-P74XAVQ3.mjs";
 
 // src/index.ts
 import { ToolRegistry } from "@aiready/core";
@@ -44,26 +44,33 @@ function calculateDocDriftScore(report) {
     uncommentedExports: rawData.uncommentedExports,
     totalExports: rawData.totalExports,
     outdatedComments: rawData.outdatedComments,
-    undocumentedComplexity: rawData.undocumentedComplexity
+    undocumentedComplexity: rawData.undocumentedComplexity,
+    actualDrift: rawData.actualDrift
   });
   const factors = [
     {
-      name: "Uncommented Exports",
+      name: "Undocumented Complexity",
       impact: -Math.min(
-        20,
-        rawData.uncommentedExports / Math.max(1, rawData.totalExports) * 100 * 0.2
+        50,
+        rawData.undocumentedComplexity / Math.max(1, rawData.totalExports) / 0.2 * 100 * 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`
     }
   ];
   const recommendations = riskResult.recommendations.map((rec) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/doc-drift",
-  "version": "0.13.4",
+  "version": "0.13.5",
   "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.6"
   },
   "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,6 +11,16 @@ 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> {
@@ -24,6 +34,7 @@ export async function analyzeDocDrift(
   let totalExports = 0;
   let outdatedComments = 0;
   let undocumentedComplexity = 0;
+  let actualDrift = 0;
 
   const now = Math.floor(Date.now() / 1000);
 
@@ -76,7 +87,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 +100,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 +149,7 @@ export async function analyzeDocDrift(
     totalExports,
     outdatedComments,
     undocumentedComplexity,
+    actualDrift,
   });
 
   return {
@@ -151,6 +165,7 @@ export async function analyzeDocDrift(
       totalExports,
       outdatedComments,
       undocumentedComplexity,
+      actualDrift,
     },
     recommendations: riskResult.recommendations,
   };

package/src/scoring.ts

@@ -16,28 +16,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[];