Skip to content

Commit a7cb6e9

Browse files
CopilotCopilot
authored
Add AGENTS.md with project architecture and contributor guidance (#1103)
1 parent b9d6bb8 commit a7cb6e9

1 file changed

Lines changed: 192 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# AGENTS.md – TypeScript Generator Developer Guide
2+
3+
This file describes the project architecture, module layout, technologies, and workflow conventions for AI agents and human contributors working on this repository.
4+
5+
---
6+
7+
## Project Overview
8+
9+
**typescript-generator** is a Java tool that generates TypeScript definition files (`.d.ts`) from Java classes that are serialized as JSON. It works by analyzing compiled Java bytecode (via reflection/ClassGraph), building an internal model, and emitting TypeScript interfaces and types. It supports multiple JSON libraries (Jackson 2 & 3, Gson, JSON-B) and multiple REST frameworks (JAX-RS, Spring Web MVC).
10+
11+
The tool is distributed in two forms:
12+
- **Maven plugin** – integrated into a Maven build via the `generate` goal.
13+
- **Gradle plugin** – integrated into a Gradle build via the `generateTypeScript` task.
14+
15+
---
16+
17+
## Base Technologies
18+
19+
| Technology | Version | Purpose |
20+
|---|---|---|
21+
| Java | 17 | Language and compilation target |
22+
| Maven | 3.9+ | Primary build tool and plugin distribution |
23+
| Gradle | 8.x (wrapper) | Alternative build tool and plugin distribution |
24+
| Jackson | 2.x / 3.x | JSON serialization library support (both versions) |
25+
| Spring Boot | 4.x | Spring REST framework support |
26+
| Jakarta APIs | 4.x+ | JAX-RS, JSON-B, JAXB support |
27+
| JUnit | 5 (Jupiter) | Testing framework |
28+
| Kotlin | 2.x | JVM interop and Kotlin-class generation support |
29+
| Spotless | 3.x | Code formatting (Eclipse formatter) |
30+
31+
---
32+
33+
## Repository Layout
34+
35+
```
36+
typescript-generator/
37+
├── typescript-generator-core/ # Core generation engine (JAR)
38+
├── typescript-generator-maven-plugin/ # Maven plugin wrapper
39+
├── typescript-generator-gradle-plugin/ # Gradle plugin wrapper
40+
├── typescript-generator-spring/ # Spring framework support (JAR)
41+
├── sample-maven/ # Example: Maven + Jackson
42+
├── sample-gradle/ # Example: Gradle + Jackson
43+
├── sample-maven-spring/ # Example: Maven + Spring
44+
├── sample-gradle-spring/ # Example: Gradle + Spring
45+
├── build/ # Release scripts and docs
46+
├── .github/workflows/ # GitHub Actions CI/CD
47+
├── eclipse-formatter-typescript-generator.xml # Code style config
48+
├── pom.xml # Parent Maven POM
49+
└── README.md # User-facing documentation
50+
```
51+
52+
---
53+
54+
## Module Descriptions
55+
56+
### `typescript-generator-core`
57+
58+
The central engine. Contains:
59+
- **`TypeScriptGenerator`** – main public API entry point.
60+
- **`Settings`** – all configuration parameters.
61+
- **`parser/`** – library-specific model parsers (`Jackson2Parser`, `Jackson3Parser`, `GsonParser`, `JsonbParser`, `RestApplicationParser`).
62+
- **`compiler/`** – transforms the Java model into a TypeScript model (`TsModel`).
63+
- **`emitter/`** – renders the TypeScript model as `.d.ts` text, `info.json`, or `package.json`.
64+
- **`ext/`** – extension / customisation hooks.
65+
- **`type/`** – Java type abstractions for generics, wildcards, and nullability.
66+
67+
### `typescript-generator-maven-plugin`
68+
69+
Thin Maven Mojo wrapper around the core. Accepts configuration as XML inside `<configuration>`. The main goal is `generate`, bound to the `process-classes` lifecycle phase.
70+
71+
### `typescript-generator-gradle-plugin`
72+
73+
Gradle plugin (ID: `cz.habarta.typescript-generator`). Exposes the `generateTypeScript` task. Supports both Groovy and Kotlin DSLs.
74+
75+
### `typescript-generator-spring`
76+
77+
Optional add-on module that adds support for generating typed HTTP clients from Spring `@RestController` / `@RequestMapping` annotations. Depends on `typescript-generator-core`.
78+
79+
---
80+
81+
## Three-Stage Architecture
82+
83+
```
84+
ModelParser → ModelCompiler → Emitter
85+
↓ ↓
86+
TypeProcessor TypeProcessor
87+
```
88+
89+
1. **ModelParser** – Reads compiled Java classes via reflection/ClassGraph. Produces a library-agnostic `Model`. `TypeProcessor` implementations discover additional dependent types (e.g., following `List<Person>` to include `Person`).
90+
2. **ModelCompiler** – Maps Java types to TypeScript types (`int` → `number`, `List<T>` → `T[]`, etc.). Resolves generics. Produces a `TsModel`.
91+
3. **Emitter** – Serialises the `TsModel` to `.d.ts` output (or other output formats).
92+
93+
All three stages are pluggable via `TypeProcessor` implementations.
94+
95+
---
96+
97+
## Building the Project
98+
99+
The project is built with **Maven**. The parent POM is at the repository root. **Always run Maven commands from the repository root** unless you are working exclusively inside the Gradle plugin.
100+
101+
```bash
102+
# Build everything and run all tests
103+
mvn clean install
104+
105+
# Build without running tests
106+
mvn clean install -DskipTests
107+
108+
# Build a single module (e.g. core only)
109+
mvn -pl typescript-generator-core clean install
110+
```
111+
112+
For the Gradle plugin specifically:
113+
114+
```bash
115+
cd typescript-generator-gradle-plugin
116+
./gradlew build
117+
./gradlew test
118+
```
119+
120+
---
121+
122+
## Running Tests
123+
124+
```bash
125+
# All tests (Maven modules)
126+
mvn test
127+
128+
# Tests in a specific module
129+
mvn -pl typescript-generator-core test
130+
131+
# A specific test class
132+
mvn test -Dtest=Jackson2ParserTest
133+
```
134+
135+
Test classes live under `src/test/java/` inside each module. The project uses JUnit 5 (Jupiter).
136+
137+
---
138+
139+
## ⚠️ Code Formatting – IMPORTANT
140+
141+
The project enforces code style via **Spotless** (Eclipse formatter). **The CI build will fail if code is not properly formatted.**
142+
143+
Before committing or opening a pull request, always run:
144+
145+
```bash
146+
mvn spotless:apply
147+
```
148+
149+
Run this command from the **repository root**. Running it inside a single module subdirectory does not apply the formatting correctly across all modules.
150+
151+
To verify formatting without modifying files:
152+
153+
```bash
154+
mvn spotless:check
155+
```
156+
157+
The formatter configuration is in `eclipse-formatter-typescript-generator.xml`. Import this file into your IDE (IntelliJ IDEA or Eclipse) to keep formatting consistent while you edit.
158+
159+
Import ordering convention:
160+
- Normal imports come first (alphabetical).
161+
- Static imports come last.
162+
- Wildcard and module imports are **forbidden**.
163+
164+
---
165+
166+
## Dependency Policy
167+
168+
Do **not** add new dependencies without first opening an issue for discussion. The project deliberately keeps its dependency footprint small.
169+
170+
---
171+
172+
## Pull Request Guidelines
173+
174+
- Keep PRs small and focused on a single concern.
175+
- Run `mvn spotless:apply` before pushing (see above).
176+
- Make sure `mvn clean install` passes locally before opening a PR.
177+
- Do not remove or modify existing tests unless the test itself is the subject of the change.
178+
- The project targets Java 17 as the compilation baseline.
179+
180+
---
181+
182+
## CI / CD
183+
184+
| Workflow | Trigger | Purpose |
185+
|---|---|---|
186+
| Appveyor | Every push / PR | Runs `mvn clean install spotless:check` – **must pass before merging** |
187+
| `release.yml` | Manual dispatch | Builds, signs, and uploads to Maven Central |
188+
| `release-gradle-plugin.yml` | Manual dispatch | Publishes Gradle plugin to Gradle Plugin Portal |
189+
190+
Releases are signed with GPG. Credentials are stored as GitHub repository secrets.
191+
192+
---

0 commit comments

Comments
 (0)