Skip to content

Commit d5da10b

Browse files
georgewfrasergeorgewfraser
committed
docs: add repository agent guidance
1 parent 85fbb42 commit d5da10b

1 file changed

Lines changed: 129 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# AGENTS
2+
3+
## Purpose
4+
5+
This repository contains a Java language server and a VS Code extension that packages and launches it.
6+
7+
- Java server code lives under `src/main/java/org/javacs`.
8+
- VS Code extension code lives under `lib`.
9+
- JUnit tests live under `src/test/java`.
10+
- Test workspaces and fixtures live under `src/test/examples`.
11+
12+
When making changes, optimize for the behavior users see through the language server protocol rather than for internal structure.
13+
14+
## Product Goals
15+
16+
The primary goal of this project is robustness.
17+
18+
- The language server should be able to drop into a Java project with little or no manual configuration and figure out the project structure.
19+
- When a feature conflicts with robustness, prefer the more robust behavior.
20+
- Prefer degraded functionality over fragile behavior, crashes, or incorrect results.
21+
- Avoid assumptions that only hold for a narrow set of build tools or project layouts unless the code has an explicit fallback.
22+
23+
## Environment
24+
25+
Use the repository's actual build scripts as the source of truth.
26+
27+
- Maven, npm, and `protoc` are required for normal development.
28+
- Run `./configure` once per clone to install the repository git hook.
29+
- `scripts/build.sh` bundles JDK 21 runtimes and is the authoritative packaging path.
30+
- `README.md` still mentions Java 18 for local setup. Treat that as stale documentation until it is reconciled.
31+
32+
## Repo Map
33+
34+
Important source areas:
35+
36+
- `src/main/java/org/javacs/completion`: completions and signature help support.
37+
- `src/main/java/org/javacs/navigation`: go-to-definition and references.
38+
- `src/main/java/org/javacs/hover`: hover and documentation lookup.
39+
- `src/main/java/org/javacs/rewrite`: code actions and refactorings.
40+
- `src/main/java/org/javacs/debug`: debug adapter support.
41+
- `src/main/java/org/javacs/lsp`: protocol types and transport helpers.
42+
- `lib`: VS Code extension entry points and editor integration.
43+
- `src/test/java/org/javacs/LanguageServerFixture.java`: common server test harness.
44+
- `src/test/java/org/javacs/lsp`: protocol-level tests.
45+
- `src/test/examples`: workspace fixtures used by end-to-end tests.
46+
47+
## Code Style
48+
49+
Prefer simple, procedural code.
50+
51+
- Use straightforward control flow, explicit loops, and local variables.
52+
- Avoid functional-style pipelines, stream-heavy code, callback-heavy code, and clever abstractions when a direct procedural implementation is clearer.
53+
- Keep data flow easy to trace in a debugger.
54+
- Write code that is easy to refactor without hidden coupling.
55+
- Favor small, explicit helper methods over dense abstractions.
56+
57+
## Testing Philosophy
58+
59+
Prefer end-to-end tests that exercise behavior through the LSP interface.
60+
61+
- Most tests should validate externally visible behavior through the language server interface.
62+
- Tests should be resilient to internal refactors and avoid coupling to implementation details.
63+
- When fixing a user-visible bug, prefer an LSP-level regression test.
64+
- True unit tests should be rare.
65+
- Add a unit test only when the behavior cannot be tested reasonably through the LSP interface, or when the isolated case would be impractical to cover end-to-end.
66+
67+
Use the existing test harness where possible:
68+
69+
- `src/test/java/org/javacs/LanguageServerFixture.java`
70+
- `src/test/java/org/javacs/lsp`
71+
72+
## Build And Validation
73+
74+
Choose the narrowest command set that covers the change, then report exactly what was run.
75+
76+
- Java-only changes: run `mvn test`.
77+
- VS Code extension changes: run `npm test`.
78+
- Cross-cutting Java and extension changes: run `mvn test` and `npm test`.
79+
- Packaging or release changes: use `./scripts/build.sh`.
80+
- Build a Java package without tests only when you specifically need the artifact: `mvn package -DskipTests`.
81+
82+
If a command fails because of an existing repo issue, capture that failure and report it clearly.
83+
84+
## Benchmarks
85+
86+
Performance matters, especially for core language-server operations.
87+
88+
- For code changes, run `./scripts/benchmark.sh` before and after the change and report the result or failure.
89+
- If the benchmark does not exercise the changed area well, say so explicitly.
90+
- Do not claim a performance improvement without benchmark output.
91+
- Treat benchmark failures as real signal to report, not as a step to skip silently.
92+
93+
Current limitation:
94+
95+
- `scripts/benchmark.sh` now runs `BenchmarkParser` and `BenchmarkPruner`, but coverage is still narrow and does not yet exercise completion, navigation, indexing, or incremental compilation.
96+
97+
## Generated And Derived Files
98+
99+
Do not hand-edit generated artifacts unless the task is explicitly about regenerating them.
100+
101+
- Protobuf sources live in `src/main/protobuf`.
102+
- Regenerate protobuf Java classes with `./scripts/gen_proto.sh`.
103+
- Generated protobuf Java files under `src/main/java/com/google/devtools/build/lib` should be treated as generated output.
104+
- Do not edit `out`, `target`, packaged JDKs under `jdks`, or packaged runtime trees under `dist` unless the task specifically requires it.
105+
- Do not edit `build.vsix` manually.
106+
107+
## Formatting
108+
109+
Formatting is partially automated, but verify the actual tooling before relying on it.
110+
111+
- `./configure` installs the repository pre-commit hook from `git_hooks/pre-commit`.
112+
- Java formatting in the hook uses `google-java-format` with AOSP style.
113+
- `scripts/format.sh` references an older formatter jar name than the jar currently checked into `git_hooks`. Treat the hook as the more reliable source of truth.
114+
115+
## Change Boundaries
116+
117+
Keep changes focused and avoid incidental churn.
118+
119+
- Do not rewrite working code into a different style without a concrete reason.
120+
- Do not introduce new configuration requirements if the same behavior can be inferred automatically.
121+
- Be careful when changing files in `src/test/examples`; they are part of the end-to-end test surface.
122+
- Preserve public protocol behavior unless the task explicitly requires a protocol-visible change.
123+
124+
## Known Gotchas
125+
126+
- The project spans Maven Java code and a VS Code extension; validate both sides when a change crosses that boundary.
127+
- `scripts/build.sh` installs the built VSIX into the local VS Code instance as part of packaging.
128+
- The forked Guava code under `src/main/java/org/javacs/guava` exists to avoid the external dependency and keep `jlink` working.
129+
- Benchmark coverage is currently narrow, and the benchmark script is currently failing; do not hide that fact in change reports.

0 commit comments

Comments
 (0)