@tangle-network/agent-docs 0.1.0 → 0.2.0

package/README.md

@@ -65,6 +65,20 @@ export default {
 - **Private repos:** the deterministic core runs fully offline — no network, no LLM, no external service. This is the whole tool for a private repo.
 - **Public repos:** add `--deepwiki` to pull the free, no-auth DeepWiki wiki + Q&A for the repo. If the repo isn't indexed yet, the augment is skipped and the deterministic map is unaffected. (Index a public repo once at `deepwiki.com/<owner>/<repo>`.)
 
+## Filling the JSDoc gap (`suggest`)
+
+The `llms.txt` / API pages are only as rich as your JSDoc — and most codebases leave the majority of exports undocumented. `agent-docs suggest` closes that gap with a cheap model, **at authoring time**:
+
+```bash
+export TANGLE_API_KEY=...   # any OpenAI-compatible endpoint via ROUTER_URL (default: Tangle router)
+agent-docs suggest --subpath chat-routes   # draft JSDoc for undocumented exports, write into source
+agent-docs suggest --dry-run               # draft + print, write nothing
+```
+
+It finds every exported declaration that has no JSDoc, drafts a one-line summary from the signature + source, and inserts it above the declaration. Review the diff, commit, then re-run `agent-docs` — the new comments flow into the gated `llms.txt` **deterministically**.
+
+This is the tool's only LLM path, and it is deliberately at authoring time, not generation time: the model improves your **source comments**; the generated docs stay type-derived and never contain raw model text, so `--check` keeps working. Defaults to `gpt-4.1-mini` via the Tangle router; override with `--model`.
+
 ## Requirements
 
 Node ≥ 20, and `typescript` resolvable from the target repo (it's a peer dependency — every TS repo has it). agent-docs carries no runtime dependencies of its own.

package/dist/{chunk-EKQKRTAN.js → chunk-62CEZZVU.js}

@@ -1,6 +1,6 @@
 // src/index.ts
-import { existsSync as existsSync4, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync4, rmSync, writeFileSync } from "fs";
-import { basename, dirname as dirname3, join as join5, resolve as resolve2 } from "path";
+import { existsSync as existsSync4, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { basename, dirname as dirname3, join as join5, resolve as resolve3 } from "path";
 
 // src/config.ts
 import { execFileSync } from "child_process";
@@ -478,6 +478,160 @@ async function loadTs(repoRoot) {
   );
 }
 
+// src/suggest.ts
+import { readFileSync as readFileSync4, writeFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+function modelConfig(opts) {
+  const baseUrl = (opts.baseUrl ?? process.env.ROUTER_URL ?? "https://router.tangle.tools/v1").replace(/\/$/, "");
+  const apiKey = opts.apiKey ?? process.env.TANGLE_API_KEY ?? process.env.OPENAI_API_KEY ?? "";
+  const model = opts.model ?? "gpt-4.1-mini";
+  if (!apiKey) throw new Error("suggest: no API key. Set TANGLE_API_KEY (or pass --api-key).");
+  return { baseUrl, apiKey, model };
+}
+var PROMPT_RULES = 'Write ONE line of JSDoc summary for this TypeScript export. Rules: imperative mood ("Resolve\u2026", "Build\u2026"), describe what it IS or DOES, <= 110 characters, do NOT restate the type signature, do NOT start with "This function/type", no trailing period, no markdown. Return ONLY the summary text, nothing else.';
+async function draftDoc(item, cfg) {
+  const content = `${PROMPT_RULES}
+
+Name: ${item.name}
+Kind: ${item.kind}
+Signature: ${item.signature}
+
+Source:
+${item.snippet}`;
+  let res;
+  try {
+    res = await fetch(`${cfg.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${cfg.apiKey}` },
+      body: JSON.stringify({
+        model: cfg.model,
+        messages: [{ role: "user", content }],
+        temperature: 0.2,
+        max_tokens: 120
+      })
+    });
+  } catch {
+    return null;
+  }
+  if (!res.ok) return null;
+  const j = await res.json();
+  const raw = j.choices?.[0]?.message?.content?.trim();
+  if (!raw) return null;
+  const line = raw.replace(/\s+/g, " ").replace(/^["'`]|["'`]$/g, "").replace(/^\/\*+|\*+\/$/g, "").replace(/\.$/, "").trim();
+  return line || null;
+}
+function statementOf(ts, decl) {
+  let n = decl;
+  while (n.parent && !ts.isSourceFile(n.parent)) n = n.parent;
+  return n;
+}
+function collectCandidates(ts, repoRoot, entries, subpath) {
+  const srcRoot = resolve2(repoRoot, "src");
+  const scoped = subpath ? entries.filter((e) => e.id === subpath) : entries;
+  const options = { noEmit: true, skipLibCheck: true, allowJs: true };
+  const program = ts.createProgram(
+    scoped.map((e) => e.file),
+    options
+  );
+  const checker = program.getTypeChecker();
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const entry of scoped) {
+    const sf = program.getSourceFile(entry.file);
+    if (!sf) continue;
+    const moduleSym = checker.getSymbolAtLocation(sf);
+    if (!moduleSym) continue;
+    for (const exp of checker.getExportsOfModule(moduleSym)) {
+      const name = exp.getName();
+      if (name.startsWith("__")) continue;
+      let sym = exp;
+      if (sym.flags & ts.SymbolFlags.Alias) {
+        try {
+          sym = checker.getAliasedSymbol(sym);
+        } catch {
+        }
+      }
+      if (ts.displayPartsToString(exp.getDocumentationComment(checker)).trim()) continue;
+      if (ts.displayPartsToString(sym.getDocumentationComment(checker)).trim()) continue;
+      const decl = sym.declarations?.[0];
+      if (!decl) continue;
+      const declSf = decl.getSourceFile();
+      if (!declSf.fileName.startsWith(srcRoot + "/")) continue;
+      const stmt = statementOf(ts, decl);
+      const start = stmt.getStart(declSf);
+      const key = `${declSf.fileName}:${start}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const { line } = declSf.getLineAndCharacterOfPosition(start);
+      const lineStart = declSf.getPositionOfLineAndCharacter(line, 0);
+      const indent = (declSf.text.slice(lineStart, start).match(/^\s*/) ?? [""])[0];
+      const kind = kindOf(ts, sym);
+      const type = decl && sym.valueDeclaration ? checker.typeToString(checker.getTypeOfSymbolAtLocation(sym, sym.valueDeclaration)) : "";
+      const snippet = stmt.getText(declSf).split("\n").slice(0, 14).join("\n").slice(0, 1200);
+      out.push({ name, kind, signature: (type || kind).replace(/\s+/g, " ").slice(0, 200), file: declSf.fileName, pos: start, indent, snippet });
+    }
+  }
+  return out;
+}
+function kindOf(ts, sym) {
+  const f = sym.flags;
+  if (f & ts.SymbolFlags.Class) return "class";
+  if (f & ts.SymbolFlags.Interface) return "interface";
+  if (f & ts.SymbolFlags.TypeAlias) return "type";
+  if (f & ts.SymbolFlags.Enum) return "enum";
+  if (f & ts.SymbolFlags.Function) return "function";
+  return "const";
+}
+async function pool(items, n, fn) {
+  const q = [...items];
+  const workers = Array.from({ length: Math.min(n, q.length) }, async () => {
+    for (; ; ) {
+      const item = q.shift();
+      if (item === void 0) return;
+      await fn(item);
+    }
+  });
+  await Promise.all(workers);
+}
+async function suggest(repoRoot, opts = {}) {
+  const root = resolve2(repoRoot);
+  const cfg = modelConfig(opts);
+  const log = opts.log ?? (() => {
+  });
+  const config = await loadConfig(root);
+  const ts = await loadTs(root);
+  const entries = resolveEntries(root, config, ts);
+  let candidates = collectCandidates(ts, root, entries, opts.subpath);
+  if (opts.limit) candidates = candidates.slice(0, opts.limit);
+  log(`suggest: ${candidates.length} undocumented exports to draft (model ${cfg.model})`);
+  const drafts = [];
+  const byFile = /* @__PURE__ */ new Map();
+  let done = 0;
+  await pool(candidates, opts.concurrency ?? 5, async (c) => {
+    const doc = await draftDoc(c, cfg);
+    done++;
+    if (done % 20 === 0) log(`  drafted ${done}/${candidates.length}`);
+    if (!doc) return;
+    drafts.push({ name: c.name, file: c.file, doc });
+    const arr = byFile.get(c.file) ?? [];
+    arr.push({ pos: c.pos, indent: c.indent, doc });
+    byFile.set(c.file, arr);
+  });
+  const files = [];
+  if (!opts.dryRun) {
+    for (const [file, inserts] of byFile) {
+      let text = readFileSync4(file, "utf8");
+      for (const { pos, indent, doc } of inserts.sort((a, b) => b.pos - a.pos)) {
+        text = text.slice(0, pos) + `/** ${doc} */
+${indent}` + text.slice(pos);
+      }
+      writeFileSync(file, text);
+      files.push(file);
+    }
+  }
+  return { documented: drafts.length, skipped: candidates.length - drafts.length, files, drafts, dryRun: !!opts.dryRun };
+}
+
 // src/index.ts
 var DEFAULT_ASK = [
   "What is the high-level architecture and what are the main components?",
@@ -487,7 +641,7 @@ function readPackageDescription(root) {
   const pkg = join5(root, "package.json");
   if (!existsSync4(pkg)) return void 0;
   try {
-    const d = JSON.parse(readFileSync4(pkg, "utf8")).description;
+    const d = JSON.parse(readFileSync5(pkg, "utf8")).description;
     return typeof d === "string" && d ? d : void 0;
   } catch {
     return void 0;
@@ -499,14 +653,14 @@ function describeSource(root, config) {
   const pkg = join5(root, "package.json");
   if (existsSync4(pkg)) {
     try {
-      if (JSON.parse(readFileSync4(pkg, "utf8")).exports) return "package.json `exports`";
+      if (JSON.parse(readFileSync5(pkg, "utf8")).exports) return "package.json `exports`";
     } catch {
     }
   }
   return "src/index";
 }
 async function analyze(repoRoot, opts = {}) {
-  const root = resolve2(repoRoot);
+  const root = resolve3(repoRoot);
   const config = await loadConfig(root);
   const ts = await loadTs(root);
   const entries = resolveEntries(root, config, ts);
@@ -536,13 +690,13 @@ async function write(repoRoot, opts = {}) {
   for (const [rel, content] of r.files) {
     const abs = join5(r.root, rel);
     mkdirSync(dirname3(abs), { recursive: true });
-    writeFileSync(abs, content);
+    writeFileSync2(abs, content);
     written.push(rel);
   }
   if (r.wiki) {
     const abs = join5(r.root, r.wiki.path);
     mkdirSync(dirname3(abs), { recursive: true });
-    writeFileSync(abs, r.wiki.content);
+    writeFileSync2(abs, r.wiki.content);
     written.push(r.wiki.path);
   }
   return { ...r, written };
@@ -554,7 +708,7 @@ async function check(repoRoot, opts = {}) {
   for (const [rel, content] of r.files) {
     const abs = join5(r.root, rel);
     if (!existsSync4(abs)) missing.push(rel);
-    else if (readFileSync4(abs, "utf8") !== content) stale.push(rel);
+    else if (readFileSync5(abs, "utf8") !== content) stale.push(rel);
   }
   const apiDir = join5(r.root, r.meta.out, "api");
   const orphan = existsSync4(apiDir) ? readdirSync2(apiDir).filter((f) => f.endsWith(".md")).map((f) => `${r.meta.out}/api/${f}`).filter((rel) => !r.files.has(rel)) : [];
@@ -565,6 +719,7 @@ export {
   parseRemoteUrl,
   detectRepoSlug,
   fetchDeepwiki,
+  suggest,
   analyze,
   write,
   check

package/dist/cli.js

@@ -1,33 +1,46 @@
 #!/usr/bin/env node
 import {
   check,
+  suggest,
   write
-} from "./chunk-EKQKRTAN.js";
+} from "./chunk-62CEZZVU.js";
 
 // src/cli.ts
 var HELP = `agent-docs \u2014 deterministic repo surface + dependency map for any TypeScript package.
 
 Usage:
-  agent-docs [gen]            Regenerate docs/CODEMAP.md + docs/api/*.md + docs/codemap.json
+  agent-docs [gen]            Regenerate docs/CODEMAP.md + docs/api/*.md + llms.txt + codemap.json
   agent-docs --check         Exit 1 if the committed deterministic docs are stale (CI gate)
   agent-docs --deepwiki      Also write docs/WIKI.md from DeepWiki (public GitHub repos only)
+  agent-docs suggest         Draft JSDoc for UNDOCUMENTED exports via a cheap model, write into source
 
 Options:
   --repo <path>              Repo root (default: cwd)
   --out <dir>                Output dir (default: docs, or agent-docs.config \`out\`)
+  suggest --subpath <id>     Only document one subpath (e.g. chat-routes)
+  suggest --model <id>       Model (default: claude-haiku-4-5-20251001, via TANGLE_API_KEY + ROUTER_URL)
+  suggest --limit <n>        Cap exports documented this run
+  suggest --dry-run          Draft + print, do not write to source
   -h, --help
 
 Entry points are auto-detected: agent-docs.config > tsup.config \`entry\` > package.json \`exports\` > src/index.
-The deterministic files are what --check gates on; the DeepWiki WIKI.md is a non-authoritative reading aid and is never gated.`;
+generate/check are deterministic and LLM-free; suggest is the only LLM path and runs at AUTHORING time \u2014 it edits
+your JSDoc so the gated docs stay type-derived.`;
 function parseArgs(argv) {
-  const args2 = { repo: process.cwd(), check: false, deepwiki: false, help: false };
+  const args2 = { command: "gen", repo: process.cwd(), deepwiki: false, dryRun: false, help: false };
   const rest = argv.slice(2);
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--check" || a === "check") args2.check = true;
+    if (a === "suggest") args2.command = "suggest";
+    else if (a === "--check" || a === "check") args2.command = "check";
     else if (a === "--deepwiki") args2.deepwiki = true;
     else if (a === "--repo") args2.repo = rest[++i];
     else if (a === "--out") args2.out = rest[++i];
+    else if (a === "--subpath") args2.subpath = rest[++i];
+    else if (a === "--model") args2.model = rest[++i];
+    else if (a === "--limit") args2.limit = Number(rest[++i]);
+    else if (a === "--concurrency") args2.concurrency = Number(rest[++i]);
+    else if (a === "--dry-run") args2.dryRun = true;
     else if (a === "-h" || a === "--help") args2.help = true;
     else if (a === "gen") {
     } else if (a.startsWith("-")) {
@@ -43,7 +56,7 @@ if (args.help) {
   process.exit(0);
 }
 try {
-  if (args.check) {
+  if (args.command === "check") {
     const r2 = await check(args.repo, { out: args.out });
     if (r2.ok) {
       console.log("agent-docs: docs are fresh");
@@ -55,6 +68,23 @@ try {
     for (const f of r2.orphan) console.error(`  orphaned: ${f}`);
     process.exit(1);
   }
+  if (args.command === "suggest") {
+    const r2 = await suggest(args.repo, {
+      subpath: args.subpath,
+      model: args.model,
+      limit: args.limit,
+      concurrency: args.concurrency,
+      dryRun: args.dryRun,
+      log: (m) => console.error(m)
+    });
+    if (r2.dryRun) {
+      for (const d of r2.drafts) console.log(`${d.name}: ${d.doc}`);
+      console.log(`agent-docs: drafted ${r2.documented} (dry run \u2014 nothing written)`);
+    } else {
+      console.log(`agent-docs: documented ${r2.documented} exports across ${r2.files.length} files (${r2.skipped} skipped). Review the diff, then \`agent-docs\` to refresh the map.`);
+    }
+    process.exit(0);
+  }
   const r = await write(args.repo, { out: args.out, deepwiki: args.deepwiki });
   const det = r.written.filter((f) => !f.endsWith("WIKI.md")).length;
   console.log(`agent-docs: wrote ${det} files under ${r.meta.out}/ (${r.rows.length} entries)`);

package/dist/index.d.ts

@@ -107,6 +107,43 @@ declare function fetchDeepwiki(slug: string, { ask, timeoutMs }?: {
     timeoutMs?: number;
 }): Promise<DeepwikiResult | null>;
 
+/**
+ * `agent-docs suggest` — draft a one-line JSDoc for every UNDOCUMENTED public
+ * export via a cheap model on an OpenAI-compatible endpoint (the Tangle router
+ * by default), and insert it into source above the declaration.
+ *
+ * This is the ONLY LLM-touching authoring path, and it is deliberately at
+ * AUTHORING time, not generation time: the model improves the source comments;
+ * once committed, the deterministic extractor picks them up so the gated
+ * `llms.txt` / `CODEMAP.md` stay type-derived and never contain raw model text.
+ * Nothing here runs during `generate` or `check`.
+ */
+interface SuggestOptions {
+    /** Only document this export subpath id (e.g. `chat-routes`); default: all. */
+    subpath?: string;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    /** Cap the number of exports documented in one run. */
+    limit?: number;
+    /** Draft + report, but do NOT write to source. */
+    dryRun?: boolean;
+    concurrency?: number;
+    log?: (msg: string) => void;
+}
+interface SuggestResult {
+    documented: number;
+    skipped: number;
+    files: string[];
+    drafts: Array<{
+        name: string;
+        file: string;
+        doc: string;
+    }>;
+    dryRun: boolean;
+}
+declare function suggest(repoRoot: string, opts?: SuggestOptions): Promise<SuggestResult>;
+
 /** Extract the surface + graph (+ optional DeepWiki) and build the output files. */
 declare function analyze(repoRoot: string, opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 /** Regenerate all files to disk. Cleans stale `api/*.md` first. */
@@ -120,4 +157,4 @@ declare function write(repoRoot: string, opts?: AnalyzeOptions): Promise<Analyze
  */
 declare function check(repoRoot: string, opts?: AnalyzeOptions): Promise<CheckResult>;
 
-export { type AnalyzeOptions, type AnalyzeResult, type CartographConfig, type CheckResult, type DeepwikiResult, type Entry, type ExportInfo, type ExportKind, type Meta, type RepoSlug, type Row, type TS, analyze, check, detectRepoSlug, fetchDeepwiki, parseRemoteUrl, write };
+export { type AnalyzeOptions, type AnalyzeResult, type CartographConfig, type CheckResult, type DeepwikiResult, type Entry, type ExportInfo, type ExportKind, type Meta, type RepoSlug, type Row, type SuggestOptions, type SuggestResult, type TS, analyze, check, detectRepoSlug, fetchDeepwiki, parseRemoteUrl, suggest, write };

package/dist/index.js

@@ -4,13 +4,15 @@ import {
   detectRepoSlug,
   fetchDeepwiki,
   parseRemoteUrl,
+  suggest,
   write
-} from "./chunk-EKQKRTAN.js";
+} from "./chunk-62CEZZVU.js";
 export {
   analyze,
   check,
   detectRepoSlug,
   fetchDeepwiki,
   parseRemoteUrl,
+  suggest,
   write
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-docs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic repo surface + dependency map for any TypeScript package, with an optional DeepWiki narrative augment for public repos.",
   "type": "module",
   "publishConfig": {
@@ -30,7 +30,9 @@
     "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
-    "typescript": { "optional": false }
+    "typescript": {
+      "optional": false
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",