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