@aiready/doc-drift 0.9.2 → 0.9.3

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/doc-drift@0.9.1 build /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.9.2 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
 
- WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]       8:13:04 pm
+ WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]       7:57:09 pm
 
     package.json:33:6:
       33 │       "types": "./dist/index.d.ts"
@@ -31,7 +31,7 @@
 
 
 
- WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]       8:13:04 pm
+ WARN  ▲ [WARNING] The condition "types" here will never be used as it comes after both "import" and "require" [package.json]       7:57:09 pm
 
     package.json:33:6:
       33 │       "types": "./dist/index.d.ts"
@@ -51,16 +51,16 @@
 
 
 
-CJS dist/cli.js   7.52 KB
-CJS dist/index.js 5.50 KB
-CJS ⚡️ Build success in 332ms
+CJS dist/index.js 5.57 KB
+CJS dist/cli.js   7.60 KB
+CJS ⚡️ Build success in 38ms
 ESM dist/cli.mjs            1.39 KB
 ESM dist/index.mjs          88.00 B
-ESM dist/chunk-FMK4O4O7.mjs 4.79 KB
-ESM ⚡️ Build success in 331ms
+ESM dist/chunk-CGSYYULO.mjs 4.85 KB
+ESM ⚡️ Build success in 38ms
 DTS Build start
-DTS ⚡️ Build success in 3595ms
+DTS ⚡️ Build success in 2875ms
 DTS dist/cli.d.ts    108.00 B
-DTS dist/index.d.ts  950.00 B
+DTS dist/index.d.ts  968.00 B
 DTS dist/cli.d.mts   108.00 B
-DTS dist/index.d.mts 950.00 B
+DTS dist/index.d.mts 968.00 B

package/.turbo/turbo-test.log

@@ -1,16 +1,16 @@
 
 
-> @aiready/doc-drift@0.9.1 test /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.9.2 test /Users/pengcao/projects/aiready/packages/doc-drift
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/doc-drift
 
- ✓ src/__tests__/analyzer.test.ts (1 test) 39ms
+ ✓ src/__tests__/analyzer.test.ts (1 test) 273ms
 
  Test Files  1 passed (1)
       Tests  1 passed (1)
