autodocs-engine 0.5.0

package/dist/inferability.js

@@ -0,0 +1,142 @@
+// src/inferability.ts — Compute how "inferable" a repo's patterns are from source code alone
+// High score = AI can figure it out from sibling files (AGENTS.md pattern sections redundant)
+// Low score = AI needs AGENTS.md guidance (non-obvious patterns, unique conventions)
+// ─── Standard Directory Names ────────────────────────────────────────────────
+const OBVIOUS_DIR_NAMES = new Set([
+    "src", "lib", "dist", "build", "out", "coverage",
+    "components", "component", "utils", "util", "utilities", "helpers", "helper",
+    "types", "typings", "interfaces", "models", "model",
+    "hooks", "hook",
+    "styles", "css", "assets", "images", "icons", "fonts",
+    "public", "static",
+    "pages", "page", "views", "view", "screens",
+    "app", "apps",
+    "api", "apis", "routes", "route", "controllers", "controller",
+    "config", "configs", "configuration", "settings",
+    "constants", "const",
+    "test", "tests", "__tests__", "spec", "specs",
+    "middleware", "middlewares",
+    "services", "service",
+    "store", "stores", "state",
+    "context", "contexts", "providers",
+    "actions", "reducers", "selectors",
+    "layouts", "layout",
+    "features", "modules",
+    "common", "shared", "core",
+    "server", "client",
+    "bin", "cli", "cmd",
+]);
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Compute how inferable a package's patterns are from source code alone.
+ * Used to decide which AGENTS.md sections to include.
+ */
+export function computeInferabilityScore(pkg) {
+    const directoryObviousness = computeDirectoryObviousness(pkg);
+    const namingConsistency = computeNamingConsistency(pkg);
+    const patternUniqueness = computePatternUniqueness(pkg);
+    const registrationComplexity = computeRegistrationComplexity(pkg);
+    // Weighted average: directory and patterns matter most
+    const score = Math.round(directoryObviousness * 0.30 +
+        namingConsistency * 0.25 +
+        patternUniqueness * 0.25 +
+        registrationComplexity * 0.20);
+    // Thresholds
+    let recommendation;
+    if (score <= 35) {
+        recommendation = "full"; // Repo has non-obvious patterns → include all sections
+    }
+    else if (score <= 65) {
+        recommendation = "minimal"; // Mixed → include architecture + commands, skip verbose patterns
+    }
+    else {
+        recommendation = "skip"; // Standard patterns → omit pattern sections
+    }
+    // Floor rule: if most directories are non-obvious, never "skip" — the repo
+    // has structure worth documenting even if patterns are standard.
+    // Calibrated against 20-repo benchmark: vitest (directoryObviousness=25, delta=+13.2%)
+    // was incorrectly recommended "skip" without this rule.
+    if (directoryObviousness < 40 && recommendation === "skip") {
+        recommendation = "minimal";
+    }
+    return {
+        score,
+        factors: { directoryObviousness, namingConsistency, patternUniqueness, registrationComplexity },
+        recommendation,
+    };
+}
+// ─── Factor Computation ──────────────────────────────────────────────────────
+/**
+ * What fraction of directories have standard/obvious names?
+ * High = all dirs are standard (src/, lib/, utils/) → AI can infer
+ * Low = has unique dirs (integration-tests/, adapters/, protocols/) → needs guidance
+ */
+function computeDirectoryObviousness(pkg) {
+    const dirs = pkg.architecture.directories;
+    if (dirs.length === 0)
+        return 100;
+    let obvious = 0;
+    for (const dir of dirs) {
+        const name = dir.path.replace(/\/$/, "").split("/").pop()?.toLowerCase() ?? "";
+        if (OBVIOUS_DIR_NAMES.has(name))
+            obvious++;
+    }
+    return Math.round((obvious / dirs.length) * 100);
+}
+/**
+ * How consistent is the file naming pattern?
+ * High = one dominant pattern (>90% kebab-case) → AI infers from siblings
+ * Low = mixed patterns or non-standard naming → needs explicit guidance
+ */
+function computeNamingConsistency(pkg) {
+    const namingConvention = pkg.conventions.find(c => c.category === "file-naming");
+    if (!namingConvention)
+        return 80; // No naming convention detected → assume standard
+    return Math.min(100, namingConvention.confidence.percentage);
+}
+/**
+ * Inverse of pattern uniqueness — how many deep pattern signals exist?
+ * High = no deep signals (AI can infer everything from siblings)
+ * Low = has commonImports, exportSuffix, registrationFile → needs AGENTS.md
+ */
+function computePatternUniqueness(pkg) {
+    const patterns = pkg.contributionPatterns ?? [];
+    if (patterns.length === 0)
+        return 90; // No patterns detected → standard structure
+    let deepSignals = 0;
+    let totalPossible = 0;
+    for (const p of patterns) {
+        totalPossible += 3; // 3 possible deep signals per pattern
+        if (p.commonImports && p.commonImports.length > 0)
+            deepSignals++;
+        if (p.exportSuffix)
+            deepSignals++;
+        if (p.registrationFile)
+            deepSignals++;
+    }
+    if (totalPossible === 0)
+        return 90;
+    // More deep signals = lower inferability (patterns are non-obvious)
+    const uniqueRatio = deepSignals / totalPossible;
+    return Math.round((1 - uniqueRatio) * 100);
+}
+/**
+ * Inverse of registration complexity.
+ * High = no registration files → standard structure
+ * Low = multiple registration files → complex wiring the AI would miss
+ */
+function computeRegistrationComplexity(pkg) {
+    const patterns = pkg.contributionPatterns ?? [];
+    const registrationFiles = patterns
+        .filter(p => p.registrationFile)
+        .map(p => p.registrationFile);
+    const uniqueRegistrations = new Set(registrationFiles).size;
+    if (uniqueRegistrations === 0)
+        return 100;
+    if (uniqueRegistrations === 1)
+        return 60;
+    if (uniqueRegistrations === 2)
+        return 30;
+    return 10; // 3+ registration files = complex wiring
+}
+//# sourceMappingURL=inferability.js.map

