docs-drift-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas Kadam
+
+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

@@ -0,0 +1,38 @@
+# docs-drift-lite
+
+Detects drift between documented API names (e.g. from a README) and the actual exported names of a module — catches stale docs in CI.
+
+## Install
+
+```bash
+npm install docs-drift-lite
+```
+
+## Quick start
+
+```ts
+import { checkReadmeDrift, hasUndocumentedExports } from 'docs-drift-lite';
+import { readFileSync } from 'fs';
+import * as pkg from './src/index';
+
+const readme = readFileSync('README.md', 'utf8');
+const report = checkReadmeDrift(readme, Object.keys(pkg));
+
+console.log(report);
+if (hasUndocumentedExports(report)) process.exit(1);
+```
+
+## Why docs-drift-lite
+
+READMEs go stale the moment someone adds or renames an export without updating the docs — and nobody notices until a user hits a wall. docs-drift-lite pulls a rough set of "documented names" out of Markdown (inline code spans and call-expression heads in code blocks) and diffs them against your module's real export list, reporting names that are documented but no longer exist, exports that are undocumented, and everything that matches. It's intentionally a text heuristic rather than a full doc-comment parser, so it works on any README without extra tooling.
+
+## API
+
+- `extractDocumentedNames(markdown)` — pulls candidate identifier names out of Markdown text.
+- `detectDrift(documentedNames, actualExportNames, ignore?)` — compares two name lists into `{ matched, missingFromDocs, undocumentedInCode }`.
+- `checkReadmeDrift(markdown, actualExportNames, ignore?)` — extraction + comparison in one call.
+- `hasUndocumentedExports(report)` — true if any export isn't mentioned in the docs (a common CI gate).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+interface DriftReport {
+    /** Names documented but not found among the actual exports. */
+    undocumentedInCode: string[];
+    /** Names actually exported but never mentioned in the docs. */
+    missingFromDocs: string[];
+    /** Names present in both. */
+    matched: string[];
+}
+/**
+ * Extracts a plausible set of "documented API names" from Markdown text: bare identifiers
+ * inside inline code spans (`likeThis`) and the head of fenced code-block call expressions
+ * (`likeThis(...)`), each optionally namespaced with a leading module dot.
+ */
+declare function extractDocumentedNames(markdown: string): string[];
+/**
+ * Compares a list of documented names against a list of actual export names and reports
+ * what's undocumented, what's missing from docs, and what matches.
+ */
+declare function detectDrift(documentedNames: string[], actualExportNames: string[], ignore?: string[]): DriftReport;
+/** Convenience: runs extractDocumentedNames + detectDrift in one call. */
+declare function checkReadmeDrift(markdown: string, actualExportNames: string[], ignore?: string[]): DriftReport;
+/** True if the report has any names missing from docs (a common CI gate; ignores extra doc mentions). */
+declare function hasUndocumentedExports(report: DriftReport): boolean;
+
+export { type DriftReport, checkReadmeDrift, detectDrift, extractDocumentedNames, hasUndocumentedExports };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+interface DriftReport {
+    /** Names documented but not found among the actual exports. */
+    undocumentedInCode: string[];
+    /** Names actually exported but never mentioned in the docs. */
+    missingFromDocs: string[];
+    /** Names present in both. */
+    matched: string[];
+}
+/**
+ * Extracts a plausible set of "documented API names" from Markdown text: bare identifiers
+ * inside inline code spans (`likeThis`) and the head of fenced code-block call expressions
+ * (`likeThis(...)`), each optionally namespaced with a leading module dot.
+ */
+declare function extractDocumentedNames(markdown: string): string[];
+/**
+ * Compares a list of documented names against a list of actual export names and reports
+ * what's undocumented, what's missing from docs, and what matches.
+ */
+declare function detectDrift(documentedNames: string[], actualExportNames: string[], ignore?: string[]): DriftReport;
+/** Convenience: runs extractDocumentedNames + detectDrift in one call. */
+declare function checkReadmeDrift(markdown: string, actualExportNames: string[], ignore?: string[]): DriftReport;
+/** True if the report has any names missing from docs (a common CI gate; ignores extra doc mentions). */
+declare function hasUndocumentedExports(report: DriftReport): boolean;
+
+export { type DriftReport, checkReadmeDrift, detectDrift, extractDocumentedNames, hasUndocumentedExports };

