agent-readable-ts 0.1.0

package/dist/src/packages.js

@@ -0,0 +1,201 @@
+/**
+ * Specifier parsing, type-declaration loading, and on-demand package
+ * acquisition for the CLI.
+ *
+ * Everything here is side-effect-light and free of `process.exit`: functions
+ * that hit an unrecoverable condition throw, so the CLI entry point can convert
+ * the error to a message and the logic stays unit-testable.
+ */
+import { parseTypeSignatures } from "./source-types.js";
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+export const CACHE_DIR = process.env.AGENT_READABLE_CACHE ?? join(homedir(), ".cache", "agent-readable-ts");
+// ── specifier parsing ──────────────────────────────────────────────────────────
+export function parseSpecifier(specifier) {
+    const colonIdx = specifier.lastIndexOf(":");
+    // Ignore a Windows drive-letter colon (e.g. "C:\path") so paths without an
+    // explicit export are not split at the drive letter.
+    if (colonIdx <= 1) {
+        return { modulePath: specifier, exportName: null };
+    }
+    return { modulePath: specifier.slice(0, colonIdx), exportName: specifier.slice(colonIdx + 1) };
+}
+export function isBarePackageName(modulePath) {
+    if (modulePath.startsWith("."))
+        return false;
+    if (modulePath.startsWith("/"))
+        return false;
+    if (modulePath.startsWith("node:"))
+        return false;
+    if (/\.[a-zA-Z]{1,4}$/.test(modulePath))
+        return false;
+    return true;
+}
+export function splitPackageSpec(spec) {
+    // Separate an install spec (which may carry a version) from the import name.
+    // Scoped: "@scope/pkg@1.2.3" → name "@scope/pkg". Plain: "pkg@1" → name "pkg".
+    const at = spec.startsWith("@") ? spec.indexOf("@", 1) : spec.indexOf("@");
+    return at > 0 ? { name: spec.slice(0, at), install: spec } : { name: spec, install: spec };
+}
+// ── export walking ─────────────────────────────────────────────────────────────
+export function walkExportPath(target, exportPath) {
+    let current = target;
+    for (const part of exportPath.split(".")) {
+        if (current === null || current === undefined) {
+            throw new Error(`Cannot resolve "${part}" on null/undefined while walking "${exportPath}".`);
+        }
+        const obj = current;
+        if (!(part in obj)) {
+            const available = Object.keys(obj).join(", ");
+            throw new Error(`Export "${part}" not found. Available exports: ${available || "(none)"}`);
+        }
+        current = obj[part];
+    }
+    return current;
+}
+// ── type signature loading ─────────────────────────────────────────────────────
+function parseFile(path, exportName) {
+    try {
+        const source = readFileSync(path, "utf-8");
+        return parseTypeSignatures(source, exportName, path) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function adjacentDtsPath(absolutePath) {
+    if (absolutePath.endsWith(".js"))
+        return absolutePath.replace(/\.js$/, ".d.ts");
+    if (absolutePath.endsWith(".mjs"))
+        return absolutePath.replace(/\.mjs$/, ".d.mts");
+    if (absolutePath.endsWith(".cjs"))
+        return absolutePath.replace(/\.cjs$/, ".d.cts");
+    return null;
+}
+export function loadTypeSigs(absolutePath, exportName) {
+    // Declaration files: parse directly.
+    if (absolutePath.endsWith(".d.ts") || absolutePath.endsWith(".d.mts") || absolutePath.endsWith(".d.cts")) {
+        return parseFile(absolutePath, exportName);
+    }
+    // Source files (.ts excluding .d.ts, or .tsx): parse directly.
+    if (absolutePath.endsWith(".tsx") || (absolutePath.endsWith(".ts") && !absolutePath.endsWith(".d.ts"))) {
+        return parseFile(absolutePath, exportName);
+    }
+    // .js/.mjs/.cjs: look for an adjacent declaration file.
+    const dtsPath = adjacentDtsPath(absolutePath);
+    return dtsPath ? parseFile(dtsPath, exportName) : undefined;
+}
+// ── export list formatting ─────────────────────────────────────────────────────
+export function formatExportList(packageName, exports, typeSigs) {
+    const lines = exports.map((e) => {
+        if (e.kind === "class")
+            return `- \`${e.name}\` class`;
+        if (e.kind === "function") {
+            const sig = typeSigs?.get(e.name);
+            if (sig) {
+                const params = sig.params.map((p) => `${p.name}: ${p.type}`).join(", ");
+                const ret = sig.returnType ? `: ${sig.returnType}` : "";
+                return `- \`${e.name}(${params})${ret}\` function`;
+            }
+            return `- \`${e.name}(...)\` function`;
+        }
+        if (e.kind === "default")
+            return `- \`${e.name}\` (default export)`;
+        return `- \`${e.name}\` object`;
+    });
+    return `# ${packageName}\n\n## Exports\n\n${lines.join("\n")}\n`;
+}
+// ── on-demand package acquisition ───────────────────────────────────────────────
+export function isModuleNotFound(err) {
+    const code = err.code;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+export function isInstalledIn(name, dir) {
+    const req = createRequire(join(dir, "__resolve__.js"));
+    try {
+        req.resolve(name);
+        return true;
+    }
+    catch {
+        // ESM-only packages can refuse `require.resolve`; fall back to package.json.
+    }
+    try {
+        req.resolve(`${name}/package.json`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function ensureCacheInstall(name, install, dir = CACHE_DIR) {
+    mkdirSync(dir, { recursive: true });
+    const pkgJson = join(dir, "package.json");
+    if (!existsSync(pkgJson)) {
+        writeFileSync(pkgJson, JSON.stringify({ name: "agent-readable-cache", private: true }) + "\n");
+    }
+    if (!isInstalledIn(name, dir)) {
+        process.stderr.write(`Installing ${install} on demand into ${dir} ...\n`);
+        try {
+            // Save into the cache's own package.json so previously fetched packages are
+            // not pruned as "extraneous" when a different package is installed later.
+            execFileSync("npm", ["install", install, "--prefix", dir, "--save", "--no-audit", "--no-fund", "--loglevel=error"], { stdio: ["ignore", "ignore", "inherit"] });
+        }
+        catch (err) {
+            throw new Error(`Failed to install "${install}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return dir;
+}
+function resolveEntry(name, dir) {
+    try {
+        return createRequire(join(dir, "__resolve__.js")).resolve(name);
+    }
+    catch {
+        return null;
+    }
+}
+export async function importFromDir(name, dir) {
+    // A loader placed in `dir` resolves the bare specifier against dir/node_modules;
+    // dynamic import transparently handles both CJS and ESM packages.
+    const loaderPath = join(dir, `.arload-${randomUUID()}.mjs`);
+    writeFileSync(loaderPath, `export default await import(${JSON.stringify(name)});\n`);
+    try {
+        const loaded = (await import(pathToFileURL(loaderPath).href));
+        return loaded.default;
+    }
+    catch (err) {
+        // Some package layouts (CJS, no "exports" map) trip ESM bare-specifier
+        // resolution, which falls back to a non-existent index.js. Resolve the real
+        // entry via Node's CJS resolver and import that file directly instead.
+        const entry = resolveEntry(name, dir);
+        if (!entry)
+            throw err;
+        return (await import(pathToFileURL(entry).href));
+    }
+    finally {
+        rmSync(loaderPath, { force: true });
+    }
+}
+export async function loadPackage(spec, cacheDir = CACHE_DIR) {
+    const { name, install } = splitPackageSpec(spec);
+    // Prefer a copy already resolvable from the current project.
+    try {
+        const mod = (await import(name));
+        return { mod, typesDir: process.cwd() };
+    }
+    catch (err) {
+        if (!isModuleNotFound(err)) {
+            throw new Error(`Cannot import package "${name}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Not installed locally: fetch on demand into the cache, then load from there.
+    const dir = ensureCacheInstall(name, install, cacheDir);
+    const mod = await importFromDir(name, dir);
+    return { mod, typesDir: dir };
+}
+//# sourceMappingURL=packages.js.map

package/dist/src/packages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.js","sourceRoot":"","sources":["../../src/packages.ts"],"names":[],"mappings":"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"}

package/dist/src/protocol.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent-documentation protocols.
+ *
+ * A target may opt into either protocol independently:
+ * - {@link AgentHelper} is full replacement — its return value IS the output.
+ * - {@link AgentNoter} is additive — its return value is appended to auto-docs.
+ *
+ * The type guards here are the only place that decides whether a runtime value
+ * implements a protocol, so both the orchestrator and the extractor agree.
+ */
+/** Full-replacement protocol. Returned string IS the output verbatim. */
+export interface AgentHelper {
+    agentHelp(): string;
+}
+/** Additive protocol. Returned string is appended to auto-generated docs. */
+export interface AgentNoter {
+    agentNotes(): string;
+}
+export declare function hasAgentHelper(target: unknown): target is AgentHelper;
+export declare function hasAgentNoter(target: unknown): target is AgentNoter;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/src/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,SAAS,IAAI,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,UAAU,IAAI,MAAM,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,WAAW,CAMrE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,UAAU,CAMnE"}

package/dist/src/protocol.js

@@ -0,0 +1,21 @@
+/**
+ * Agent-documentation protocols.
+ *
+ * A target may opt into either protocol independently:
+ * - {@link AgentHelper} is full replacement — its return value IS the output.
+ * - {@link AgentNoter} is additive — its return value is appended to auto-docs.
+ *
+ * The type guards here are the only place that decides whether a runtime value
+ * implements a protocol, so both the orchestrator and the extractor agree.
+ */
+export function hasAgentHelper(target) {
+    return (target !== null &&
+        target !== undefined &&
+        typeof target.agentHelp === "function");
+}
+export function hasAgentNoter(target) {
+    return (target !== null &&
+        target !== undefined &&
+        typeof target.agentNotes === "function");
+}
+//# sourceMappingURL=protocol.js.map

package/dist/src/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,OAAO,CACL,MAAM,KAAK,IAAI;QACf,MAAM,KAAK,SAAS;QACpB,OAAQ,MAAkC,CAAC,SAAS,KAAK,UAAU,CACpE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,CACL,MAAM,KAAK,IAAI;QACf,MAAM,KAAK,SAAS;QACpB,OAAQ,MAAkC,CAAC,UAAU,KAAK,UAAU,CACrE,CAAC;AACJ,CAAC"}

package/dist/src/render.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Markdown renderer for the {@link HelpDoc} model.
+ *
+ * This is the only place that knows about Markdown syntax. Adding another
+ * output format (plain text, HTML, JSON for MCP servers) means adding a sibling
+ * renderer that consumes the same `model.ts` types — the introspection layer
+ * stays untouched.
+ */
+import type { HelpDoc } from "./model.js";
+/**
+ * Render a {@link HelpDoc} as the structured Markdown `agentHelp()` returns.
+ *
+ * Sections are emitted in a fixed order and only when their data is present, so
+ * a class (members), a plain object (members), and a function (signature) all
+ * flow through the same path. A `null` `members` omits the Public API section;
+ * an empty array renders it with `(none)`.
+ */
+export declare function renderMarkdown(doc: HelpDoc): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/src/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAwB,MAAM,YAAY,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAkBnD"}

package/dist/src/render.js

@@ -0,0 +1,45 @@
+/**
+ * Markdown renderer for the {@link HelpDoc} model.
+ *
+ * This is the only place that knows about Markdown syntax. Adding another
+ * output format (plain text, HTML, JSON for MCP servers) means adding a sibling
+ * renderer that consumes the same `model.ts` types — the introspection layer
+ * stays untouched.
+ */
+/**
+ * Render a {@link HelpDoc} as the structured Markdown `agentHelp()` returns.
+ *
+ * Sections are emitted in a fixed order and only when their data is present, so
+ * a class (members), a plain object (members), and a function (signature) all
+ * flow through the same path. A `null` `members` omits the Public API section;
+ * an empty array renders it with `(none)`.
+ */
+export function renderMarkdown(doc) {
+    const sections = [`# ${doc.title}`];
+    if (doc.signature !== null) {
+        sections.push(`## Signature\n\n\`\`\`ts\n${doc.signature}\n\`\`\``);
+    }
+    if (doc.members !== null) {
+        sections.push(`## Public API\n\n${renderMembers(doc.members)}`);
+    }
+    sections.push(`## Agent usage rules\n\n${doc.usageRules.join("\n")}`);
+    for (const note of doc.notes) {
+        sections.push(renderNote(note));
+    }
+    return sections.join("\n\n") + "\n";
+}
+function renderMembers(members) {
+    if (members.length === 0)
+        return "- (none)";
+    return members
+        .map((m) => `- \`${m.name}${m.signature ?? ""}\` ${m.kind}`)
+        .join("\n");
+}
+function renderNote(note) {
+    let header = `## Notes from ${note.className}`;
+    if (note.inherited.length > 0) {
+        header += ` (extends ${note.inherited.join(", ")}; if notes conflict, these take precedence)`;
+    }
+    return `${header}\n\n${note.body}`;
+}
+//# sourceMappingURL=render.js.map

package/dist/src/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,MAAM,QAAQ,GAAa,CAAC,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IAE9C,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,6BAA6B,GAAG,CAAC,SAAS,UAAU,CAAC,CAAC;IACtE,CAAC;IAED,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,oBAAoB,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,2BAA2B,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEtE,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AACtC,CAAC;AAED,SAAS,aAAa,CAAC,OAAqB;IAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5C,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;SAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,IAAc;IAChC,IAAI,MAAM,GAAG,iBAAiB,IAAI,CAAC,SAAS,EAAE,CAAC;IAC/C,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,6CAA6C,CAAC;IAChG,CAAC;IACD,OAAO,GAAG,MAAM,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/dist/src/source-types.d.ts

@@ -0,0 +1,9 @@
+import type { TypeSignatureMap } from "./model.js";
+export declare function resolvePackageTypesPath(packageName: string, fromDir?: string): string | null;
+export interface ExportDescriptor {
+    name: string;
+    kind: "class" | "function" | "constant" | "default";
+}
+export declare function listPackageExports(source: string, filePath: string): ExportDescriptor[];
+export declare function parseTypeSignatures(source: string, exportName: string | null, filePath?: string): TypeSignatureMap | null;
+//# sourceMappingURL=source-types.d.ts.map

package/dist/src/source-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-types.d.ts","sourceRoot":"","sources":["../../src/source-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,YAAY,CAAC;AAmQlE,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAK3G;AAID,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CACrD;AAmFD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKvF;AAID,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,QAAQ,CAAC,EAAE,MAAM,GAChB,gBAAgB,GAAG,IAAI,CASzB"}

package/dist/src/source-types.js

@@ -0,0 +1,298 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+let _ts;
+function getTs() {
+    if (_ts === undefined) {
+        try {
+            _ts = createRequire(import.meta.url)("typescript"); /* node:coverage disable */
+        }
+        catch {
+            _ts = null;
+        } /* node:coverage enable */
+    }
+    return _ts;
+}
+function extractParams(params) {
+    return params.map((p) => ({
+        name: p.name.getText(),
+        type: p.type ? p.type.getText().replace(/\s+/g, " ").trim() : "any",
+    }));
+}
+function visitClass(ts, node, result) {
+    const decl = node;
+    for (const member of decl.members) {
+        const m = member;
+        if (!m.name)
+            continue;
+        if (m.kind === ts.SyntaxKind.MethodDeclaration && !result.has(m.name.getText())) {
+            result.set(m.name.getText(), {
+                params: extractParams(m.parameters),
+                returnType: m.type ? m.type.getText().replace(/\s+/g, " ").trim() : null,
+            });
+        }
+        else if (m.kind === ts.SyntaxKind.GetAccessor && !result.has(m.name.getText())) {
+            result.set(m.name.getText(), {
+                params: [],
+                returnType: m.type ? m.type.getText().replace(/\s+/g, " ").trim() : null,
+            });
+        }
+    }
+}
+// ── module resolution helpers ──────────────────────────────────────────────────
+function makeResolutionHost() {
+    return {
+        fileExists(path) {
+            return existsSync(path);
+        },
+        readFile(path) {
+            try {
+                return readFileSync(path, "utf-8"); /* node:coverage disable */
+            }
+            catch {
+                return undefined;
+            } /* node:coverage enable */
+        },
+        directoryExists(path) {
+            try {
+                return existsSync(path) && statSync(path).isDirectory(); /* node:coverage disable */
+            }
+            catch {
+                return false;
+            } /* node:coverage enable */
+        },
+        getCurrentDirectory() {
+            return process.cwd();
+        },
+    };
+}
+function tryTsResolve(ts, specifier, fromFile) {
+    const host = makeResolutionHost();
+    for (const kind of [ts.ModuleResolutionKind.Node10, ts.ModuleResolutionKind.Node16]) {
+        const result = ts.resolveModuleName(specifier, fromFile, { moduleResolution: kind }, host);
+        if (result.resolvedModule?.resolvedFileName) {
+            return result.resolvedModule.resolvedFileName;
+        }
+    }
+    return null;
+}
+function resolveNodeSpecifier(specifier, fromFile) {
+    const nodeMatch = /^node:(.+)$/.exec(specifier);
+    if (!nodeMatch)
+        return null;
+    const moduleName = nodeMatch[1];
+    for (const searchDir of getSearchDirs(fromFile)) {
+        const dtsPath = resolve(searchDir, "node_modules", "@types", "node", `${moduleName}.d.ts`);
+        if (existsSync(dtsPath))
+            return dtsPath;
+    }
+    return null;
+}
+function resolveRelativeSpecifier(specifier, fromFile) {
+    if (!specifier.startsWith("."))
+        return null;
+    const dir = dirname(fromFile);
+    for (const ext of [".d.ts", ".d.mts", ".ts", ".tsx"]) {
+        const p = resolve(dir, specifier + ext);
+        if (existsSync(p))
+            return p;
+    }
+    for (const ext of [".d.ts", ".d.mts"]) {
+        const p = resolve(dir, specifier, "index" + ext);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function resolveModulePath(ts, specifier, fromFile) {
+    return tryTsResolve(ts, specifier, fromFile)
+        ?? resolveNodeSpecifier(specifier, fromFile)
+        ?? resolveRelativeSpecifier(specifier, fromFile);
+}
+function getSearchDirs(fromFile) {
+    const dirs = [];
+    let dir = dirname(fromFile);
+    while (dir !== dirname(dir)) {
+        dirs.push(dir);
+        dir = dirname(dir);
+    }
+    dirs.push(dir);
+    return dirs;
+}
+// ── AST visitor helpers ────────────────────────────────────────────────────────
+function collectClassAndFunc(api, node, exportName, classMap, result) {
+    const n = node;
+    if (api.isClassDeclaration(node) && n.name) {
+        classMap.set(n.name.getText(), node);
+    }
+    if (api.isFunctionDeclaration(node) && n.name) {
+        const fnName = n.name.getText();
+        if (!exportName || fnName === exportName) {
+            if (!result.has(fnName)) {
+                result.set(fnName, {
+                    params: extractParams(n.parameters ?? []),
+                    returnType: n.type ? n.type.getText().replace(/\s+/g, " ").trim() : null,
+                });
+            }
+        }
+    }
+}
+function collectModuleBody(api, node, visit) {
+    if (!api.isModuleDeclaration(node))
+        return;
+    const body = node.body;
+    if (body && api.isModuleBlock(body)) {
+        for (const stmt of body.statements) {
+            visit(stmt);
+        }
+    }
+}
+function collectReExport(api, node, exportName, filePath, visited, result) {
+    if (!api.isExportDeclaration(node))
+        return;
+    const n = node;
+    if (!n.moduleSpecifier || typeof n.moduleSpecifier.text !== "string" || !filePath)
+        return;
+    const resolvedPath = resolveModulePath(api, n.moduleSpecifier.text, filePath);
+    if (!resolvedPath || visited.has(resolvedPath))
+        return;
+    visited.add(resolvedPath);
+    try {
+        const resolvedSource = readFileSync(resolvedPath, "utf-8");
+        const resolvedSigs = parseSourceForTypes(api, resolvedSource, exportName, resolvedPath, visited);
+        for (const [key, value] of resolvedSigs) {
+            if (!result.has(key))
+                result.set(key, value);
+        }
+    }
+    catch {
+        // resolved file not readable, skip
+    }
+}
+function collectInheritanceChain(api, exportName, classMap, result) {
+    const targetClass = classMap.get(exportName);
+    if (!targetClass)
+        return;
+    const chainVisited = new Set();
+    let current = exportName;
+    while (current) {
+        const decl = classMap.get(current);
+        if (!decl || chainVisited.has(current))
+            break;
+        chainVisited.add(current);
+        visitClass(api, decl, result);
+        const cls = decl;
+        const parent = cls.heritageClauses?.[0]?.types?.[0]?.expression?.getText();
+        current = parent && classMap.has(parent) ? parent : "";
+    }
+}
+// ── main parsing ───────────────────────────────────────────────────────────────
+function parseSourceForTypes(ts, source, exportName, filePath, visited) {
+    const sf = ts.createSourceFile(filePath ?? "input.ts", source, ts.ScriptTarget.Latest, true);
+    const result = new Map();
+    const api = ts;
+    const classMap = new Map();
+    function visit(node) {
+        collectClassAndFunc(api, node, exportName, classMap, result);
+        collectModuleBody(api, node, visit);
+        collectReExport(api, node, exportName, filePath, visited, result);
+        api.forEachChild(node, visit);
+    }
+    api.forEachChild(sf, visit);
+    if (exportName) {
+        collectInheritanceChain(api, exportName, classMap, result);
+    }
+    else {
+        for (const [, decl] of classMap) {
+            visitClass(api, decl, result);
+        }
+    }
+    return result;
+}
+// ── package resolution ──────────────────────────────────────────────────────────
+export function resolvePackageTypesPath(packageName, fromDir = process.cwd()) {
+    const ts = getTs();
+    if (!ts)
+        return null;
+    const virtualFrom = resolve(fromDir, "__resolve__.ts");
+    return tryTsResolve(ts, packageName, virtualFrom);
+}
+function hasExportModifier(api, node) {
+    const modifiers = node.modifiers;
+    if (!modifiers)
+        return false;
+    return modifiers.some((m) => m.kind === api.SyntaxKind.ExportKeyword);
+}
+function variableExports(n) {
+    return (n.declarationList?.declarations ?? []).map((d) => ({ name: d.name.getText(), kind: "constant" }));
+}
+function defaultExport(expression) {
+    if (!expression)
+        return [];
+    const name = expression.getText();
+    return /^[A-Za-z_$]/.test(name) ? [{ name, kind: "default" }] : [];
+}
+function reExportNames(clause) {
+    return (clause?.elements ?? []).map((e) => ({ name: e.name.getText(), kind: "constant" }));
+}
+function isExported(api, node) {
+    // `export { … }` / `export … from` (ExportDeclaration) and `export default …`
+    // (ExportAssignment) are exports by syntax and carry no `export` modifier.
+    return (hasExportModifier(api, node) ||
+        api.isExportDeclaration(node) ||
+        api.isExportAssignment(node));
+}
+function exportDescriptors(api, node, n) {
+    if (api.isClassDeclaration(node) && n.name) {
+        return [{ name: n.name.getText(), kind: "class" }];
+    }
+    if (api.isFunctionDeclaration(node) && n.name) {
+        return [{ name: n.name.getText(), kind: "function" }];
+    }
+    if (api.isVariableStatement(node)) {
+        return variableExports(n);
+    }
+    if (api.isExportAssignment(node)) {
+        return defaultExport(n.expression);
+    }
+    if (api.isExportDeclaration(node)) {
+        return reExportNames(n.exportClause);
+    }
+    return [];
+}
+function collectExportedDeclarations(api, sf) {
+    const seen = new Set();
+    const exports = [];
+    function visitStatement(node) {
+        if (!isExported(api, node))
+            return;
+        const n = node;
+        for (const d of exportDescriptors(api, node, n)) {
+            if (!seen.has(d.name)) {
+                seen.add(d.name);
+                exports.push(d);
+            }
+        }
+    }
+    api.forEachChild(sf, visitStatement);
+    return exports;
+}
+export function listPackageExports(source, filePath) {
+    const ts = getTs();
+    if (!ts)
+        return [];
+    const sf = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+    return collectExportedDeclarations(ts, sf);
+}
+// ── type signature parsing ─────────────────────────────────────────────────────
+export function parseTypeSignatures(source, exportName, filePath) {
+    const ts = getTs();
+    if (!ts)
+        return null;
+    const visited = new Set();
+    if (filePath)
+        visited.add(filePath);
+    const result = parseSourceForTypes(ts, source, exportName, filePath ?? null, visited);
+    return result.size > 0 ? result : null;
+}
+//# sourceMappingURL=source-types.js.map