@aiready/doc-drift 0.13.5 → 0.13.7

package/.turbo/turbo-build.log

@@ -1,24 +1,23 @@
-
-
-> @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
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Target: es2020
-CJS Build start
-ESM Build start
-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 dist/chunk-P74XAVQ3.mjs 4.54 KB
-ESM ⚡️ Build success in 124ms
-DTS Build start
-DTS ⚡️ Build success in 5302ms
-DTS dist/cli.d.ts    108.00 B
-DTS dist/index.d.ts  2.66 KB
-DTS dist/cli.d.mts   108.00 B
-DTS dist/index.d.mts 2.66 KB
+
+> @aiready/doc-drift@0.13.7 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
+ESM dist/cli.mjs            1.39 KB
+ESM dist/index.mjs          2.59 KB
+ESM dist/chunk-MAPV5YQR.mjs 4.40 KB
+ESM ⚡️ Build success in 92ms
+CJS dist/index.js 7.71 KB
+CJS dist/cli.js   7.11 KB
+CJS ⚡️ Build success in 93ms
+DTS Build start
+DTS ⚡️ Build success in 5320ms
+DTS dist/cli.d.ts    108.00 B
+DTS dist/index.d.ts  2.83 KB
+DTS dist/cli.d.mts   108.00 B
+DTS dist/index.d.mts 2.83 KB

package/.turbo/turbo-test.log

