@aiready/doc-drift 0.14.14 → 0.14.16

package/dist/index.js

@@ -32,13 +32,258 @@ var import_core2 = require("@aiready/core");
 // src/analyzer.ts
 var import_core = require("@aiready/core");
 var import_fs = require("fs");
+
+// src/constants.ts
+var DESCRIPTIVE_PARAMS = /* @__PURE__ */ new Set([
+  "data",
+  "item",
+  "value",
+  "key",
+  "index",
+  "id",
+  "name",
+  "type",
+  "config",
+  "options",
+  "params",
+  "args",
+  "input",
+  "output",
+  "result",
+  "response",
+  "request",
+  "callback",
+  "handler",
+  "event",
+  "error",
+  "message",
+  "context",
+  "file",
+  "path",
+  "url",
+  "source",
+  "target",
+  "content",
+  "body",
+  "payload",
+  "user",
+  "userid",
+  "user_id",
+  "starttime",
+  "endtime",
+  "duration",
+  "timeout",
+  "retry",
+  "count",
+  "limit",
+  "offset",
+  "page",
+  "size",
+  "length",
+  "width",
+  "height",
+  "depth",
+  "color",
+  "background",
+  "foreground",
+  "border",
+  "margin",
+  "padding",
+  "position",
+  "top",
+  "bottom",
+  "left",
+  "right",
+  "center",
+  "start",
+  "end",
+  "begin",
+  "finish",
+  "complete",
+  "pending",
+  "active",
+  "inactive",
+  "enabled",
+  "disabled",
+  "visible",
+  "hidden",
+  "open",
+  "closed",
+  "locked",
+  "unlocked",
+  "read",
+  "write",
+  "append",
+  "prepend",
+  "insert",
+  "replace",
+  "merge",
+  "split",
+  "join",
+  "filter",
+  "map",
+  "reduce",
+  "find",
+  "sort",
+  "reverse",
+  "unique",
+  "flatten",
+  "compact",
+  "chunk",
+  "zip",
+  "unzip",
+  "completed",
+  "failed",
+  "healthy",
+  "high",
+  "medium",
+  "low",
+  "running",
+  "stopped",
+  "title",
+  "subtitle",
+  "label",
+  "description",
+  "version",
+  "timestamp",
+  "date",
+  "time",
+  "status",
+  "mode",
+  "action",
+  "effect",
+  "resource",
+  "principal",
+  "statement",
+  "sid",
+  "allow",
+  "deny",
+  "roi",
+  "unifiedbudget",
+  "filepath",
+  "rootdir",
+  "fp",
+  "email",
+  "username",
+  "password",
+  "token",
+  "secret",
+  "apikey",
+  "api_key",
+  "baseurl",
+  "base_url",
+  "endpoint",
+  "method",
+  "headers",
+  "queryparams",
+  "query_params",
+  "bodyparams",
+  "body_params",
+  "formdata",
+  "form_data",
+  "filename",
+  "file_name",
+  "filetype",
+  "file_type",
+  "filesize",
+  "file_size",
+  "filecontent",
+  "file_content",
+  "fileurl",
+  "file_url",
+  "fileid",
+  "file_id",
+  "filekey",
+  "file_key",
+  "filepath",
+  "file_path",
+  "filedir",
+  "file_dir",
+  "fileext",
+  "file_ext",
+  "filebase",
+  "file_base",
+  "filenamewithoutext",
+  "file_name_without_ext",
+  "filedirname",
+  "file_dirname",
+  "filebasename",
+  "file_basename",
+  "fileextname",
+  "file_extname",
+  "fileroot",
+  "file_root",
+  "filesep",
+  "file_sep",
+  "filejoin",
+  "file_join",
+  "fileresolve",
+  "file_resolve",
+  "filenormalize",
+  "file_normalize",
+  "exp",
+  "ctx",
+  "options",
+  "done",
+  "next",
+  "reject",
+  "resolve",
+  "error",
+  "err",
+  "req",
+  "res",
+  "event",
+  "payload",
+  "metadata",
+  "params",
+  "props",
+  "state",
+  "dispatch",
+  "action",
+  "config",
+  "directory",
+  "useroptions",
+  "resultslength",
+  "totalissues",
+  "totaltokencost",
+  "elapsedtime"
+]);
+
+// src/heuristics.ts
+function getMissingParams(exp) {
+  if (exp.type !== "function" || !exp.parameters || !exp.documentation) {
+    return [];
+  }
+  const docContent = exp.documentation.content;
+  const params = exp.parameters;
+  return params.filter((p) => {
+    if (DESCRIPTIVE_PARAMS.has(p.toLowerCase())) {
+      return false;
+    }
+    const regex = new RegExp(`\\b${p}\\b`);
+    return !regex.test(docContent);
+  });
+}
+function isUndocumentedComplexity(exp) {
+  if (exp.documentation) return false;
+  if (!exp.loc) return false;
+  const lines = exp.loc.end.line - exp.loc.start.line;
+  return lines > 20;
+}
+function hasTemporalDrift(bodyModified, docModified) {
+  if (bodyModified <= 0 || docModified <= 0) return false;
+  const DRIFT_THRESHOLD_SECONDS = 24 * 60 * 60;
+  return bodyModified - docModified > DRIFT_THRESHOLD_SECONDS;
+}
+
+// src/analyzer.ts
 async function analyzeDocDrift(options) {
   const files = await (0, import_core.scanFiles)(options);
   const issues = [];
   let uncommentedExports = 0;
   let totalExports = 0;
   let outdatedComments = 0;
-  let undocumentedComplexity = 0;
+  let undocumentedComplexityCount = 0;
   let actualDrift = 0;
   let processed = 0;
   for (const file of files) {
@@ -67,33 +312,22 @@ async function analyzeDocDrift(options) {
           totalExports++;
           if (!exp.documentation) {
             uncommentedExports++;
-            if (exp.loc) {
-              const lines = exp.loc.end.line - exp.loc.start.line;
-              if (lines > 20) undocumentedComplexity++;
-            }
+            if (isUndocumentedComplexity(exp)) undocumentedComplexityCount++;
           } 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);
+            const missingParams = getMissingParams(exp);
+            if (missingParams.length > 0) {
+              outdatedComments++;
+              issues.push({
+                type: import_core.IssueType.DocDrift,
+                severity: import_core.Severity.Major,
+                message: `Documentation mismatch: function parameters (${missingParams.join(", ")}) are not mentioned in the docs.`,
+                location: { file, line: exp.loc?.start.line || 1 }
               });
-              if (missingParams.length > 0) {
-                outdatedComments++;
-                issues.push({
-                  type: import_core.IssueType.DocDrift,
-                  severity: import_core.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) {
+              if (!fileLineStamps)
                 fileLineStamps = (0, import_core.getFileCommitTimestamps)(file);
-              }
               const bodyModified = (0, import_core.getLineRangeLastModifiedCached)(
                 fileLineStamps,
                 exp.loc.start.line,
@@ -104,17 +338,14 @@ async function analyzeDocDrift(options) {
                 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 }
-                  });
-                }
+              if (hasTemporalDrift(bodyModified, docModified)) {
+                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 }
+                });
               }
             }
           }
