doc-sync-check 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chetan Basuray
+
+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,46 @@
+# doc-sync-check
+
+> **Stop documentation drift in its tracks.**
+
+`doc-sync-check` is a fast, specialized CLI tool that statically analyzes your TypeScript codebase using an Abstract Syntax Tree (AST). It scans your Markdown files for function names and ensures that the documented function signatures match the actual source code perfectly. 
+
+If you update a parameter or return type in your code but forget to update the documentation, `doc-sync-check` will catch it and fail your CI build, reminding your team to keep the docs in sync!
+
+## 🚀 Installation
+
+You can install `doc-sync-check` globally, but it is recommended to add it as a `devDependency` to your project and run it via an npm script or CI pipeline.
+
+```bash
+npm install -D doc-sync-check
+```
+
+## 🛠️ Usage
+
+Run `doc-sync-check` by pointing it to your source code directory and specifying your documentation folder.
+
+```bash
+npx doc-sync-check <source-dir> --docs <docs-dir>
+```
+
+### Options
+- `<source-dir>`: The root directory containing your TypeScript files.
+- `--docs, -d`: The path to the folder containing your Markdown documentation files. Defaults to `./docs`.
+
+### Example
+```bash
+npx doc-sync-check src --docs docs
+```
+
+## 🧠 How it Works
+
+1. **Extraction**: Parsers comb through your target TypeScript directory looking for exported functions.
+2. **Analysis**: The script breaks apart definitions into precise semantic substrings (e.g. tracking `userAuth(uuid: string, options?: any): boolean | void`).
+3. **Drift Detection**: Any Markdown file mentioning a detected function name by exact match must also include its corresponding up-to-date signature. If it doesn't, the CLI flags a drift warning and immediately fails the process (Exit Code 1).
+
+## 🤝 Contributing
+
+We welcome community contributions! Please check out our [Contributing Guide](CONTRIBUTING.md) to get started on setting up the repository, running tests, and understanding the architecture.
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import meow from 'meow';
+import { globby } from 'globby';
+import fs from 'fs-extra';
+import { extractSignatures } from './extractor.js';
+import { checkDrift } from './validator.js';
+const cli = meow(`
+	Usage
+	  $ doc-sync-check <source-dir>
+
+	Options
+	  --docs, -d  Path to documentation folder (default: ./docs)
+
+	Examples
+	  $ doc-sync-check src --docs ./documentation
+`, {
+    importMeta: import.meta,
+    flags: {
+        docs: {
+            type: 'string',
+            shortFlag: 'd',
+            default: './docs'
+        }
+    }
+});
+async function run() {
+    const sourceDir = cli.input[0];
+    if (!sourceDir) {
+        console.error("Please specify a source directory.");
+        process.exit(1);
+    }
+    console.log(`🔍 Scanning ${sourceDir} for documentation drift...`);
+    // 1. Find all TypeScript files
+    const files = await globby(`${sourceDir}/**/*.ts`);
+    const allSigs = [];
+    for (const file of files) {
+        const code = fs.readFileSync(file, 'utf-8');
+        const sigs = extractSignatures(code);
+        if (sigs.length > 0) {
+            allSigs.push(...sigs);
+        }
+    }
+    console.log(`\n📚 Checking against documentation in ${cli.flags.docs}...`);
+    const hasDrift = await checkDrift(allSigs, cli.flags.docs);
+    if (hasDrift) {
+        console.error("\n❌ Drift check failed. Please update your documentation.");
+        process.exit(1);
+    }
+    console.log("\n✅ Drift check complete. No issues found.");
+}
+run();

package/dist/src/extractor.d.ts

@@ -0,0 +1,7 @@
+export interface FunctionSignature {
+    name: string;
+    parameters: string[];
+    returnType: string;
+    fullSignature: string;
+}
+export declare function extractSignatures(code: string): FunctionSignature[];

package/dist/src/extractor.js

