autodocs-engine 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 autodocs-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# autodocs-engine
+
+Deterministic codebase intelligence for AI coding tools.
+
+[![npm version](https://img.shields.io/npm/v/autodocs-engine)](https://www.npmjs.com/package/autodocs-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/autodocs-engine)](https://nodejs.org)
+
+## What It Does
+
+Analyzes TypeScript/JavaScript codebases and extracts actionable intelligence — commands, conventions, file coupling patterns, contribution recipes, architecture — that AI coding tools need to write code that fits your project.
+
+Two ways to use it:
+
+1. **MCP Server** — Live codebase queries via Model Context Protocol. AI tools ask for exactly the context they need, on demand.
+2. **AGENTS.md Generator** — Static context file for universal compatibility. Works with every tool that reads AGENTS.md, CLAUDE.md, or .cursorrules.
+
+## Quick Start
+
+```bash
+# Generate a focused AGENTS.md (no API key needed)
+npx autodocs-engine init --minimal
+
+# Or start the MCP server for live queries
+npx autodocs-engine serve
+```
+
+### MCP Server Setup (Claude Code)
+
+```bash
+claude mcp add autodocs -- npx autodocs-engine serve
+```
+
+This gives Claude Code 8 codebase intelligence tools:
+
+| Tool | What It Returns |
+|------|----------------|
+| `get_commands` | Build, test, lint commands with exact flags |
+| `get_architecture` | Directory structure, entry points, package type |
+| `get_conventions` | DO/DON'T rules detected from your code |
+| `get_workflow_rules` | File coupling and co-change patterns |
+| `get_contribution_guide` | How to add new code in a specific directory |
+| `get_exports` | Public API sorted by usage |
+| `analyze_impact` | What breaks if you change a file |
+| `list_packages` | Monorepo package inventory |
+
+## Why Minimal Mode?
+
+Research shows comprehensive context files can actually **hurt** AI performance:
+
+- LLM-generated AGENTS.md: **-0.5% to -2%** accuracy ([arxiv 2602.11988](https://arxiv.org/abs/2602.11988))
+- Developer-written focused AGENTS.md: **+4%** accuracy, **-29% runtime** ([arxiv 2601.20404](https://arxiv.org/abs/2601.20404))
+
+The difference: developer-written files are short, focused, and only include what the AI can't figure out on its own. That's exactly what `--minimal` generates.
+
+**Minimal mode** (~200-450 tokens) includes only:
+- Exact commands with flags (proven to help, never hurts)
+- Workflow rules from git co-change analysis (patterns the AI can't discover from code)
+- High-confidence conventions (only if ≥95% consistent and non-obvious)
+- Non-obvious directories (with "non-exhaustive" qualifier to prevent anchoring)
+
+**Full mode** (~1,500-2,500 tokens) adds public API, dependency graphs, all conventions, and architecture details. Use `--full` when you need comprehensive documentation.
+
+## How It Works
+
+Unlike tools that dump code into an LLM or pack everything into one file, autodocs-engine uses deterministic static analysis:
+
+1. **Parse** — AST analysis via TypeScript Compiler API
+2. **Detect** — 8 convention detectors (naming, hooks, testing, frameworks, etc.)
+3. **Extract** — Commands from package.json, turbo.json, biome.json, and 10+ config formats
+4. **Graph** — Call graph, import chains, and git co-change analysis (Jaccard similarity)
+5. **Score** — Inferability scoring decides what's worth including vs. what the AI already knows
+6. **Generate** — 14/16 sections are deterministic (no LLM). Only architecture summary and domain terms use optional micro-LLM calls.
+
+**No API key needed** for minimal mode or JSON output. The analysis is pure computation.
+
+## Output Formats
+
+```bash
+npx autodocs-engine init --minimal              # Focused AGENTS.md (~300 tokens)
+npx autodocs-engine init                         # Full AGENTS.md (needs API key)
+npx autodocs-engine analyze . --format json      # Raw analysis JSON
+npx autodocs-engine analyze . --format claude.md # CLAUDE.md format
+npx autodocs-engine analyze . --format cursorrules # .cursorrules format
+```
+
+## Monorepo Support
+
+Auto-detects workspace packages from `pnpm-workspace.yaml`, `workspaces` field in package.json, `turbo.json`, or `nx.json`:
+
+```bash
+npx autodocs-engine init --minimal    # Works for monorepos too
+```
+
+For explicit control:
+
+```bash
+npx autodocs-engine analyze packages/app packages/hooks packages/ui \
+  --format agents.md --hierarchical --root .
+```
+
+## Staleness Detection
+
+Check if your AGENTS.md needs updating (for CI):
+
+```bash
+npx autodocs-engine check
+```
+
+Returns exit code 1 if conventions have drifted. Useful in CI pipelines to keep context files honest.
+
+## Tested On
+
+| Repo | Files | Time | Token Count (minimal) |
+|------|------:|-----:|:-----:|
+| autodocs-engine | 115 | 450ms | ~443 |
+| vitest | 1,200+ | 1.2s | ~307 |
+| nitro | 469 | 220ms | ~121 |
+| sanity | 3,746 | 1.6s | — |
+| medusa | 720 | 316ms | — |
+
+501 tests. Zero type errors. Zero technology hallucinations across all tested repos.
+
+## Library API
+
+```typescript
+import { analyze, generateMinimalAgentsMd } from 'autodocs-engine';
+
+// Analyze (pure computation, no API key)
+const analysis = await analyze({ packages: ['./packages/my-pkg'] });
+
+// Generate minimal AGENTS.md (no API key)
+const minimal = generateMinimalAgentsMd(analysis);
+
+// Or use the full deterministic format (optional API key for 2 LLM sections)
+import { formatDeterministic } from 'autodocs-engine';
+const full = await formatDeterministic(analysis, config);
+```
+
+## Configuration
+
+Optional `autodocs.config.json`:
+
+```json
+{
+  "exclude": ["**/vendor/**", "**/generated/**"],
+  "conventions": { "disable": ["telemetry-patterns"] }
+}
+```
+
+Most options are auto-detected. Zero config is the default.
+
+## CLI Reference
+
+```
+autodocs-engine init [--minimal]           Generate AGENTS.md (zero-config)
+autodocs-engine serve [path]               Start MCP server
+autodocs-engine check                      Check if AGENTS.md needs regeneration
+autodocs-engine analyze [paths...] [options]
+
+Options:
+  --minimal          Focused output (<500 tokens, no API key needed)
+  --format, -f       json | agents.md | claude.md | cursorrules
+  --output, -o       Output directory (default: .)
+  --root             Monorepo root directory
+  --hierarchical     Root + per-package output
+  --merge            Preserve human-written sections when regenerating
+  --verbose, -v      Timing details
+  --dry-run          Print to stdout (no file writes)
+```
+
+## Contributing
+
+```bash
+git clone https://github.com/msiric/autodocs-engine.git
+cd autodocs-engine
+npm install
+npm test          # 501 tests
+npm run typecheck # Zero errors
+npm run build
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/analysis-builder.d.ts

@@ -0,0 +1,13 @@
+import type { ParsedFile, SymbolGraph, TierInfo, Convention, CommandSet, PackageArchitecture, PackageAnalysis, PublicAPIEntry, StructuredAnalysis, CrossPackageAnalysis, ResolvedConfig, Warning } from "./types.js";
+/**
+ * E-31: Compute publicAPI from barrel exports. Called BEFORE Architecture Detector.
+ */
+export declare function buildPublicAPI(symbolGraph: SymbolGraph, parsedFiles: ParsedFile[], maxEntries: number, warnings: Warning[]): PublicAPIEntry[];
+/**
+ * Build a complete PackageAnalysis from all module outputs.
+ */
+export declare function buildPackageAnalysis(packageDir: string, rootDir: string | undefined, parsedFiles: ParsedFile[], symbolGraph: SymbolGraph, tiers: Map<string, TierInfo>, conventions: Convention[], commands: CommandSet, architecture: PackageArchitecture, publicAPI: PublicAPIEntry[], warnings: Warning[]): PackageAnalysis;
+/**
+ * Build the final StructuredAnalysis object.
+ */
+export declare function buildStructuredAnalysis(packages: PackageAnalysis[], crossPackage: CrossPackageAnalysis | undefined, config: ResolvedConfig, warnings: Warning[], startTime: number): StructuredAnalysis;

package/dist/analysis-builder.js

@@ -0,0 +1,268 @@
+// src/analysis-builder.ts — Module 9: Structured Analysis Builder
+// Errata applied: E-31 (publicAPI computed before arch detector),
+//                 E-32 (importCount per public symbol), E-13 (cap publicAPI)
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, basename, dirname, extname, relative } from "node:path";
+import { ENGINE_VERSION } from "./types.js";
+/**
+ * E-31: Compute publicAPI from barrel exports. Called BEFORE Architecture Detector.
+ */
+export function buildPublicAPI(symbolGraph, parsedFiles, maxEntries, warnings) {
+    // Fix B: Build a set of files that import from React (for hook classification)
+    const fileMap = new Map();
+    for (const pf of parsedFiles) {
+        fileMap.set(pf.relativePath, pf);
+    }
+    const REACT_MODULES = new Set(["react", "react-dom", "preact", "preact/hooks", "preact/compat"]);
+    const entries = symbolGraph.barrelExports.map((exp) => {
+        let kind = exp.kind;
+        // Ensure hook classification — Fix B: only if source file imports React
+        if ((kind === "function" || kind === "unknown") &&
+            exp.name.startsWith("use") &&
+            exp.name.length > 3 &&
+            exp.name[3] === exp.name[3].toUpperCase()) {
+            const sourceFile = fileMap.get(exp.definedIn);
+            const hasReactImport = sourceFile?.imports.some((imp) => REACT_MODULES.has(imp.moduleSpecifier)) ?? false;
+            kind = hasReactImport ? "hook" : "function";
+        }
+        return {
+            name: exp.name,
+            kind,
+            sourceFile: exp.definedIn,
+            signature: exp.signature,
+            isTypeOnly: exp.isTypeOnly,
+            description: exp.jsDocComment,
+            importCount: 0, // E-32: will be computed below
+        };
+    });
+    // E-32: Compute importCount per public symbol
+    // Pre-build symbol → count map in a single pass (avoids O(entries * files * imports))
+    const importCounts = new Map();
+    for (const pf of parsedFiles) {
+        for (const imp of pf.imports) {
+            for (const name of imp.importedNames) {
+                importCounts.set(name, (importCounts.get(name) ?? 0) + 1);
+            }
+        }
+    }
+    for (const entry of entries) {
+        entry.importCount = importCounts.get(entry.name) ?? 0;
+    }
+    // E-13 + Fix C: Cap publicAPI entries with multi-criteria ranking
+    if (entries.length > maxEntries) {
+        entries.sort(comparePublicAPIEntries);
+        warnings.push({
+            level: "info",
+            module: "analysis-builder",
+            message: `Public API truncated: showing top ${maxEntries} of ${entries.length} exports`,
+        });
+        return entries.slice(0, maxEntries);
+    }
+    return entries;
+}
+/**
+ * Fix C: Kind priority for export cap ranking.
+ * Higher priority kinds sort first.
+ */
+const KIND_PRIORITY = {
+    hook: 0,
+    function: 1,
+    component: 2,
+    class: 3,
+    enum: 4,
+    const: 5,
+    type: 6,
+    interface: 7,
+    namespace: 8,
+    unknown: 9,
+};
+function comparePublicAPIEntries(a, b) {
+    // (a) Kind priority: hooks first, types last
+    const kindDiff = (KIND_PRIORITY[a.kind] ?? 9) - (KIND_PRIORITY[b.kind] ?? 9);
+    if (kindDiff !== 0)
+        return kindDiff;
+    // (b) Import count descending within same kind
+    const importDiff = (b.importCount ?? 0) - (a.importCount ?? 0);
+    if (importDiff !== 0)
+        return importDiff;
+    // (c) Alphabetical tiebreaker
+    return a.name.localeCompare(b.name);
+}
+/**
+ * Walk up from analysisDir to find nearest package.json with a name field.
+ * Stops at rootDir boundary or filesystem root.
+ */
+function resolvePackageMetadata(analysisDir, rootDir) {
+    const absDir = resolve(analysisDir);
+    // Only walk up if rootDir is provided (monorepo context).
+    // Without rootDir, we don't know the boundary and could pick up unrelated package.json.
+    const stopAt = rootDir ? resolve(rootDir) : absDir;
+    let dir = absDir;
+    while (true) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+                if (pkg.name) {
+                    return {
+                        name: pkg.name,
+                        version: pkg.version ?? "0.0.0",
+                        description: pkg.description ?? "",
+                    };
+                }
+            }
+            catch {
+                // Skip unparseable
+            }
+        }
+        // Stop at root dir boundary
+        if (dir === stopAt)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    // Last resort: use the analysis directory name, but filter out meaningless names
+    const dirName = basename(resolve(analysisDir));
+    const MEANINGLESS_NAMES = new Set(["src", "lib", "dist", "app", "packages", "core", "main"]);
+    if (MEANINGLESS_NAMES.has(dirName)) {
+        const parentName = basename(dirname(resolve(analysisDir)));
+        return { name: parentName, version: "0.0.0", description: "" };
+    }
+    return { name: dirName, version: "0.0.0", description: "" };
+}
+/**
+ * Build a complete PackageAnalysis from all module outputs.
+ */
+export function buildPackageAnalysis(packageDir, rootDir, parsedFiles, symbolGraph, tiers, conventions, commands, architecture, publicAPI, warnings) {
+    const absPackageDir = resolve(packageDir);
+    const absRootDir = rootDir ? resolve(rootDir) : absPackageDir;
+    // Resolve package metadata by walking up to nearest package.json with a name
+    const meta = resolvePackageMetadata(packageDir, rootDir);
+    let name = meta.name;
+    let version = meta.version;
+    let description = meta.description;
+    // Build FileInventory
+    const files = buildFileInventory(parsedFiles, tiers);
+    // Build DependencySummary
+    const dependencies = buildDependencies(parsedFiles, name);
+    // Empty publicAPI warning
+    if (publicAPI.length === 0) {
+        warnings.push({
+            level: "info",
+            module: "analysis-builder",
+            message: "No public API detected — package may not have a barrel file or may export nothing.",
+        });
+    }
+    return {
+        name,
+        version,
+        description,
+        relativePath: relative(absRootDir, absPackageDir) || ".",
+        files,
+        publicAPI,
+        conventions,
+        commands,
+        architecture,
+        dependencies,
+        role: { summary: "", purpose: "", whenToUse: "", inferredFrom: [] },
+        antiPatterns: [],
+        contributionPatterns: [],
+    };
+}
+function buildFileInventory(parsedFiles, tiers) {
+    const tier1Files = [];
+    const tier2Files = [];
+    let t1Lines = 0, t2Lines = 0, t3Lines = 0, t3Count = 0;
+    const byExtension = {};
+    for (const pf of parsedFiles) {
+        const tier = tiers.get(pf.relativePath);
+        const ext = extname(pf.relativePath);
+        byExtension[ext] = (byExtension[ext] ?? 0) + 1;
+        if (tier?.tier === 1) {
+            tier1Files.push(pf.relativePath);
+            t1Lines += pf.lineCount;
+        }
+        else if (tier?.tier === 2) {
+            tier2Files.push(pf.relativePath);
+            t2Lines += pf.lineCount;
+        }
+        else {
+            t3Count++;
+            t3Lines += pf.lineCount;
+        }
+    }
+    return {
+        total: parsedFiles.length,
+        byTier: {
+            tier1: { count: tier1Files.length, lines: t1Lines, files: tier1Files },
+            tier2: { count: tier2Files.length, lines: t2Lines, files: tier2Files },
+            tier3: { count: t3Count, lines: t3Lines },
+        },
+        byExtension,
+    };
+}
+function buildDependencies(parsedFiles, packageName) {
+    const internal = new Set();
+    const externalCounts = new Map();
+    // Detect org scope from package name
+    const scope = packageName.startsWith("@")
+        ? packageName.split("/")[0]
+        : null;
+    for (const pf of parsedFiles) {
+        for (const imp of pf.imports) {
+            if (imp.moduleSpecifier.startsWith("."))
+                continue; // relative
+            if (imp.isDynamic)
+                continue;
+            if (scope && imp.moduleSpecifier.startsWith(scope + "/")) {
+                internal.add(imp.moduleSpecifier);
+            }
+            else if (imp.moduleSpecifier.startsWith("@")) {
+                const pkg = imp.moduleSpecifier.split("/").slice(0, 2).join("/");
+                externalCounts.set(pkg, (externalCounts.get(pkg) ?? 0) + 1);
+            }
+            else {
+                const pkg = imp.moduleSpecifier.split("/")[0];
+                externalCounts.set(pkg, (externalCounts.get(pkg) ?? 0) + 1);
+            }
+        }
+    }
+    const external = [...externalCounts.entries()]
+        .map(([name, importCount]) => ({ name, importCount }))
+        .sort((a, b) => b.importCount - a.importCount);
+    return {
+        internal: [...internal].sort(),
+        external,
+        totalUniqueDependencies: internal.size + externalCounts.size,
+    };
+}
+/**
+ * Build the final StructuredAnalysis object.
+ */
+export function buildStructuredAnalysis(packages, crossPackage, config, warnings, startTime) {
+    const publicConfig = {
+        ...config,
+        llm: {
+            provider: config.llm.provider,
+            model: config.llm.model,
+            baseUrl: config.llm.baseUrl,
+            maxOutputTokens: config.llm.maxOutputTokens,
+        },
+    };
+    const meta = {
+        engineVersion: ENGINE_VERSION,
+        analyzedAt: new Date().toISOString(),
+        rootDir: config.rootDir ?? config.packages[0] ?? ".",
+        config: publicConfig,
+        timingMs: Math.round(performance.now() - startTime),
+    };
+    return {
+        meta,
+        packages,
+        crossPackage,
+        warnings,
+    };
+}
+//# sourceMappingURL=analysis-builder.js.map

package/dist/analysis-builder.js.map

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

package/dist/anti-pattern-detector.d.ts

@@ -0,0 +1,9 @@
+import type { Convention, AntiPattern } from "./types.js";
+/**
+ * Derive anti-patterns from conventions.
+ */
+export declare function deriveAntiPatterns(conventions: Convention[]): AntiPattern[];
+/**
+ * Derive shared anti-patterns from cross-package shared conventions.
+ */
+export declare function deriveSharedAntiPatterns(sharedConventions: Convention[]): AntiPattern[];

package/dist/anti-pattern-detector.js

@@ -0,0 +1,58 @@
+// src/anti-pattern-detector.ts — Enhancement 3: Anti-Pattern Derivation
+// Derives "DO NOT" rules by inverting strong conventions.
+// W5-A: Removed inversion rules for deleted detectors (named exports, barrel imports,
+// type-only imports, relative imports, displayName). Kept: file naming, testing, hooks.
+const INVERSION_RULES = [
+    {
+        match: /kebab.?case/i,
+        rule: () => "Do NOT use camelCase or PascalCase for filenames",
+        reason: (c) => `${c.confidence.description} use kebab-case — the codebase exclusively uses kebab-case filenames`,
+    },
+    {
+        match: /camel.?case/i,
+        rule: () => "Do NOT use kebab-case or PascalCase for filenames",
+        reason: (c) => `${c.confidence.description} use camelCase — the codebase exclusively uses camelCase filenames`,
+    },
+    {
+        match: /co.?located tests/i,
+        rule: () => "Do NOT put tests in a separate __tests__ directory — co-locate tests with source",
+        reason: (c) => `${c.confidence.description} co-locate tests next to source files`,
+    },
+    {
+        match: /hooks return objects/i,
+        rule: () => "Do NOT return arrays from hooks (use { value, setter } not [value, setter])",
+        reason: (c) => `${c.confidence.description} return objects from hooks`,
+    },
+];
+/**
+ * Derive anti-patterns from conventions.
+ */
+export function deriveAntiPatterns(conventions) {
+    const antiPatterns = [];
+    for (const conv of conventions) {
+        const pct = conv.confidence.percentage;
+        if (pct < 80)
+            continue; // Only derive from strong conventions
+        const confidence = pct >= 95 ? "high" : "medium";
+        // Try each inversion rule
+        for (const rule of INVERSION_RULES) {
+            if (rule.match.test(conv.name)) {
+                antiPatterns.push({
+                    rule: rule.rule(conv),
+                    reason: rule.reason(conv),
+                    confidence,
+                    derivedFrom: conv.name,
+                });
+                break; // Only one inversion per convention
+            }
+        }
+    }
+    return antiPatterns;
+}
+/**
+ * Derive shared anti-patterns from cross-package shared conventions.
+ */
+export function deriveSharedAntiPatterns(sharedConventions) {
+    return deriveAntiPatterns(sharedConventions);
+}
+//# sourceMappingURL=anti-pattern-detector.js.map

package/dist/anti-pattern-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anti-pattern-detector.js","sourceRoot":"","sources":["../src/anti-pattern-detector.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,0DAA0D;AAI1D,sFAAsF;AACtF,wFAAwF;AACxF,MAAM,eAAe,GAIf;IACJ;QACE,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,GAAG,EAAE,CAAC,kDAAkD;QAC9D,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,WAAW,sEAAsE;KACjH;IACD;QACE,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,GAAG,EAAE,CAAC,mDAAmD;QAC/D,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,WAAW,oEAAoE;KAC/G;IACD;QACE,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,GAAG,EAAE,CAAC,kFAAkF;QAC9F,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,WAAW,uCAAuC;KAClF;IACD;QACE,KAAK,EAAE,uBAAuB;QAC9B,IAAI,EAAE,GAAG,EAAE,CAAC,6EAA6E;QACzF,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,WAAW,4BAA4B;KACvE;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAyB;IAC1D,MAAM,YAAY,GAAkB,EAAE,CAAC;IAEvC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QACvC,IAAI,GAAG,GAAG,EAAE;YAAE,SAAS,CAAC,sCAAsC;QAE9D,MAAM,UAAU,GAAsB,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;QAEpE,0BAA0B;QAC1B,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/B,YAAY,CAAC,IAAI,CAAC;oBAChB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;oBACrB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;oBACzB,UAAU;oBACV,WAAW,EAAE,IAAI,CAAC,IAAI;iBACvB,CAAC,CAAC;gBACH,MAAM,CAAC,oCAAoC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,iBAA+B;IACtE,OAAO,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;AAC/C,CAAC"}

package/dist/architecture-detector.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedFile, PublicAPIEntry, PackageArchitecture, Warning } from "./types.js";
+export declare function detectArchitecture(parsedFiles: ParsedFile[], packageDir: string, publicAPI: PublicAPIEntry[], barrelFile: string | undefined, warnings?: Warning[]): PackageArchitecture;
+/**
+ * Enhancement 2: Detect file naming pattern from a set of filenames.
+ * Finds the longest common prefix and suffix, with the variable part as {...}.
+ */
+export declare function detectFilePattern(filenames: string[]): string | undefined;