jsdoc-scribe 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chintan Goswami
+
+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,131 @@
+# jsdoc-scribe
+
+Pure, deterministic, **AST-based** JSDoc comment generator for JavaScript & TypeScript.
+**No AI / LLM is used anywhere** — every line of every comment is derived
+mechanically from the syntax tree (names, modifiers, type annotations,
+parameter lists, heritage clauses, enum members, etc). Same input always
+produces the same output.
+
+## Install
+
+```bash
+# run once without installing anything
+npx jsdoc-scribe . --write
+
+# or add it to your project
+npm install --save-dev jsdoc-scribe
+
+# or install it globally
+npm install -g jsdoc-scribe
+```
+
+Once installed, the command is **`gen-comments`**.
+
+## Usage
+
+```bash
+gen-comments <path> [path2 ...] [options]
+```
+
+`<path>` can be a single file **or a directory** — directories are scanned
+recursively for `.js` / `.jsx` / `.ts` / `.tsx` files. `node_modules`, `.git`,
+`dist`, `build`, `out`, `coverage`, `.next`, `.turbo`, `.cache`, and any other
+dotfolder are skipped automatically.
+
+| Flag | Description |
+|---|---|
+| `--write`, `-w` | Edit files **in place**. Without this flag, output goes to a sibling `<name>.commented.<ext>` file next to each original, so you can review a diff before committing to it. |
+| `--force`, `-f` | Re-insert comment blocks even on nodes that already have a leading `/** */`. Off by default, to stay idempotent. |
+| `--help`, `-h` | Show usage. |
+| `--version`, `-v` | Show the installed version. |
+
+```bash
+gen-comments src/utils.ts                  # preview only -> utils.commented.ts
+gen-comments .                              # scan whole project, preview only
+gen-comments . --write                      # scan whole project, edit in place
+gen-comments src --write --force             # also re-document already-commented files
+```
+
+If you run `--write` outside a git repo, the CLI prints a one-line warning
+(not a blocker) recommending you commit first so you have something to diff
+or revert against.
+
+## The algorithm
+
+1. **Parse** each file into a `ts.SourceFile` AST using the TypeScript
+   compiler's parser (`typescript` npm package). That parser is syntax-only —
+   it never type-checks — and it's a superset parser for JavaScript, which is
+   why this works on plain `.js`/`.jsx` just as well as `.ts`/`.tsx`.
+2. **Walk** the AST recursively. Tracked node kinds:
+   - `FunctionDeclaration` (top-level or nested)
+   - `ClassDeclaration` + its `constructor` / methods / properties / get-set
+   - `VariableStatement` (`const`/`let`/`var`, including arrow/function inits)
+   - `PropertyAssignment` with a function/arrow value inside an object literal
+   - `InterfaceDeclaration`, `TypeAliasDeclaration`, `EnumDeclaration`
+3. **Skip** any node that already has a leading `/** ... */` block (checked
+   via `ts.getLeadingCommentRanges`) — unless `--force` is passed. This makes
+   the tool idempotent: running it twice never duplicates comments.
+4. **Build** the comment block from pure syntax only:
+   - An explicit type annotation is always used as-is.
+   - With no annotation, it falls back to a syntactic guess: literal kind for
+     variables (`'x'` → `string`, `[1,2]` → `Array`, …), and for function
+     return types, a scan for a top-level `return <value>;` (so a function
+     that clearly returns something is never mislabeled `void` just because
+     it lacks a type annotation).
+   - Modifiers (`async`, `static`, `private`, `readonly`, `abstract`,
+     `export`, generator `*`) are read directly off the AST node.
+5. **Insert** the comment as plain text at the exact byte offset where the
+   node's own line indentation begins. All edits across a file are collected
+   first, then applied **bottom-to-top** so earlier offsets never shift.
+   The rest of the file is never re-printed or reformatted — only insertions
+   happen.
+6. **Write** the result — to `<file>.commented.<ext>` by default, or back to
+   the original file with `--write`.
+
+## Using it as a library
+
+```js
+const { processFile, collectFiles } = require('jsdoc-scribe');
+
+// process one file, return number of comment blocks added
+processFile('src/utils.ts', { write: true });
+
+// recursively find every matching source file under a directory
+const files = collectFiles('src');
+```
+
+## Known scope / limitations (by design)
+
+- Inline anonymous callbacks passed directly as call arguments
+  (`arr.map(x => x * 2)`) are **not** commented — inserting a multi-line block
+  there would mangle the call expression. Anything with its own declaration
+  (function decl, class member, variable, named object property) is covered.
+- Type/return inference is 100% syntactic. It is never "smart" about what
+  your code *means* — only what it *looks like* structurally. That's the
+  whole point: deterministic, reproducible output, every time.
+- Multi-declarator statements (`const a = 1, b = 2;`) get one combined block
+  rather than a per-declarator function-style doc.
+- `.d.ts` files are skipped (no implementation to document).
+
+## Development
+
+```bash
+git clone <your-repo-url>
+cd jsdoc-scribe
+npm install
+npm test          # runs the self-test suite (test/run.js)
+npm run demo      # runs the CLI against the bundled example/ files
+```
+
+## Publishing new versions
+
+```bash
+npm version patch   # or minor / major
+npm publish
+```
+
+`prepublishOnly` runs the test suite automatically before every publish.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { processFile, collectFiles } = require("../lib/index.js");
+const pkg = require("../package.json");
+
+function printHelp() {
+    console.log(`
+${pkg.name} v${pkg.version}
+Pure, AST-based JSDoc comment generator for JavaScript & TypeScript. No AI involved.
+
+Usage:
+  gen-comments <path> [path2 ...] [options]
+
+  <path> can be a single file OR a directory (scanned recursively for
+  .js/.jsx/.ts/.tsx files; node_modules, .git, dist, build, etc. are skipped).
+
+Options:
+  --write, -w     Overwrite files in place.
+                   (default: writes a sibling "<name>.commented.<ext>" file
+                    next to each original, so you can review a diff first)
+  --force, -f     Add comment blocks even on nodes that already have one.
+  --help, -h      Show this help.
+  --version, -v   Show the installed version.
+
+Examples:
+  gen-comments src/utils.ts                  # preview only, writes utils.commented.ts
+  gen-comments .                              # scan whole project, preview only
+  gen-comments . --write                      # scan whole project, edit files in place
+  gen-comments src --write --force            # re-document files that already have JSDoc
+`);
+}
+
+function parseArgs(argv) {
+    const args = { inputs: [], write: false, force: false, help: false, version: false };
+    for (const a of argv) {
+        if (a === "--write" || a === "-w") args.write = true;
+        else if (a === "--force" || a === "-f") args.force = true;
+        else if (a === "--help" || a === "-h") args.help = true;
+        else if (a === "--version" || a === "-v") args.version = true;
+        else args.inputs.push(a);
+    }
+    return args;
+}
+
+function isInsideGitRepo(startDir) {
+    let dir = path.resolve(startDir);
+    while (true) {
+        if (fs.existsSync(path.join(dir, ".git"))) return true;
+        const parent = path.dirname(dir);
+        if (parent === dir) return false;
+        dir = parent;
+    }
+}
+
+function main() {
+    const argv = process.argv.slice(2);
+    const { inputs, write, force, help, version } = parseArgs(argv);
+
+    if (version) {
+        console.log(pkg.version);
+        return;
+    }
+    if (help || inputs.length === 0) {
+        printHelp();
+        process.exitCode = inputs.length === 0 && !help ? 1 : 0;
+        return;
+    }
+
+    if (write && !isInsideGitRepo(process.cwd())) {
+        console.warn(
+            "⚠ --write will edit files in place and this folder is not (or you are not inside) a git repo.\n" +
+                "  Consider committing your work first so you have something to diff/revert against.\n",
+        );
+    }
+
+    let files = [];
+    for (const input of inputs) {
+        if (!fs.existsSync(input)) {
+            console.error(`skip: path not found - ${input}`);
+            continue;
+        }
+        files.push(...collectFiles(input));
+    }
+    files = [...new Set(files)];
+
+    if (files.length === 0) {
+        console.log("No matching .js/.jsx/.ts/.tsx files found.");
+        return;
+    }
+
+    console.log(`Scanning ${files.length} file(s)...`);
+    let totalBlocks = 0;
+    let touchedFiles = 0;
+    for (const file of files) {
+        try {
+            const count = processFile(file, { write, force });
+            totalBlocks += count;
+            if (count > 0) touchedFiles += 1;
+        } catch (err) {
+            console.error(`  ${file} -> FAILED: ${err.message}`);
+        }
+    }
+
+    console.log(
+        `\nDone. ${totalBlocks} comment block(s) added across ${touchedFiles} file(s) ` + `(${files.length} scanned).`,
+    );
+    if (!write) {
+        console.log("This was a preview run — pass --write to edit the original files in place.");
+    }
+}
+
+main();

