docs agent's ast parser missed re-exported symbols in the barrel file
Fixes a docs agent whose AST parser misses symbols re-exported through barrel files. The skill shows how to detect the coverage gap, follow re-export chains, and verify the documented surface matches the package exports. It covers ES modules, Python __init__ chains, and Rust re-exports.
TL;DR
Make the parser follow re-export chains: resolve export * and named re-exports to their source modules. Verify the documented symbol set against the package's actual public exports. Test with a barrel file that re-exports from depth.
The exact error
docs missing re-exported symbols from barrel fileSteps
Compare exports to docs List the package's public exports (import the entry and enumerate) and diff against the documented symbols. Success check: You have the list of missing re-exported symbols.
Trace the re-export chain Follow the barrel file's re-exports to the defining modules and confirm the symbols exist there. Success check: You know the full chain from barrel to definition.
Fix the parser Extend the AST walk to resolve re-export statements to their targets instead of stopping at the barrel file. Success check: The parser follows re-exports to the defining module.
Verify coverage Regenerate and confirm the documented set matches the public exports exactly. Success check: No public symbol is undocumented and no private one leaks in.
When to use
- Use when generated API docs miss re-exported symbols.
- Use when an agent parses module structure for doc generation.
When not to use
- Not for symbols missing because the module was never scanned (discovery problem).
- Not for private symbols leaking into docs (filter problem).
Why it happens
Barrel files re-export symbols defined elsewhere, so a parser that only reads definitions misses everything the barrel surfaces. The public API of many packages lives almost entirely behind re-exports, making this a large silent gap.
Edge cases
The ground truth is the runtime export list, not the AST: importing the entry point and enumerating exports catches whatever the parser missed. Some bundlers rewrite re-exports, so test the parser against the source tree, not the bundle.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_cE1zHFI5FtjPsTQT9J0jXw