package/dist/inferability.js.map

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

package/dist/llm/adapter.d.ts

@@ -0,0 +1,33 @@
+import type { StructuredAnalysis, ResolvedConfig, PackageAnalysis } from "../types.js";
+/**
+ * Format a StructuredAnalysis into a single context file via LLM.
+ * For "json" format, returns JSON.stringify directly (no LLM call).
+ */
+export declare function formatWithLLM(analysis: StructuredAnalysis, config: Pick<ResolvedConfig, "output" | "llm">): Promise<string>;
+/**
+ * Validate LLM output against analysis. If errors found, retry once with corrections.
+ * Maximum 1 retry (2x cost per file cap).
+ */
+export declare function validateAndCorrect(output: string, analysis: StructuredAnalysis | PackageAnalysis, format: "root" | "package-detail", systemPrompt: string, llmConfig: ResolvedConfig["llm"]): Promise<string>;
+/**
+ * Format a StructuredAnalysis using deterministic code for 13 sections
+ * and micro-LLM calls for architecture + domain terminology.
+ * This is the default mode for agents.md output.
+ */
+export declare function formatDeterministic(analysis: StructuredAnalysis, config: Pick<ResolvedConfig, "output" | "llm">, rootDir?: string): Promise<string>;
+/**
+ * Generate ONLY the architecture section via a constrained micro-LLM call.
+ * Input is limited to directory names, export names, and call graph edges.
+ * The LLM cannot hallucinate technologies because it doesn't see them.
+ */
+export declare function synthesizeArchitecture(pkg: PackageAnalysis, llmConfig: ResolvedConfig["llm"]): Promise<string>;
+/**
+ * Generate domain terminology from README context.
+ * Input is ONLY the README first paragraph — can't hallucinate technology stack.
+ */
+export declare function synthesizeDomainTerms(readmeContext: string | undefined, llmConfig: ResolvedConfig["llm"]): Promise<string>;
+/**
+ * Extract contributing workflow rules from CONTRIBUTING.md context.
+ * Input is the first 1000 chars of CONTRIBUTING.md content.
+ */
+export declare function synthesizeContributingRules(contributingContext: string | undefined, llmConfig: ResolvedConfig["llm"]): Promise<string>;

