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.

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