@@ -129,7 +360,7 @@ async function analyzeDocDrift(options) {
     uncommentedExports,
     totalExports,
     outdatedComments,
-    undocumentedComplexity,
+    undocumentedComplexity: undocumentedComplexityCount,
     actualDrift
   });
   return {
@@ -144,7 +375,7 @@ async function analyzeDocDrift(options) {
       uncommentedExports,
       totalExports,
       outdatedComments,
-      undocumentedComplexity,
+      undocumentedComplexity: undocumentedComplexityCount,
       actualDrift
     },
     recommendations: riskResult.recommendations

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/doc-drift",
-  "version": "0.14.14",
+  "version": "0.14.16",
   "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.24.15"
+    "@aiready/core": "0.24.19"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -33,6 +33,8 @@
     "test:watch": "vitest",
     "lint": "eslint src --ext .ts",
     "type-check": "tsc --noEmit",
-    "format-check": "prettier --check . --ignore-path ../../.prettierignore"
+    "format-check": "prettier --check . --ignore-path ../../.prettierignore",
+    "format": "prettier --write . --ignore-path ../../.prettierignore",
+    "lint:fix": "eslint . --fix"
   }
 }

package/src/analyzer.ts

@@ -10,33 +10,27 @@ import {
 } from '@aiready/core';
 import type { DocDriftOptions, DocDriftReport, DocDriftIssue } from './types';
 import { readFileSync } from 'fs';
