@prabhat-singh/docdrift 0.0.0-stage → 0.1.0

package/src/check.js

@@ -0,0 +1,228 @@
+import { relative, sep } from 'node:path';
+
+import { scanJava } from './scan.js';
+import { scanDocs } from './docs.js';
+import { compare, normalizePath } from './match.js';
+
+const FRAMEWORK_PREFIXES = [
+  '/actuator',
+  '/swagger-ui',
+  '/v3/api-docs',
+  '/v2/api-docs',
+  '/swagger-resources',
+  '/h2-console',
+  '/error',
+];
+
+/**
+ * Run the whole drift check for a project directory.
+ *
+ * @param {string} codeDir directory with .java sources
+ * @param {string} [docsDir] directory with README.md/docs, defaults to codeDir
+ * @param {object | null} [style] optional createStyle() result for colored output
+ * @param {{ strict?: boolean, codeEndpoints?: object[] }} [options] strict reports framework endpoints as stale
+ * @returns {{ report: string, exitCode: number, code: object[], docs: object[], result: object }}
+ */
+export function check(codeDir, docsDir = codeDir, style = null, options = {}) {
+  const code = Array.isArray(options.codeEndpoints)
+    ? options.codeEndpoints
+    : scanJava(codeDir);
+  const docs = scanDocs(docsDir);
+
+  if (docs.length === 0) {
+    const message = `No endpoints are documented in ${docsDir}, nothing to compare (${code.length} endpoints found in code).`;
+    return {
+      code,
+      docs,
+      result: { matched: 0, stale: [], undocumented: [] },
+      report: style?.enabled ? style.warning(message) : message,
+      exitCode: 0,
+    };
+  }
+
+  const result = compare(code, docs);
+  const strict = options.strict === true;
+  const stale = strict
+    ? result.stale
+    : result.stale.filter((endpoint) => !isFrameworkPath(endpoint.path));
+  const ignored = strict
+    ? []
+    : result.stale.filter((endpoint) => isFrameworkPath(endpoint.path));
+  const undocumented = result.undocumented;
+  const drift = stale.length + undocumented.length;
+  const documentedCount = new Set(
+    docs.map(
+      (endpoint) => `${endpoint.method} ${normalizePath(endpoint.path)}`,
+    ),
+  ).size;
+  const matchedCount = Math.min(countMatched(code, docs), code.length);
+  const ignoredText = ignored.length > 0 ? frameworkLine(ignored) : null;
+  const lines = [];
+
+  if (style?.enabled) {
+    lines.push(
+      `${style.muted('docdrift check:')} ${style.bold(style.success(String(code.length)))} code endpoints, ${style.bold(style.success(String(documentedCount)))} documented endpoints, ${style.bold(style.success(String(matchedCount)))} matched`,
+    );
+    if (ignoredText) lines.push(ignoredText);
+    lines.push('');
+
+    if (drift > 0) {
+      const methodWidth = Math.max(
+        0,
+        ...stale.map((endpoint) => endpoint.method.length),
+        ...undocumented.map((endpoint) => endpoint.method.length),
+      );
+
+      if (stale.length > 0) {
+        lines.push(style.danger('STALE (documented, not in code)'));
+        lines.push(...formatEndpointList(stale, docsDir, methodWidth, style));
+        lines.push('');
+      }
+
+      if (undocumented.length > 0) {
+        lines.push(style.danger('UNDOCUMENTED (in code, not documented)'));
+        lines.push(
+          ...formatEndpointList(
+            undocumented,
+            codeDir,
+            methodWidth,
+            style,
+          ),
+        );
+        lines.push('');
+      }
+    }
+
+    lines.push(
+      drift === 0
+        ? style.success('✔ No drift found')
+        : style.danger(
+            `✖ ${stale.length} stale, ${undocumented.length} undocumented`,
+          ),
+    );
+  } else {
+    lines.push(
+      `docdrift check: ${code.length} code endpoints, ${documentedCount} documented endpoints, ${matchedCount} matched`,
+    );
+    if (ignoredText) lines.push(ignoredText);
+    lines.push('');
+
+    if (drift === 0) {
+      lines.push('No drift found.');
+    } else {
+      const methodWidth = Math.max(
+        0,
+        ...stale.map((endpoint) => endpoint.method.length),
+        ...undocumented.map((endpoint) => endpoint.method.length),
+      );
+
+      if (stale.length > 0) {
+        lines.push('STALE (documented, not in code)');
+        lines.push(...formatEndpointList(stale, docsDir, methodWidth));
+        lines.push('');
+      }
+
+      if (undocumented.length > 0) {
+        lines.push('UNDOCUMENTED (in code, not documented)');
+        lines.push(
+          ...formatEndpointList(undocumented, codeDir, methodWidth),
+        );
+        lines.push('');
+      }
+    }
+  }
+
+  return {
+    code,
+    docs,
+    result,
+    report: lines.join('\n').trimEnd(),
+    exitCode: drift === 0 ? 0 : 1,
+  };
+}
+
+// Count each documented (METHOD, normalised path) once, so a duplicate entry
+// does not inflate the header, and never exceed the number of code endpoints.
+function countMatched(codeEndpoints, docEndpoints) {
+  const matchedKeys = new Set();
+
+  for (const docEndpoint of docEndpoints) {
+    if (
+      codeEndpoints.some((codeEndpoint) =>
+        codeCovers(codeEndpoint, docEndpoint),
+      )
+    ) {
+      matchedKeys.add(
+        `${docEndpoint.method} ${normalizePath(docEndpoint.path)}`,
+      );
+    }
+  }
+
+  return matchedKeys.size;
+}
+
+function codeCovers(codeEndpoint, docEndpoint) {
+  if (normalizePath(codeEndpoint.path) !== normalizePath(docEndpoint.path)) {
+    return false;
+  }
+
+  const methods = String(codeEndpoint.method ?? '')
+    .split('|')
+    .map((method) => method.trim());
+
+  return methods.includes('ANY') || methods.includes(docEndpoint.method);
+}
+
+function isFrameworkPath(path) {
+  const normalized = normalizePath(path);
+  return FRAMEWORK_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+function frameworkLine(endpoints) {
+  const labels = [...endpoints]
+    .sort(
+      (a, b) =>
+        compareText(normalizePath(a.path), normalizePath(b.path)) ||
+        compareText(a.method, b.method),
+    )
+    .map((endpoint) => `${endpoint.method} ${endpoint.path}`);
+
+  return `Ignored ${endpoints.length} framework endpoint(s) documented but provided by libraries: ${labels.join(', ')}`;
+}
+
+/**
+ * Format endpoints as "METHOD PATH (relative/file.java:line)", sorted by path
+ * and then method, with the method column padded to align the paths.
+ */
+export function formatEndpointList(
+  endpoints,
+  baseDir,
+  methodWidth = 0,
+  style = null,
+) {
+  return [...endpoints]
+    .sort(
+      (a, b) =>
+        compareText(a.path, b.path) || compareText(a.method, b.method),
+    )
+    .map((endpoint) => {
+      const method = endpoint.method.padEnd(methodWidth);
+      const where = `${relativeFile(baseDir, endpoint.file)}:${endpoint.line}`;
+
+      if (style?.enabled) {
+        return `  ${style.success(method)} ${endpoint.path} (${style.muted(where)})`;
+      }
+
+      return `  ${method} ${endpoint.path} (${where})`;
+    });
+}
+
+function relativeFile(baseDir, file) {
+  return relative(baseDir, file).split(sep).join('/');
+}
+
+function compareText(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}

package/src/config.js

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const REQUIRED = ['DOCDRIFT_BASE_URL', 'DOCDRIFT_MODEL'];
+const API_KEY = 'DOCDRIFT_API_KEY';
+
+/**
+ * Load config from the environment, falling back to a .env file in `cwd`.
+ * Real environment variables win over .env values.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, cwd?: string }} [options]
+ * @returns {{ baseUrl: string, apiKey: string, model: string } | { error: string }}
+ */
+export function loadConfig({ env = process.env, cwd = process.cwd() } = {}) {
+  const fileValues = readDotEnv(join(cwd, '.env'));
+
+  const read = (name) => {
+    const fromEnv = env[name];
+    if (fromEnv) return fromEnv;
+    return fileValues[name] ?? '';
+  };
+
+  const baseUrl = read('DOCDRIFT_BASE_URL');
+  const model = read('DOCDRIFT_MODEL');
+  const apiKey = read(API_KEY);
+
+  const missing = REQUIRED.filter((name) => !read(name));
+  if (!apiKey && !isLocal(baseUrl)) missing.push(API_KEY);
+
+  if (missing.length > 0) {
+    return {
+      error: `Missing ${missing.join(', ')}. Set these as environment variables or in .env (see .env.example).`,
+    };
+  }
+
+  return { baseUrl, apiKey, model };
+}
+
+function readDotEnv(path) {
+  if (!existsSync(path)) return {};
+
+  const values = {};
+  for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const separator = trimmed.indexOf('=');
+    if (separator === -1) continue;
+
+    const key = trimmed.slice(0, separator).trim();
+    let value = trimmed.slice(separator + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) values[key] = value;
+  }
+
+  return values;
+}
+
+function isLocal(baseUrl) {
+  if (!baseUrl) return false;
+
+  try {
+    const { hostname } = new URL(baseUrl);
+    return hostname === 'localhost' || hostname === '127.0.0.1';
+  } catch {
+    return /^(?:https?:\/\/)?(?:localhost|127\.0\.0\.1)(?::\d+)?(?:\/|$)/.test(
+      baseUrl,
+    );
+  }
+}

