From 303656a6c9bc6866e12ee2e7af79ee5841283df2 Mon Sep 17 00:00:00 2001 From: Nikolay Gagarinov Date: Fri, 4 Sep 2026 20:06:37 +0500 Subject: [PATCH] docs(agents): rename CLAUDE.md to AGENTS.md and rewrite it The dist/ notes described a committed bundle; it is gitignored and built by release.yml onto the release branch. Add the rollout mechanics of that branch, the circular make setup target and the three places pinning the fixture image name. Drop the rtk block: machine-specific tooling belongs in a global config, not in a shared repository. --- AGENTS.md | 42 +++++++++++++ CLAUDE.md | 184 +----------------------------------------------------- 2 files changed, 43 insertions(+), 183 deletions(-) create mode 100644 AGENTS.md mode change 100644 => 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..220f723 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# AGENTS.md + +## What this repo is + +A GitHub Action that runs the automated check of a Hexlet educational project inside the student's own repository: it pulls the project image, lays the student's code into it, runs the check through Docker Compose and reports the verdict back to the Hexlet API. + +The same check has a second runner for GitLab — `hexlethq/hexlet-project-source-ci`, which also publishes the project images this action pulls. + +## A push to `master` ships to every student + +Student workflows are pinned to `hexlet/project-action@release`, and the Hexlet monolith validates that exact string with the schema `^hexlet/project-action@release$`, so no project can stay on another ref. + +The `release` branch is built automatically: `test.yml` runs on every push to `master`, and a green run triggers `release.yml`, which runs `make build` and force-pushes `dist/` onto `release`. **Anything landing on `master` reaches every student of every project within minutes**, and the rollback is just as global: revert on `master` and wait for the next `release` build. + +- Changes land through a pull request, and the merge is a human's call. +- `release.yml` installs with `npm install`, so even a docs-only commit on `master` rebuilds the bundle against freshly resolved dependencies. A push to `master` that ships nothing does not exist. +- Without a green `test.yml` the `release` build never starts, so the merge ships nothing while looking successful. After a merge, check that `release` received a fresh `build: update dist` commit. + +## Commands + +Dependencies come from `make install`, and CI uses the same target. The rest of the targets live in the `Makefile`. + +**`make setup` installs nothing.** The target reads `setup: pull setup`, so make drops the circular dependency, runs `pull`, stops there and still exits 0. + +`make test` needs the fixture image that `make pull` fetches. A single file goes through jest directly: `npx jest __tests__/packageChecker.test.js`. + +The fixture image name `hexlet-project-source-ci_en` is pinned in three places that have to agree: `Makefile` (target `pull`), `server.js` (the API stub for `e2e`) and `__tests__/index.test.js` (the nock response). + +## Architecture + +- `dist/` is gitignored and stays out of git: `release.yml` builds it with `@vercel/ncc` and force-adds it onto the `release` branch. `action.yml` points at `dist/run-tests/index.js` and `dist/run-post-actions/index.js`. +- Two entry points in `bin/` are the two phases of the Action: `bin/run-tests.js` (main) and `bin/run-post-actions.js` (post — finishes the check and uploads artifacts). +- `src/index.js` holds the orchestration: `prepareProject()` pulls the image and extracts the project source, `check()` runs Compose, `runTests()` and `runPostActions()` talk to the Hexlet API. +- `src/routes.js` builds the API urls. `src/packageChecker.js` validates the package name of the student's project against the conventions of its language, reading `pyproject.toml`, `composer.json` or `package.json`. +- `check()` calls two fixed compose service names of the project — `app` for `make setup`, then `test` — and the exit code of `test` is the verdict. Both the fixed names and the flags carry `NOTE` comments in the code; read them before changing the commands. +- Tests stub the Hexlet API with a local Fastify server (`server.js`), fixtures live in `__fixtures__/`. +- Artifacts of the student's tests are collected from `/tmp/artifacts/*/**` and uploaded as the `test-results` artifact. The glob starts one level down, so a file lying directly in `tmp/artifacts/` never reaches the student. + +## Conventions + +- ES modules (`"type": "module"`): `import` and `export`. +- Biome holds the style — single quotes, no unused imports or variables. `make lint-fix` applies it. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 7dff646..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,183 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -A GitHub Action that automates testing of educational coding projects on Hexlet. It pulls a Docker image, extracts project source, runs tests via Docker Compose, and reports results back to the Hexlet API. - -## Commands - -```bash -make setup # Install dependencies and pull Docker images -make install # npm install only -make build # Bundle both entry points into dist/ using ncc -make test # Run Jest tests (with ACTIONS_RUNNER_DEBUG=1) -make lint # Biome lint check -make lint-fix # Biome lint auto-fix -``` - -To run a single test file: -```bash -npx jest __tests__/packageChecker.test.js -``` - -## Architecture - -Two entry points in `bin/` correspond to two GitHub Actions phases: -- `bin/run-tests.js` → main phase: reads action inputs, calls `runTests()` -- `bin/run-post-actions.js` → post phase: calls `runPostActions()` to finalize check status and upload artifacts - -Both are bundled by `@vercel/ncc` into `dist/run-tests/index.js` and `dist/run-post-actions/index.js` (referenced in `action.yml`). **Always run `make build` before committing changes.** - -Core logic lives in `src/`: -- `src/index.js` — orchestration: `prepareProject()` pulls Docker image and extracts project source, `check()` runs Docker Compose, `runTests()` and `runPostActions()` tie everything together and communicate with the Hexlet API -- `src/routes.js` — builds Hexlet API URLs (`projectMemberPath`, `projectMemberCheckPath`) -- `src/packageChecker.js` — validates that the project's package name matches language conventions; reads `pyproject.toml`, `composer.json`, or `package.json` depending on language - -Tests use a local Fastify mock server (`server.js`) to stub Hexlet API responses. Fixtures are in `__fixtures__/`. - -## Key Conventions - -- ES modules (`"type": "module"` in package.json) — use `import`/`export`, not `require` -- Biome enforces single quotes and no unused imports/variables -- The `dist/` directory is committed — regenerate it with `make build` after any source change - - -# RTK (Rust Token Killer) - Token-Optimized Commands - -## Golden Rule - -**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use. - -**Important**: Even in command chains with `&&`, use `rtk`: -```bash -# ❌ Wrong -git add . && git commit -m "msg" && git push - -# ✅ Correct -rtk git add . && rtk git commit -m "msg" && rtk git push -``` - -## RTK Commands by Workflow - -### Build & Compile (80-90% savings) -```bash -rtk cargo build # Cargo build output -rtk cargo check # Cargo check output -rtk cargo clippy # Clippy warnings grouped by file (80%) -rtk tsc # TypeScript errors grouped by file/code (83%) -rtk lint # ESLint/Biome violations grouped (84%) -rtk prettier --check # Files needing format only (70%) -rtk next build # Next.js build with route metrics (87%) -``` - -### Test (60-99% savings) -```bash -rtk cargo test # Cargo test failures only (90%) -rtk go test # Go test failures only (90%) -rtk jest # Jest failures only (99.5%) -rtk vitest # Vitest failures only (99.5%) -rtk playwright test # Playwright failures only (94%) -rtk pytest # Python test failures only (90%) -rtk rake test # Ruby test failures only (90%) -rtk rspec # RSpec test failures only (60%) -rtk test # Generic test wrapper - failures only -``` - -### Git (59-80% savings) -```bash -rtk git status # Compact status -rtk git log # Compact log (works with all git flags) -rtk git diff # Compact diff (80%) -rtk git show # Compact show (80%) -rtk git add # Ultra-compact confirmations (59%) -rtk git commit # Ultra-compact confirmations (59%) -rtk git push # Ultra-compact confirmations -rtk git pull # Ultra-compact confirmations -rtk git branch # Compact branch list -rtk git fetch # Compact fetch -rtk git stash # Compact stash -rtk git worktree # Compact worktree -``` - -Note: Git passthrough works for ALL subcommands, even those not explicitly listed. - -### GitHub (26-87% savings) -```bash -rtk gh pr view # Compact PR view (87%) -rtk gh pr checks # Compact PR checks (79%) -rtk gh run list # Compact workflow runs (82%) -rtk gh issue list # Compact issue list (80%) -rtk gh api # Compact API responses (26%) -``` - -### JavaScript/TypeScript Tooling (70-90% savings) -```bash -rtk pnpm list # Compact dependency tree (70%) -rtk pnpm outdated # Compact outdated packages (80%) -rtk pnpm install # Compact install output (90%) -rtk npm run