package/dist/llm/adapter.js

@@ -0,0 +1,202 @@
+// src/llm/adapter.ts — Orchestration: serialize -> call LLM -> validate -> output
+// Split from llm-adapter.ts (W5-B1)
+import { LLMError } from "../types.js";
+import { validateOutput } from "../output-validator.js";
+import { callLLMWithRetry } from "./client.js";
+import { serializeToMarkdown } from "./serializer.js";
+import { getTemplate } from "./template-selector.js";
+import { generateDeterministicAgentsMd, assembleFinalOutput, formatArchitectureFallback, } from "../deterministic-formatter.js";
+import { extractReadmeContext, extractContributingContext } from "../existing-docs.js";
+// Note: formatHierarchical and HierarchicalOutput are re-exported from the
+// barrel (src/llm-adapter.ts) via hierarchical.ts, not through this module,
+// to avoid circular dependencies.
+function mapReplacer(_key, value) {
+    if (value instanceof Map)
+        return Object.fromEntries(value);
+    if (value instanceof Set)
+        return [...value];
+    return value;
+}
+/**
+ * Format a StructuredAnalysis into a single context file via LLM.
+ * For "json" format, returns JSON.stringify directly (no LLM call).
+ */
+export async function formatWithLLM(analysis, config) {
+    if (config.output.format === "json") {
+        return JSON.stringify(analysis, mapReplacer, 2);
+    }
+    const serialized = serializeToMarkdown(analysis);
+    const isMultiPackage = analysis.packages.length > 1;
+    const template = getTemplate(config.output.format, isMultiPackage);
+    const systemPrompt = template.systemPrompt;
+    const userPrompt = `<instructions>
+${template.formatInstructions}
+</instructions>
+
+<analysis>
+${serialized}
+</analysis>
+
+Generate the AGENTS.md now. Use ONLY data from the <analysis> section. Do NOT add technologies, frameworks, runtimes, or version numbers that are not explicitly present in <analysis>.`;
+    const apiKey = config.llm.apiKey;
+    if (!apiKey) {
+        throw new LLMError("No API key provided. Set ANTHROPIC_API_KEY or use --format json.");
+    }
+    // W2-1: Generate, validate, optionally retry once with corrections
+    const output = await callLLMWithRetry(systemPrompt, userPrompt, config.llm);
+    return validateAndCorrect(output, analysis, "root", template.systemPrompt, config.llm);
+}
+// ---- W2-1: Validation + Correction ----
+/**
+ * Validate LLM output against analysis. If errors found, retry once with corrections.
+ * Maximum 1 retry (2x cost per file cap).
+ */
+export async function validateAndCorrect(output, analysis, format, systemPrompt, llmConfig) {
+    const validation = validateOutput(output, analysis, format);
+    if (validation.isValid || !validation.correctionPrompt) {
+        return output;
+    }
+    // One targeted retry
+    try {
+        const corrected = await callLLMWithRetry(systemPrompt, validation.correctionPrompt, llmConfig);
+        return corrected;
+    }
+    catch {
+        // If retry fails, return original output
+        return output;
+    }
+}
+// ---- Deterministic Formatting (70% code, 30% micro-LLM) ----
+/**
+ * Format a StructuredAnalysis using deterministic code for 13 sections
+ * and micro-LLM calls for architecture + domain terminology.
+ * This is the default mode for agents.md output.
+ */
+export async function formatDeterministic(analysis, config, rootDir) {
+    if (config.output.format === "json") {
+        return JSON.stringify(analysis, mapReplacer, 2);
+    }
+    // Step 1: Deterministic sections (no LLM)
+    const deterministic = generateDeterministicAgentsMd(analysis);
+    // Step 2: Extract context from docs for LLM synthesis
+    const pkgDir = analysis.packages[0]?.relativePath ?? ".";
+    const readmeContext = extractReadmeContext(pkgDir, rootDir);
+    const contributingContext = extractContributingContext(pkgDir, rootDir);
+    // Step 3: Micro-LLM calls for synthesis (small, constrained)
+    let architectureSection;
+    let domainSection;
+    let contributingSection;
+    if (config.llm.apiKey) {
+        // Parallel micro-LLM calls
+        const [archResult, domainResult, contributingResult] = await Promise.all([
+            synthesizeArchitecture(analysis.packages[0], config.llm),
+            synthesizeDomainTerms(readmeContext, config.llm),
+            synthesizeContributingRules(contributingContext, config.llm),
+        ]);
+        architectureSection = archResult;
+        domainSection = domainResult;
+        contributingSection = contributingResult;
+    }
+    else {
+        // No API key: use deterministic fallback
+        architectureSection = formatArchitectureFallback(analysis.packages[0]);
+        domainSection = "";
+        contributingSection = "";
+    }
+    // Step 4: Assemble final output
+    return assembleFinalOutput(deterministic, architectureSection, domainSection, contributingSection);
+}
+/**
+ * Generate ONLY the architecture section via a constrained micro-LLM call.
+ * Input is limited to directory names, export names, and call graph edges.
+ * The LLM cannot hallucinate technologies because it doesn't see them.
+ */
+export async function synthesizeArchitecture(pkg, llmConfig) {
+    // Build constrained input — ONLY architecture data
+    const input = [];
+    input.push(`Package: ${pkg.name}`);
+    input.push(`Type: ${pkg.architecture.packageType}`);
+    input.push(`Entry: ${pkg.architecture.entryPoint}`);
+    input.push("");
+    input.push("Directories and their exports:");
+    for (const dir of pkg.architecture.directories) {
+        if (dir.exports?.length) {
+            input.push(`  ${dir.purpose}: ${dir.exports.join(", ")}`);
+        }
+        else {
+            input.push(`  ${dir.purpose}: ${dir.fileCount} files`);
+        }
+    }
+    if (pkg.callGraph?.length) {
+        input.push("");
+        input.push("Key call relationships:");
+        for (const edge of pkg.callGraph.slice(0, 10)) {
+            input.push(`  ${edge.from} \u2192 ${edge.to}`);
+        }
+    }
+    const systemPrompt = `You are writing 4-6 bullet points describing a TypeScript package's architecture.
+Use ONLY the directory names, export names, and call relationships provided below.
+Describe CAPABILITIES (what the code does), not file locations.
+Do NOT mention any technology, framework, or library by name — only describe what the exports DO.
+Output ONLY the bullet points, no headers or explanations.`;
+    const userPrompt = input.join("\n");
+    if (!llmConfig.apiKey)
+        return formatArchitectureFallback(pkg);
+    try {
+        const result = await callLLMWithRetry(systemPrompt, userPrompt, {
+            ...llmConfig,
+            maxOutputTokens: 500,
+        });
+        return `## Architecture\n\n${result.trim()}`;
+    }
+    catch {
+        return formatArchitectureFallback(pkg);
+    }
+}
+/**
+ * Generate domain terminology from README context.
+ * Input is ONLY the README first paragraph — can't hallucinate technology stack.
+ */
+export async function synthesizeDomainTerms(readmeContext, llmConfig) {
+    if (!readmeContext || readmeContext.length < 50 || !llmConfig.apiKey)
+        return "";
+    const systemPrompt = `Extract 3-5 domain-specific terms from the project description below.
+For each term, provide a one-line definition.
+These are terms that an AI coding tool wouldn't know from reading source code alone.
+Output as a markdown list. If no domain-specific terms are found, output nothing.`;
+    try {
+        const result = await callLLMWithRetry(systemPrompt, readmeContext, {
+            ...llmConfig,
+            maxOutputTokens: 300,
+        });
+        const trimmed = result.trim();
+        return trimmed ? `## Domain Terminology\n\n${trimmed}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Extract contributing workflow rules from CONTRIBUTING.md context.
+ * Input is the first 1000 chars of CONTRIBUTING.md content.
+ */
+export async function synthesizeContributingRules(contributingContext, llmConfig) {
+    if (!contributingContext || contributingContext.length < 50 || !llmConfig.apiKey)
+        return "";
+    const systemPrompt = `Extract 4-6 concrete contribution workflow rules from this CONTRIBUTING guide.
+Focus on: PR process, branch naming, commit conventions, setup requirements, testing expectations.
+Format as a markdown bullet list. Only include rules that are specific to this project.
+If the content is just a redirect or generic "contributions welcome" with no process details, output nothing.`;
+    try {
+        const result = await callLLMWithRetry(systemPrompt, contributingContext, {
+            ...llmConfig,
+            maxOutputTokens: 400,
+        });
+        const trimmed = result.trim();
+        return trimmed ? `## Contributing Guidelines\n\n${trimmed}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/llm/adapter.js.map

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

package/dist/llm/client.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedConfig } from "../types.js";
+/**
+ * Call LLM API with automatic retry (1 retry after 2s delay).
+ */
+export declare function callLLMWithRetry(systemPrompt: string, userPrompt: string, llmConfig: ResolvedConfig["llm"]): Promise<string>;

package/dist/llm/client.js

@@ -0,0 +1,68 @@
+// src/llm/client.ts — HTTP client for LLM API calls
+// Split from llm-adapter.ts (W5-B1)
+import { LLMError } from "../types.js";
+/**
+ * Call LLM API with automatic retry (1 retry after 2s delay).
+ */
+export async function callLLMWithRetry(systemPrompt, userPrompt, llmConfig) {
+    try {
+        return await callLLM(systemPrompt, userPrompt, llmConfig);
+    }
+    catch (err) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        try {
+            return await callLLM(systemPrompt, userPrompt, llmConfig);
+        }
+        catch (retryErr) {
+            throw new LLMError(`LLM API failed after retry: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+        }
+    }
+}
+async function callLLM(systemPrompt, userPrompt, llmConfig) {
+    const baseUrl = llmConfig.baseUrl ?? "https://api.anthropic.com";
+    const url = `${baseUrl}/v1/messages`;
+    // E-33: AbortController timeout
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 120_000);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            signal: controller.signal,
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": llmConfig.apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({
+                model: llmConfig.model,
+                max_tokens: llmConfig.maxOutputTokens,
+                system: systemPrompt,
+                messages: [{ role: "user", content: userPrompt }],
+                temperature: 0,
+            }),
+        });
+        clearTimeout(timer);
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            // Truncate error body to avoid leaking sensitive data in logs
+            const safeBody = body.slice(0, 200);
+            throw new LLMError(`LLM API returned ${response.status}: ${safeBody}`, response.status);
+        }
+        const data = await response.json();
+        const text = data?.content?.[0]?.text;
+        if (!text) {
+            throw new LLMError("LLM response missing content text");
+        }
+        return text;
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (err instanceof LLMError)
+            throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new LLMError("LLM API request timed out after 120s");
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/llm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/llm/client.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,oCAAoC;AAGpC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAMvC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,YAAoB,EACpB,UAAkB,EAClB,SAAgC;IAEhC,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,QAAQ,CAChB,+BAA+B,QAAQ,YAAY,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CACjG,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,OAAO,CACpB,YAAoB,EACpB,UAAkB,EAClB,SAAgC;IAEhC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,2BAA2B,CAAC;IACjE,MAAM,GAAG,GAAG,GAAG,OAAO,cAAc,CAAC;IAErC,gCAAgC;IAChC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;IAE5D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,SAAS,CAAC,MAAO;gBAC9B,mBAAmB,EAAE,YAAY;aAClC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,UAAU,EAAE,SAAS,CAAC,eAAe;gBACrC,MAAM,EAAE,YAAY;gBACpB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;gBACjD,WAAW,EAAE,CAAC;aACf,CAAC;SACH,CAAC,CAAC;QAEH,YAAY,CAAC,KAAK,CAAC,CAAC;QAEpB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,8DAA8D;YAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACpC,MAAM,IAAI,QAAQ,CAChB,oBAAoB,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,EAClD,QAAQ,CAAC,MAAM,CAChB,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAsB,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;QACtC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,QAAQ,CAAC,mCAAmC,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,IAAI,GAAG,YAAY,QAAQ;YAAE,MAAM,GAAG,CAAC;QACvC,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACtD,MAAM,IAAI,QAAQ,CAAC,sCAAsC,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/llm/hierarchical.d.ts

@@ -0,0 +1,23 @@
+import type { StructuredAnalysis, ResolvedConfig } from "../types.js";
+export interface HierarchicalOutput {
+    root: string;
+    packages: {
+        filename: string;
+        content: string;
+    }[];
+}
+/**
+ * Format a StructuredAnalysis into hierarchical output: root AGENTS.md + per-package detail files.
+ * Only applicable when format is "agents.md" and there are multiple packages.
+ */
+export declare function formatHierarchical(analysis: StructuredAnalysis, config: Pick<ResolvedConfig, "output" | "llm">): Promise<HierarchicalOutput>;
+/**
+ * Format hierarchical output using deterministic code for sections + micro-LLM for synthesis.
+ * Generates root AGENTS.md + per-package detail files without full LLM calls.
+ */
+export declare function formatHierarchicalDeterministic(analysis: StructuredAnalysis, config: Pick<ResolvedConfig, "output" | "llm">): Promise<HierarchicalOutput>;
+/**
+ * Convert a package name to a safe filename.
+ * @scope/my-package-name -> my-package-name.md
+ */
+export declare function toPackageFilename(name: string): string;

package/dist/llm/hierarchical.js

@@ -0,0 +1,126 @@
+// src/llm/hierarchical.ts — Multi-file hierarchical output
+// Split from llm-adapter.ts (W5-B1)
+import { LLMError } from "../types.js";
+import { agentsMdMultiRootTemplate, agentsMdPackageDetailTemplate, } from "../templates/agents-md.js";
+import { callLLMWithRetry } from "./client.js";
+import { serializeToMarkdown, serializePackageToMarkdown } from "./serializer.js";
+import { validateAndCorrect, synthesizeArchitecture, synthesizeDomainTerms, synthesizeContributingRules } from "./adapter.js";
+import { generateDeterministicAgentsMd, generatePackageDeterministicAgentsMd, assembleFinalOutput, formatArchitectureFallback, } from "../deterministic-formatter.js";
+import { extractReadmeContext, extractContributingContext } from "../existing-docs.js";
+/**
+ * Format a StructuredAnalysis into hierarchical output: root AGENTS.md + per-package detail files.
+ * Only applicable when format is "agents.md" and there are multiple packages.
+ */
+export async function formatHierarchical(analysis, config) {
+    const apiKey = config.llm.apiKey;
+    if (!apiKey) {
+        throw new LLMError("No API key provided. Set ANTHROPIC_API_KEY or use --format json.");
+    }
+    // Generate root AGENTS.md with lean multi-package template
+    const rootSerialized = serializeToMarkdown(analysis);
+    const rootTemplate = agentsMdMultiRootTemplate;
+    // Build package detail filename list for root template to reference
+    const packageFilenames = analysis.packages.map((pkg) => ({
+        name: pkg.name,
+        filename: toPackageFilename(pkg.name),
+    }));
+    const filenameHint = `\n\nPackage detail files will be at:\n${packageFilenames.map((p) => `- packages/${p.filename}`).join("\n")}`;
+    const rootPrompt = `<instructions>
+${rootTemplate.formatInstructions}${filenameHint}
+</instructions>
+
+<analysis>
+${rootSerialized}
+</analysis>
+
+Generate the AGENTS.md now. Use ONLY data from the <analysis> section. Do NOT add technologies, frameworks, runtimes, or version numbers that are not explicitly present in <analysis>.`;
+    const rawRoot = await callLLMWithRetry(rootTemplate.systemPrompt, rootPrompt, config.llm);
+    // W2-1: Validate root output
+    const rootContent = await validateAndCorrect(rawRoot, analysis, "root", rootTemplate.systemPrompt, config.llm);
+    // Generate per-package detail files (can be parallelized)
+    const packagePromises = analysis.packages.map(async (pkg) => {
+        const pkgSerialized = serializePackageToMarkdown(pkg);
+        const pkgTemplate = agentsMdPackageDetailTemplate;
+        const pkgPrompt = `<instructions>
+${pkgTemplate.formatInstructions}
+</instructions>
+
+<analysis>
+${pkgSerialized}
+</analysis>
+
+Generate the package detail file now. Use ONLY data from the <analysis> section. Do NOT add technologies, frameworks, runtimes, or version numbers that are not explicitly present in <analysis>.`;
+        const rawContent = await callLLMWithRetry(pkgTemplate.systemPrompt, pkgPrompt, config.llm);
+        // W2-1: Validate per-package output
+        const content = await validateAndCorrect(rawContent, pkg, "package-detail", pkgTemplate.systemPrompt, config.llm);
+        return {
+            filename: toPackageFilename(pkg.name),
+            content,
+        };
+    });
+    const packages = await Promise.all(packagePromises);
+    return { root: rootContent, packages };
+}
+/**
+ * Format hierarchical output using deterministic code for sections + micro-LLM for synthesis.
+ * Generates root AGENTS.md + per-package detail files without full LLM calls.
+ */
+export async function formatHierarchicalDeterministic(analysis, config) {
+    // Root AGENTS.md — deterministic sections
+    const rootDeterministic = generateDeterministicAgentsMd(analysis);
+    // Doc context for LLM synthesis
+    const pkgDir = analysis.packages[0]?.relativePath ?? ".";
+    const readmeContext = extractReadmeContext(pkgDir, analysis.meta.rootDir);
+    const contributingContext = extractContributingContext(pkgDir, analysis.meta.rootDir);
+    // Micro-LLM calls for root architecture + domain + contributing (if API key available)
+    let rootArchitecture;
+    let rootDomain;
+    let rootContributing;
+    if (config.llm.apiKey) {
+        const [archResult, domainResult, contributingResult] = await Promise.all([
+            synthesizeArchitecture(analysis.packages[0], config.llm),
+            synthesizeDomainTerms(readmeContext, config.llm),
+            synthesizeContributingRules(contributingContext, config.llm),
+        ]);
+        rootArchitecture = archResult;
+        rootDomain = domainResult;
+        rootContributing = contributingResult;
+    }
+    else {
+        rootArchitecture = formatArchitectureFallback(analysis.packages[0]);
+        rootDomain = "";
+        rootContributing = "";
+    }
+    const rootContent = assembleFinalOutput(rootDeterministic, rootArchitecture, rootDomain, rootContributing);
+    // Per-package detail files — deterministic + micro-LLM architecture per package
+    const packagePromises = analysis.packages.map(async (pkg) => {
+        const pkgDeterministic = generatePackageDeterministicAgentsMd(pkg);
+        let pkgArchitecture;
+        if (config.llm.apiKey) {
+            pkgArchitecture = await synthesizeArchitecture(pkg, config.llm);
+        }
+        else {
+            pkgArchitecture = formatArchitectureFallback(pkg);
+        }
+        const content = assembleFinalOutput(pkgDeterministic, pkgArchitecture, "");
+        return {
+            filename: toPackageFilename(pkg.name),
+            content,
+        };
+    });
+    const packages = await Promise.all(packagePromises);
+    return { root: rootContent, packages };
+}
+/**
+ * Convert a package name to a safe filename.
+ * @scope/my-package-name -> my-package-name.md
+ */
+export function toPackageFilename(name) {
+    return name
+        .replace(/^@[^/]+\//, "") // Strip scope
+        .replace(/[^a-z0-9-]/gi, "-") // Replace unsafe chars
+        .replace(/-+/g, "-") // Collapse multiple dashes
+        .replace(/^-|-$/g, "") // Trim dashes
+        + ".md";
+}
+//# sourceMappingURL=hierarchical.js.map

package/dist/llm/hierarchical.js.map

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