@aiready/doc-drift 0.14.14 → 0.14.16

package/src/constants.ts

@@ -0,0 +1,214 @@
+export const DESCRIPTIVE_PARAMS = 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',
+]);

package/src/heuristics.ts

@@ -0,0 +1,53 @@
+import { DESCRIPTIVE_PARAMS } from './constants';
+import { ExportInfo } from '@aiready/core';
+
+/**
+ * Checks if documentation for an export correctly covers its parameters.
+ * Returns a list of missing parameters that are NOT in DESCRIPTIVE_PARAMS.
+ */
+export function getMissingParams(exp: ExportInfo): string[] {
+  if (exp.type !== 'function' || !exp.parameters || !exp.documentation) {
+    return [];
+  }
+
+  const docContent = exp.documentation.content;
+  const params = exp.parameters;
+
+  return params.filter((p) => {
+    // Skip descriptive parameters that don't need documentation
+    if (DESCRIPTIVE_PARAMS.has(p.toLowerCase())) {
+      return false;
+    }
+    const regex = new RegExp(`\\b${p}\\b`);
+    return !regex.test(docContent);
+  });
+}
+
+/**
+ * Heuristic check if an export has high complexity but is undocumented.
+ */
+export function isUndocumentedComplexity(exp: ExportInfo): boolean {
+  if (exp.documentation) return false;
+  if (!exp.loc) return false;
+
+  const lines = exp.loc.end.line - exp.loc.start.line;
+  // Heuristic: more than 20 lines of code usually deserves documentation
+  return lines > 20;
+}
+
+/**
+ * Checks for temporal drift between documentation and code.
+ *
+ * @param bodyModified - Timestamp of last code modification
+ * @param docModified - Timestamp of last documentation modification
+ */
+export function hasTemporalDrift(
+  bodyModified: number,
+  docModified: number
+): boolean {
+  if (bodyModified <= 0 || docModified <= 0) return false;
+
+  // If body was modified more than 1 day AFTER the documentation
+  const DRIFT_THRESHOLD_SECONDS = 24 * 60 * 60;
+  return bodyModified - docModified > DRIFT_THRESHOLD_SECONDS;
+}