Skip to content

Commit f6fc823

Browse files
committed
docs: add AI assistant guidelines (CLAUDE.md, AGENTS.md)
1 parent 49a4fee commit f6fc823

File tree

10 files changed

+221
-0
lines changed

10 files changed

+221
-0
lines changed

.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,5 @@ dist-ssr
2626
openapi
2727
*.tsbuildinfo
2828
coverage
29+
30+
.agents

.serena/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/cache
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Project purpose
2+
- Library: `@7nohe/openapi-react-query-codegen` generates React Query (TanStack Query) hooks, prefetch/ensure helpers, and TS clients from an OpenAPI schema by leveraging `@hey-api/openapi-ts`.
3+
- Outputs React Query wrappers around the generated request client, supporting useQuery/useSuspenseQuery/useMutation/useInfiniteQuery and query key functions.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Style and conventions
2+
- Code: TypeScript strict, NodeNext modules, ESNext target. Imports organized; prefer named imports. Uses ts-morph/TypeScript factory for AST-based codegen.
3+
- Formatting/lint: Biome enforced (formatter + linter). 2-space indent, spaces not tabs. Import organization enabled. Biome ignores build artifacts (dist, docs/.astro, examples outputs).
4+
- Generated output: Comments include generator version header. Use double quotes and trailing commas (ts-morph manipulation settings). Keep code ASCII unless needed.
5+
- Tests: Vitest. Coverage flag enabled in test script.
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Suggested commands
2+
- Install deps: `pnpm install`
3+
- Build generator: `pnpm build`
4+
- Lint (Biome): `pnpm lint`
5+
- Fix lint/format: `pnpm lint:fix`
6+
- Tests (Vitest + coverage): `pnpm test`
7+
- Update snapshots: `pnpm snapshot`
8+
- Preview example generation (build then generate in sample app): `pnpm preview:react`, `pnpm preview:nextjs`, `pnpm preview:tanstack-router`
9+
- Release (bumpp + git-ensure): `pnpm release`
10+
- Docs (Astro) lives under docs/; run from that workspace if needed.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# What to run before finishing a task
2+
- Run `pnpm lint` (Biome) to ensure style/lint compliance.
3+
- Run `pnpm test` for Vitest with coverage (or `pnpm snapshot` if snapshots changed intentionally).
4+
- Run `pnpm build` to confirm the generator compiles to dist.
5+
- If touching example outputs, rerun the relevant `preview:*` command to verify generation still works.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Tech stack and structure
2+
- Runtime/tooling: Node (>=14), pnpm (>=9), TypeScript (strict, NodeNext). Uses ts-morph and TypeScript factory APIs for codegen. Tests: Vitest. Lint/format: Biome. Bundling/CLI output in `dist/` via `tsc`.
3+
- Source layout: `src/` contains CLI/generator pieces (generate.mts, createSource.mts, createImports.mts, createExports.mts, format.mts, service.mts, etc.). `tests/` holds Vitest suites. `examples/` has sample apps per framework; `docs/` uses Astro for docs site. Built artifacts land in `dist/`.
4+
- Config: `tsconfig.json` sets strict + ESNext + DOM libs, NodeNext module resolution. `biome.json` enables formatter/linter with 2-space indent and import organization; ignores dist/examples build outputs.
5+
- Scripts of interest (package.json): build via `pnpm build` (rimraf dist && tsc), lint via `pnpm lint` (biome check), tests via `pnpm test` (vitest --coverage.enabled true), preview generators under examples (preview:*), release uses bumpp/git-ensure.