@@ -1,18 +1,16 @@
-
-
-> @aiready/doc-drift@0.13.3 test /Users/pengcao/projects/aiready/packages/doc-drift
-> vitest run
-
-[?25l
- RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/doc-drift
-
- ✓ src/__tests__/scoring.test.ts (2 tests) 12ms
- ✓ src/__tests__/analyzer.test.ts (1 test) 47ms
- ✓ src/__tests__/provider.test.ts (2 tests) 8ms
-
- Test Files  3 passed (3)
-      Tests  5 passed (5)
-   Start at  10:36:26
-   Duration  1.89s (transform 1.09s, setup 0ms, import 3.19s, tests 66ms, environment 0ms)
-
-[?25h
+
+> @aiready/doc-drift@0.13.6 test /Users/pengcao/projects/aiready/packages/doc-drift
+> vitest run
+
+
+ RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/doc-drift
+
+ ✓ src/__tests__/scoring.test.ts (2 tests) 21ms
+ ✓ src/__tests__/provider.test.ts (2 tests) 7ms
+ ✓ src/__tests__/analyzer.test.ts (1 test) 262ms
+
+ Test Files  3 passed (3)
+      Tests  5 passed (5)
+   Start at  15:20:15
+   Duration  2.78s (transform 895ms, setup 0ms, import 5.59s, tests 290ms, environment 0ms)
+

package/dist/chunk-6EHZXHM7.mjs

@@ -0,0 +1,143 @@
+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,
+  Severity,
+  IssueType,
+  emitProgress,
+  getParser
+} from "@aiready/core";
+import { readFileSync } from "fs";
+async function analyzeDocDrift(options) {
+  const files = await scanFiles(options);
+  const issues = [];
+  const staleMonths = options.staleMonths ?? 6;
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexity = 0;
+  let actualDrift = 0;
+  let processed = 0;
+  for (const file of files) {
+    processed++;
+    emitProgress(
+      processed,
+      files.length,
+      "doc-drift",
+      "analyzing files",
+      options.onProgress
+    );
+    const parser = getParser(file);
+    if (!parser) continue;
+    let code;
+    try {
+      code = readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    try {
+      await parser.initialize();
+      const parseResult = parser.parse(code, file);
+      let fileLineStamps;
+      for (const exp of parseResult.exports) {
+        if (exp.type === "function" || exp.type === "class") {
+          totalExports++;
+          if (!exp.documentation) {
+            uncommentedExports++;
+            if (exp.loc) {
+              const lines = exp.loc.end.line - exp.loc.start.line;
+              if (lines > 20) undocumentedComplexity++;
+            }
+          } else {
+            const doc = exp.documentation;
+            const docContent = doc.content;
+            if (exp.type === "function" && exp.parameters) {
+              const params = exp.parameters;
+              const missingParams = params.filter((p) => {
+                const regex = new RegExp(`\\b${p}\\b`, "i");
+                return !regex.test(docContent);
+              });
+              if (missingParams.length > 0) {
+                outdatedComments++;
+                issues.push({
+                  type: IssueType.DocDrift,
+                  severity: Severity.Major,
+                  message: `Documentation mismatch: function parameters (${missingParams.join(", ")}) are not mentioned in the docs.`,
+                  location: { file, line: exp.loc?.start.line || 1 }
+                });
+              }
+            }
+            if (exp.loc && doc.loc) {
+              if (!fileLineStamps) {
+                fileLineStamps = getFileCommitTimestamps(file);
+              }
+              const bodyModified = getLineRangeLastModifiedCached(
+                fileLineStamps,
+                exp.loc.start.line,
+                exp.loc.end.line
+              );
+              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 }
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(`Doc-drift: Failed to parse ${file}: ${error}`);
+      continue;
+    }
+  }
+  const riskResult = calculateDocDrift({
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity,
+    actualDrift
+  });
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity,
+      actualDrift
+    },
+    recommendations: riskResult.recommendations
+  };
+}
+
+export {
+  __require,
+  analyzeDocDrift
+};

package/dist/chunk-MAPV5YQR.mjs

@@ -0,0 +1,142 @@
+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,
+  Severity,
+  IssueType,
+  emitProgress,
+  getParser
+} from "@aiready/core";
+import { readFileSync } from "fs";
+async function analyzeDocDrift(options) {
+  const files = await scanFiles(options);
+  const issues = [];
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexity = 0;
+  let actualDrift = 0;
+  let processed = 0;
+  for (const file of files) {
+    processed++;
+    emitProgress(
+      processed,
+      files.length,
+      "doc-drift",
+      "analyzing files",
+      options.onProgress
+    );
+    const parser = getParser(file);
+    if (!parser) continue;
+    let code;
+    try {
+      code = readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    try {
+      await parser.initialize();
+      const parseResult = parser.parse(code, file);
+      let fileLineStamps;
+      for (const exp of parseResult.exports) {
+        if (exp.type === "function" || exp.type === "class") {
+          totalExports++;
+          if (!exp.documentation) {
+            uncommentedExports++;
+            if (exp.loc) {
+              const lines = exp.loc.end.line - exp.loc.start.line;
+              if (lines > 20) undocumentedComplexity++;
+            }
+          } else {
+            const doc = exp.documentation;
+            const docContent = doc.content;
+            if (exp.type === "function" && exp.parameters) {
+              const params = exp.parameters;
+              const missingParams = params.filter((p) => {
+                const regex = new RegExp(`\\b${p}\\b`, "i");
+                return !regex.test(docContent);
+              });
+              if (missingParams.length > 0) {
+                outdatedComments++;
+                issues.push({
+                  type: IssueType.DocDrift,
+                  severity: Severity.Major,
+                  message: `Documentation mismatch: function parameters (${missingParams.join(", ")}) are not mentioned in the docs.`,
+                  location: { file, line: exp.loc?.start.line || 1 }
+                });
+              }
+            }
+            if (exp.loc && doc.loc) {
+              if (!fileLineStamps) {
+                fileLineStamps = getFileCommitTimestamps(file);
+              }
+              const bodyModified = getLineRangeLastModifiedCached(
+                fileLineStamps,
+                exp.loc.start.line,
+                exp.loc.end.line
+              );
+              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 }
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(`Doc-drift: Failed to parse ${file}: ${error}`);
+      continue;
+    }
+  }
+  const riskResult = calculateDocDrift({
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity,
+    actualDrift
+  });
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity,
+      actualDrift
+    },
+    recommendations: riskResult.recommendations
+  };
+}
+
+export {
+  __require,
+  analyzeDocDrift
+};

package/dist/cli.js

@@ -41,14 +41,11 @@ var import_fs = require("fs");
 async function analyzeDocDrift(options) {
   const files = await (0, import_core.scanFiles)(options);
   const issues = [];
-  const staleMonths = options.staleMonths ?? 6;
-  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
   let uncommentedExports = 0;
   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) {
     processed++;

package/dist/cli.mjs

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

package/dist/index.d.mts

@@ -69,7 +69,11 @@ interface DocDriftReport {
 declare function analyzeDocDrift(options: DocDriftOptions): Promise<DocDriftReport>;
 
 /**
- * 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
  */
 declare function calculateDocDriftScore(report: DocDriftReport): ToolScoringOutput;
 

package/dist/index.d.ts

@@ -69,7 +69,11 @@ interface DocDriftReport {
 declare function analyzeDocDrift(options: DocDriftOptions): Promise<DocDriftReport>;
 
 /**
- * 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
  */
 declare function calculateDocDriftScore(report: DocDriftReport): ToolScoringOutput;
 

package/dist/index.js

@@ -36,14 +36,11 @@ var import_fs = require("fs");
 async function analyzeDocDrift(options) {
   const files = await (0, import_core.scanFiles)(options);
   const issues = [];
-  const staleMonths = options.staleMonths ?? 6;
-  const staleSeconds = staleMonths * 30 * 24 * 60 * 60;
   let uncommentedExports = 0;
   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) {
     processed++;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   analyzeDocDrift
-} from "./chunk-P74XAVQ3.mjs";
+} from "./chunk-MAPV5YQR.mjs";
 
 // src/index.ts
 import { ToolRegistry } from "@aiready/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/doc-drift",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "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.6"
+    "@aiready/core": "0.23.8"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/analyzer.ts

@@ -27,8 +27,7 @@ export async function analyzeDocDrift(
   // 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;
@@ -36,7 +35,7 @@ export async function analyzeDocDrift(
   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) {

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