@aiready/doc-drift 0.14.15 → 0.14.17

package/dist/chunk-57NUPDIO.mjs

@@ -0,0 +1,357 @@
+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",
+  "exp",
+  "ctx",
+  "options",
+  "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 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
+};

package/dist/chunk-IQBAXGOK.mjs

@@ -0,0 +1,373 @@
+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",
+  "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 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
+};