.serena/project.yml

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# list of languages for which language servers are started; choose from:
2+
# al bash clojure cpp csharp csharp_omnisharp
3+
# dart elixir elm erlang fortran go
4+
# haskell java julia kotlin lua markdown
5+
# nix perl php python python_jedi r
6+
# rego ruby ruby_solargraph rust scala swift
7+
# terraform typescript typescript_vts yaml zig
8+
# Note:
9+
# - For C, use cpp
10+
# - For JavaScript, use typescript
11+
# Special requirements:
12+
# - csharp: Requires the presence of a .sln file in the project folder.
13+
# When using multiple languages, the first language server that supports a given file will be used for that file.
14+
# The first language is the default language and the respective language server will be used as a fallback.
15+
# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
16+
languages:
17+
- typescript
18+
19+
# the encoding used by text files in the project
20+
# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
21+
encoding: "utf-8"
22+
23+
# whether to use the project's gitignore file to ignore files
24+
# Added on 2025-04-07
25+
ignore_all_files_in_gitignore: true
26+
27+
# list of additional paths to ignore
28+
# same syntax as gitignore, so you can use * and **
29+
# Was previously called `ignored_dirs`, please update your config if you are using that.
30+
# Added (renamed) on 2025-04-07
31+
ignored_paths: []
32+
33+
# whether the project is in read-only mode
34+
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
35+
# Added on 2025-04-18
36+
read_only: false
37+
38+
# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
39+
# Below is the complete list of tools for convenience.
40+
# To make sure you have the latest list of tools, and to view their descriptions,
41+
# execute `uv run scripts/print_tool_overview.py`.
42+
#
43+
# * `activate_project`: Activates a project by name.
44+
# * `check_onboarding_performed`: Checks whether project onboarding was already performed.
45+
# * `create_text_file`: Creates/overwrites a file in the project directory.
46+
# * `delete_lines`: Deletes a range of lines within a file.
47+
# * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
48+
# * `execute_shell_command`: Executes a shell command.
49+
# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
50+
# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
51+
# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
52+
# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
53+
# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
54+
# * `initial_instructions`: Gets the initial instructions for the current project.
55+
# Should only be used in settings where the system prompt cannot be set,
56+
# e.g. in clients you have no control over, like Claude Desktop.
57+
# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
58+
# * `insert_at_line`: Inserts content at a given line in a file.
59+
# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
60+
# * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
61+
# * `list_memories`: Lists memories in Serena's project-specific memory store.
62+
# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
63+
# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
64+
# * `read_file`: Reads a file within the project directory.
65+
# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
66+
# * `remove_project`: Removes a project from the Serena configuration.
67+
# * `replace_lines`: Replaces a range of lines within a file with new content.
68+
# * `replace_symbol_body`: Replaces the full definition of a symbol.
69+
# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
70+
# * `search_for_pattern`: Performs a search for a pattern in the project.
71+
# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
72+
# * `switch_modes`: Activates modes by providing a list of their names
73+
# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
74+
# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
75+
# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
76+
# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
77+
excluded_tools: []
78+
79+
# initial prompt for the project. It will always be given to the LLM upon activating the project
80+
# (contrary to the memories, which are loaded on demand).
81+
initial_prompt: ""
82+
83+
project_name: "openapi-react-query-codegen"
84+
included_optional_tools: []

AGENTS.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
- Source code lives in `src/` (CLI entry `cli.mts`, generator pipeline `generate.mts`, codegen helpers like `createSource.mts`, `createImports.mts`, `createExports.mts`, `service.mts`, formatting in `format.mts`).
5+
- Tests reside in `tests/` (Vitest).
6+
- Example apps under `examples/` (React/Next.js/TanStack Router) consume the generated client.
7+
- Docs site in `docs/` (Astro). Build artifacts output to `dist/`.
8+
9+
## Build, Test, and Development Commands
10+
- Install: `pnpm install`
11+
- Build generator: `pnpm build` (cleans `dist/`, runs `tsc`).
12+
- Lint/format check: `pnpm lint` (Biome). Auto-fix: `pnpm lint:fix`.
13+
- Tests: `pnpm test` (Vitest with coverage). Snapshots: `pnpm snapshot`.
14+
- Preview generation into examples: `pnpm preview:react`, `pnpm preview:nextjs`, `pnpm preview:tanstack-router`.
15+
16+
## Coding Style & Naming Conventions
17+
- Language: TypeScript (strict, ESNext, NodeNext). Keep code in modules (`.mts`), output compiled to `dist/`.
18+
- Formatting/linting via Biome: 2-space indent, double quotes, trailing commas, organized imports. Run formatters before committing.
19+
- Generated outputs include a header comment with package version; preserve this when modifying generation.
20+
- Prefer descriptive function names and explicit types; avoid implicit `any`.
21+
22+
## Testing Guidelines
23+
- Framework: Vitest. Coverage enabled by default.
24+
- Place tests in `tests/`; mirror generator behavior with snapshot tests where helpful.
25+
- After generator changes, run tests and consider regenerating example outputs to manually diff.
26+
27+
## Commit & Pull Request Guidelines
28+
- Commits: clear, descriptive messages (e.g., `fix: align imports for generated queries`, `chore: update ts-morph config`). Avoid bundling unrelated changes.
29+
- Pull requests: include summary of changes, affected areas (e.g., codegen output, docs, examples), and test commands run. Link issues when applicable. Add before/after notes or sample generated snippets if behavior changes.
30+
31+
## Agent-Specific Notes
32+
- Use AST-aware paths (ts-morph/TypeScript factory) when editing generators to keep output structurally valid.
33+
- Respect ignore patterns in `biome.json` and avoid checking in `dist/` or example-generated artifacts unless explicitly intended.

