|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Instructions for LLM agents and human contributors working on this project. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +AdGuard Filters Compiler — a Node.js library that compiles ad-blocking filter |
| 8 | +lists into platform-specific formats. It is consumed by [FiltersRegistry] |
| 9 | +to produce production filter builds for AdGuard products across all supported |
| 10 | +platforms (extensions and apps). |
| 11 | + |
| 12 | +## Technical Context |
| 13 | + |
| 14 | +- **Language**: JavaScript (ES2022 modules), Node.js 22 |
| 15 | +- **Package Manager**: pnpm 10.7 |
| 16 | +- **Bundler**: Rollup (dual ESM + CJS output) |
| 17 | +- **Testing**: Vitest (node environment) |
| 18 | +- **Linting**: ESLint with airbnb-base config |
| 19 | +- **Target Platform**: Node.js (library) |
| 20 | +- **Project Type**: Single package |
| 21 | +- **Key Dependencies**: |
| 22 | + - `@adguard/agtree` |
| 23 | + - `@adguard/tsurlfilter` |
| 24 | + - `@adguard/scriptlets` |
| 25 | + - `@adguard/filters-downloader` |
| 26 | + |
| 27 | +## Project Structure |
| 28 | + |
| 29 | +```text |
| 30 | +├── src/ |
| 31 | +│ ├── index.js # Library entry point (compile, validateJSONSchema, validateLocales) |
| 32 | +│ └── main/ |
| 33 | +│ ├── builder.js # Core filter compilation logic |
| 34 | +│ ├── converter.js # Rule format conversion |
| 35 | +│ ├── validator.js # Filter rule validation |
| 36 | +│ ├── optimization.js # Filter list optimization |
| 37 | +│ ├── platforms-config.js # Platform definitions and configuration |
| 38 | +│ ├── json-validator.js # JSON schema validation for built filters |
| 39 | +│ ├── locales-validator.js # Locales validation |
| 40 | +│ ├── platforms/ |
| 41 | +│ │ ├── generator.js # Platform-specific filter generation |
| 42 | +│ │ └── filter.js # Platform filter processing |
| 43 | +│ ├── rule/ |
| 44 | +│ │ └── rule-masks.js # Rule mask constants |
| 45 | +│ └── utils/ |
| 46 | +│ ├── log.js # Logger utility |
| 47 | +│ ├── report.js # Compilation report generation |
| 48 | +│ ├── builder-utils.js # Builder helper functions |
| 49 | +│ ├── extended-css-validator.js # Extended CSS validation |
| 50 | +│ ├── version.js # Version utilities |
| 51 | +│ ├── webutils.js # Web-related utilities |
| 52 | +│ ├── workaround.js # Platform-specific workarounds |
| 53 | +│ ├── utils.js # General utilities |
| 54 | +│ └── trust-levels/ # Trust-level exclusion files (low, high, full) |
| 55 | +├── test/ # Test files (Vitest) |
| 56 | +│ ├── resources/ # Test fixtures and filter data |
| 57 | +│ └── utils/ # Test utilities |
| 58 | +├── schemas/ # JSON schemas for validating built filters |
| 59 | +│ ├── filters.schema.json # Filters metadata schema |
| 60 | +│ ├── filters_i18n.schema.json # Filters i18n metadata schema |
| 61 | +│ ├── mac/ # Legacy macOS v1 schemas (do not modify) |
| 62 | +│ └── mac_v2/ # macOS v2 schemas (do not modify) |
| 63 | +├── tasks/ |
| 64 | +│ ├── build-schemas/ # Schema generation scripts |
| 65 | +│ └── build-txt.mjs # Build version text file |
| 66 | +├── bamboo-specs/ # Bamboo CI/CD pipeline definitions |
| 67 | +├── index.js # Development entry point (unbundled) |
| 68 | +├── package.json # Project metadata and scripts |
| 69 | +├── rollup.config.js # Rollup bundler configuration |
| 70 | +├── vitest.config.js # Vitest test configuration |
| 71 | +├── AGENTS.md # AI agent instructions (this file) |
| 72 | +├── DEVELOPMENT.md # Development environment setup guide |
| 73 | +├── README.md # Project overview and usage documentation |
| 74 | +└── CHANGELOG.md # Version history |
| 75 | +``` |
| 76 | + |
| 77 | +## Build And Test Commands |
| 78 | + |
| 79 | +| Command | Description | |
| 80 | +| ------- | ----------- | |
| 81 | +| `pnpm install` | Install dependencies | |
| 82 | +| `pnpm build` | Build the library (Rollup → `dist/`) | |
| 83 | +| `pnpm test` | Run all tests (Vitest) | |
| 84 | +| `pnpm lint` | Run ESLint | |
| 85 | +| `pnpm build-schemas` | Regenerate JSON schemas from `tasks/build-schemas/` | |
| 86 | +| `pnpm build-txt` | Generate `dist/build.txt` with version info | |
| 87 | +| `pnpm increment` | Bump patch version (`package.json`) | |
| 88 | +| `pnpm tgz` | Pack release tarball (`filters-compiler.tgz`) | |
| 89 | + |
| 90 | +## Contribution Instructions |
| 91 | + |
| 92 | +You MUST follow the following rules for EVERY task that you perform: |
| 93 | + |
| 94 | +- You MUST run `pnpm lint` and `pnpm test` before completing a task. Both are |
| 95 | + enforced by Husky pre-commit hook. |
| 96 | + |
| 97 | +- When the task changes code in `src/`, update `CHANGELOG.md` in the |
| 98 | + `Unreleased` section. Add entries to the appropriate subsection (`Added`, |
| 99 | + `Changed`, or `Fixed`); do not create duplicate subsections. |
| 100 | + Documentation-only changes (e.g., `AGENTS.md`, `DEVELOPMENT.md`, `README.md`) |
| 101 | + do NOT belong in the changelog. |
| 102 | + |
| 103 | +- **Never edit JSON schemas in `schemas/` manually.** Edit the generation |
| 104 | + scripts in `tasks/build-schemas/` and run `pnpm build-schemas` to regenerate. |
| 105 | + |
| 106 | +- Legacy schemas in `schemas/mac/` and `schemas/mac_v2/` must not be changed. |
| 107 | + |
| 108 | +- No new metadata fields should be added for old `mac` and current `mac_v2` |
| 109 | + platforms — see `src/main/platforms/generator.js` for details. |
| 110 | + |
| 111 | +- When updating scriptlets/redirects support, update `@adguard/tsurlfilter` |
| 112 | + (which bundles updated `@adguard/scriptlets`). For fixing scriptlets |
| 113 | + converting or validation, update `@adguard/scriptlets` directly. |
| 114 | + |
| 115 | +## Code Guidelines |
| 116 | + |
| 117 | +### I. Style |
| 118 | + |
| 119 | +Follow the [AdGuard JavaScript Code Guidelines][code-guidelines] for |
| 120 | +conventions not covered by the linter. |
| 121 | + |
| 122 | +[code-guidelines]: https://github.com/AdguardTeam/CodeGuidelines/blob/master/JavaScript/Javascript.md |
| 123 | + |
| 124 | +1. **ES module syntax** (`import`/`export`). The project uses |
| 125 | + `"type": "module"` in `package.json`. |
| 126 | + |
| 127 | +2. **ESLint airbnb-base** rules apply. Run `pnpm lint` to check. |
| 128 | + |
| 129 | +### II. Architecture |
| 130 | + |
| 131 | +1. **Dual output format.** Rollup produces both ESM (`dist/index.js`) and CJS |
| 132 | + (`dist/index.cjs`). The library is consumed via `@adguard/filters-compiler` |
| 133 | + by [FiltersRegistry]. |
| 134 | + |
| 135 | +2. **Schemas are copied to `dist/`.** Rollup copies `schemas/*` and |
| 136 | + `src/main/utils/trust-levels/*` into `dist/` at build time. |
| 137 | + |
| 138 | +3. **Three public API functions** are exported from `src/index.js`: |
| 139 | + `compile`, `validateJSONSchema`, `validateLocales`. |
| 140 | + |
| 141 | +### III. Testing |
| 142 | + |
| 143 | +1. **Vitest** with node environment. Test files are in `test/*.test.js`. |
| 144 | + |
| 145 | +2. **Test resources** are in `test/resources/` (filter files, platform configs, |
| 146 | + expected outputs). Some resources are gitignored (generated during tests). |
| 147 | + |
| 148 | +[FiltersRegistry]: https://github.com/AdguardTeam/FiltersRegistry/ |
0 commit comments