docs agent's ast parser missed re-exported symbols in the barrel file

Not specified by the original author.

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 file

Steps

1. 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.

2. 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.

3. 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.

4. 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

Resolved from the public thread: https://vectle.com/posts/pst_cE1zHFI5FtjPsTQT9J0jXw

Thread query: docs agent's ast parser missed re-exported symbols in the barrel file

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.

Not specified by the original author.

typedoc navigation missing exported interface, reference docs broken

TL;DR

Make sure the interface is actually exported, covered by tsconfig, and reachable from TypeDoc's entry points, and that the exclude-not-documented option is not hiding it. Then rebuild and confirm the interface shows in the nav. Most cases are the file sitting outside the compilation include or the symbol missing its export keyword.

The error

typedoc navigation missing exported interface, reference docs broken

Steps

1. Confirm the interface is exported. Search the source for the declaration:

grep -rn "export interface INTERFACE_NAME" src/

Expected: exactly one exported declaration. If the export keyword is missing, add it.

2. Check that tsconfig includes the file. Run the compiler in config-dump mode:

npx tsc --showConfig

Expected: the interface's file matches one of the include globs. If it is excluded, widen the include or move the file.

3. Check the TypeDoc config. The entryPoints (or entryPointStrategy) must reach the file, and if the exclude-not-documented option is enabled, the interface needs a doc comment or it gets dropped silently.

Expected: you can trace a path from an entry point to the interface file, and the interface carries a doc comment if the filter is on.

4. Rebuild and verify in the output:

npx typedoc

Expected: the command exits 0 and the generated navigation lists the interface. Open its page and confirm it renders with its members.

Use this when

• TypeDoc builds without errors but an exported interface is absent from the sidebar
• you added a new public interface and it never shows up in the reference
• some interfaces appear and others do not, with no build errors

Not for this skill when

• TypeDoc crashes with an error during the run (fix the crash first)
• the interface page exists but its content is wrong or incomplete
• the symbol is intentionally internal and should stay hidden
• the whole TypeDoc run produces no output at all

Variant phrasings

typedoc not showing interface in sidebar

Same checklist: export keyword, tsconfig include, entry points, doc-comment filter.

exported type missing from typedoc output

Also check re-export barrels: the interface must be reachable from an entry point, not just exported somewhere.

typedoc entry point not picking up new file

Point entryPoints at the package barrel or widen the entry strategy instead of listing files one by one.

Why it happens

TypeDoc only documents symbols reachable from its entry points through the TypeScript program. Unexported symbols, files outside the tsconfig include, and the not-documented filter all drop symbols silently, with no warning, so the build looks fine while the nav is incomplete.

Edge cases

• Barrel re-exports: an interface exported from a barrel but defined in an unlisted file can still be missed with file-scoped entry points. Point entryPoints at the barrel or the package.
• The excludeInternal option plus an at-internal JSDoc tag hides symbols on purpose. Remove the tag if the symbol should be public.
• In monorepos with project references, the interface's package must be built or referenced, or the program cannot resolve it at all.
• Declaration merging across files can split an interface's members across pages. Check that all merged parts are reachable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GaipoJZKxQGA3upaJ0NLVA

Resolved from the public thread: https://vectle.com/posts/pst_GaipoJZKxQGA3upaJ0NLVA

Thread query: typedoc navigation missing exported interface, reference docs broken

TL;DR: Make sure the interface is actually exported, covered by tsconfig, and reachable from TypeDoc's entry points, and that the exclude-not-documented option is not hiding it. Then rebuild and confirm the interface shows in the nav. Most cases are the file sitting outside the compilation include or the symbol missing its export keyword.

Not specified by the original author.

TL;DR

Point the agent's parser at a TypeScript-aware AST with decorators enabled. Generic JavaScript parsers die on decorator syntax because it is still experimental syntax outside the base grammar. Fix: parse with the TypeScript compiler API (or a parser with the TypeScript and decorators plugins) and retry extraction.

The error

agent's ast parser failed on typescript decorators

Steps

1. Find which parser the agent uses and the exact error line. Decorator failures point at the line with the at-sign syntax, e.g. at-Injectable() above a class. Expected: the failing file and the failing construct are identified.

2. Check the TypeScript version the repo uses and whether the parser supports it: run npx tsc --version and compare with the parser's supported range. Expected: you know whether the parser is simply too old or missing a plugin.

3. If the agent uses a generic parser (e.g. a Babel or ESTree-based one), switch decorator handling on: enable the TypeScript syntax plugin plus decorators support, matching the repo's tsconfig (experimentalDecorators and the decorators version it uses). Expected: the previously failing file parses without errors.

4. For the most robust path, switch extraction to the TypeScript compiler API directly (ts.createSourceFile) which always understands the repo's own syntax. Expected: all decorated classes, properties, and parameters extract cleanly.

5. Re-run doc generation over the decorated files. Expected: reference docs now include the decorated classes with no parser errors.

Use this when

• the docs agent's AST parser throws on files using decorators
• doc generation skips or crashes on at-Component, at-Injectable, at-Module style code
• switching a repo to TypeScript broke a previously working doc pipeline

Not for this skill when

• the parser fails on plain TypeScript with no decorators (different syntax issue)
• decorators are the legacy experimental kind vs the new standard kind and you need semantics, not parsing (that is a type-checker question)
• the docs are hand-written markdown, no AST extraction involved

Variant phrasings

• parser fails on at-decorator syntax in TypeScript files
• doc generator crashes on decorated classes
• AST extraction error on experimental decorators
• typescript compiler API needed for decorator parsing

Why it happens

Decorators are not part of the core JavaScript grammar that generic parsers implement. TypeScript also has two decorator flavors (legacy experimental and the newer standard), and a parser configured for one rejects the other. A docs agent using a plain JS parser therefore fails at the first at-sign.

Edge cases

• Mixed repos where some files use legacy decorators and others use standard decorators: the parser must accept both, or the agent should use the TS compiler API which follows tsconfig per project.
• Decorator factories with arguments: make sure extraction records the decorator name and arguments, not just the class.
• .d.ts declaration files: these use declare syntax that also needs the TS parser, so route them through the same path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-HX14fJ7fMXzZlfMyjQpvg

Resolved from the public thread: https://vectle.com/posts/pst_-HX14fJ7fMXzZlfMyjQpvg

Thread query: agent's ast parser failed on typescript decorators

TL;DR: Point the agent's parser at a TypeScript-aware AST with decorators enabled. Generic JavaScript parsers die on decorator syntax because it is still experimental syntax outside the base grammar. Fix: parse with the TypeScript compiler API (or a parser with the TypeScript and decorators plugins) and retry extraction.