@aiready/doc-drift 0.14.14 → 0.14.16

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/doc-drift@0.14.13 build /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.14.15 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
-CJS dist/cli.js   6.71 KB
-CJS dist/index.js 6.04 KB
-CJS ⚡️ Build success in 101ms
-ESM dist/index.mjs          989.00 B
+CJS dist/index.js 9.11 KB
+CJS dist/cli.js   9.79 KB
+CJS ⚡️ Build success in 286ms
 ESM dist/cli.mjs            1.07 KB
-ESM dist/chunk-GZDN7B4K.mjs 4.40 KB
-ESM ⚡️ Build success in 105ms
-DTS Build start
-DTS ⚡️ Build success in 7374ms
-DTS dist/cli.d.ts    108.00 B
-DTS dist/index.d.ts  2.48 KB
-DTS dist/cli.d.mts   108.00 B
-DTS dist/index.d.mts 2.48 KB
+ESM dist/index.mjs          989.00 B
+ESM dist/chunk-IQBAXGOK.mjs 7.48 KB
+ESM ⚡️ Build success in 287ms
+DTS Build start
+DTS ⚡️ Build success in 3510ms
+DTS dist/cli.d.ts    108.00 B
+DTS dist/index.d.ts  2.09 KB
+DTS dist/cli.d.mts   108.00 B
+DTS dist/index.d.mts 2.09 KB

package/.turbo/turbo-format-check.log

@@ -1,7 +1,7 @@
 
 
-> @aiready/doc-drift@0.14.13 format-check /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.14.15 format-check /Users/pengcao/projects/aiready/packages/doc-drift
 > prettier --check . --ignore-path ../../.prettierignore
 
 Checking formatting...
-package.jsonREADME.mdsrc/__tests__/analyzer.test.tssrc/__tests__/provider.test.tssrc/__tests__/scoring.test.tssrc/analyzer.tssrc/cli.tssrc/index.tssrc/provider.tssrc/scoring.tssrc/types.tstsconfig.jsonAll matched files use Prettier code style!
+package.jsonREADME.mdsrc/__tests__/analyzer.test.tssrc/__tests__/provider.test.tssrc/__tests__/scoring.test.tssrc/analyzer.tssrc/cli.tssrc/constants.tssrc/heuristics.tssrc/index.tssrc/provider.tssrc/scoring.tssrc/types.tstsconfig.jsonAll matched files use Prettier code style!

package/.turbo/turbo-lint$colon$fix.log

@@ -0,0 +1,2 @@
+
+

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
 
 
-> @aiready/doc-drift@0.14.13 lint /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.14.15 lint /Users/pengcao/projects/aiready/packages/doc-drift
 > eslint src --ext .ts
 

package/.turbo/turbo-test.log

@@ -1,19 +1,51 @@
 
 
-> @aiready/doc-drift@0.14.13 test /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.14.15 test /Users/pengcao/projects/aiready/packages/doc-drift
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/doc-drift
 
+[?2026h
+ ❯ src/__tests__/analyzer.test.ts [queued]
+
+ Test Files 0 passed (3)
+      Tests 0 passed (0)
+   Start at 23:35:29
+   Duration 213ms
+[?2026l[?2026h
+ ❯ src/__tests__/analyzer.test.ts [queued]
+ ❯ src/__tests__/provider.test.ts [queued]
+ ❯ src/__tests__/scoring.test.ts [queued]
+
+ Test Files 0 passed (3)
+      Tests 0 passed (0)
+   Start at 23:35:29
+   Duration 1.01s
+[?2026l[?2026h
+ ❯ src/__tests__/analyzer.test.ts [queued]
+ ❯ src/__tests__/provider.test.ts [queued]
+ ❯ src/__tests__/scoring.test.ts 0/2
+
+ Test Files 0 passed (3)
+      Tests 0 passed (2)
+   Start at 23:35:29
+   Duration 1.31s
+[?2026l[?2026h ✓ src/__tests__/scoring.test.ts (2 tests) 2ms
  ✓ src/__tests__/provider.test.ts (2 tests) 5ms
- ✓ src/__tests__/scoring.test.ts (2 tests) 2ms
- ✓ src/__tests__/analyzer.test.ts (1 test) 310ms
-     ✓ detects missing param documentation and uncommented complexity  304ms
+
+
+ ❯ src/__tests__/analyzer.test.ts 1/1
+
+ Test Files 2 passed (3)
+      Tests 5 passed (5)
+   Start at 23:35:29
+   Duration 1.41s
+[?2026l ✓ src/__tests__/analyzer.test.ts (1 test) 40ms
 
  Test Files  3 passed (3)
       Tests  5 passed (5)
-   Start at  20:52:15
-   Duration  6.39s (transform 2.68s, setup 0ms, import 14.19s, tests 316ms, environment 0ms)
+   Start at  23:35:29
+   Duration  1.51s (transform 823ms, setup 0ms, import 3.20s, tests 47ms, environment 0ms)
 
 [?25h

package/.turbo/turbo-type-check.log

@@ -1,5 +1,5 @@
 
 
-> @aiready/doc-drift@0.14.13 type-check /Users/pengcao/projects/aiready/packages/doc-drift
+> @aiready/doc-drift@0.14.15 type-check /Users/pengcao/projects/aiready/packages/doc-drift
 > tsc --noEmit
 

package/dist/chunk-35XBIDVM.mjs

@@ -0,0 +1,347 @@
+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";
+
+// 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"
+]);
+
+// 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 scanFiles(options);
+  const issues = [];
+  let uncommentedExports = 0;
+  let totalExports = 0;
+  let outdatedComments = 0;
+  let undocumentedComplexityCount = 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 (isUndocumentedComplexity(exp)) undocumentedComplexityCount++;
+          } else {
+            const doc = exp.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 (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 (hasTemporalDrift(bodyModified, docModified)) {
+                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: undocumentedComplexityCount,
+    actualDrift
+  });
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      functionsAnalyzed: totalExports,
+      score: riskResult.score,
+      rating: riskResult.rating
+    },
+    issues,
+    rawData: {
+      uncommentedExports,
+      totalExports,
+      outdatedComments,
+      undocumentedComplexity: undocumentedComplexityCount,
+      actualDrift
+    },
+    recommendations: riskResult.recommendations
+  };
+}
+
+export {
+  __require,
+  analyzeDocDrift
+};