package/lib/index.js

@@ -0,0 +1,427 @@
+"use strict";
+
+/**
+ * jsdoc-scribe — lib/index.js
+ * ----------------------------------------
+ * A PURE, deterministic, AST-based JSDoc comment generator.
+ * No AI / LLM / external API is used anywhere — every comment line is
+ * derived mechanically from syntax: names, modifiers, type annotations,
+ * parameter lists, heritage clauses, enum members, etc.
+ *
+ * Works on plain JavaScript (.js/.jsx) AND TypeScript (.ts/.tsx) because
+ * both are parsed with the TypeScript compiler's parser, which is a
+ * superset parser for JS (it never type-checks, only parses syntax).
+ *
+ * This file exports plain functions so it can be:
+ *   1. Driven by bin/cli.js as a command-line tool, or
+ *   2. require()'d directly in another Node script / build pipeline:
+ *        const { processFile } = require('jsdoc-scribe');
+ */
+
+const fs = require("fs");
+const path = require("path");
+const ts = require("typescript");
+
+const DEFAULT_EXTENSIONS = [".js", ".jsx", ".ts", ".tsx"];
+const DEFAULT_IGNORE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+
+// ---------------------------------------------------------------------------
+// Low-level helpers
+// ---------------------------------------------------------------------------
+
+function getScriptKind(file) {
+    switch (path.extname(file).toLowerCase()) {
+        case ".tsx":
+            return ts.ScriptKind.TSX;
+        case ".ts":
+            return ts.ScriptKind.TS;
+        case ".jsx":
+            return ts.ScriptKind.JSX;
+        default:
+            return ts.ScriptKind.JS;
+    }
+}
+
+/** True if `node` already has a leading /** ... *\/ block right above it. */
+function hasLeadingJSDoc(sourceFile, node) {
+    const ranges = ts.getLeadingCommentRanges(sourceFile.text, node.getFullStart()) || [];
+    return ranges.some((r) => sourceFile.text.slice(r.pos, r.pos + 3) === "/**");
+}
+
+/**
+ * Walk backwards from the node's first real token to find where its own
+ * line-indentation begins. Returns the exact insertion offset + the
+ * whitespace string to reuse for every comment line, so the comment lines
+ * up visually with the code it documents — without re-printing/reformatting
+ * the rest of the file.
+ */
+function getIndentAndInsertionPos(sourceFile, node) {
+    const start = node.getStart(sourceFile);
+    const text = sourceFile.text;
+    let i = start;
+    while (i > 0 && (text[i - 1] === " " || text[i - 1] === "\t")) i--;
+    return { pos: i, indent: text.slice(i, start) };
+}
+
+function modifiersOf(node) {
+    const mods = (node.modifiers || []).map((m) => ts.SyntaxKind[m.kind]);
+    return {
+        isExported: mods.includes("ExportKeyword"),
+        isAsync: mods.includes("AsyncKeyword"),
+        isStatic: mods.includes("StaticKeyword"),
+        isReadonly: mods.includes("ReadonlyKeyword"),
+        isPrivate: mods.includes("PrivateKeyword"),
+        isProtected: mods.includes("ProtectedKeyword"),
+        isAbstract: mods.includes("AbstractKeyword"),
+    };
+}
+
+function typeText(node) {
+    return node && node.type ? node.type.getText() : null;
+}
+
+function isFunctionLikeInitializer(init) {
+    return !!init && (init.kind === ts.SyntaxKind.ArrowFunction || init.kind === ts.SyntaxKind.FunctionExpression);
+}
+
+/** Purely syntactic: does this block contain a `return <value>;` at its own level (not inside a nested function)? */
+function hasReturnWithValue(block) {
+    let found = false;
+    function walk(n) {
+        if (found) return;
+        if (ts.isReturnStatement(n)) {
+            if (n.expression) found = true;
+            return;
+        }
+        if (ts.isFunctionLike(n)) return; // don't attribute a nested closure's return to the outer function
+        ts.forEachChild(n, walk);
+    }
+    walk(block);
+    return found;
+}
+
+/**
+ * Decide the @returns type with no semantics, no AI — just syntax:
+ * 1. An explicit type annotation always wins.
+ * 2. A concise arrow body (`x => x + 1`, no braces) always produces a value.
+ * 3. A block body is scanned for a top-level `return <value>;`.
+ * 4. Otherwise it's void.
+ */
+function inferReturnType(fnNode) {
+    const explicit = typeText(fnNode);
+    if (explicit) return explicit;
+    const body = fnNode.body;
+    if (!body) return "void";
+    if (body.kind !== ts.SyntaxKind.Block) return "any"; // concise arrow body
+    return hasReturnWithValue(body) ? "any" : "void";
+}
+
+/** Best-effort, purely syntactic type guess from an initializer expression. No semantics, no AI. */
+function inferTypeFromInitializer(init) {
+    if (!init) return "any";
+    switch (init.kind) {
+        case ts.SyntaxKind.StringLiteral:
+        case ts.SyntaxKind.NoSubstitutionTemplateLiteral:
+            return "string";
+        case ts.SyntaxKind.NumericLiteral:
+            return "number";
+        case ts.SyntaxKind.TrueKeyword:
+        case ts.SyntaxKind.FalseKeyword:
+            return "boolean";
+        case ts.SyntaxKind.ArrayLiteralExpression:
+            return "Array";
+        case ts.SyntaxKind.ObjectLiteralExpression:
+            return "Object";
+        case ts.SyntaxKind.ArrowFunction:
+        case ts.SyntaxKind.FunctionExpression:
+            return "Function";
+        case ts.SyntaxKind.NewExpression:
+            return init.expression ? init.expression.getText() : "Object";
+        default:
+            return "any";
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Comment builders — every line below comes ONLY from AST shape, never from
+// guessing "what the code means".
+// ---------------------------------------------------------------------------
+
+function buildParamLines(params) {
+    return (params || []).map((p) => {
+        const name = p.name.getText();
+        const optional = !!p.questionToken || !!p.initializer;
+        const type = typeText(p) || (p.initializer ? inferTypeFromInitializer(p.initializer) : "any");
+        const label = optional ? `[${name}]` : name;
+        return ` * @param {${type}} ${label}`;
+    });
+}
+
+function buildFunctionDoc({ name, params, returnType, mods, isGenerator }) {
+    const lines = ["/**", ` * @function ${name || "anonymous"}`];
+    if (mods.isExported) lines.push(" * @exported");
+    if (mods.isAsync) lines.push(" * @async");
+    if (isGenerator) lines.push(" * @generator");
+    lines.push(...buildParamLines(params));
+    lines.push(` * @returns {${returnType || "void"}}`);
+    lines.push(" */");
+    return lines;
+}
+
+function buildClassDoc(node) {
+    const name = node.name ? node.name.getText() : "AnonymousClass";
+    const mods = modifiersOf(node);
+    const heritage = node.heritageClauses || [];
+    const lines = ["/**", ` * @class ${name}`];
+    if (mods.isExported) lines.push(" * @exported");
+    if (mods.isAbstract) lines.push(" * @abstract");
+    for (const h of heritage) {
+        const kw = h.token === ts.SyntaxKind.ExtendsKeyword ? "@extends" : "@implements";
+        for (const t of h.types) lines.push(` * ${kw} ${t.getText()}`);
+    }
+    lines.push(" */");
+    return lines;
+}
+
+function buildMethodDoc(node) {
+    const mods = modifiersOf(node);
+    const visibility = mods.isPrivate ? "private" : mods.isProtected ? "protected" : "public";
+    const name = node.name.getText();
+    const kind = ts.isGetAccessorDeclaration(node) ? "getter" : ts.isSetAccessorDeclaration(node) ? "setter" : "method";
+    const lines = ["/**", ` * @${kind} ${name}`, ` * @${visibility}`];
+    if (mods.isStatic) lines.push(" * @static");
+    if (mods.isAbstract) lines.push(" * @abstract");
+    if (mods.isAsync) lines.push(" * @async");
+    if (node.asteriskToken) lines.push(" * @generator");
+    lines.push(...buildParamLines(node.parameters));
+    lines.push(` * @returns {${inferReturnType(node)}}`);
+    lines.push(" */");
+    return lines;
+}
+
+function buildMemberDoc(node) {
+    if (ts.isConstructorDeclaration(node)) {
+        const lines = ["/**", " * @constructor"];
+        lines.push(...buildParamLines(node.parameters));
+        lines.push(" */");
+        return lines;
+    }
+    if (ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) {
+        return buildMethodDoc(node);
+    }
+    if (ts.isPropertyDeclaration(node)) {
+        const mods = modifiersOf(node);
+        const visibility = mods.isPrivate ? "private" : mods.isProtected ? "protected" : "public";
+        const name = node.name.getText();
+        const type = typeText(node) || inferTypeFromInitializer(node.initializer);
+        const lines = ["/**", ` * @member ${name}`, ` * @type {${type}}`, ` * @${visibility}`];
+        if (mods.isStatic) lines.push(" * @static");
+        if (mods.isReadonly) lines.push(" * @readonly");
+        lines.push(" */");
+        return lines;
+    }
+    return null;
+}
+
+function buildSingleVariableDoc(decl, isConst) {
+    const name = decl.name.getText();
+    const init = decl.initializer;
+    if (isFunctionLikeInitializer(init)) {
+        return buildFunctionDoc({
+            name,
+            params: init.parameters,
+            returnType: inferReturnType(init),
+            mods: { isAsync: (init.modifiers || []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) },
+            isGenerator: !!init.asteriskToken,
+        });
+    }
+    const type = typeText(decl) || inferTypeFromInitializer(init);
+    return ["/**", ` * @${isConst ? "constant" : "variable"} ${name}`, ` * @type {${type}}`, " */"];
+}
+
+function buildVariableStatementDoc(node, isConst) {
+    const decls = node.declarationList.declarations;
+    if (decls.length === 1) return buildSingleVariableDoc(decls[0], isConst);
+    const lines = ["/**"];
+    for (const decl of decls) {
+        const type = typeText(decl) || inferTypeFromInitializer(decl.initializer);
+        lines.push(` * @${isConst ? "constant" : "variable"} ${decl.name.getText()} {${type}}`);
+    }
+    lines.push(" */");
+    return lines;
+}
+
+function buildInterfaceDoc(node) {
+    const name = node.name.getText();
+    const lines = ["/**", ` * @interface ${name}`];
+    for (const m of node.members) {
+        if (ts.isPropertySignature(m) && m.name) {
+            lines.push(` * @property {${typeText(m) || "any"}} ${m.name.getText()}`);
+        }
+    }
+    lines.push(" */");
+    return lines;
+}
+
+function buildTypeAliasDoc(node) {
+    return ["/**", ` * @typedef {${node.type.getText()}} ${node.name.getText()}`, " */"];
+}
+
+function buildEnumDoc(node) {
+    const members = node.members.map((m) => m.name.getText()).join(" | ");
+    return ["/**", ` * @enum ${node.name.getText()}`, ` * @values ${members}`, " */"];
+}
+
+// ---------------------------------------------------------------------------
+// AST walk: collect {pos, text} edits, never mutating the source directly.
+// ---------------------------------------------------------------------------
+
+function collectEdits(sourceFile, force) {
+    const edits = [];
+
+    function addEdit(node, linesFn) {
+        if (!force && hasLeadingJSDoc(sourceFile, node)) return;
+        const lines = linesFn();
+        if (!lines) return;
+        const { pos, indent } = getIndentAndInsertionPos(sourceFile, node);
+        const text = lines.map((l) => indent + l).join("\n") + "\n";
+        edits.push({ pos, text });
+    }
+
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) && node.body) {
+            addEdit(node, () =>
+                buildFunctionDoc({
+                    name: node.name ? node.name.getText() : null,
+                    params: node.parameters,
+                    returnType: inferReturnType(node),
+                    mods: modifiersOf(node),
+                    isGenerator: !!node.asteriskToken,
+                }),
+            );
+        } else if (ts.isClassDeclaration(node)) {
+            addEdit(node, () => buildClassDoc(node));
+        } else if (
+            ts.isMethodDeclaration(node) ||
+            ts.isConstructorDeclaration(node) ||
+            ts.isPropertyDeclaration(node) ||
+            ts.isGetAccessorDeclaration(node) ||
+            ts.isSetAccessorDeclaration(node)
+        ) {
+            addEdit(node, () => buildMemberDoc(node));
+        } else if (ts.isPropertyAssignment(node) && isFunctionLikeInitializer(node.initializer)) {
+            const init = node.initializer;
+            addEdit(node, () =>
+                buildFunctionDoc({
+                    name: node.name.getText(),
+                    params: init.parameters,
+                    returnType: inferReturnType(init),
+                    mods: { isAsync: (init.modifiers || []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) },
+                    isGenerator: !!init.asteriskToken,
+                }),
+            );
+        } else if (ts.isVariableStatement(node)) {
+            const isConst = (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+            addEdit(node, () => buildVariableStatementDoc(node, isConst));
+        } else if (ts.isInterfaceDeclaration(node)) {
+            addEdit(node, () => buildInterfaceDoc(node));
+        } else if (ts.isTypeAliasDeclaration(node)) {
+            addEdit(node, () => buildTypeAliasDoc(node));
+        } else if (ts.isEnumDeclaration(node)) {
+            addEdit(node, () => buildEnumDoc(node));
+        }
+        ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return edits;
+}
+
+// ---------------------------------------------------------------------------
+// File processing
+// ---------------------------------------------------------------------------
+
+/**
+ * Process a single file. Returns the number of comment blocks added.
+ * @param {string} filePath
+ * @param {{ write?: boolean, force?: boolean, silent?: boolean }} [options]
+ * @returns {number}
+ */
+function processFile(filePath, options = {}) {
+    const { write = false, force = false, silent = false } = options;
+    const sourceText = fs.readFileSync(filePath, "utf8");
+    const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+
+    const edits = collectEdits(sourceFile, force);
+    edits.sort((a, b) => b.pos - a.pos); // bottom-to-top so earlier offsets stay valid
+
+    let output = sourceText;
+    for (const edit of edits) {
+        output = output.slice(0, edit.pos) + edit.text + output.slice(edit.pos);
+    }
+
+    const outPath = write ? filePath : filePath.replace(/(\.[jt]sx?)$/, ".commented$1");
+    if (edits.length > 0 || write) {
+        fs.writeFileSync(outPath, output, "utf8");
+    }
+    if (!silent) {
+        console.log(`  ${filePath} -> ${outPath} (${edits.length} block${edits.length === 1 ? "" : "s"})`);
+    }
+    return edits.length;
+}
+
+// ---------------------------------------------------------------------------
+// Directory / project-wide scanning
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively collect all matching source files under a path.
+ * If `inputPath` is itself a file, returns it (if its extension matches).
+ * @param {string} inputPath
+ * @param {string[]} [extensions]
+ * @param {Set<string>} [ignoreDirs]
+ * @returns {string[]}
+ */
+function collectFiles(inputPath, extensions = DEFAULT_EXTENSIONS, ignoreDirs = DEFAULT_IGNORE_DIRS) {
+    const stat = fs.statSync(inputPath);
+    if (stat.isFile()) {
+        return extensions.includes(path.extname(inputPath).toLowerCase()) ? [inputPath] : [];
+    }
+    if (!stat.isDirectory()) return [];
+
+    const results = [];
+    function walk(dir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (ignoreDirs.has(entry.name) || entry.name.startsWith(".")) continue;
+                walk(full);
+            } else if (entry.isFile()) {
+                const lower = entry.name.toLowerCase();
+                if (lower.endsWith(".d.ts")) continue; // type-declaration files have no implementations to document
+                if (/\.commented\.[jt]sx?$/.test(lower)) continue; // skip our own previous output
+                if (extensions.includes(path.extname(lower))) results.push(full);
+            }
+        }
+    }
+    walk(inputPath);
+    return results;
+}
+
+module.exports = {
+    processFile,
+    collectFiles,
+    collectEdits,
+    DEFAULT_EXTENSIONS,
+    DEFAULT_IGNORE_DIRS,
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "jsdoc-scribe",
+    "version": "1.0.0",
+    "description": "Pure AST-based JSDoc comment generator for JS/TS - no AI involved.",
+    "main": "lib/index.js",
+    "bin": {
+        "gen-comments": "./bin/cli.js"
+    },
+    "files": [
+        "bin",
+        "lib",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "demo": "node bin/cli.js example",
+        "test": "node test/run.js",
+        "prepublishOnly": "npm test"
+    },
+    "keywords": [
+        "jsdoc",
+        "comments",
+        "documentation",
+        "typescript",
+        "javascript",
+        "cli",
+        "ast",
+        "code-documentation",
+        "comment-generator",
+        "autodoc"
+    ],
+    "author": {
+        "name": "Chintan Goswami"
+    },
+    "license": "MIT",
+    "engines": {
+        "node": ">=14"
+    },
+    "dependencies": {
+        "typescript": ">=5.0.0"
+    }
+}