CLAUDE.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
OpenAPI React Query Codegen generates React Query (TanStack Query) hooks from OpenAPI specifications. It uses `@hey-api/openapi-ts` to generate TypeScript clients and then creates additional query/mutation hooks on top.
8+
9+
## Commands
10+
11+
```bash
12+
# Build
13+
npm run build
14+
15+
# Run tests with coverage
16+
npm test
17+
18+
# Run a single test file
19+
npx vitest tests/generate.test.ts
20+
21+
# Update snapshots
22+
npm run snapshot
23+
24+
# Lint
25+
npm run lint
26+
npm run lint:fix
27+
28+
# Preview generated output in example apps
29+
npm run preview:react
30+
npm run preview:nextjs
31+
npm run preview:tanstack-router
32+
```
33+
34+
## Architecture
35+
36+
### Code Generation Pipeline
37+
38+
1. **CLI Entry** (`src/cli.mts`): Parses command-line options using Commander
39+
2. **Generate** (`src/generate.mts`): Orchestrates the generation process:
40+
- Calls `@hey-api/openapi-ts` to generate base TypeScript client in `openapi/requests/`
41+
- Calls `createSource()` to generate React Query hooks in `openapi/queries/`
42+
3. **Service Parsing** (`src/service.mts`): Uses ts-morph to parse the generated `services.gen.ts` file and extract function descriptions (method name, HTTP method, JSDoc, etc.)
43+
4. **Export Creation** (`src/createExports.mts`): Routes methods to appropriate generators based on HTTP method:
44+
- GET methods → `createUseQuery()` (queries, suspense queries, infinite queries)
45+
- POST/PUT/PATCH/DELETE → `createUseMutation()`
46+
5. **Hook Generators**:
47+
- `src/createUseQuery.mts`: Generates `useQuery`, `useSuspenseQuery`, and `useInfiniteQuery` hooks
48+
- `src/createUseMutation.mts`: Generates `useMutation` hooks
49+
- `src/createPrefetchOrEnsure.mts`: Generates `prefetchQuery` and `ensureQueryData` functions
50+
6. **Print** (`src/print.mts`): Writes generated TypeScript to files
51+
52+
### Generated Output Structure
53+
54+
The tool generates files in `openapi/queries/`:
55+
- `common.ts`: Shared types, query keys, and key functions
56+
- `queries.ts`: `useQuery` and `useMutation` hooks
57+
- `suspense.ts`: `useSuspenseQuery` hooks
58+
- `infiniteQueries.ts`: `useInfiniteQuery` hooks
59+
- `prefetch.ts`: `prefetchQuery` functions
60+
- `ensureQueryData.ts`: `ensureQueryData` functions
61+
- `index.ts`: Re-exports
62+
63+
### Key Dependencies
64+
65+
- **ts-morph**: AST manipulation for reading the generated service file
66+
- **typescript**: AST creation for generating new TypeScript code
67+
- **@hey-api/openapi-ts**: Base OpenAPI to TypeScript client generator
68+
69+
## Testing
70+
71+
Tests use Vitest with snapshot testing. Test files in `tests/` correspond to source modules. The `tests/utils.ts` file provides a shared `project` fixture using `examples/petstore.yaml`.
72+
73+
Coverage thresholds: 95% lines/functions/statements, 90% branches.

0 commit comments

Comments
 (0)