Skip to content

feat(codegen): add docs generation for ORM, React Query, and multi-target support#728

Merged
pyramation merged 5 commits intomainfrom
devin/1771353478-docs-all-generators
Feb 19, 2026
Merged

feat(codegen): add docs generation for ORM, React Query, and multi-target support#728
pyramation merged 5 commits intomainfrom
devin/1771353478-docs-all-generators

Conversation

@pyramation
Copy link
Contributor

feat(codegen): extend docs generation to ORM and React Query generators

Summary

Extends the docs generation system (previously CLI-only from PR #725) to also cover ORM and React Query generators. Adds multi-target orchestration (generateMulti()) to core so the CLI entry point delegates looping rather than owning it.

New files:

  • docs-utils.ts — shared utilities extracted from the CLI docs generator (resolveDocsConfig, fieldTypeToTs, McpTool type)
  • orm/docs-generator.ts — README, AGENTS.md, MCP tools, and skills for the ORM layer (~525 lines)
  • hooks-docs-generator.ts — README, AGENTS.md, MCP tools, and skills for React Query hooks (~595 lines)
  • target-docs-generator.ts — per-target root README, combined mcp.json, root-root README for multi-target configs

Modified files:

  • types/config.tsdocs: DocsConfig | boolean moved to top-level GraphQLSDKConfigTarget (removed from CliConfig)
  • core/generate.ts — wires docs generation for all enabled generators after code generation; adds generateMulti() for multi-target configs
  • cli/index.ts (entry point) — uses generateMulti() instead of its own loop
  • cli/docs-generator.ts — refactored to import shared utils from docs-utils.ts
  • cli/index.ts (codegen) — removed docs generation from generateCli(); docs are now handled centrally in generate()

3-level README hierarchy:

  1. Root-root README (multi-target only) — table-of-contents routing to each target
  2. Per-target README — ties together ORM/hooks/CLI docs for one API
  3. Per-generator README/AGENTS.md/skills — detailed docs per generator subdirectory

Review & Testing Checklist for Human

  • generateMulti() file writing approach — the root-root README is written via a dynamic import('./output') and writeGeneratedFiles() call to . (outside the normal filesToWrite array flow). Verify this doesn't cause issues with pruning, path resolution, or concurrent writes in real multi-target configs.
  • Docs generators are all string-based markdown — unlike the code generators which use Babel AST, these produce markdown via string concatenation. The previous conversation had a "no string concatenation" directive for code generation. Verify this is acceptable for non-code (markdown/JSON) output, or if you'd prefer a different approach.
  • Lockfile changespnpm-lock.yaml has thousands of lines changed including @types/node version shifts (22 → 20) and ts-node entry removals. Verify this was intentional or if the lockfile was regenerated in a different environment. May want to regenerate with pnpm install in a clean state.
  • Test a multi-target config end-to-end — create a config with 3 targets (e.g., auth, members, app) each with different generator combinations, run codegen, verify:
    • Each target's output directory has correct docs
    • Root-root README is generated at project root with correct links
    • Combined mcp.json at each target root includes tools from all enabled generators
    • No file path issues or missing docs

Notes

  • All 262 tests pass, 31 new snapshots added
  • Defaults: readme + agents always on, mcp + skills opt-in
  • docs: true enables all 4 formats
  • docs: false disables all docs

Link to Devin run: https://app.devin.ai/sessions/e9c668834d394cdc8ebcb371b6ebf430
Requested by: @pyramation

- Add cli config option (CliConfig | boolean) to GraphQLSDKConfigTarget
- Add komoji dependency for toKebabCase casing
- Create CLI generator orchestrator (cli/index.ts)
- Create arg-mapper: converts CleanTypeRef to inquirerer Question[]
- Create infra-generator: context + auth commands via Babel AST
- Create executor-generator: ORM client init with appstash credentials
- Create table-command-generator: per-table CRUD using ORM methods
- Create custom-command-generator: per-operation using ORM methods
- Create command-map-generator: command registry (Record<string, Function>)
- Wire CLI generation into generate.ts alongside ORM/React Query
- Update root barrel to include CLI exports

Architecture: CLI -> ORM -> GraphQL (not CLI -> raw GraphQL)
CLI commands: prompt for args -> call ORM method -> print JSON result
Uses appstash@0.4.0 config-store for context/credential management
- Add cli-generator.test.ts with 13 tests covering all generated files
- Snapshot executor, context, auth, table commands, custom commands, command map
- Verify ORM method calls in table and custom commands
- Verify appstash config-store usage in executor
- Fix: runOrm now includes runCli so ORM is auto-enabled when CLI is enabled
- Add docs-generator.ts that produces README.md (overview, setup, commands)
  and COMMANDS.md (man-page style reference with synopsis, options, examples)
- Wire into CLI orchestrator so docs are always generated alongside commands
- Update snapshot tests: 15 tests, 10 snapshots covering all generated files
…CP, Skills)

- Add DocsConfig interface: { readme, agents, mcp, skills } with boolean flags
- Defaults: readme + agents on, mcp + skills opt-in. docs: true enables all.
- generateAgentsDocs(): structured AGENTS.md for LLM consumption with TOOL
  sections, INPUT/OUTPUT schemas, WORKFLOWS, and ERROR HANDLING
- generateMcpConfig(): mcp.json with typed inputSchema per command (JSON Schema)
- generateSkills(): per-command .md skill files for agent systems
- Wire into cli/index.ts orchestrator with config-driven conditional generation
- 22 tests, 17 snapshots covering all formats and config combinations
…rget support

- Move docs config to top-level GraphQLSDKConfigTarget (removed from CliConfig)
- Create shared docs-utils.ts with common utilities
- Add ORM docs generator (README, AGENTS.md, MCP tools, skills)
- Add React Query hooks docs generator (README, AGENTS.md, MCP tools, skills)
- Add per-target README and combined MCP config generators
- Add root-root README for multi-target configs
- Add generateMulti() to core for multi-target orchestration
- Update CLI entry point to use core generateMulti()
- Wire all docs generation into generate.ts
- 32 tests, 31 snapshots covering all doc formats
@devin-ai-integration
Copy link
Contributor

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@pyramation pyramation merged commit 0fb16ea into main Feb 19, 2026
44 checks passed
@pyramation pyramation deleted the devin/1771353478-docs-all-generators branch February 19, 2026 03:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

Comments