package/dist/index.js

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  checkReadmeDrift: () => checkReadmeDrift,
+  detectDrift: () => detectDrift,
+  extractDocumentedNames: () => extractDocumentedNames,
+  hasUndocumentedExports: () => hasUndocumentedExports
+});
+module.exports = __toCommonJS(index_exports);
+function extractDocumentedNames(markdown) {
+  const names = /* @__PURE__ */ new Set();
+  const inlineCodeMatches = markdown.match(/`([^`]+)`/g) ?? [];
+  for (const raw of inlineCodeMatches) {
+    const content = raw.slice(1, -1).trim();
+    const identMatch = content.match(/^[A-Za-z_$][A-Za-z0-9_$]*/);
+    if (identMatch && identMatch[0] === content.replace(/\(.*$/, "")) {
+      names.add(identMatch[0]);
+    }
+  }
+  const callMatches = markdown.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g);
+  for (const match of callMatches) {
+    names.add(match[1]);
+  }
+  return [...names];
+}
+function detectDrift(documentedNames, actualExportNames, ignore = []) {
+  const ignoreSet = new Set(ignore);
+  const docSet = new Set(documentedNames.filter((n) => !ignoreSet.has(n)));
+  const exportSet = new Set(actualExportNames.filter((n) => !ignoreSet.has(n)));
+  const matched = [];
+  const missingFromDocs = [];
+  for (const name of exportSet) {
+    if (docSet.has(name)) matched.push(name);
+    else missingFromDocs.push(name);
+  }
+  const undocumentedInCode = [...docSet].filter((name) => !exportSet.has(name));
+  return {
+    undocumentedInCode: undocumentedInCode.sort(),
+    missingFromDocs: missingFromDocs.sort(),
+    matched: matched.sort()
+  };
+}
+function checkReadmeDrift(markdown, actualExportNames, ignore = []) {
+  return detectDrift(extractDocumentedNames(markdown), actualExportNames, ignore);
+}
+function hasUndocumentedExports(report) {
+  return report.missingFromDocs.length > 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkReadmeDrift,
+  detectDrift,
+  extractDocumentedNames,
+  hasUndocumentedExports
+});

package/dist/index.mjs

@@ -0,0 +1,46 @@
+// src/index.ts
+function extractDocumentedNames(markdown) {
+  const names = /* @__PURE__ */ new Set();
+  const inlineCodeMatches = markdown.match(/`([^`]+)`/g) ?? [];
+  for (const raw of inlineCodeMatches) {
+    const content = raw.slice(1, -1).trim();
+    const identMatch = content.match(/^[A-Za-z_$][A-Za-z0-9_$]*/);
+    if (identMatch && identMatch[0] === content.replace(/\(.*$/, "")) {
+      names.add(identMatch[0]);
+    }
+  }
+  const callMatches = markdown.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g);
+  for (const match of callMatches) {
+    names.add(match[1]);
+  }
+  return [...names];
+}
+function detectDrift(documentedNames, actualExportNames, ignore = []) {
+  const ignoreSet = new Set(ignore);
+  const docSet = new Set(documentedNames.filter((n) => !ignoreSet.has(n)));
+  const exportSet = new Set(actualExportNames.filter((n) => !ignoreSet.has(n)));
+  const matched = [];
+  const missingFromDocs = [];
+  for (const name of exportSet) {
+    if (docSet.has(name)) matched.push(name);
+    else missingFromDocs.push(name);
+  }
+  const undocumentedInCode = [...docSet].filter((name) => !exportSet.has(name));
+  return {
+    undocumentedInCode: undocumentedInCode.sort(),
+    missingFromDocs: missingFromDocs.sort(),
+    matched: matched.sort()
+  };
+}
+function checkReadmeDrift(markdown, actualExportNames, ignore = []) {
+  return detectDrift(extractDocumentedNames(markdown), actualExportNames, ignore);
+}
+function hasUndocumentedExports(report) {
+  return report.missingFromDocs.length > 0;
+}
+export {
+  checkReadmeDrift,
+  detectDrift,
+  extractDocumentedNames,
+  hasUndocumentedExports
+};

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "docs-drift-lite",
+  "version": "0.1.0",
+  "description": "Detects drift between documented API names (e.g. from a README) and the actual exported names of a module — catches stale docs in CI.",
+  "main": "dist/index.js", "module": "dist/index.mjs", "types": "dist/index.d.ts", "files": ["dist"],
+  "license": "MIT", "author": "Tejas Kadam",
+  "repository": { "type": "git", "url": "git+https://github.com/tejas821/docs-drift-lite.git" },
+  "keywords": ["documentation", "drift", "ci", "typescript"],
+  "scripts": { "build": "tsup src/index.ts --format cjs,esm --dts", "test": "jest", "typecheck": "tsc --noEmit" },
+  "devDependencies": { "typescript": "^5.5.4", "tsup": "^8.2.4", "jest": "^29.7.0", "ts-jest": "^29.2.5", "@types/jest": "^29.5.12" }
+}