Skip to content

Commit 5f75b1e

Browse files
OscarCookeAbbottOscarCookeAbbott
authored
Improve AGENTS.md (#860)
1 parent 13d23e8 commit 5f75b1e

File tree

1 file changed

+365
-16
lines changed

1 file changed

+365
-16
lines changed

‎AGENTS.md‎

Lines changed: 365 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,372 @@
1-
# Repository information
1+
# Atlaspack Agent Guide
22

3-
- This is a repository on GitHub and GitHub actions are used to trigger builds.
4-
- Github configuration is loaded in .github/.
5-
- Validate that the builds will pass on CI before completing tasks, .github/workflows/ci.yml contains the configuration for most builds - run these first.
6-
- This repository uses yarn as its package manager. Any commands you want to run, or dependencies to install, should be done using yarn.
3+
## Critical Rules ⚠️
74

8-
## Pull requests
5+
1. **Public Repository Warning**: This is a PUBLIC repository. Never include internal/sensitive Atlassian information in the project.
96

10-
- You can offer to write the pull request description using the template in .github/PULL_REQUEST_TEMPLATE.md. Do not delete headings or restructure the template.
11-
- Keep in mind that we are in a public repository that non-Atlassian employees can access.
12-
- Make sure you ask the developer before creating any pull requests and ensure they have reviewed the pull request description.
13-
- Each PR should have a changeset, which can be generated by running `yarn changeset`. Documentation can be found at https://github.com/changesets/changesets/tree/main/docs and configuration is in .changeset/.
14-
- You don't need a changeset if the change does not affect published packages.
15-
- You can create the pull request using the github cli (gh).
7+
2. **File Operations**:
8+
- Always read files before editing them
9+
- Always prefer editing existing files instead of creating new ones
10+
- Always use specialized tools (read_files, edit, write) instead of bash commands where possible
11+
- Never create documentation files unless directed
1612

17-
## Git
13+
3. **Communication Style**:
14+
- Always be concise and technical
15+
- Always output text directly to user, NOT via bash echo or comments
16+
- Always request more information when necessary
17+
- Never use emoji
1818

19-
- Do not push to the repository without confirmation from the developer.
19+
4. **Code Quality**:
20+
- Always run relevant tests for the area of code being modified
21+
- Always improve the test suite when fixing issues instead of just reading the code or using CLI
22+
- Always format files after editing using the relevant tool
23+
- Never use placeholders in code, always use real values or ask for them
2024

21-
## Rust
25+
5. **Git Safety**:
26+
- Never push or commit unless directed
27+
- Never update git config
28+
- Never force push to main/master
29+
- Never use interactive git commands (`-i` flag)
30+
- Never skip hooks (--no-verify, --no-gpg-sign)
31+
- Never run destructive git commands unless directed
32+
- Never create PRs unless directed
2233

23-
- When writing tests for Rust code, always put them in the same file as the code they are testing, using the #[cfg(test)] attribute.
34+
6. **Task Management**:
35+
- Always use the todo/task tool
36+
- Always mark todos/tasks as complete immediately after finishing them
37+
- Never work on multiple todos/tasks simultaneously
38+
39+
7. **When stuck**:
40+
- Check "Development Workflow Guide" section
41+
- Ask the developer for clarification
42+
- Review recent commits for context
43+
44+
## Project Overview
45+
46+
Atlaspack is a high-performance frontend bundler designed to build exceptionally large applications at Atlassian scale. It is written in JavaScript/TypeScript and Rust, forked from Parcel, and optimized for internal Atlassian product development. While publicly available, it is not intended for production use outside Atlassian.
47+
48+
### Core Architecture
49+
50+
Atlaspack follows a plugin-based architecture with these key components:
51+
52+
1. **Core Engine** - Orchestrates the build process through request tracking and caching
53+
2. **Asset Graph** - Dependency graph that tracks all assets and their relationships
54+
3. **Bundle Graph** - Determines how assets are grouped into output bundles
55+
4. **Plugin System** - Specialised and modular extensions
56+
- **Transformers**: Convert source files to Atlaspack-compatible format
57+
- **Resolvers**: Find dependencies and resolve import paths
58+
- **Bundlers**: Determine how assets are grouped into bundles
59+
- **Namers**: Generate output filenames
60+
- **Packagers**: Concatenate assets into final bundle files
61+
- **Optimizers**: Minify and optimize bundled code
62+
- **Reporters**: Report build progress and results
63+
- **Compressors**: Compress output files
64+
65+
### Project Structure
66+
67+
- Atlaspack uses the `yarn` package manager for JS/TS packages
68+
- Atlaspack uses Lerna for managing its multiple JS/TS packages
69+
- Atlaspack uses a Cargo workspace for Rust crates (defined in root `Cargo.toml`)
70+
71+
```
72+
packages/ # JavaScript/TypeScript packages
73+
├── core/ # Core Atlaspack packages
74+
├── transformers/ # Transformer plugins (JS, CSS, HTML, etc.)
75+
├── bundlers/ # Bundler plugins
76+
├── optimizers/ # Optimizer plugins (minifiers, etc.)
77+
├── packagers/ # Packager plugins
78+
├── resolvers/ # Module resolvers
79+
├── namers/ # Bundle naming strategies
80+
├── reporters/ # Build reporters (CLI, dev server, etc.)
81+
├── runtimes/ # Runtime code injected into bundles
82+
├── utils/ # Shared utilities
83+
├── dev/ # Development tools
84+
│ ├── atlaspack-inspector/ # Build inspector UI
85+
│ ├── query/ # Query tool for builds
86+
│ └── bundle-stats-cli/ # Bundle statistics
87+
└── examples/ # Example projects for testing
88+
crates/ # Rust crates (Cargo workspace)
89+
├── atlaspack/ # Main Atlaspack crate
90+
├── atlaspack_core/ # Core types and asset graph
91+
├── atlaspack_config/ # Configuration handling
92+
├── atlaspack_filesystem/ # FS operations
93+
├── atlaspack_sourcemap/ # Source map handling
94+
├── atlaspack_monitoring/ # Sentry integration for crash reporting
95+
├── atlaspack_plugin_transformer_js/ # SWC-based JS transformer
96+
├── atlaspack_plugin_transformer_css/ # Lightning CSS transformer
97+
├── atlaspack_plugin_transformer_html/ # HTML parser/transformer
98+
├── atlaspack_plugin_transformer_image/ # Image optimization
99+
├── atlaspack_plugin_resolver/ # Module resolver
100+
├── atlaspack_plugin_rpc/ # Plugin RPC communication
101+
├── atlaspack_swc_runner/ # SWC runner utilities
102+
├── lmdb-js-lite/ # LMDB bindings for caching
103+
├── node-bindings/ # N-API bindings for Node.js
104+
└── ... # Other crates (VCS, macros, etc.)
105+
docs/ # Documentation
106+
.github/ # GitHub Actions CI
107+
└── workflows/ci.yml # Main CI configuration
108+
scripts/ # Build and utility scripts
109+
```
110+
111+
### Language Split: JavaScript/TypeScript and Rust
112+
113+
Atlaspack is a **hybrid codebase**:
114+
115+
- **JavaScript/TypeScript**:
116+
- Core orchestration
117+
- Plugin coordination
118+
- Configuration
119+
- Some plugin implementations
120+
- Rust: Performance-critical operations including:
121+
- Core orchestration (feature gated)
122+
- JavaScript transformation (SWC-based, in `packages/transformers/js/core/`)
123+
- CSS transformation (Lightning CSS)
124+
- HTML parsing and transformation
125+
- Image optimization
126+
- Resolver logic
127+
- Native LMDB bindings for caching
128+
129+
Atlaspack aims to eventually become a fully native Rust bundler.
130+
131+
### Build Modes
132+
133+
- **Development**: Fast rebuilds, no scope hoisting, includes debugging info
134+
- **Production**: Scope hoisting enabled, minification, tree shaking, optimizations
135+
136+
## Development Workflow Guide
137+
138+
This section consolidates all workflow commands and patterns for development. Refer to this section for any build, test, or deployment workflow questions.
139+
140+
### Building
141+
142+
When to rebuild:
143+
144+
- Full rebuild required for using Atlaspack for actual local bundling after any code changes
145+
- Native rebuild required after altering Rust code
146+
- JS build not required for running integration tests
147+
148+
Native (Rust) artifacts:
149+
150+
```bash
151+
yarn build-native # Development build (faster)
152+
yarn build-native-release # Release build (optimized, slower)
153+
yarn build-native-wasm # WASM build
154+
```
155+
156+
Build artifacts are stored in `packages/` as platform-specific native modules (`.node` files) and used by the JavaScript runtime.
157+
158+
JavaScript/TypeScript:
159+
160+
```bash
161+
yarn build # Build everything (clean, prepare, gulp, TypeScript)
162+
yarn build:ts # Type check TypeScript only
163+
```
164+
165+
### Testing
166+
167+
- Tests should be run for the modified region
168+
- Always run tests from project root
169+
- `cargo nextest` should be used instead of `cargo test` if installed
170+
171+
```bash
172+
# Unit tests (fast - use during active development):
173+
yarn test:js:unit # All JS/TS unit tests
174+
cargo test # All Rust unit tests
175+
cargo test -p atlaspack_core # Specific Rust package tests
176+
yarn test:unit # All unit tests
177+
178+
# Integration tests (slower - only run affected area):
179+
yarn test:integration # Full integration test suite
180+
yarn test:integration-ci # CI mode (includes retries)
181+
yarn test:integration:v3 # V3 experimental features
182+
183+
# E2E tests (slowest - only use in CI):
184+
yarn test:e2e # End-to-end tests with real builds
185+
186+
# All tests (extremely slow - only use in CI):
187+
yarn test # Runs unit + integration
188+
189+
# Specific package tests:
190+
yarn workspace @atlaspack/integration-tests test
191+
yarn workspace @atlaspack/inspector test:unit
192+
yarn workspace @atlaspack/inspector test:e2e
193+
194+
# Run a single test:
195+
yarn test:js:unit --grep "test name pattern" # JS unit test
196+
yarn test:integration --grep "test name pattern" # JS integration test
197+
cargo test test_name # Rust unit test (all packages)
198+
cargo test -p atlaspack_core test_name # Rust unit test (specific package - check Cargo.toml for exact name)
199+
cargo test --lib module::tests::test_name # Rust unit test (by module path)
200+
cargo test --test integration_test_name # Rust integration test
201+
202+
# Clean test cache if tests behave unexpectedly:
203+
yarn clean-test
204+
```
205+
206+
**When tests fail:**
207+
208+
1. Read the error message carefully
209+
2. Check if you need to fully rebuild: `yarn build-native && yarn build`
210+
3. Clean cache if tests behave unexpectedly: `yarn clean-test`
211+
4. Use `ATLASPACK_MOCHA_HANG_DEBUG=true` for hanging tests
212+
5. Check recent commits - tests may be flaky
213+
6. Do not mark task as completed
214+
7. Create new task describing what needs resolution
215+
8. Fix the issue before moving on
216+
217+
### Linting and Formatting Workflow
218+
219+
Perform file linting and formatting before completing any task, using tools and/or the following commands:
220+
221+
```bash
222+
# Lint all code:
223+
yarn lint # Runs ESLint and Prettier
224+
225+
# Format all code:
226+
yarn format # Format JS + Rust
227+
228+
# Rust linting:
229+
cargo fmt --all -- --check # Check Rust formatting
230+
cargo clippy -- -D warnings # Rust linting
231+
232+
# Other checks:
233+
yarn build:ts # Type check TypeScript
234+
yarn lint:feature-flags # Check for unused feature flags
235+
```
236+
237+
## Git and CI
238+
239+
CI configuration: `.github/workflows/ci.yml`
240+
241+
### Git Workflow
242+
243+
- Main branch: `main`
244+
- Always write concise git messages that focus on "why" not "what"
245+
- Never push to the repository unless directed
246+
- Never use interactive git commands (`-i` flag)
247+
- Never commit 'amended' unless directed
248+
249+
### Pull Requests
250+
251+
- Never create a PR unless directed
252+
- Always get developer approval of the PR title and description
253+
- Always use the template in `.github/PULL_REQUEST_TEMPLATE.md`
254+
- Each PR requires a **changeset** via `yarn changeset` if it affects published packages
255+
- Add to PR description: `<!-- [no-changeset]: Explanation why -->` if no changeset needed
256+
- This is a **public repository** - Never include internal/sensitive information **anywhere**
257+
- Create PRs using GitHub CLI: `gh pr create`
258+
259+
## Project Systems
260+
261+
### Transformers
262+
263+
Transformers are given code and output modified code.
264+
265+
**Execution flow**:
266+
267+
1. Core requests asset transformation
268+
2. Config selects transformer based on file type
269+
3. Transformer runs (in worker pool if multi-threaded)
270+
4. Results cached in LMDB
271+
5. Asset graph updated with transformed assets and dependencies
272+
273+
**JavaScript Transformer** (`packages/transformers/js/`):
274+
275+
- Most complex transformer, combines TypeScript orchestration with Rust (SWC-based) transformation
276+
- Handles: TypeScript, JSX, dependency collection, scope hoisting, tree shaking
277+
- Pipeline: Parse → SWC visitors → Atlaspack transforms (env vars, globals, fs inlining) → Code generation
278+
- In production: Enables scope hoisting (concatenates modules into single scope like Rollup)
279+
- Location: `src/JSTransformer.ts` (orchestration), `core/src/` (Rust implementation)
280+
281+
**vs Babel/Webpack**:
282+
283+
- Babel: Sequential AST transforms, JS-based, transpiler only
284+
- Webpack loaders: Sequential chain, single input→output
285+
- Atlaspack: Parallel where possible, Rust-based (faster), can return multiple assets, integrated caching
286+
287+
**Notes**:
288+
289+
- Atlaspack transformers are often orchestrated with other transformers in Babel and the like. In such cases the project's native transformers typically run after external transformers.
290+
291+
### Scope Hoisting and Tree Shaking
292+
293+
Symbols: Atlaspack tracks imported and exported symbols for each asset.
294+
295+
Tree shaking process:
296+
297+
1. **Symbol Collection**: During transformation, collect all exports
298+
2. **Symbol Propagation**: Determine which symbols are actually used
299+
3. **Dead Code Elimination**: Remove unused exports and their dependencies
300+
4. **Scope Hoisting**: Concatenate modules into single scope in production
301+
302+
Deferring: Assets can be "deferred" (not transformed) if their exports aren't used. This speeds up builds significantly for large libraries where only a subset is imported.
303+
304+
See `docs/Scopehoisting.md` and `docs/Symbol Propagation.md` for details.
305+
306+
### Conditional Bundling
307+
308+
Atlaspack supports **conditional imports** executed at **runtime**:
309+
310+
```javascript
311+
import { foo } from importCond('cond', './a', './b');
312+
```
313+
314+
Configuration lives in `@atlaspack/conditional-import-types`.
315+
316+
See `docs/features/Conditional Bundling.md` for implementation details.
317+
318+
### Caching System
319+
320+
- **LMDB-based**: Fast key-value store (Rust bindings in `crates/lmdb-js-lite/`)
321+
- **Request Tracker**: Tracks all build requests and dependencies
322+
- **Invalidation**: Based on file changes, config changes, and plugin changes
323+
- **Location**: `.parcel-cache/` in project root (usually gitignored)
324+
325+
### Monitoring and Crash Reporting
326+
327+
Sentry Integration (`crates/atlaspack_monitoring/`):
328+
329+
- Crash reporting for Rust panics
330+
- Performance tracing
331+
- Configured via environment variables for Atlassian products
332+
333+
Tracing:
334+
335+
- Chrome tracing format support
336+
- Enable with profiler API or reporter
337+
338+
### Additional Tools & Utilities
339+
340+
**Inspector** (`packages/dev/atlaspack-inspector/`):
341+
342+
- Debug tool for inspecting builds, bundle graphs, and cache
343+
- Web-based UI for visualizing the build process
344+
- Useful for understanding why certain bundles were created
345+
346+
**Examples** (`packages/examples/`):
347+
348+
- `kitchen-sink/` - Comprehensive example with many features
349+
- Use these to test changes: `cd packages/examples/kitchen-sink && yarn start`
350+
351+
**Query Tool** (`packages/dev/query/`):
352+
353+
- CLI tool for querying build information
354+
- Useful for inspecting deep imports and dependency trees
355+
356+
## Feature Flags
357+
358+
Atlaspack uses runtime and compile-time feature flags for gradual rollouts:
359+
360+
**Location**: `@atlaspack/feature-flags` package
361+
362+
**Usage**:
363+
364+
```typescript
365+
import {getFeatureFlag} from '@atlaspack/feature-flags';
366+
367+
if (getFeatureFlag('myNewFeature')) {
368+
// New code path
369+
}
370+
```
371+
372+
**Linting**: Run `yarn lint:feature-flags` to find unused flags.

0 commit comments

Comments
 (0)