@@ -0,0 +1,38 @@
+import { parse } from '@babel/parser';
+import * as babelTraverse from '@babel/traverse';
+const traverse = (babelTraverse.default?.default || babelTraverse.default || babelTraverse);
+export function extractSignatures(code) {
+    const signatures = [];
+    try {
+        const ast = parse(code, {
+            sourceType: "module",
+            plugins: ["typescript"]
+        });
+        traverse(ast, {
+            // TypeScript now knows this is a type-only reference
+            ExportNamedDeclaration(path) {
+                const { declaration } = path.node;
+                if (declaration && declaration.type === 'FunctionDeclaration') {
+                    const name = declaration.id?.name || 'anonymous';
+                    const parameters = declaration.params.map((param) => {
+                        return code.substring(param.start, param.end);
+                    });
+                    const returnType = declaration.returnType
+                        ? code.substring(declaration.returnType.start, declaration.returnType.end)
+                        : '';
+                    const fullSignature = `${name}(${parameters.join(', ')})${returnType}`;
+                    signatures.push({
+                        name,
+                        parameters,
+                        returnType,
+                        fullSignature,
+                    });
+                }
+            }
+        });
+    }
+    catch (e) {
+        console.error("Parsing error:", e);
+    }
+    return signatures;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './extractor.js';
+export * from './validator.js';

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export * from './extractor.js';
+export * from './validator.js';

package/dist/src/validator.d.ts

@@ -0,0 +1,2 @@
+import type { FunctionSignature } from './extractor.js';
+export declare function checkDrift(signatures: FunctionSignature[], docsDir: string): Promise<boolean>;

package/dist/src/validator.js

@@ -0,0 +1,50 @@
+import { globby } from 'globby';
+import fs from 'fs-extra';
+function normalizeSpace(str) {
+    return str.replace(/\s+/g, ' ').trim();
+}
+export async function checkDrift(signatures, docsDir) {
+    const mdFiles = await globby(`${docsDir}/**/*.md`);
+    if (mdFiles.length === 0) {
+        console.warn(`No markdown files found in ${docsDir}`);
+        return false;
+    }
+    const docs = await Promise.all(mdFiles.map(async (file) => {
+        const content = await fs.readFile(file, 'utf-8');
+        return {
+            path: file,
+            content,
+            normalizedContent: normalizeSpace(content)
+        };
+    }));
+    let hasDrift = false;
+    for (const sig of signatures) {
+        const normalizedSig = normalizeSpace(sig.fullSignature);
+        let nameFound = false;
+        let signatureFound = false;
+        for (const doc of docs) {
+            // Check if the exact function name is present (bounded by non-word chars if possible, but includes is fine for now)
+            // A simple includes might match 'a' inside 'banana', but 'sig.name' usually is a full word.
+            const nameRegex = new RegExp(`\\b${sig.name}\\b`);
+            if (nameRegex.test(doc.content)) {
+                nameFound = true;
+                if (doc.normalizedContent.includes(normalizedSig)) {
+                    signatureFound = true;
+                    break;
+                }
+            }
+        }
+        if (nameFound && !signatureFound) {
+            console.error(`❌ DRIFT DETECTED: Function '${sig.name}' is mentioned in documentation, but the updated signature was not found.`);
+            console.error(`   Expected to find: ${sig.fullSignature}`);
+            hasDrift = true;
+        }
+        else if (nameFound && signatureFound) {
+            console.log(`✅ IN SYNC: '${sig.name}' is correctly documented.`);
+        }
+        else {
+            console.log(`⚠️  UNDOCUMENTED: '${sig.name}' was not found in any documentation.`);
+        }
+    }
+    return hasDrift;
+}

package/dist/tests/extractor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extractor.test.js

@@ -0,0 +1,24 @@
+import { extractSignatures } from '../src/extractor.js';
+describe('AST Extractor', () => {
+    it('should correctly extract function name and parameters', () => {
+        const code = `
+      export function testAuth(token: string, options?: any): boolean {
+        return true;
+      }
+    `;
+        const signatures = extractSignatures(code);
+        expect(signatures).toHaveLength(1);
+        expect(signatures[0].name).toBe('testAuth');
+        expect(signatures[0].parameters).toEqual(['token: string', 'options?: any']);
+        expect(signatures[0].returnType).toBe(': boolean');
+    });
+    it('should correctly assemble the full signature string', () => {
+        const code = `
+      export function getUser(id: number): any {
+        return { name: "Test" };
+      }
+    `;
+        const signatures = extractSignatures(code);
+        expect(signatures[0].fullSignature).toBe('getUser(id: number): any');
+    });
+});

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "doc-sync-check",
+  "version": "1.0.0",
+  "description": "Documentation Drift Detector",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "doc-sync-check": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "release": "standard-version",
+    "prepare": "husky"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chetanbasuray/doc-sync-check.git"
+  },
+  "keywords": [],
+  "author": "Chetan Basuray",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/chetanbasuray/doc-sync-check/issues"
+  },
+  "homepage": "https://github.com/chetanbasuray/doc-sync-check#readme",
+  "dependencies": {
+    "@babel/parser": "^7.29.2",
+    "@babel/traverse": "^7.29.0",
+    "fs-extra": "^11.3.4",
+    "globby": "^16.2.0",
+    "meow": "^14.1.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^10.0.1",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.2",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "eslint": "^10.2.0",
+    "husky": "^9.1.7",
+    "jest": "^30.3.0",
+    "semantic-release": "^25.0.3",
+    "standard-version": "^9.5.0",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.0"
+  },
+  "overrides": {
+    "picomatch": "^4.0.4",
+    "brace-expansion": "^5.0.5"
+  }
+}