@aiready/doc-drift 0.13.19 → 0.13.20

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/doc-drift@0.13.19 build /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.13.20 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,15 +9,15 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/index.mjs          2.59 KB
-ESM dist/chunk-DEXSCXHS.mjs 4.39 KB
+CJS dist/cli.js   7.11 KB
+CJS dist/index.js 7.71 KB
+CJS ⚡️ Build success in 538ms
+ESM dist/chunk-GZDN7B4K.mjs 4.40 KB
 ESM dist/cli.mjs            1.39 KB
-ESM ⚡️ Build success in 209ms
-CJS dist/index.js 7.70 KB
-CJS dist/cli.js   7.10 KB
-CJS ⚡️ Build success in 209ms
+ESM dist/index.mjs          2.59 KB
+ESM ⚡️ Build success in 538ms
 DTS Build start
-DTS ⚡️ Build success in 5549ms
+DTS ⚡️ Build success in 11801ms
 DTS dist/cli.d.ts    108.00 B
 DTS dist/index.d.ts  2.83 KB
 DTS dist/cli.d.mts   108.00 B

package/.turbo/turbo-test.log

@@ -1,18 +1,19 @@
 
 
-> @aiready/doc-drift@0.13.18 test /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.13.19 test /Users/pengcao/projects/aiready/packages/doc-drift
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/doc-drift
 
- ✓ src/__tests__/provider.test.ts (2 tests) 4ms
- ✓ src/__tests__/scoring.test.ts (2 tests) 3ms
- ✓ src/__tests__/analyzer.test.ts (1 test) 205ms
+ ✓ src/__tests__/scoring.test.ts (2 tests) 4ms
+ ✓ src/__tests__/analyzer.test.ts (1 test) 708ms
+     ✓ detects missing param documentation and uncommented complexity  462ms
+ ✓ src/__tests__/provider.test.ts (2 tests) 137ms
 
  Test Files  3 passed (3)
       Tests  5 passed (5)
-   Start at  13:03:36
-   Duration  4.40s (transform 1.07s, setup 0ms, import 9.17s, tests 213ms, environment 0ms)
+   Start at  23:31:08
+   Duration  11.40s (transform 5.06s, setup 0ms, import 27.10s, tests 848ms, environment 0ms)
 
 [?25h

package/dist/chunk-GZDN7B4K.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 = await 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`);
+                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

@@ -56,7 +56,7 @@ async function analyzeDocDrift(options) {
       "analyzing files",
       options.onProgress
     );
-    const parser = (0, import_core.getParser)(file);
+    const parser = await (0, import_core.getParser)(file);
     if (!parser) continue;
     let code;
     try {

package/dist/cli.mjs

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

package/dist/index.js

@@ -51,7 +51,7 @@ async function analyzeDocDrift(options) {
       "analyzing files",
       options.onProgress
     );
-    const parser = (0, import_core.getParser)(file);
+    const parser = await (0, import_core.getParser)(file);
     if (!parser) continue;
     let code;
     try {

package/dist/index.mjs

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

package/package.json

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

package/src/analyzer.ts

@@ -48,7 +48,7 @@ export async function analyzeDocDrift(
       options.onProgress
     );
 
-    const parser = getParser(file);
+    const parser = await getParser(file);
     if (!parser) continue;
 
     let code: string;