Skip to content

Commit f02ab6f

Browse files
Fluf22Fluf22
authored
chore: agentic config prep (#5825)
1 parent 609737c commit f02ab6f

File tree

18 files changed

+2694
-0
lines changed

18 files changed

+2694
-0
lines changed

‎AGENTS.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# PROJECT KNOWLEDGE BASE
2+
3+
**Generated:** 2026-01-14
4+
**Commit:** 609737c378
5+
**Branch:** main
6+
7+
## OVERVIEW
8+
9+
Multi-language API client generator for Algolia. Generates 11 language clients (JavaScript, Python, Java, Go, Ruby, PHP, Kotlin, Scala, Swift, Dart, C#) from OpenAPI specs using custom OpenAPI Generator extensions.
10+
11+
## STRUCTURE
12+
13+
```
14+
api-clients-automation/
15+
├── clients/ # Generated API clients (11 languages) - DO NOT EDIT directly
16+
├── generators/ # Custom Java OpenAPI generators (Gradle)
17+
├── templates/ # Mustache templates per language
18+
├── specs/ # OpenAPI YAML specifications
19+
│ ├── bundled/ # Pre-built specs for generation
20+
│ └── {api}/ # Modular specs (search, ingestion, insights...)
21+
├── scripts/ # TypeScript CLI and build orchestration
22+
│ ├── cli/ # Commander.js CLI entry point
23+
│ ├── cts/ # Common Test Suite generation
24+
│ ├── release/ # Release automation
25+
│ └── ci/ # GitHub Actions helpers
26+
├── config/ # Generation config, version files
27+
├── tests/ # CTS test definitions and output
28+
├── docs/ # Snippets, guides per language
29+
├── website/ # Docusaurus documentation site
30+
├── eslint/ # Custom ESLint plugin for spec validation
31+
└── playground/ # Language-specific test environments
32+
```
33+
34+
## WHERE TO LOOK
35+
36+
| Task | Location | Notes |
37+
| ------------------------------- | -------------------------------------------------- | ----------------------- |
38+
| Add/modify API endpoint | `specs/{api}/paths/` | Then regenerate clients |
39+
| Change generated code structure | `templates/{language}/` | Mustache templates |
40+
| Custom generation logic | `generators/src/main/java/com/algolia/codegen/` | Java generators |
41+
| CLI commands | `scripts/cli/index.ts` | Commander.js |
42+
| Build/test a client | `scripts/buildLanguages.ts` | Via `yarn cli build` |
43+
| Add new language | `config/clients.config.json` + `templates/{lang}/` | See docs |
44+
| CI/CD workflows | `.github/workflows/check.yml` | Main pipeline |
45+
| Release process | `scripts/release/` | `yarn cli release` |
46+
47+
## CODE MAP
48+
49+
### Entry Points
50+
51+
- `yarn cli` → `scripts/cli/index.ts` (main CLI)
52+
- `yarn cli generate [lang] [clients]` → Code generation
53+
- `yarn cli build clients|specs|snippets` → Build artifacts
54+
- `yarn cli cts generate|run` → Common Test Suite
55+
56+
### Key Files
57+
58+
| File | Purpose |
59+
| ------------------------------ | -------------------------------------------- |
60+
| `config/clients.config.json` | All language/client definitions |
61+
| `config/generation.config.mjs` | Which files are generated vs hand-written |
62+
| `openapitools.json` | OpenAPI Generator config (auto-generated) |
63+
| `scripts/common.ts` | Shared utilities (run, toAbsolutePath, etc.) |
64+
| `scripts/buildLanguages.ts` | Language build orchestration |
65+
66+
## CONVENTIONS
67+
68+
### Commit Messages
69+
70+
```
71+
type(scope): description
72+
```
73+
74+
Types: `fix`, `feat`, `refactor`, `docs`, `chore`
75+
Scopes: `specs`, `javascript`, `python`, language names, or `deps`
76+
77+
### Generated vs Hand-Written
78+
79+
- Check `config/generation.config.mjs` for exact patterns
80+
- **Hand-written** (safe to edit): all files mentioned in `config/generation.config.mjs` that START with `!`
81+
- **Generated** (DO NOT EDIT): all files mentioned in `config/generation.config.mjs` that DON'T START with `!`, or all non-mentioned files in generated client folders
82+
83+
Be careful to check for glob patterns!
84+
85+
### Code Generation Flow
86+
87+
1. Edit OpenAPI spec in `specs/{api}/`
88+
2. Run `yarn cli build specs` to bundle
89+
3. Run `yarn cli generate {language}` to regenerate
90+
4. Hand-written code in folders and files mentioned in `config/generation.config.mjs` is preserved
91+
92+
## ANTI-PATTERNS (THIS PROJECT)
93+
94+
- **NEVER** edit files in file not explicitly marked as hand-written in `config/generation.config.mjs` because they will be overwritten at generation time
95+
- **NEVER** use `as any` or `@ts-ignore` in scripts/
96+
- **NEVER** commit without running `yarn cli format {language} {folder}`
97+
- **NEVER** manually edit `openapitools.json` - it's auto-generated
98+
- **NEVER** bypass pre-commit hooks as they ensure consistency, formatting, code quality
99+
- **DO NOT** add language-specific logic to `scripts/` - use templates instead
100+
101+
## UNIQUE STYLES
102+
103+
### Multi-Build System
104+
105+
- **Node.js/TypeScript**: Scripts, CLI, website, ESLint plugin (`yarn`)
106+
- **Java/Gradle**: Custom OpenAPI generators (`./gradlew build` in `generators/`)
107+
- **Docker**: Language-specific builds via `yarn docker:setup`
108+
109+
### Language Version Files
110+
111+
All in `config/`: `.java-version`, `.python-version`, `.ruby-version`, `.go-version`, `.swift-version`, `.php-version`, `.dart-version`, `.csharp-version`
112+
113+
### Protected Files Pattern
114+
115+
Files in `.openapi-generator-ignore` and negated patterns in `generation.config.mjs` are hand-written and NOT overwritten during generation.
116+
117+
## COMMANDS
118+
119+
```bash
120+
# Setup
121+
nvm use && yarn # Install dependencies
122+
yarn docker:setup # Setup Docker environment
123+
124+
# Generation
125+
yarn cli generate javascript # Generate all JS clients
126+
yarn cli generate python search # Generate Python search client
127+
yarn cli build specs # Bundle OpenAPI specs
128+
yarn cli build specs --docs # Build specs with doc snippets
129+
130+
# Testing
131+
yarn cli cts generate [lang] # Generate CTS tests
132+
yarn cli cts run [lang] # Run CTS tests
133+
yarn cli playground {lang} {client} # Run interactive playground
134+
135+
# Formatting
136+
yarn cli format {language} {folder}
137+
138+
# Release
139+
yarn cli release # Create release PR
140+
yarn cli release --dry-run # Test release without pushing
141+
```
142+
143+
## NOTES
144+
145+
### Docker Required
146+
147+
Most language builds require Docker. Run `yarn docker:setup` first. Images: `apic_base` (most languages), `apic_ruby`, `apic_swift`.
148+
149+
### CI Matrix
150+
151+
CI runs parallel builds per language. Dynamic matrix generated from git diff - only changed clients rebuild. See `.github/workflows/check.yml`.

‎clients/AGENTS.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# CLIENTS KNOWLEDGE BASE
2+
3+
## OVERVIEW
4+
5+
Generated API clients for 11 languages. Most code is auto-generated - only edit hand-written directories.
6+
7+
**Each client has its own AGENTS.md** with language-specific conventions, patterns, and gotchas. See the per-language file for detailed guidance.
8+
9+
## STRUCTURE
10+
11+
```
12+
clients/
13+
├── algoliasearch-client-javascript/ # TypeScript/JavaScript (monorepo) → See AGENTS.md
14+
├── algoliasearch-client-python/ # Python (Poetry) → See AGENTS.md
15+
├── algoliasearch-client-java/ # Java (Gradle) → See AGENTS.md
16+
├── algoliasearch-client-go/ # Go (modules) → See AGENTS.md
17+
├── algoliasearch-client-ruby/ # Ruby (Bundler) → See AGENTS.md
18+
├── algoliasearch-client-php/ # PHP (Composer) → See AGENTS.md
19+
├── algoliasearch-client-kotlin/ # Kotlin (Gradle, multiplatform) → See AGENTS.md
20+
├── algoliasearch-client-scala/ # Scala (SBT) → See AGENTS.md
21+
├── algoliasearch-client-swift/ # Swift (SPM) → See AGENTS.md
22+
├── algoliasearch-client-dart/ # Dart (Pub/Melos) → See AGENTS.md
23+
└── algoliasearch-client-csharp/ # C# (.NET) → See AGENTS.md
24+
```
25+
26+
## GENERATED VS HAND-WRITTEN
27+
28+
**Before editing any file in `clients/`, verify it's not auto-generated.**
29+
30+
Check `config/generation.config.mjs` for glob patterns:
31+
32+
- Patterns **without** `!` prefix → **generated** (DO NOT EDIT - will be overwritten)
33+
- Patterns **with** `!` prefix → **hand-written** (safe to edit)
34+
35+
Example from the config:
36+
37+
```javascript
38+
'clients/algoliasearch-client-go/algolia/**', // Generated
39+
'!clients/algoliasearch-client-go/algolia/transport/**', // Hand-written (safe)
40+
```
41+
42+
When in doubt, check the config file before making changes.
43+
44+
## WHERE TO LOOK
45+
46+
| Task | Location | Notes |
47+
| ----------------------- | ----------------------------------------------------- | ------------------- |
48+
| Fix transport/HTTP bug | Check `config/generation.config.mjs` for `!` patterns | Hand-written code |
49+
| Fix model serialization | `templates/{lang}/model.mustache` | Regenerate after |
50+
| Add API method | `specs/{api}/paths/` then regenerate | Via code generation |
51+
| Add client helper | `templates/{lang}/*.mustache` | Regenerate after |
52+
53+
## CONVENTIONS
54+
55+
### Package Versions
56+
57+
Defined in `config/clients.config.json`. Updated during release.
58+
59+
### Client APIs (All Languages)
60+
61+
Each client has consistent API structure:
62+
63+
- Constructor with `appId`, `apiKey`, optional config
64+
- Method per API operation (named from `operationId`)
65+
- Async variants where applicable
66+
- Request options parameter for overrides
67+
68+
### Testing
69+
70+
- CTS (Common Test Suite) in `tests/output/{lang}/`
71+
- E2E tests require credentials in `.env`
72+
- Run: `yarn cli cts run {lang}`
73+
74+
## ANTI-PATTERNS
75+
76+
- **NEVER** manually edit generated directories
77+
- **NEVER** commit without regenerating after spec changes
78+
- **DO NOT** add language-specific API logic - use templates
79+
- **DO NOT** bypass transport layer for HTTP calls
80+
81+
## COMMANDS
82+
83+
```bash
84+
# Generate
85+
yarn cli generate javascript # All JS clients
86+
yarn cli generate python search # Python search only
87+
88+
# Build
89+
yarn cli build clients javascript # Build JS clients
90+
yarn cli build playground go search # Build Go playground
91+
92+
# Test
93+
yarn cli cts run javascript # Run JS CTS tests
94+
yarn cli playground python search # Interactive playground
95+
96+
# Format
97+
yarn cli format javascript clients/algoliasearch-client-javascript
98+
```

0 commit comments

Comments
 (0)