-   Start at  20:13:26
-   Duration  520ms (transform 120ms, setup 0ms, import 335ms, tests 39ms, environment 0ms)
+   Start at  20:00:26
+   Duration  2.33s (transform 304ms, setup 0ms, import 1.34s, tests 273ms, environment 0ms)
 
 [?25h

package/dist/chunk-CGSYYULO.mjs

@@ -0,0 +1,145 @@
+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
+} from "@aiready/core";
+import { readFileSync } from "fs";
+import { parse } from "@typescript-eslint/typescript-estree";
+async function analyzeDocDrift(options) {
+  const files = await 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;
+  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: IssueType.DocDrift,
+                  severity: 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: IssueType.DocDrift,
+                  severity: 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

@@ -101,8 +101,8 @@ async function analyzeDocDrift(options) {
               if (missingParams.length > 0) {
                 outdatedComments++;
                 issues.push({
-                  type: "doc-drift",
-                  severity: "major",
+                  type: import_core.IssueType.DocDrift,
+                  severity: import_core.Severity.Major,
                   message: `JSDoc @param mismatch: function has parameters (${missingParams.join(", ")}) not documented in JSDoc.`,
                   location: { file, line: nodeLine }
                 });
@@ -126,8 +126,8 @@ async function analyzeDocDrift(options) {
               if (now - commentModified > staleSeconds && bodyModified - commentModified > staleSeconds / 2) {
                 outdatedComments++;
                 issues.push({
-                  type: "doc-drift",
-                  severity: "minor",
+                  type: import_core.IssueType.DocDrift,
+                  severity: import_core.Severity.Minor,
                   message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
                   location: { file, line: jsdoc.loc.start.line }
                 });

package/dist/cli.mjs

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

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Issue, ScanOptions } from '@aiready/core';
+import { Issue, IssueType, ScanOptions } from '@aiready/core';
 
 interface DocDriftOptions extends ScanOptions {
     /** Maximum commit distance to check for drift */
@@ -7,7 +7,7 @@ interface DocDriftOptions extends ScanOptions {
     staleMonths?: number;
 }
 interface DocDriftIssue extends Issue {
-    type: 'doc-drift';
+    type: IssueType.DocDrift;
 }
 interface DocDriftReport {
     summary: {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Issue, ScanOptions } from '@aiready/core';
+import { Issue, IssueType, ScanOptions } from '@aiready/core';
 
 interface DocDriftOptions extends ScanOptions {
     /** Maximum commit distance to check for drift */
@@ -7,7 +7,7 @@ interface DocDriftOptions extends ScanOptions {
     staleMonths?: number;
 }
 interface DocDriftIssue extends Issue {
-    type: 'doc-drift';
+    type: IssueType.DocDrift;
 }
 interface DocDriftReport {
     summary: {

package/dist/index.js

@@ -90,8 +90,8 @@ async function analyzeDocDrift(options) {
               if (missingParams.length > 0) {
                 outdatedComments++;
                 issues.push({
-                  type: "doc-drift",
-                  severity: "major",
+                  type: import_core.IssueType.DocDrift,
+                  severity: import_core.Severity.Major,
                   message: `JSDoc @param mismatch: function has parameters (${missingParams.join(", ")}) not documented in JSDoc.`,
                   location: { file, line: nodeLine }
                 });
@@ -115,8 +115,8 @@ async function analyzeDocDrift(options) {
               if (now - commentModified > staleSeconds && bodyModified - commentModified > staleSeconds / 2) {
                 outdatedComments++;
                 issues.push({
-                  type: "doc-drift",
-                  severity: "minor",
+                  type: import_core.IssueType.DocDrift,
+                  severity: import_core.Severity.Minor,
                   message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
                   location: { file, line: jsdoc.loc.start.line }
                 });

package/dist/index.mjs

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

package/package.json

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

package/src/analyzer.ts

@@ -3,6 +3,8 @@ import {
   calculateDocDrift,
   getFileCommitTimestamps,
   getLineRangeLastModifiedCached,
+  Severity,
+  IssueType,
 } from '@aiready/core';
 import type { DocDriftOptions, DocDriftReport, DocDriftIssue } from './types';
 import { readFileSync } from 'fs';
@@ -103,8 +105,8 @@ export async function analyzeDocDrift(
               if (missingParams.length > 0) {
                 outdatedComments++;
                 issues.push({
-                  type: 'doc-drift',
-                  severity: 'major',
+                  type: IssueType.DocDrift,
+                  severity: Severity.Major,
                   message: `JSDoc @param mismatch: function has parameters (${missingParams.join(', ')}) not documented in JSDoc.`,
                   location: { file, line: nodeLine },
                 });
@@ -135,8 +137,8 @@ export async function analyzeDocDrift(
               ) {
                 outdatedComments++;
                 issues.push({
-                  type: 'doc-drift',
-                  severity: 'minor',
+                  type: IssueType.DocDrift,
+                  severity: Severity.Minor,
                   message: `JSDoc is significantly older than the function body implementation. Code may have drifted.`,
                   location: { file, line: jsdoc.loc.start.line },
                 });

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ScanOptions, Issue } from '@aiready/core';
+import type { ScanOptions, Issue, IssueType } from '@aiready/core';
 
 export interface DocDriftOptions extends ScanOptions {
   /** Maximum commit distance to check for drift */
@@ -8,7 +8,7 @@ export interface DocDriftOptions extends ScanOptions {
 }
 
 export interface DocDriftIssue extends Issue {
-  type: 'doc-drift';
+  type: IssueType.DocDrift;
 }
 
 export interface DocDriftReport {