@prabhat-singh/docdrift 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prabhat Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# DocDrift
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find stale and undocumented REST endpoints by comparing your Spring Boot code with your docs.
+
+## Why DocDrift?
+
+Docs drift from Spring Boot controllers silently: routes get renamed, removed or added without a README update.
+DocDrift finds stale and undocumented endpoints deterministically, with no AI in the detection path.
+AI is used only to draft the fix, and a code-based verifier checks that draft before it is marked VERIFIED.
+
+## Quick start
+
+```bash
+cd my-spring-app
+npx github:prabhatsingh415/docdrift check
+```
+
+That scans every `.java` file under the current folder and compares it with `README.md` and `docs/*.md` in that folder.
+
+If the docs live elsewhere:
+
+```bash
+docdrift check ./my-spring-app/src/main/java ./path/to/docs
+```
+
+## What it does
+
+- **STALE** - an endpoint is documented but not present in the code.
+- **UNDOCUMENTED** - an endpoint exists in the code but is not documented.
+
+Both come straight from the code and the docs, with no AI involved.
+
+AI is optional and only used to draft a README fix. A code-based verifier checks the draft: it must mention only endpoints that exist in the code, remove stale ones and add undocumented ones. Until that check passes, the draft is **UNVERIFIED**. The original README is never overwritten - the draft is written to `README.drift.md`.
+
+## Install
+
+For a one-off run without installing:
+
+```bash
+npx @prabhat-singh/docdrift check .
+```
+
+For a global install:
+
+```bash
+npm install -g @prabhat-singh/docdrift
+```
+
+After a global install, use `docdrift ...` directly. Requires Node 18+. Zero dependencies.
+
+## Usage
+
+```bash
+docdrift scan
+docdrift docs
+docdrift check
+docdrift fix
+```
+
+Run these from your project root. All four commands also accept optional paths: `scan [dir]`, `docs [dir]`, `check [codeDir] [docsDir]`, and `fix [codeDir] [docsDir]`.
+
+- `scan [dir]` - print the endpoints found in `.java` files as JSON.
+- `docs [dir]` - print the endpoints documented in `README.md` and `docs/*.md` as JSON.
+- `check [codeDir] [docsDir]` - compare code and docs and print a report. `docsDir` defaults to `codeDir`.
+- `fix [codeDir] [docsDir]` - ask a model to draft a fixed README, verify the draft, and write it to `README.drift.md`.
+
+Flags:
+
+- `--dry-run` - print the writer prompt for `fix` without calling any model.
+- `--strict` - report Spring framework endpoints as STALE instead of ignoring them.
+- `--no-color` - disable ANSI colors.
+
+Exit codes:
+
+- `check`: `1` when drift is found, `0` otherwise.
+- `fix`: `0` for VERIFIED or NO_DRIFT, `1` for UNVERIFIED, `2` for a config error.
+
+## Example output
+
+Real output from `docdrift check` on a private Spring Boot project whose README had seeded drift:
+
+```text
+docdrift check: 23 code endpoints, 16 documented endpoints, 14 matched
+
+STALE (documented, not in code)
+  GET    /giveaway/winners (Readme.md:7)
+  DELETE /user/delete (Readme.md:31)
+
+UNDOCUMENTED (in code, not documented)
+  POST   /api/webhooks/razorpay (com/LuckyHub/Backend/controller/WebhookController.java:19)
+  PUT    /user/changePassword (com/LuckyHub/Backend/controller/UserController.java:181)
+  DELETE /user/confirm-delete (com/LuckyHub/Backend/controller/UserController.java:212)
+  POST   /user/logout (com/LuckyHub/Backend/controller/UserController.java:193)
+  GET    /user/me (com/LuckyHub/Backend/controller/UserController.java:146)
+  POST   /user/request-delete (com/LuckyHub/Backend/controller/UserController.java:204)
+  GET    /user/resendToken (com/LuckyHub/Backend/controller/UserController.java:107)
+  PUT    /user/updateAvatar (com/LuckyHub/Backend/controller/UserController.java:168)
+  PUT    /user/updateName (com/LuckyHub/Backend/controller/UserController.java:156)
+```
+
+From a checkout of this repo:
+
+```bash
+node bin/docdrift.js check test/fixtures-check --no-color
+```
+
+```text
+docdrift check: 3 code endpoints, 3 documented endpoints, 2 matched
+
+STALE (documented, not in code)
+  GET    /api/legacy (README.md:7)
+
+UNDOCUMENTED (in code, not documented)
+  DELETE /api/users/{id} (UserController.java:15)
+```
+
+### Example run on a demo project
+
+```text
+Status: VERIFIED
+Model: recursive/flint-v1.0:free
+Attempts: 1
+Stale removed: 2 | Undocumented added: 9
+```
+
+## Configuring `fix`
+
+`fix` works with any OpenAI-compatible endpoint; bring your own key. Set these variables as environment variables or in a `.env` file:
+
+- `DOCDRIFT_API_KEY`
+- `DOCDRIFT_BASE_URL`
+- `DOCDRIFT_MODEL`
+
+Never commit `.env` (a `.env.example` is included). The key is optional for local endpoints such as Ollama (`http://localhost:11434/v1`).
+
+`fix --dry-run` prints the prompt without calling any model. `check`, `scan` and `docs` need no key and no AI.
+
+This project was demoed with the open-weight model `recursive/flint-v1.0:free` through OpenRouter.
+
+## How it works
+
+- **Scanner** - reads `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping` and `@RequestMapping` from `.java` files, joins the class-level prefix, ignores comments, and skips non-literal paths with a warning.
+- **Docs parser** - finds `"METHOD /path"` in prose, inline code, code blocks and tables.
+- **Matcher** - treats path parameters `{id}`, `:id` and `{userId}` as equal, ignores trailing slashes and query strings, and lets a code `@RequestMapping` without a method match any documented method. Spring library endpoints such as `/actuator` and `/swagger-ui` are reported as ignored instead of stale unless `--strict` is used.
+- **Verifier loop** - the writer gets up to 2 retries to produce a draft that passes the code-based checks.
+
+## Tests and evaluation
+
+- **60 unit tests** with `node:test` (`npm test`).
+- **Seeded-drift evaluation** (`npm run eval`): for 5 Java repos (4 public repos and one private project), 150 trials. Endpoints were removed from and fake endpoints added to a README generated from the code scan, plus harmless noise (renamed path parameters, trailing slashes). Result: **100% precision and recall** for both STALE and UNDOCUMENTED, with no failures. This is a controlled test: the README is generated from the scan, so it validates the matcher and the docs parser, not the scanner and not messy real-world READMEs. Results are in `evals/RESULTS.md`.
+- **Real READMEs**: `check` was run on 4 public Spring Boot repos with their own READMEs. DocDrift reported no drift on 3 of them. The one false alarm (documented `/actuator/health` and `/swagger-ui.html`, provided by libraries) led to the framework-endpoint rule. No ground truth exists for real READMEs, so no recall is claimed.
+- **Scanner**: on 5 repos it found 51 endpoints. In 4 repos the count matched a grep count; in the 5th, grep also counted a commented-out `@GetMapping` that the scanner correctly skipped (checked by hand).
+- **`fix`**: verified on the demo project above. A systematic success rate for `fix` has not been measured yet because the free model endpoint was rate-limited.
+
+## Limitations
+
+- Only Spring Boot REST annotations in `.java` files (no Kotlin, no Express, no OpenAPI files).
+- Constants in paths (like `BASE + "/x"`) are skipped with a warning, not resolved.
+- `server.servlet.context-path` and class-level inheritance are not handled.
+- A `@RequestMapping` without a method matches any documented method, so it can hide a wrong HTTP method.
+- Docs are matched textually as `"METHOD /path"`, so endpoints written in other styles (for example a bare path without the method) are not found.
+- The verifier only checks endpoints, not the rest of the text a model writes.
+- The free open model used for the demo can be rate-limited.
+
+## Built with Alan AI
+
+This project was built with Alan AI (the code was written by Alan and reviewed and tested by the author).
+
+## Not related
+
+Not related to the npm package `docdrift` by Nico Schwandner, which links business decisions to code.
+
+## License
+
+MIT.