+import {
+  getMissingParams,
+  isUndocumentedComplexity,
+  hasTemporalDrift,
+} from './heuristics';
 
 /**
  * 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 staleSeconds = staleMonths * 30 * 24 * 60 * 60; // Unused, removed
 
   let uncommentedExports = 0;
   let totalExports = 0;
   let outdatedComments = 0;
-  let undocumentedComplexity = 0;
+  let undocumentedComplexityCount = 0;
   let actualDrift = 0;
 
-  // const now = Math.floor(Date.now() / 1000); // Unused, removed
-
   let processed = 0;
   for (const file of files) {
     processed++;
@@ -59,79 +53,57 @@ export async function analyzeDocDrift(
     }
 
     try {
-      // Initialize parser (it's a singleton in core, but ensures WASM is loaded)
       await parser.initialize();
       const parseResult = parser.parse(code, file);
 
       let fileLineStamps: Record<number, number> | undefined;
 
       for (const exp of parseResult.exports) {
-        // Only analyze functions and classes for documentation drift
         if (exp.type === 'function' || exp.type === 'class') {
           totalExports++;
 
           if (!exp.documentation) {
             uncommentedExports++;
-
-            // Complexity check (heuristic based on line count if range available)
-            if (exp.loc) {
-              const lines = exp.loc.end.line - exp.loc.start.line;
-              if (lines > 20) undocumentedComplexity++;
-            }
+            if (isUndocumentedComplexity(exp)) undocumentedComplexityCount++;
           } else {
             const doc = exp.documentation;
-            const docContent = doc.content;
 
-            // Signature mismatch detection (generalized heuristic)
-            if (exp.type === 'function' && exp.parameters) {
-              const params = exp.parameters;
-              // Check if params mentioned in doc (standard @param or simple mention)
-              const missingParams = params.filter((p) => {
-                const regex = new RegExp(`\\b${p}\\b`);
-                return !regex.test(docContent);
+            // Check for missing parameters in documentation
+            const missingParams = getMissingParams(exp);
+            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 (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 },
-                });
-              }
             }
 
-            // Timestamp comparison for temporal drift
+            // Check for temporal drift
             if (exp.loc && doc.loc) {
-              if (!fileLineStamps) {
+              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) {
-                // 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 },
-                  });
-                }
+              if (hasTemporalDrift(bodyModified, docModified)) {
+                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 },
+                });
               }
             }
           }
@@ -147,7 +119,7 @@ export async function analyzeDocDrift(
     uncommentedExports,
     totalExports,
     outdatedComments,
-    undocumentedComplexity,
+    undocumentedComplexity: undocumentedComplexityCount,
     actualDrift,
   });
 
@@ -163,7 +135,7 @@ export async function analyzeDocDrift(
       uncommentedExports,
       totalExports,
       outdatedComments,
-      undocumentedComplexity,
+      undocumentedComplexity: undocumentedComplexityCount,
       actualDrift,
     },
     recommendations: riskResult.recommendations,