agent-readable-ts 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvF,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIhE,oCAAoC;AACpC,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GACjC,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAKjC,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAE5D;AAED,gDAAgD;AAChD,wBAAgB,aAAa,IAAI,WAAW,GAAG,IAAI,CAElD;AAmCD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAuB9E"}

package/dist/src/index.js

@@ -0,0 +1,87 @@
+/**
+ * agent-readable-ts
+ *
+ * Attach agent-oriented documentation to any class, object, or function.
+ * Coding agents call `agentHelp(target)` to see the real callable surface
+ * and author-supplied behavioral rules before writing code against the target.
+ *
+ * This module is the orchestrator: it handles the `AgentHelper` full-replacement
+ * path and the advisory warning sink, then delegates to `model.ts` (extraction
+ * into a format-neutral `HelpDoc`) and `render.ts` (Markdown rendering).
+ */
+import { hasAgentHelper, hasAgentNoter } from "./protocol.js";
+import { FAILED, safeCall, isClassConstructor, protoOf, buildClassDoc, buildObjectDoc, buildFunctionDoc, } from "./model.js";
+import { renderMarkdown } from "./render.js";
+let warnSink = typeof process !== "undefined" && process.stderr ? process.stderr : null;
+/** Replace the advisory warning sink. Pass `null` to silence warnings. */
+export function setWarnOutput(sink) {
+    warnSink = sink;
+}
+/** Return the current advisory warning sink. */
+export function getWarnOutput() {
+    return warnSink;
+}
+function warn(message) {
+    if (warnSink === null)
+        return;
+    try {
+        if (typeof warnSink === "function") {
+            warnSink(message + "\n");
+        }
+        else {
+            warnSink.write(message + "\n");
+        }
+    }
+    catch {
+        // swallow
+    }
+}
+// ── AgentHelper full-replacement path ───────────────────────────────────────────
+function tryAgentHelperOutput(receiver) {
+    if (!hasAgentHelper(receiver))
+        return null;
+    const hadNotes = hasAgentNoter(receiver);
+    const result = safeCall(() => receiver.agentHelp());
+    if (result !== FAILED) {
+        if (hadNotes) {
+            warn("agentNotes() is ignored because agentHelp() owns the full output.");
+        }
+        const str = String(result);
+        return str.endsWith("\n") ? str : str + "\n";
+    }
+    return null;
+}
+// ── public API ──────────────────────────────────────────────────────────────────
+const NULL_MSG = "No documentation available: null or undefined value.\n";
+/**
+ * Return agent-oriented help for a class constructor, class instance,
+ * plain object, function, arrow function, bound method, or callable object.
+ *
+ * If the target implements `AgentHelper.agentHelp()`, the returned string is
+ * used verbatim. Otherwise auto-generated documentation is produced from
+ * safe runtime introspection, with any `AgentNoter.agentNotes()` appended.
+ */
+export function agentHelp(target, typeSigs) {
+    if (target === null || target === undefined) {
+        return NULL_MSG;
+    }
+    // AgentHelper: full replacement (direct target or class prototype)
+    const directOutput = tryAgentHelperOutput(target);
+    if (directOutput !== null)
+        return directOutput;
+    if (typeof target === "function") {
+        if (isClassConstructor(target)) {
+            const proto = protoOf(target);
+            if (proto) {
+                const instance = Object.create(proto);
+                const protoOutput = tryAgentHelperOutput(instance);
+                if (protoOutput !== null)
+                    return protoOutput;
+            }
+            return renderMarkdown(buildClassDoc(target, null, typeSigs));
+        }
+        return renderMarkdown(buildFunctionDoc(target, typeSigs));
+    }
+    return renderMarkdown(buildObjectDoc(target, typeSigs)); // NOSONAR: narrowed by earlier typeof/function checks
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

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

package/dist/src/model.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Structured, format-neutral model of agent-oriented documentation.
+ *
+ * This module owns **extraction**: turning a class, instance, plain object, or
+ * function into a {@link HelpDoc} — a renderer-agnostic intermediate
+ * representation. A renderer (see `render.ts` for the Markdown one) turns a
+ * `HelpDoc` into a concrete string. Keeping the two apart means new output
+ * formats (plain text, HTML, JSON for MCP servers) only need a new renderer;
+ * the introspection logic here is shared by all of them.
+ */
+/** Parameter type info extracted from TypeScript source. */
+export interface ParamTypeInfo {
+    name: string;
+    type: string;
+}
+/** Method/function type signature extracted from TypeScript source. */
+export interface MethodTypeSignature {
+    params: ParamTypeInfo[];
+    returnType: string | null;
+}
+/** Map from member name to its TypeScript type signature. */
+export type TypeSignatureMap = Map<string, MethodTypeSignature>;
+/** One public member of a class, instance, or plain object. */
+export interface HelpMember {
+    name: string;
+    kind: "method" | "accessor" | "property";
+    /** Call signature starting at `(` (e.g. `"(key: string): unknown"`); `null` for non-callable members. */
+    signature: string | null;
+}
+/** One class's `agentNotes()` contribution. */
+export interface HelpNote {
+    className: string;
+    /** Ancestor class names this note overrides (leaf only); empty otherwise. */
+    inherited: string[];
+    body: string;
+}
+/**
+ * Format-neutral model of an object's agent-oriented documentation.
+ *
+ * A single shape covers classes, objects, and functions: each populates the
+ * fields that apply to it and leaves the rest at their empty defaults. A
+ * `null` `members` means "no Public API section" (functions); an empty array
+ * means the section renders with `(none)`. A non-null `signature` is a
+ * function's call signature.
+ */
+export interface HelpDoc {
+    title: string;
+    signature: string | null;
+    members: HelpMember[] | null;
+    usageRules: string[];
+    notes: HelpNote[];
+}
+export declare const FAILED: unique symbol;
+export declare function safeCall<T>(fn: () => T): T | typeof FAILED;
+export declare function protoOf(ctor: Function): object | null;
+export declare function isClassConstructor(fn: Function): boolean;
+export declare function buildClassDoc(ctor: Function, instance: unknown, typeSigs?: TypeSignatureMap): HelpDoc;
+export declare function buildObjectDoc(target: object, typeSigs?: TypeSignatureMap): HelpDoc;
+export declare function buildFunctionDoc(fn: Function, typeSigs?: TypeSignatureMap): HelpDoc;
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAIhE,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IACzC,yGAAyG;IACzG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AA+BD,eAAO,MAAM,MAAM,eAAmB,CAAC;AAEvC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,MAAM,CAM1D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAGrD;AAYD,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAMxD;AAuXD,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAQrG;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAYnF;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,OAAO,CASnF"}

package/dist/src/model.js

@@ -0,0 +1,426 @@
+/**
+ * Structured, format-neutral model of agent-oriented documentation.
+ *
+ * This module owns **extraction**: turning a class, instance, plain object, or
+ * function into a {@link HelpDoc} — a renderer-agnostic intermediate
+ * representation. A renderer (see `render.ts` for the Markdown one) turns a
+ * `HelpDoc` into a concrete string. Keeping the two apart means new output
+ * formats (plain text, HTML, JSON for MCP servers) only need a new renderer;
+ * the introspection logic here is shared by all of them.
+ */
+import { hasAgentNoter } from "./protocol.js";
+const CLASS_RULES = [
+    "- Prefer the public API listed above.",
+    "- Do not use private, protected, underscored, or internal members.",
+    "- Do not invent unsupported behavior.",
+    "- If usage is ambiguous, prefer the simplest documented usage pattern.",
+];
+const FUNCTION_RULES = [
+    "- Call this function according to the signature above.",
+    "- Do not invent unsupported parameters, return values, side effects, or lifecycle behavior.",
+    "- Do not use private, underscored, or internal implementation details.",
+    "- If usage is ambiguous, prefer the simplest documented usage pattern.",
+];
+// ── shared low-level helpers ────────────────────────────────────────────────────
+function getName(val) {
+    const raw = val.name;
+    return typeof raw === "string" ? raw : "";
+}
+function getProto(val) {
+    return val.prototype;
+}
+function getCtor(val) {
+    return val.constructor;
+}
+export const FAILED = Symbol("FAILED");
+export function safeCall(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return FAILED;
+    }
+}
+export function protoOf(ctor) {
+    const p = getProto(ctor);
+    return typeof p === "object" && p !== null ? p : null;
+}
+const EXCLUDED = new Set(["constructor", "agentHelp", "agentNotes"]);
+function isExcluded(name) {
+    return EXCLUDED.has(name) || name.startsWith("_");
+}
+function isPublicProtoMember(n) {
+    return !isExcluded(n);
+}
+export function isClassConstructor(fn) {
+    const src = Function.prototype.toString.call(fn);
+    if (src.startsWith("class ") || src.startsWith("class{"))
+        return true;
+    const proto = getProto(fn);
+    if (proto == null || typeof proto !== "object")
+        return false;
+    return Object.getOwnPropertyNames(proto).some(isPublicProtoMember);
+}
+function buildPrototypeChain(ctor) {
+    const chain = [];
+    let p = getProto(ctor);
+    while (p != null) {
+        if (typeof p === "object") {
+            chain.unshift(p);
+        }
+        p = Object.getPrototypeOf(p);
+    }
+    return chain;
+}
+// ── parameter name recovery ───────────────────────────────────────────────────
+function fallbackArgs(arity) {
+    const args = [];
+    for (let i = 0; i < arity; i++)
+        args.push(`arg${i}`);
+    return args;
+}
+const QUOTES = new Set(["'", '"', "`"]);
+function skipTemplateExpr(src, start) {
+    let i = start;
+    let depth = 1;
+    while (i < src.length && depth > 0) {
+        const ch = src[i];
+        if (ch === "`") {
+            i = skipStringLike(src, i);
+            continue;
+        }
+        if (ch === "{")
+            depth++;
+        else if (ch === "}")
+            depth--;
+        i++;
+    }
+    return i;
+}
+function skipStringLike(src, start) {
+    const quote = src[start];
+    let i = start + 1;
+    while (i < src.length) {
+        const ch = src[i];
+        if (ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === quote)
+            return i + 1;
+        if (quote === "`" && ch === "$" && src[i + 1] === "{") {
+            i = skipTemplateExpr(src, i + 2);
+            continue;
+        }
+        i++;
+    } /* node:coverage disable */
+    // Unterminated string is impossible for valid fn source from Function.prototype.toString.
+    return src.length;
+    /* node:coverage enable */
+}
+const BRACKET_DEPTH = { "(": 1, ")": -1, "{": 1, "}": -1, "[": 1, "]": -1 };
+function splitCommas(str) {
+    const result = [];
+    let depth = 0;
+    let current = "";
+    let i = 0;
+    while (i < str.length) {
+        const ch = str[i];
+        if (QUOTES.has(ch)) {
+            const end = skipStringLike(str, i);
+            current += str.slice(i, end);
+            i = end;
+            continue;
+        }
+        depth += BRACKET_DEPTH[ch] ?? 0;
+        if (ch === "," && depth === 0) {
+            result.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+        i++;
+    }
+    if (current)
+        result.push(current);
+    return result;
+}
+function extractParamName(seg) {
+    seg = seg.trim();
+    if (seg.startsWith("{") || seg.startsWith("["))
+        return null;
+    if (seg.startsWith("..."))
+        seg = seg.slice(3).trim();
+    const match = /^([a-zA-Z_$][a-zA-Z0-9_$]*)/.exec(seg);
+    return match ? match[1] : null;
+}
+const PAREN_DEPTH = { "(": 1, ")": -1 };
+function findMatchingCloseParen(src, openIdx) {
+    let depth = 0;
+    let i = openIdx;
+    while (i < src.length) {
+        const ch = src[i];
+        if (ch === "'" || ch === '"' || ch === "`") {
+            i = skipStringLike(src, i);
+            continue;
+        }
+        depth += PAREN_DEPTH[ch] ?? 0;
+        if (depth === 0)
+            return i;
+        i++;
+    } /* node:coverage disable */
+    // Unbalanced parens are impossible for valid fn source from Function.prototype.toString.
+    return -1;
+    /* node:coverage enable */
+}
+function extractParamString(src) {
+    const openIdx = src.indexOf("(");
+    if (openIdx === -1)
+        return null;
+    const closeIdx = findMatchingCloseParen(src, openIdx);
+    if (closeIdx === -1)
+        return null;
+    return src.slice(openIdx + 1, closeIdx).trim();
+}
+function buildParamNames(paramStr, arity) {
+    const segments = splitCommas(paramStr);
+    const names = [];
+    for (let i = 0; i < segments.length && names.length < arity; i++) {
+        const name = extractParamName(segments[i]);
+        names.push(name ?? `arg${names.length}`);
+    }
+    while (names.length < arity)
+        names.push(`arg${names.length}`);
+    return names.slice(0, arity);
+}
+function parseParamNames(fn) {
+    const arity = fn.length;
+    if (arity === 0)
+        return [];
+    try {
+        const src = Function.prototype.toString.call(fn);
+        if (src.includes("[native code]"))
+            return fallbackArgs(arity);
+        const paramStr = extractParamString(src);
+        if (paramStr === null)
+            return fallbackArgs(arity);
+        if (!paramStr)
+            return [];
+        return buildParamNames(paramStr, arity);
+    }
+    catch {
+        return fallbackArgs(arity);
+    }
+}
+// ── method meta (arity + param names) ──────────────────────────────────────────
+function methodMeta(ctor, name) {
+    let p = getProto(ctor);
+    while (p != null && p !== Object.prototype) {
+        if (typeof p === "object") {
+            const desc = Object.getOwnPropertyDescriptor(p, name);
+            if (desc && typeof desc.value === "function") {
+                const fn = desc.value;
+                return { arity: fn.length, paramNames: parseParamNames(fn) };
+            }
+        }
+        p = Object.getPrototypeOf(p);
+    } /* node:coverage disable */
+    // Name is always found on the prototype chain it was collected from.
+    return { arity: 0, paramNames: [] };
+    /* node:coverage enable */
+}
+const KIND_ORDER = {
+    method: 0,
+    accessor: 1,
+    property: 2,
+};
+function sortMembers(members) {
+    return members.sort((a, b) => {
+        const k = KIND_ORDER[a.kind] - KIND_ORDER[b.kind];
+        return k === 0 ? a.name.localeCompare(b.name) : k;
+    });
+}
+function argList(arity, paramNames) {
+    if (paramNames && paramNames.length > 0) {
+        return paramNames.join(", ");
+    }
+    const args = [];
+    for (let i = 0; i < arity; i++)
+        args.push(`arg${i}`);
+    return args.join(", ");
+}
+function formatTypedSig(typeSig) {
+    const params = typeSig.params.length > 0
+        ? typeSig.params.map((p) => `${p.name}: ${p.type}`).join(", ")
+        : "";
+    const ret = typeSig.returnType ? `: ${typeSig.returnType}` : "";
+    return `(${params})${ret}`;
+}
+/** Build the call-signature suffix (`(params)` or `(params): ret`) for a method. */
+function methodSignature(m) {
+    return m.typeSig ? formatTypedSig(m.typeSig) : `(${argList(m.arity, m.paramNames)})`;
+}
+function toHelpMember(m) {
+    return {
+        name: m.name,
+        kind: m.kind,
+        signature: m.kind === "method" ? methodSignature(m) : null,
+    };
+}
+function collectMemberFromDesc(name, desc, objProtoNames, ctor, seen, members, typeSigs) {
+    if (seen.has(name) || isExcluded(name))
+        return;
+    if (objProtoNames.has(name) && typeof desc.value !== "function")
+        return;
+    if (typeof desc.value === "function") {
+        seen.add(name);
+        const meta = methodMeta(ctor, name);
+        members.push({ name, kind: "method", arity: meta.arity, paramNames: meta.paramNames, typeSig: typeSigs?.get(name) });
+    }
+    else if (desc.get || desc.set) {
+        seen.add(name);
+        members.push({ name, kind: "accessor", arity: 0, paramNames: [] });
+    }
+}
+function collectPrototypeMembers(ctor, typeSigs) {
+    const seen = new Set();
+    const members = [];
+    const chain = buildPrototypeChain(ctor);
+    const objProtoNames = new Set(Object.getOwnPropertyNames(Object.prototype));
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const proto = chain[i];
+        if (proto === Object.prototype)
+            continue;
+        const descs = Object.getOwnPropertyDescriptors(proto);
+        for (const [name, desc] of Object.entries(descs)) {
+            collectMemberFromDesc(name, desc, objProtoNames, ctor, seen, members, typeSigs);
+        }
+    }
+    return sortMembers(members);
+}
+function ownMemberKind(desc) {
+    if (typeof desc.value === "function")
+        return null;
+    if (desc.enumerable === false)
+        return null;
+    return (desc.get || desc.set) ? "accessor" : "property";
+}
+function collectOwnMembers(target, seen, members) {
+    const descs = Object.getOwnPropertyDescriptors(target);
+    for (const [name, desc] of Object.entries(descs)) {
+        if (seen.has(name) || isExcluded(name))
+            continue;
+        const kind = ownMemberKind(desc);
+        if (kind) {
+            members.push({ name, kind, arity: 0, paramNames: [] });
+            seen.add(name);
+        }
+    }
+}
+function collectInstanceMembers(target, ctor, typeSigs) {
+    const seen = new Set();
+    const members = [];
+    if (ctor != null) {
+        for (const m of collectPrototypeMembers(ctor, typeSigs)) {
+            members.push(m);
+            seen.add(m.name);
+        }
+    }
+    collectOwnMembers(target, seen, members);
+    return sortMembers(members);
+}
+// ── notes collection ──────────────────────────────────────────────────────────
+function collectNoteFromProto(proto, isLeaf, parentNames, instance) {
+    const desc = Object.getOwnPropertyDescriptor(proto, "agentNotes");
+    if (!desc || typeof desc.value !== "function")
+        return null;
+    const ctorOfProto = getCtor(proto);
+    const sectionName = ctorOfProto ? String(getName(ctorOfProto) || "Object") : "Object";
+    const receiver = instance != null && proto.isPrototypeOf(instance) // NOSONAR: dynamic type guard
+        ? instance
+        : Object.create(proto);
+    const result = safeCall(() => desc.value.call(receiver));
+    if (result === FAILED)
+        return null;
+    const body = String(result).trim();
+    if (!body)
+        return null;
+    return {
+        className: sectionName,
+        body,
+        inherited: isLeaf && parentNames.length > 0 ? [...parentNames] : [],
+    };
+}
+function collectNotes(ctor, instance) {
+    const notes = [];
+    const parentNames = [];
+    const chain = buildPrototypeChain(ctor);
+    for (const proto of chain) {
+        if (proto === Object.prototype)
+            continue;
+        const isLeaf = proto === chain.at(-1);
+        const note = collectNoteFromProto(proto, !!isLeaf, parentNames, instance);
+        if (!note)
+            continue;
+        notes.push(note);
+        if (!isLeaf) {
+            parentNames.push(note.className);
+        }
+    }
+    return notes;
+}
+// ── function signature + name ───────────────────────────────────────────────────
+function resolveFunctionName(fn) {
+    let name = getName(fn) || "function";
+    if (name.startsWith("bound "))
+        name = name.slice(6);
+    return name || "function";
+}
+function functionSignature(fn, name, typeSigs) {
+    const typeSig = typeSigs?.get(name);
+    const suffix = typeSig ? formatTypedSig(typeSig) : `(${argList(fn.length, parseParamNames(fn))})`;
+    return `${name}${suffix}`;
+}
+function functionNotes(fn, name) {
+    if (!hasAgentNoter(fn))
+        return [];
+    const result = safeCall(() => fn.agentNotes());
+    if (result === FAILED)
+        return [];
+    const body = String(result).trim();
+    return body ? [{ className: name, inherited: [], body }] : [];
+}
+// ── doc builders (extraction → HelpDoc) ─────────────────────────────────────────
+export function buildClassDoc(ctor, instance, typeSigs) {
+    return {
+        title: getName(ctor) || "AnonymousClass",
+        signature: null,
+        members: collectPrototypeMembers(ctor, typeSigs).map(toHelpMember),
+        usageRules: CLASS_RULES,
+        notes: collectNotes(ctor, instance),
+    };
+}
+export function buildObjectDoc(target, typeSigs) {
+    const ctorRaw = getCtor(target);
+    const ctor = typeof ctorRaw === "function" ? ctorRaw : null;
+    const title = ctor && ctor !== Object && getName(ctor) ? getName(ctor) : "Object";
+    return {
+        title,
+        signature: null,
+        members: collectInstanceMembers(target, ctor, typeSigs).map(toHelpMember),
+        usageRules: CLASS_RULES,
+        notes: ctor ? collectNotes(ctor, target) : [],
+    };
+}
+export function buildFunctionDoc(fn, typeSigs) {
+    const name = resolveFunctionName(fn);
+    return {
+        title: name,
+        signature: functionSignature(fn, name, typeSigs),
+        members: null,
+        usageRules: FUNCTION_RULES,
+        notes: functionNotes(fn, name),
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/src/model.js.map

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

package/dist/src/packages.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 type { TypeSignatureMap } from "./model.js";
+import type { ExportDescriptor } from "./source-types.js";
+export declare const CACHE_DIR: string;
+export declare function parseSpecifier(specifier: string): {
+    modulePath: string;
+    exportName: string | null;
+};
+export declare function isBarePackageName(modulePath: string): boolean;
+export declare function splitPackageSpec(spec: string): {
+    name: string;
+    install: string;
+};
+export declare function walkExportPath(target: unknown, exportPath: string): unknown;
+export declare function loadTypeSigs(absolutePath: string, exportName: string | null): TypeSignatureMap | undefined;
+export declare function formatExportList(packageName: string, exports: ExportDescriptor[], typeSigs?: TypeSignatureMap): string;
+export declare function isModuleNotFound(err: unknown): boolean;
+export declare function isInstalledIn(name: string, dir: string): boolean;
+export declare function ensureCacheInstall(name: string, install: string, dir?: string): string;
+export declare function importFromDir(name: string, dir: string): Promise<Record<string, unknown>>;
+export interface LoadedPackage {
+    mod: Record<string, unknown>;
+    typesDir: string;
+}
+export declare function loadPackage(spec: string, cacheDir?: string): Promise<LoadedPackage>;
+//# sourceMappingURL=packages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/packages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,eAAO,MAAM,SAAS,QAC8D,CAAC;AAIrF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAQnG;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKhF;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAc3E;AAoBD,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,gBAAgB,GAAG,SAAS,CAc1G;AAID,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAiBtH;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAchE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,MAAM,CAqBjG;AAUD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkB/F;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAiBpG"}