types-not-docs 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# types-not-docs
+
+Generate markdown documentation from TypeScript types. One source of truth, docs that stay in sync.
+
+Inspired by [Ship types, not docs](https://shiptypes.com) by Boris Tane.
+
+## Installation
+
+```bash
+npm install -g types-not-docs
+```
+
+Or run directly with npx:
+
+```bash
+npx types-not-docs "./src/**/*.ts" -o docs.md
+```
+
+## Usage
+
+```bash
+# Generate docs for all TypeScript files in src/
+types-not-docs "./src/**/*.ts" -o docs.md
+
+# With a custom title
+types-not-docs "./src/**/*.ts" -o docs.md -t "My SDK Reference"
+
+# Exclude additional patterns
+types-not-docs "./src/**/*.ts" -o docs.md --exclude "**/__mocks__/**"
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<glob>` | Glob pattern for TypeScript files | (required) |
+| `-o, --output <file>` | Output file | stdout |
+| `-t, --title <title>` | Document title | "API Reference" |
+| `--exclude <patterns...>` | Glob patterns to exclude | node_modules, tests, dist |
+
+## What it extracts
+
+- **Interfaces** - Properties, types, required/optional, JSDoc descriptions
+- **Type aliases** - Union types, generics, etc.
+- **Functions** - Parameters, return types, async, JSDoc with @param tags
+- **Arrow functions** - `export const fn = () => {}` syntax
+
+## Example output
+
+```markdown
+## TokenMetadata
+
+Token metadata information.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| name | `string` |  | The token's display name |
+| symbol | `string` |  | The token's ticker symbol |
+
+---
+
+## getTokenMetadata()
+
+Fetches token metadata from the chain.
+
+​```typescript
+async function getTokenMetadata(rpc: RpcClient, mint: Address): Promise<TokenMetadata>
+​```
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| rpc | `RpcClient` | ✓ | The RPC client instance |
+| mint | `Address` | ✓ | The mint address to inspect |
+
+**Returns:** `Promise<TokenMetadata>`
+```
+
+## Why?
+
+Documentation drifts from code. It's a lossy copy that inevitably falls out of sync.
+
+Types are the contract. By generating docs from types, they stay in sync automatically. This is especially valuable for AI agents that need to understand your SDK to use it.
+
+## License
+
+MIT

package/bin/types-not-docs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js');

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for types-not-docs.
+ * Parses TypeScript files and generates markdown documentation.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CLI entry point for types-not-docs.
+ * Parses TypeScript files and generates markdown documentation.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const glob_1 = require("glob");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parser_1 = require("./parser");
+const generator_1 = require("./generator");
+// Get version from package.json
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, "../package.json"), "utf-8"));
+commander_1.program
+    .name("types-not-docs")
+    .description("Generate markdown documentation from TypeScript types")
+    .version(packageJson.version)
+    .argument("<glob>", "Glob pattern for TypeScript files (e.g., ./src/**/*.ts)")
+    .option("-o, --output <file>", "Output file (defaults to stdout)")
+    .option("-t, --title <title>", "Document title", "API Reference")
+    .option("--exclude <patterns...>", "Glob patterns to exclude", [
+    "**/node_modules/**",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/dist/**",
+])
+    .addHelpText("after", `
+Examples:
+  $ types-not-docs "./src/**/*.ts"
+  $ types-not-docs "./src/**/*.ts" -o docs.md
+  $ types-not-docs "./src/**/*.ts" -o docs.md -t "My SDK Reference"
+  $ types-not-docs "./src/**/*.ts" --exclude "**/__tests__/**"
+`)
+    .action(async (globPattern, options) => {
+    try {
+        await run(globPattern, options);
+    }
+    catch (error) {
+        console.error("Error:", error.message);
+        process.exit(1);
+    }
+});
+commander_1.program.configureOutput({
+    outputError: (str, write) => {
+        write(str);
+        if (str.includes("too many arguments")) {
+            write("\nHint: Did you forget -t before the title? Use: -t \"My Title\"\n");
+        }
+    },
+});
+commander_1.program.parse();
+async function run(globPattern, options) {
+    // Find files matching the glob pattern
+    const files = await (0, glob_1.glob)(globPattern, {
+        ignore: options.exclude,
+        absolute: true,
+    });
+    if (files.length === 0) {
+        throw new Error(`No files found matching pattern: ${globPattern}`);
+    }
+    console.error(`Found ${files.length} file(s)`);
+    // Parse all files
+    const parsedFiles = [];
+    let totalInterfaces = 0;
+    let totalTypes = 0;
+    let totalFunctions = 0;
+    for (const file of files) {
+        try {
+            const parsed = (0, parser_1.parseFile)(file);
+            // Only include files that have exported types
+            if (parsed.interfaces.length > 0 ||
+                parsed.typeAliases.length > 0 ||
+                parsed.functions.length > 0) {
+                parsedFiles.push(parsed);
+                totalInterfaces += parsed.interfaces.length;
+                totalTypes += parsed.typeAliases.length;
+                totalFunctions += parsed.functions.length;
+            }
+        }
+        catch (error) {
+            console.error(`Warning: Failed to parse ${file}: ${error.message}`);
+        }
+    }
+    if (parsedFiles.length === 0) {
+        throw new Error("No exported types found in any files");
+    }
+    console.error(`Parsed ${parsedFiles.length} file(s): ${totalInterfaces} interfaces, ${totalTypes} types, ${totalFunctions} functions`);
+    // Generate markdown
+    const markdown = (0, generator_1.generateMarkdown)(parsedFiles, { title: options.title });
+    // Output
+    if (options.output) {
+        fs.writeFileSync(options.output, markdown, "utf-8");
+        console.error(`Wrote documentation to ${options.output}`);
+    }
+    else {
+        console.log(markdown);
+    }
+}

package/dist/generator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Markdown generator for parsed TypeScript types.
+ * Generates API reference-style documentation with tables.
+ */
+import type { ParsedFile } from "./types";
+export interface GeneratorOptions {
+    /** Title for the document */
+    title?: string;
+}
+/**
+ * Generate markdown documentation from parsed files.
+ */
+export declare function generateMarkdown(files: ParsedFile[], options?: GeneratorOptions): string;

package/dist/generator.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * Markdown generator for parsed TypeScript types.
+ * Generates API reference-style documentation with tables.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMarkdown = generateMarkdown;
+const path = __importStar(require("path"));
+/**
+ * Generate markdown documentation from parsed files.
+ */
+function generateMarkdown(files, options = {}) {
+    const { title = "API Reference" } = options;
+    const lines = [];
+    // Collect all items with their source files
+    const allInterfaces = [];
+    const allTypeAliases = [];
+    const allFunctions = [];
+    for (const file of files) {
+        const sourceFile = path.basename(file.filePath);
+        for (const iface of file.interfaces) {
+            allInterfaces.push({ item: iface, sourceFile });
+        }
+        for (const alias of file.typeAliases) {
+            allTypeAliases.push({ item: alias, sourceFile });
+        }
+        for (const fn of file.functions) {
+            allFunctions.push({ item: fn, sourceFile });
+        }
+    }
+    // Detect duplicate names
+    const duplicateNames = findDuplicateNames([
+        ...allInterfaces.map((i) => i.item.name),
+        ...allTypeAliases.map((t) => t.item.name),
+        ...allFunctions.map((f) => f.item.name),
+    ]);
+    // Title
+    lines.push(`# ${title}`);
+    lines.push("");
+    // Table of Contents
+    if (allInterfaces.length + allTypeAliases.length + allFunctions.length > 0) {
+        lines.push("## Table of Contents");
+        lines.push("");
+        if (allInterfaces.length > 0) {
+            lines.push("### Interfaces");
+            lines.push("");
+            for (const { item, sourceFile } of allInterfaces) {
+                const displayName = getDisplayName(item.name, sourceFile, duplicateNames);
+                const anchor = getAnchor(item.name, sourceFile, duplicateNames);
+                lines.push(`- [${displayName}](#${anchor})`);
+            }
+            lines.push("");
+        }
+        if (allTypeAliases.length > 0) {
+            lines.push("### Types");
+            lines.push("");
+            for (const { item, sourceFile } of allTypeAliases) {
+                const displayName = getDisplayName(item.name, sourceFile, duplicateNames);
+                const anchor = getAnchor(item.name, sourceFile, duplicateNames);
+                lines.push(`- [${displayName}](#${anchor})`);
+            }
+            lines.push("");
+        }
+        if (allFunctions.length > 0) {
+            lines.push("### Functions");
+            lines.push("");
+            for (const { item, sourceFile } of allFunctions) {
+                const displayName = getDisplayName(item.name, sourceFile, duplicateNames);
+                const anchor = getAnchor(item.name, sourceFile, duplicateNames);
+                lines.push(`- [${displayName}()](#${anchor})`);
+            }
+            lines.push("");
+        }
+        lines.push("---");
+        lines.push("");
+    }
+    // Interfaces
+    for (const { item, sourceFile } of allInterfaces) {
+        lines.push(...generateInterface(item, sourceFile, duplicateNames));
+        lines.push("");
+    }
+    // Type Aliases
+    for (const { item, sourceFile } of allTypeAliases) {
+        lines.push(...generateTypeAlias(item, sourceFile, duplicateNames));
+        lines.push("");
+    }
+    // Functions
+    for (const { item, sourceFile } of allFunctions) {
+        lines.push(...generateFunction(item, sourceFile, duplicateNames));
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Find names that appear more than once.
+ */
+function findDuplicateNames(names) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const name of names) {
+        if (seen.has(name)) {
+            duplicates.add(name);
+        }
+        seen.add(name);
+    }
+    return duplicates;
+}
+/**
+ * Get display name, adding source file suffix for duplicates.
+ */
+function getDisplayName(name, sourceFile, duplicates) {
+    if (duplicates.has(name)) {
+        return `${name} (${sourceFile})`;
+    }
+    return name;
+}
+/**
+ * Get anchor, adding source file suffix for duplicates.
+ */
+function getAnchor(name, sourceFile, duplicates) {
+    if (duplicates.has(name)) {
+        const combined = `${name}-${sourceFile}`;
+        return toAnchor(combined);
+    }
+    return toAnchor(name);
+}
+/**
+ * Generate markdown for an interface.
+ */
+function generateInterface(iface, sourceFile, duplicates) {
+    const lines = [];
+    const displayName = getDisplayName(iface.name, sourceFile, duplicates);
+    lines.push(`## ${displayName}`);
+    lines.push("");
+    if (iface.extends && iface.extends.length > 0) {
+        lines.push(`*Extends: ${iface.extends.join(", ")}*`);
+        lines.push("");
+    }
+    if (iface.description) {
+        lines.push(iface.description);
+        lines.push("");
+    }
+    if (iface.properties.length > 0) {
+        lines.push(...generatePropertiesTable(iface.properties));
+    }
+    else {
+        lines.push("*No properties*");
+    }
+    lines.push("");
+    lines.push("---");
+    return lines;
+}
+/**
+ * Generate a properties table.
+ */
+function generatePropertiesTable(properties) {
+    const lines = [];
+    lines.push("| Property | Type | Required | Description |");
+    lines.push("|----------|------|----------|-------------|");
+    for (const prop of properties) {
+        const required = prop.required ? "✓" : "";
+        const description = prop.description || "";
+        const type = escapeMarkdown(prop.type);
+        lines.push(`| ${prop.name} | \`${type}\` | ${required} | ${description} |`);
+    }
+    return lines;
+}
+/**
+ * Generate markdown for a type alias.
+ */
+function generateTypeAlias(alias, sourceFile, duplicates) {
+    const lines = [];
+    const displayName = getDisplayName(alias.name, sourceFile, duplicates);
+    lines.push(`## ${displayName}`);
+    lines.push("");
+    if (alias.description) {
+        lines.push(alias.description);
+        lines.push("");
+    }
+    lines.push("```typescript");
+    lines.push(`type ${alias.name} = ${alias.type}`);
+    lines.push("```");
+    lines.push("");
+    lines.push("---");
+    return lines;
+}
+/**
+ * Generate markdown for a function.
+ */
+function generateFunction(fn, sourceFile, duplicates) {
+    const lines = [];
+    const displayName = getDisplayName(fn.name, sourceFile, duplicates);
+    const asyncPrefix = fn.isAsync ? "async " : "";
+    lines.push(`## ${displayName}()`);
+    lines.push("");
+    if (fn.description) {
+        lines.push(fn.description);
+        lines.push("");
+    }
+    // Signature
+    const params = fn.parameters.map((p) => {
+        const opt = p.required ? "" : "?";
+        return `${p.name}${opt}: ${p.type}`;
+    });
+    const signature = `${asyncPrefix}function ${fn.name}(${params.join(", ")}): ${fn.returnType}`;
+    lines.push("```typescript");
+    lines.push(signature);
+    lines.push("```");
+    lines.push("");
+    // Parameters table
+    if (fn.parameters.length > 0) {
+        lines.push("**Parameters:**");
+        lines.push("");
+        lines.push(...generateParametersTable(fn.parameters));
+        lines.push("");
+    }
+    // Return type
+    lines.push(`**Returns:** \`${escapeMarkdown(fn.returnType)}\``);
+    lines.push("");
+    lines.push("---");
+    return lines;
+}
+/**
+ * Generate a parameters table.
+ */
+function generateParametersTable(parameters) {
+    const lines = [];
+    lines.push("| Name | Type | Required | Description |");
+    lines.push("|------|------|----------|-------------|");
+    for (const param of parameters) {
+        const required = param.required ? "✓" : "";
+        const description = param.description || "";
+        const type = escapeMarkdown(param.type);
+        lines.push(`| ${param.name} | \`${type}\` | ${required} | ${description} |`);
+    }
+    return lines;
+}
+/**
+ * Convert a name to a markdown anchor.
+ */
+function toAnchor(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+}
+/**
+ * Escape markdown special characters in type strings.
+ * For now, just handle pipe characters in union types.
+ */
+function escapeMarkdown(text) {
+    // Escape pipe characters for table cells
+    return text.replace(/\|/g, "\\|");
+}

package/dist/parser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * TypeScript AST parser using ts-morph.
+ * Extracts interfaces, type aliases, and functions from source files.
+ */
+import type { ParsedFile } from "./types";
+/**
+ * Parse a TypeScript file and extract all exported types.
+ */
+export declare function parseFile(filePath: string): ParsedFile;

package/dist/parser.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * TypeScript AST parser using ts-morph.
+ * Extracts interfaces, type aliases, and functions from source files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFile = parseFile;
+const ts_morph_1 = require("ts-morph");
+/**
+ * Parse a TypeScript file and extract all exported types.
+ */
+function parseFile(filePath) {
+    const project = new ts_morph_1.Project({
+        skipAddingFilesFromTsConfig: true,
+    });
+    const sourceFile = project.addSourceFileAtPath(filePath);
+    return {
+        filePath,
+        interfaces: parseInterfaces(sourceFile),
+        typeAliases: parseTypeAliases(sourceFile),
+        functions: parseFunctions(sourceFile),
+    };
+}
+// =============================================================================
+// Interface Parsing
+// =============================================================================
+/**
+ * Parse all exported interfaces from a source file.
+ */
+function parseInterfaces(sourceFile) {
+    return sourceFile
+        .getInterfaces()
+        .filter((iface) => iface.isExported())
+        .map((iface) => ({
+        kind: "interface",
+        name: iface.getName(),
+        description: getJsDocDescription(iface),
+        properties: parseProperties(iface),
+        extends: getExtendsClause(iface),
+    }));
+}
+/**
+ * Parse all properties from an interface, including method signatures.
+ */
+function parseProperties(iface) {
+    const properties = [];
+    // Regular properties
+    for (const prop of iface.getProperties()) {
+        properties.push({
+            name: prop.getName(),
+            type: prop.getType().getText(prop),
+            required: !prop.hasQuestionToken(),
+            description: getJsDocDescription(prop),
+        });
+    }
+    // Method signatures (treated as properties with function type)
+    for (const method of iface.getMethods()) {
+        const params = method
+            .getParameters()
+            .map((p) => `${p.getName()}: ${p.getType().getText(p)}`)
+            .join(", ");
+        const returnType = method.getReturnType().getText(method);
+        const funcType = `(${params}) => ${returnType}`;
+        properties.push({
+            name: method.getName(),
+            type: funcType,
+            required: !method.hasQuestionToken(),
+            description: getJsDocDescription(method),
+        });
+    }
+    return properties;
+}
+/**
+ * Get the names of interfaces that this interface extends.
+ */
+function getExtendsClause(iface) {
+    const extendsClauses = iface.getExtends();
+    if (extendsClauses.length === 0) {
+        return undefined;
+    }
+    return extendsClauses.map((clause) => clause.getText());
+}
+// =============================================================================
+// Type Alias Parsing
+// =============================================================================
+/**
+ * Parse all exported type aliases from a source file.
+ */
+function parseTypeAliases(sourceFile) {
+    return sourceFile
+        .getTypeAliases()
+        .filter((alias) => alias.isExported())
+        .map((alias) => ({
+        kind: "type",
+        name: alias.getName(),
+        type: alias.getType().getText(alias),
+        description: getJsDocDescription(alias),
+    }));
+}
+// =============================================================================
+// Function Parsing
+// =============================================================================
+/**
+ * Parse all exported functions from a source file.
+ * Includes both regular function declarations and arrow functions.
+ */
+function parseFunctions(sourceFile) {
+    const functions = [];
+    // Regular function declarations: export function foo() {}
+    for (const fn of sourceFile.getFunctions()) {
+        if (fn.isExported()) {
+            functions.push(parseFunctionDeclaration(fn));
+        }
+    }
+    // Arrow functions: export const foo = () => {}
+    for (const varDecl of sourceFile.getVariableDeclarations()) {
+        const varStatement = varDecl.getVariableStatement();
+        if (varStatement?.isExported()) {
+            const init = varDecl.getInitializer();
+            if (ts_morph_1.Node.isArrowFunction(init)) {
+                functions.push(parseArrowFunction(varDecl, init));
+            }
+        }
+    }
+    return functions;
+}
+/**
+ * Parse a regular function declaration.
+ */
+function parseFunctionDeclaration(fn) {
+    const jsDocs = fn.getJsDocs();
+    const paramDescriptions = extractParamDescriptions(jsDocs);
+    return {
+        kind: "function",
+        name: fn.getName() || "anonymous",
+        description: getJsDocDescription(fn),
+        parameters: parseParameters(fn.getParameters(), paramDescriptions),
+        returnType: fn.getReturnType().getText(fn),
+        isAsync: fn.isAsync(),
+    };
+}
+/**
+ * Parse an arrow function assigned to a variable.
+ */
+function parseArrowFunction(varDecl, arrowFn) {
+    // JSDoc is on the variable statement, not the arrow function
+    const varStatement = varDecl.getVariableStatement();
+    const jsDocs = varStatement?.getJsDocs() || [];
+    const paramDescriptions = extractParamDescriptions(jsDocs);
+    return {
+        kind: "function",
+        name: varDecl.getName(),
+        description: getJsDocDescriptionFromDocs(jsDocs),
+        parameters: parseParameters(arrowFn.getParameters(), paramDescriptions),
+        returnType: arrowFn.getReturnType().getText(arrowFn),
+        isAsync: arrowFn.isAsync(),
+    };
+}
+/**
+ * Parse function parameters with their JSDoc descriptions.
+ */
+function parseParameters(params, paramDescriptions) {
+    return params.map((param) => ({
+        name: param.getName(),
+        type: param.getType().getText(param),
+        required: !param.isOptional() && !param.hasInitializer(),
+        description: paramDescriptions.get(param.getName()),
+    }));
+}
+/**
+ * Extract @param descriptions from JSDoc comments.
+ * Only handles top-level params (not nested like @param input.authority).
+ */
+function extractParamDescriptions(jsDocs) {
+    const descriptions = new Map();
+    if (jsDocs.length === 0) {
+        return descriptions;
+    }
+    // Use the last JSDoc - the one immediately preceding the declaration
+    const jsDoc = jsDocs[jsDocs.length - 1];
+    for (const tag of jsDoc.getTags()) {
+        if (tag.getTagName() === "param" && ts_morph_1.Node.isJSDocParameterTag(tag)) {
+            const paramName = tag.getName();
+            const comment = tag.getCommentText()?.trim();
+            // Only store top-level params (no dots like input.authority)
+            if (paramName && !paramName.includes(".") && comment) {
+                // Remove leading dash if present ("- description" -> "description")
+                const description = comment.replace(/^-\s*/, "");
+                descriptions.set(paramName, description);
+            }
+        }
+    }
+    return descriptions;
+}
+// =============================================================================
+// JSDoc Utilities
+// =============================================================================
+/**
+ * Extract JSDoc description from a node.
+ * Returns undefined if no JSDoc is present.
+ */
+function getJsDocDescription(node) {
+    const jsDocs = node.getJsDocs?.();
+    return getJsDocDescriptionFromDocs(jsDocs);
+}
+/**
+ * Extract description from JSDoc array.
+ * Uses the last JSDoc comment (the one immediately preceding the declaration).
+ */
+function getJsDocDescriptionFromDocs(jsDocs) {
+    if (!jsDocs || jsDocs.length === 0) {
+        return undefined;
+    }
+    // Use the last JSDoc - this is the one immediately preceding the declaration.
+    // Earlier JSDocs might be file-level comments or comments for previous code.
+    const jsDoc = jsDocs[jsDocs.length - 1];
+    const description = jsDoc.getDescription?.();
+    if (!description || description.trim() === "") {
+        return undefined;
+    }
+    return description.trim();
+}

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Internal type model for types-not-docs.
+ * These types represent the extracted information from TypeScript source files.
+ */
+/**
+ * A property of an interface or inline object type.
+ */
+export interface ParsedProperty {
+    /** Property name */
+    name: string;
+    /** Type as a string (e.g., "string", "Address | null", "Promise<Order>") */
+    type: string;
+    /** Whether the property is required (not optional) */
+    required: boolean;
+    /** Description from JSDoc comment, if present */
+    description?: string;
+}
+/**
+ * A parsed TypeScript interface.
+ */
+export interface ParsedInterface {
+    kind: "interface";
+    /** Interface name */
+    name: string;
+    /** Description from JSDoc comment, if present */
+    description?: string;
+    /** Interface properties */
+    properties: ParsedProperty[];
+    /** Names of interfaces this extends, if any */
+    extends?: string[];
+}
+/**
+ * A parsed TypeScript type alias.
+ */
+export interface ParsedTypeAlias {
+    kind: "type";
+    /** Type alias name */
+    name: string;
+    /** The type definition as a string (e.g., "'a' | 'b' | 'c'") */
+    type: string;
+    /** Description from JSDoc comment, if present */
+    description?: string;
+}
+/**
+ * A parameter of a function.
+ */
+export interface ParsedParameter {
+    /** Parameter name */
+    name: string;
+    /** Type as a string */
+    type: string;
+    /** Whether the parameter is required (not optional, no default value) */
+    required: boolean;
+    /** Description from @param JSDoc tag, if present */
+    description?: string;
+}
+/**
+ * A parsed exported function.
+ */
+export interface ParsedFunction {
+    kind: "function";
+    /** Function name */
+    name: string;
+    /** Description from JSDoc comment, if present */
+    description?: string;
+    /** Function parameters */
+    parameters: ParsedParameter[];
+    /** Return type as a string */
+    returnType: string;
+    /** Whether the function is async */
+    isAsync: boolean;
+}
+/**
+ * Union of all parsed type kinds.
+ */
+export type ParsedType = ParsedInterface | ParsedTypeAlias | ParsedFunction;
+/**
+ * All extracted types from a single source file.
+ */
+export interface ParsedFile {
+    /** File path (relative or absolute) */
+    filePath: string;
+    /** All exported interfaces */
+    interfaces: ParsedInterface[];
+    /** All exported type aliases */
+    typeAliases: ParsedTypeAlias[];
+    /** All exported functions */
+    functions: ParsedFunction[];
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Internal type model for types-not-docs.
+ * These types represent the extracted information from TypeScript source files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "types-not-docs",
+  "version": "0.1.0",
+  "description": "Generate markdown documentation from TypeScript types",
+  "main": "dist/cli.js",
+  "bin": {
+    "types-not-docs": "./bin/types-not-docs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "typescript",
+    "documentation",
+    "markdown",
+    "types",
+    "cli",
+    "api-reference",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/types-not-docs.git"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "glob": "^13.0.3",
+    "ts-morph": "^27.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.9.3"
+  }
+}