Instructions for AI assistants working on the @jonverrier/auto-doc package (formerly @jonverrier/c4-auto). This is a standalone repository — not part of a monorepo workspace.
AutoDoc is a publishable Node.js CLI that generates C4 architecture documentation for TypeScript codebases. It walks a directory tree, refreshes LLM-generated module header comments in source files, writes per-directory C4 Component/Context markdown, and optionally rolls up nested trees into package-level summaries at the scan root using human design intent when available.
Generated output only — never modify the project README.md.
Default generated filenames (Strong AI convention, overridable via CLI):
README.StrongAI.Component.md(--component-file)README.StrongAI.Context.md(--context-file)
src/
generate-docs-cli.ts CLI entry (bin: auto-doc; legacy alias c4-auto)
DirectoryTreeTraverser.ts Tree walk + detectSubdirectorySources()
VisitorFactory.ts Wires production visitors
ModuleHeaderVisitor.ts kFirst — source file headers
C4DiagramVisitor.ts kSecond — per-directory C4 READMEs
RollupC4Visitor.ts kThird — root rollup in finalize()
DesignContextUtils.ts Design.md/DESIGN.md discovery for rollup context
C4ReadmeUtils.ts Output filenames, datestamp/staleness helpers
ModuleHeaderExtract.ts Header block extraction from .ts sources
DocGenTypes.ts Shared interfaces and enums
PromptIds.ts Prompt UUID constants
Prompts.json In-memory prompt templates (copied to dist/)
test/ Jest unit, integration, and e2e tests
dist/ Published compiled output only
Execution order per directory (ascending priority):
- ModuleHeaderVisitor — update stale header comments in
.ts/.tsx. - C4DiagramVisitor — write per-directory generated markdown from module headers. Skip scan root when
--rollupand nested sources were detected. - RollupC4Visitor — during
visit(), accumulate subdirectory README paths and record root source files; duringfinalize(), write root rollup READMEs.
Before traversal, when --rollup is set, detectSubdirectorySources() sets IDocGenOptions.hasSubdirectorySources.
Output filenames come from IDocGenOptions.componentOutputFile and contextOutputFile (defaults in DEFAULT_C4_OUTPUT_FILES, validated by validateC4OutputFilename()).
| Condition | Behaviour |
|---|---|
| Flat tree (no nested matching sources) | Per-directory C4 at root; rollup skipped |
Nested tree + --rollup |
Subdirs get per-directory C4; root READMEs are rollup-only |
| Rollup input | Subdirectory README content + root module headers ((root) section) + optional design intent |
| Rollup staleness | Use isRollupOutputStale() — includes design file mtime when available |
Do not write per-directory root C4 and rollup root C4 in the same run for nested trees.
npm install
npm run build # rimraf dist && tsc && copy Prompts.json
npm run test:ci # unit + integration (no OPENAI_API_KEY)
npm run test:e2e # real LLM (needs OPENAI_API_KEY)
npm pack --dry-run # verify dist-only tarballPublish (GitHub Packages):
- Commit on
develop, merge tomain. - On
main:npm install,npm run build,npm publishwithNODE_AUTH_TOKEN. - Return to
develop.
- TypeScript strict mode, ES2022, Node 24, CommonJS.
- Use
@jonverrier/prompt-repositoryerror classes (InvalidParameterError,InvalidOperationError,ConnectionError) — never rawError. - Interface prefix
I, enum prefixE, enum members prefixk. - JSDoc on public modules/functions; copyright header on source files.
- Constants for magic numbers at file top (timeouts, word counts, etc.).
- Tests: Jest +
expect+ Sinon;describe/itare globals. - Use exhaustive switch handling for TypeScript unions and enums.
- Mock
IFileReader,IFileWriter,IDirectoryReader,IFileFilter,IChatDriver, andIPromptRepositoryin unit tests. - Use
makeTestDocGenOptions()fromtest/testDocGenOptions.tsfor completeIDocGenOptionsin tests. - Cover CLI parsing (
generate-docs-cli.test.ts), custom output filenames, rollup behaviour, and staleness helpers. - Do not pipe live Jest output through
tail/grep— runnpm run test:cidirectly.
- Never run destructive git commands unless explicitly requested.
- Do not delete untracked files without approval.
- Inspect
git status --short --branchbefore committing. - No AI attribution in commit messages.
- PromptRepository (
@jonverrier/prompt-repository) — LLM drivers and prompt expansion. - AgentDoc — MCP server for interactive C4 diagram generation (separate repo; formerly C4-Agent).