package/bin/docdrift.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { scanJava } from '../src/scan.js';
+import { scanDocs, extractFromText } from '../src/docs.js';
+import { check } from '../src/check.js';
+import { compare } from '../src/match.js';
+import { loadConfig } from '../src/config.js';
+import { chat } from '../src/llm.js';
+import {
+  buildWriterMessages,
+  fixDocs,
+  formatFixReport,
+  writeDriftFile,
+} from '../src/fix.js';
+import { createStyle, shouldUseColor, supportsTrueColor } from '../src/style.js';
+import { compactBanner, fullBanner } from '../src/banner.js';
+
+const { version } = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+);
+
+const rawArgs = process.argv.slice(2);
+const style = createStyle(
+  shouldUseColor(process.stdout, process.env, rawArgs),
+  supportsTrueColor(process.env),
+);
+
+if (rawArgs.includes('--help')) {
+  process.stdout.write(`${fullBanner(style, version)}\n\n${helpText()}\n`);
+} else if (rawArgs.includes('--version')) {
+  process.stdout.write(`${fullBanner(style, version)}\n`);
+} else {
+  const flags = new Set(['--dry-run', '--no-color', '--strict']);
+  const [command, target, docsTarget] = rawArgs.filter(
+    (arg) => !flags.has(arg),
+  );
+  const commands = { scan: scanJava, docs: scanDocs };
+
+  if (command === undefined) {
+    process.stdout.write(`${fullBanner(style, version)}\n\n${helpText()}\n`);
+    process.exitCode = 1;
+  } else if (command === 'fix') {
+    process.exitCode = await runFix(
+      target ?? '.',
+      docsTarget,
+      rawArgs.includes('--dry-run'),
+      style,
+    );
+  } else if (command === 'check') {
+    const codeDir = target ?? '.';
+    const docsDir = docsTarget ?? codeDir;
+
+    try {
+      const codeEndpoints = scanJava(codeDir);
+      if (codeEndpoints.length === 0) {
+        console.error(noEndpointsMessage(codeDir));
+        process.exitCode = 2;
+      } else {
+        if (style.enabled) {
+          process.stdout.write(`${compactBanner(style, version)}\n\n`);
+        }
+        const { report, exitCode } = check(
+          codeDir,
+          docsDir,
+          style.enabled ? style : null,
+          {
+            strict: rawArgs.includes('--strict'),
+            codeEndpoints,
+          },
+        );
+        process.stdout.write(`${report}\n`);
+        process.exitCode = exitCode;
+      }
+    } catch (error) {
+      console.error(`docdrift: ${error.message}`);
+      process.exitCode = 1;
+    }
+  } else if (!Object.hasOwn(commands, command)) {
+    console.error('usage: docdrift <scan|docs|check|fix> [dir]');
+    process.exitCode = 1;
+  } else {
+    try {
+      const endpoints = commands[command](target ?? '.');
+      process.stdout.write(`${JSON.stringify(endpoints, null, 2)}\n`);
+    } catch (error) {
+      console.error(`docdrift: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+async function runFix(codeDir, docsTarget, isDryRun, style) {
+  const docsDir = docsTarget ?? codeDir;
+
+  let codeEndpoints;
+  try {
+    codeEndpoints = scanJava(codeDir);
+  } catch (error) {
+    console.error(`docdrift: ${error.message}`);
+    return 1;
+  }
+
+  if (codeEndpoints.length === 0) {
+    console.error(noEndpointsMessage(codeDir));
+    return 2;
+  }
+
+  if (style.enabled) {
+    process.stdout.write(`${compactBanner(style, version)}\n\n`);
+  }
+
+  let readmeName;
+  try {
+    readmeName = readdirSync(docsDir).find(
+      (name) => name.toLowerCase() === 'readme.md',
+    );
+  } catch (error) {
+    console.error(`docdrift: ${error.message}`);
+    return 1;
+  }
+
+  if (!readmeName) {
+    console.error(`docdrift: no README.md found in ${docsDir}`);
+    return 1;
+  }
+
+  const readmePath = join(docsDir, readmeName);
+  const readmeText = readFileSync(readmePath, 'utf8');
+  const docEndpoints = extractFromText(readmeText).map((endpoint) => ({
+    ...endpoint,
+    file: readmePath,
+  }));
+
+  if (isDryRun) {
+    const messages = buildWriterMessages({
+      codeEndpoints,
+      docEndpoints,
+      readmeText,
+    });
+    for (const message of messages) {
+      process.stdout.write(`[${message.role}]\n${message.content}\n\n`);
+    }
+    return 0;
+  }
+
+  const config = loadConfig();
+  if (config.error) {
+    console.error(`docdrift: ${config.error}`);
+    return 2;
+  }
+
+  try {
+    const result = await fixDocs({
+      codeEndpoints,
+      docEndpoints,
+      readmeText,
+      chatFn: (messages) => chat(config, messages),
+    });
+
+    const { stale, undocumented } = compare(codeEndpoints, docEndpoints);
+
+    if (result.status === 'NO_DRIFT') {
+      process.stdout.write(
+        `${formatFixReport(
+          {
+            status: result.status,
+            model: config.model,
+            attempts: 0,
+            staleRemoved: 0,
+            undocumentedAdded: 0,
+            draftPath: null,
+          },
+          style.enabled ? style : null,
+        )}\n`,
+      );
+      return 0;
+    }
+
+    const draftPath = writeDriftFile(readmePath, result.draft);
+    process.stdout.write(
+      `${formatFixReport(
+        {
+          status: result.status,
+          model: config.model,
+          attempts: result.attempts,
+          staleRemoved: stale.length - result.leftover.length,
+          undocumentedAdded: undocumented.length - result.missing.length,
+          draftPath,
+          invented: result.invented,
+          missing: result.missing,
+          leftover: result.leftover,
+        },
+        style.enabled ? style : null,
+      )}\n`,
+    );
+
+    return result.status === 'VERIFIED' ? 0 : 1;
+  } catch (error) {
+    console.error(`docdrift: ${error.message}`);
+    return 1;
+  }
+}
+
+function noEndpointsMessage(codeDir) {
+  const label =
+    codeDir === '.' ? basename(process.cwd()) || codeDir : codeDir;
+  return `No Spring REST endpoints found in "${label}" - run docdrift from your project root or pass the path: docdrift check <codeDir> [docsDir]`;
+}
+
+function helpText() {
+  return [
+    'Usage: docdrift <command> [paths] [options]',
+    '',
+    'Commands:',
+    '  scan [dir]                        Print code endpoints as JSON',
+    '  docs [dir]                        Print documented endpoints as JSON',
+    '  check [codeDir] [docsDir]         Compare code against docs',
+    '  fix [codeDir] [docsDir]           Draft a verified README fix',
+    '',
+    'Options:',
+    '  --strict                          Report Spring framework endpoints as STALE',
+    '  --dry-run                         Print the writer prompt, no API call',
+    '  --no-color                        Disable ANSI colors',
+    '',
+    'Environment for fix:',
+    '  DOCDRIFT_API_KEY',
+    '  DOCDRIFT_BASE_URL',
+    '  DOCDRIFT_MODEL',
+  ].join('\n');
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@prabhat-singh/docdrift",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Find stale and undocumented REST endpoints by comparing Spring Boot code with your docs. Optional AI-drafted README fixes, verified against the code.",
+  "type": "module",
+  "bin": {
+    "docdrift": "bin/docdrift.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "eval": "node evals/run.js",
+    "eval:fix": "node evals/fix-eval.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "spring-boot",
+    "documentation",
+    "docs",
+    "cli",
+    "rest",
+    "drift",
+    "endpoints"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prabhatsingh415/docdrift.git"
+  },
+  "homepage": "https://github.com/prabhatsingh415/docdrift#readme",
+  "bugs": {
+    "url": "https://github.com/prabhatsingh415/docdrift/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/banner.js

@@ -0,0 +1,60 @@
+const WIDTH = 76;
+const LETTER_GAP = '  ';
+const WORD_GAP = '    ';
+
+const GLYPHS = {
+  D: ['######', '#    #', '#    #', '#    #', '#    #', '#    #', '######'],
+  O: [' #### ', '#    #', '#    #', '#    #', '#    #', '#    #', ' #### '],
+  C: [' #####', '#     ', '#     ', '#     ', '#     ', '#     ', ' #####'],
+  R: ['##### ', '#    #', '#    #', '##### ', '#  #  ', '#   # ', '#    #'],
+  I: ['######', '  ##  ', '  ##  ', '  ##  ', '  ##  ', '  ##  ', '######'],
+  F: ['######', '#     ', '#     ', '##### ', '#     ', '#     ', '#     '],
+  T: ['######', '  ##  ', '  ##  ', '  ##  ', '  ##  ', '  ##  ', '  ##  '],
+};
+
+const WORDMARK_ROWS = Array.from({ length: 7 }, (_, row) =>
+  ['DOC', 'DRIFT']
+    .map((word) =>
+      word
+        .split('')
+        .map((letter) => GLYPHS[letter][row])
+        .join(LETTER_GAP),
+    )
+    .join(WORD_GAP),
+);
+
+function centered(text, paint) {
+  const padding = Math.max(0, Math.floor((WIDTH - text.length) / 2));
+  const right = Math.max(0, WIDTH - padding - text.length);
+  return `${' '.repeat(padding)}${paint(text)}${' '.repeat(right)}`;
+}
+
+function paintWordmark(style, text) {
+  if (!style.enabled) return text;
+  return style.bold(style.success(text));
+}
+
+/**
+ * Full DocDrift branding: the wordmark is the whole identity.
+ *
+ * @param {ReturnType<import('./style.js').createStyle>} style
+ * @param {string} version
+ * @returns {string}
+ */
+export function fullBanner(style, version = '0.0.0') {
+  const rows = WORDMARK_ROWS.map((row) =>
+    centered(row, (text) => paintWordmark(style, text)),
+  );
+
+  rows.push(centered("Code changes. Docs don't.", (text) => style.muted(text)));
+  rows.push(centered(`v${version}`, (text) => style.muted(text)));
+
+  return rows.join('\n');
+}
+
+/**
+ * One-line branding for the start of colored check/fix runs.
+ */
+export function compactBanner(style, version = '0.0.0') {
+  return `${style.bold(style.success('DocDrift'))} ${style.muted(`v${version}`)}`;
+}