package/src/docs.js

@@ -0,0 +1,99 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+// METHOD, then separators, then a path that starts with "/". The path stops at
+// any character that ends an endpoint in prose, tables or inline code.
+const ENDPOINT_RE =
+  /\b(GET|POST|PUT|DELETE|PATCH)[ \t`|*]+\/[^\s`|)\]"'<>;,?*]*/g;
+
+/**
+ * Scan Markdown docs for documented REST endpoints.
+ *
+ * @param {string} dir project root containing README.md and/or docs/
+ * @returns {{ method: string, path: string, file: string, line: number }[]}
+ */
+export function scanDocs(dir) {
+  const endpoints = [];
+
+  for (const file of collectMarkdownFiles(dir)) {
+    const text = readFileSync(file, 'utf8');
+    for (const endpoint of extractFromText(text)) {
+      endpoints.push({ ...endpoint, file });
+    }
+  }
+
+  return endpoints.sort(
+    (a, b) => compare(a.file, b.file) || a.line - b.line,
+  ).map(({ method, path, file, line }) => ({ method, path, file, line }));
+}
+
+/**
+ * Extract documented endpoints from a Markdown string.
+ *
+ * @param {string} text Markdown content
+ * @returns {{ method: string, path: string, line: number }[]}
+ */
+export function extractFromText(text) {
+  const found = [];
+
+  ENDPOINT_RE.lastIndex = 0;
+  let match;
+  while ((match = ENDPOINT_RE.exec(String(text ?? ''))) !== null) {
+    const method = match[1];
+    let path = match[0].slice(method.length).replace(/^[ \t`|*]+/, '');
+    path = path.split('?')[0].replace(/[.:]+$/, '');
+    if (!path.startsWith('/')) continue;
+
+    found.push({ method, path, line: lineOf(text, match.index) });
+  }
+
+  return found;
+}
+
+function collectMarkdownFiles(dir) {
+  const files = [];
+
+  if (!existsSync(dir)) return files;
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries.sort((a, b) => compare(a.name, b.name))) {
+    if (entry.isFile() && entry.name.toLowerCase() === 'readme.md') {
+      files.push(join(dir, entry.name));
+    }
+  }
+
+  const docsDir = join(dir, 'docs');
+  if (existsSync(docsDir) && statSync(docsDir).isDirectory()) {
+    walkMarkdown(docsDir, files);
+  }
+
+  return files;
+}
+
+function walkMarkdown(current, files) {
+  const entries = readdirSync(current, { withFileTypes: true });
+  for (const entry of entries.sort((a, b) => compare(a.name, b.name))) {
+    const full = join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) walkMarkdown(full, files);
+    } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+      files.push(full);
+    }
+  }
+}
+
+function compare(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) {
+    if (text[i] === '\n') line += 1;
+  }
+  return line;
+}

package/src/fix.js

@@ -0,0 +1,299 @@
+import { writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { compare, normalizePath } from './match.js';
+import { extractFromText } from './docs.js';
+
+/**
+ * Build the writer conversation for a fix attempt.
+ *
+ * @param {{ codeEndpoints: object[], docEndpoints: object[], readmeText: string }} input
+ * @returns {{ role: string, content: string }[]}
+ */
+export function buildWriterMessages({ codeEndpoints, docEndpoints, readmeText }) {
+  const { stale, undocumented } = compare(codeEndpoints, docEndpoints);
+
+  const system = [
+    'You update API documentation.',
+    'Return ONLY the full updated README in Markdown, with no commentary and no code fences around it.',
+    'Mention only endpoints from the lists below, plus endpoints already present in the README that also exist in the code.',
+    'Never invent endpoints, paths or HTTP methods.',
+    'Remove every STALE endpoint and add every UNDOCUMENTED endpoint.',
+    'Place each added endpoint in the section whose path prefix matches it, and create a new section if none exists.',
+    'Keep the existing formatting, wording and order of everything else.',
+  ].join(' ');
+
+  const user = [
+    'Current README:',
+    '"""',
+    readmeText,
+    '"""',
+    '',
+    'STALE endpoints to remove (documented, not in code):',
+    listEndpoints(stale),
+    '',
+    'UNDOCUMENTED endpoints to add (in code, not documented):',
+    listEndpoints(undocumented),
+  ].join('\n');
+
+  return [
+    { role: 'system', content: system },
+    { role: 'user', content: user },
+  ];
+}
+
+/**
+ * Ask the writer for a README fix and verify it with plain code.
+ *
+ * @param {{
+ *   codeEndpoints: object[],
+ *   docEndpoints: object[],
+ *   readmeText: string,
+ *   chatFn: (messages: { role: string, content: string }[]) => Promise<string>,
+ *   maxRetries?: number,
+ * }} input
+ * @returns {Promise<{
+ *   status: string, draft?: string, invented?: object[], missing?: object[],
+ *   leftover?: object[], attempts?: number,
+ * }>}
+ */
+export async function fixDocs({
+  codeEndpoints,
+  docEndpoints,
+  readmeText,
+  chatFn,
+  maxRetries = 2,
+}) {
+  const { stale, undocumented } = compare(codeEndpoints, docEndpoints);
+  if (stale.length === 0 && undocumented.length === 0) {
+    return { status: 'NO_DRIFT' };
+  }
+
+  const messages = buildWriterMessages({
+    codeEndpoints,
+    docEndpoints,
+    readmeText,
+  });
+
+  let attempts = 0;
+  let draft = '';
+  let problems = { invented: [], missing: [], leftover: [] };
+
+  while (attempts <= maxRetries) {
+    attempts += 1;
+    draft = cleanDraft(await chatFn(messages));
+    problems = verifyDraft(draft, codeEndpoints, undocumented, stale);
+
+    if (hasNoProblems(problems)) {
+      return { status: 'VERIFIED', draft, ...problems, attempts };
+    }
+
+    if (attempts > maxRetries) break;
+
+    messages.push({ role: 'assistant', content: draft });
+    messages.push({ role: 'user', content: problemsMessage(problems) });
+  }
+
+  return { status: 'UNVERIFIED', draft, ...problems, attempts };
+}
+
+/**
+ * Write the draft next to the README as README.drift.md, never overwriting it.
+ *
+ * @param {string} readmePath
+ * @param {string} draft
+ * @returns {string} path of the written file
+ */
+export function writeDriftFile(readmePath, draft) {
+  const driftPath = join(dirname(readmePath), 'README.drift.md');
+  writeFileSync(driftPath, draft);
+  return driftPath;
+}
+
+/**
+ * Trim a draft and drop a single fence wrapping the whole answer. Models often
+ * wrap the README in ```markdown fences; keeping it would write a broken
+ * README and let the fence lines confuse the verifier.
+ */
+function cleanDraft(rawDraft) {
+  const trimmed = String(rawDraft ?? '').trim();
+  const lines = trimmed.split('\n');
+
+  if (
+    lines.length >= 2 &&
+    lines[0].trim().startsWith('```') &&
+    lines[lines.length - 1].trim() === '```'
+  ) {
+    lines.shift();
+    lines.pop();
+    return lines.join('\n').trim();
+  }
+
+  return trimmed;
+}
+
+function verifyDraft(draft, codeEndpoints, undocumented, stale) {
+  const draftEndpoints = extractFromText(draft);
+
+  const invented = uniqueByMethodAndPath(
+    draftEndpoints.filter(
+      (endpoint) =>
+        !codeEndpoints.some((code) => codeCovers(code, endpoint)),
+    ),
+  );
+
+  const missing = undocumented.filter(
+    (code) => !draftEndpoints.some((endpoint) => codeCovers(code, endpoint)),
+  );
+
+  const leftover = stale.filter((staleEndpoint) =>
+    draftEndpoints.some((endpoint) =>
+      sameMethodAndPath(staleEndpoint, {
+        method: endpoint.method,
+        path: endpoint.path,
+      }),
+    ),
+  );
+
+  return { invented, missing, leftover };
+}
+
+function codeCovers(codeEndpoint, docEndpoint) {
+  if (normalizePath(codeEndpoint.path) !== normalizePath(docEndpoint.path)) {
+    return false;
+  }
+
+  const methods = String(codeEndpoint.method ?? '')
+    .split('|')
+    .map((method) => method.trim());
+
+  return methods.includes('ANY') || methods.includes(docEndpoint.method);
+}
+
+function sameMethodAndPath(a, b) {
+  return (
+    a.method === b.method && normalizePath(a.path) === normalizePath(b.path)
+  );
+}
+
+function uniqueByMethodAndPath(endpoints) {
+  const seen = new Set();
+  const unique = [];
+  for (const endpoint of endpoints) {
+    const key = `${endpoint.method} ${normalizePath(endpoint.path)}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(endpoint);
+  }
+  return unique;
+}
+
+function hasNoProblems({ invented, missing, leftover }) {
+  return invented.length + missing.length + leftover.length === 0;
+}
+
+function problemsMessage({ invented, missing, leftover }) {
+  const lines = ['The draft has problems:'];
+
+  if (invented.length > 0) {
+    lines.push(`- Invented endpoints that are not in the code: ${labels(invented)}`);
+  }
+  if (missing.length > 0) {
+    lines.push(`- Documented endpoints still missing: ${labels(missing)}`);
+  }
+  if (leftover.length > 0) {
+    lines.push(`- Stale endpoints still present: ${labels(leftover)}`);
+  }
+
+  lines.push('Return ONLY the corrected full README in Markdown.');
+  return lines.join('\n');
+}
+
+/**
+ * Format the `fix` command output. Never includes the API key or base URL.
+ *
+ * @param {{
+ *   status: string, model: string, attempts: number, staleRemoved: number,
+ *   undocumentedAdded: number, draftPath: string | null,
+ *   invented?: object[], missing?: object[], leftover?: object[],
+ * }} input
+ * @param {object | null} [style] optional createStyle() result for colored output
+ * @returns {string}
+ */
+export function formatFixReport(input, style = null) {
+  const {
+    status,
+    model,
+    attempts,
+    staleRemoved,
+    undocumentedAdded,
+    draftPath,
+    invented = [],
+    missing = [],
+    leftover = [],
+  } = input;
+
+  const colored = Boolean(style?.enabled);
+
+  const statusValue = !colored
+    ? status
+    : status === 'UNVERIFIED'
+      ? style.danger(status)
+      : style.success(status);
+
+  const lines = colored
+    ? [
+        `${style.muted('Status:')} ${statusValue}`,
+        `${style.muted('Model:')} ${style.muted(model)}`,
+        `${style.muted('Attempts:')} ${style.muted(attempts)}`,
+        `${style.muted('Stale removed:')} ${style.bold(style.success(String(staleRemoved)))} | ${style.muted('Undocumented added:')} ${style.bold(style.success(String(undocumentedAdded)))}`,
+        `${style.muted('Draft:')} ${style.muted(draftPath ?? '(none)')}`,
+      ]
+    : [
+        `Status: ${status}`,
+        `Model: ${model}`,
+        `Attempts: ${attempts}`,
+        `Stale removed: ${staleRemoved} | Undocumented added: ${undocumentedAdded}`,
+        `Draft: ${draftPath ?? '(none)'}`,
+      ];
+
+  if (status === 'UNVERIFIED') {
+    for (const endpoint of invented) {
+      lines.push(problemLine(style, 'Invented:', endpoint));
+    }
+    for (const endpoint of missing) {
+      lines.push(problemLine(style, 'Missing:', endpoint));
+    }
+    for (const endpoint of leftover) {
+      lines.push(problemLine(style, 'Leftover:', endpoint));
+    }
+  }
+
+  if (colored && status === 'VERIFIED') {
+    lines.push(style.success('✔ Draft verified against the code'));
+  }
+  if (colored && status === 'UNVERIFIED') {
+    lines.push(style.danger('✖ Draft could not be verified'));
+  }
+
+  return lines.join('\n');
+}
+
+function problemLine(style, label, endpoint) {
+  const text = `${endpoint.method} ${endpoint.path}`;
+  if (!style?.enabled) return `${label} ${text}`;
+  return `${style.danger(label)} ${style.danger(text)}`;
+}
+
+function listEndpoints(endpoints) {
+  if (endpoints.length === 0) return '- (none)';
+  return endpoints
+    .map((endpoint) => `- ${endpoint.method} ${endpoint.path}`)
+    .join('\n');
+}
+
+function labels(endpoints) {
+  return endpoints
+    .map((endpoint) => `${endpoint.method} ${endpoint.path}`)
+    .join(', ');
+}