From d0104ad73d323d00beeac77f7153b5f5c0c9befb Mon Sep 17 00:00:00 2001
From: Sergei Zharinov <zharinov@users.noreply.github.com>
Date: Tue, 9 Dec 2025 12:41:46 -0300
Subject: [PATCH] refactor: Extract commands to Makefile

---
 .github/workflows/nightly.yml |  2 +-
 .github/workflows/stable.yml  | 12 +++++++++---
 AGENTS.md                     | 22 ++++++++++++++--------
 Makefile                      | 26 ++++++++++++++++++++++++++
 4 files changed, 50 insertions(+), 12 deletions(-)
 create mode 100644 Makefile

diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index ab844269..0287a5ec 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -40,7 +40,7 @@ jobs:
           prefix-key: v0-rust-nightly
 
       - name: Generate code coverage
-        run: cargo +nightly llvm-cov --all-features --workspace --lcov --output-path lcov.info
+        run: make coverage
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5
diff --git a/.github/workflows/stable.yml b/.github/workflows/stable.yml
index 5c5fe624..fe9ede0b 100644
--- a/.github/workflows/stable.yml
+++ b/.github/workflows/stable.yml
@@ -36,14 +36,20 @@ jobs:
           cache-on-failure: "true"
           prefix-key: v0-rust-stable
 
+      - name: Install cargo-nextest
+        uses: baptiste0928/cargo-install@b687c656bda5733207e629b50a22bf68974a0305 # v3.3.2
+        with:
+          crate: cargo-nextest
+          locked: true
+
       - name: Check
-        run: cargo check --workspace --all-targets
+        run: make check
 
       - name: Clippy
-        run: cargo clippy --workspace --all-targets -- -D warnings
+        run: make clippy
 
       - name: Test
-        run: cargo test --workspace
+        run: make test
 
   check-publish:
     runs-on: ubuntu-latest
diff --git a/AGENTS.md b/AGENTS.md
index 0aa4b9fc..92b0b5d9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -189,9 +189,9 @@ cargo run -p plotnik-cli -- debug -q '(function_declaration) @fn' -s app.ts -l t
 ## CLI commands
 
 - IMPORTANT: the `debug` is your first tool you should use to test your changes
-- Run tests: `cargo nextest run --hide-progress-bar --status-level none --failure-output final`
+- Run tests: `make test`
 - We use snapshot testing (`insta`) heavily
-  - Accept snapshots: `cargo insta accept`
+  - Accept snapshots: `make snapshots`
 
 ## Test structure
 
@@ -239,17 +239,23 @@ fn error_case() {
 
 ## Coverage
 
-Uses `cargo-llvm-cov`, already installed.
+Uses `cargo-llvm-cov` (already installed)
 
 Find uncovered lines per file:
 
 ```sh
-cargo llvm-cov --package plotnik-lib --text --show-missing-lines 2>/dev/null | grep '\.rs: [0-9]'
+$ make coverage-lines | grep recursion
+crates/plotnik-lib/src/query/recursion.rs: 78, 210, 214, ...
 ```
 
 ### `invariants.rs`
 
-- Contains functions and `impl` blocks for invariant check functionality
-- Each function panics on invariant violation, it may or may not return the value
-- When returning value, the name is `ensure_something(...)`, where something is related to return value
-- When there is no return value, the name is `assert_something(...)` and something is related to function arguments
+- The goal of this file is to exclude coverage of the unreachable code branches
+- It contains functions and `impl` blocks for invariant check functionality
+- Each function panics on invariant violation
+- The naming convention: `ensure_something(...)`, where something refers the return value
+- It doesn't make sense to put the `panic!(...)`, `assert!()` or `.expect()` because they don't cause coverage problems:
+  - `panic!()` usually is called in catch-all `match` branches
+    - eventually we extract the whole `match` to the `invariants.rs`, for well-established code
+  - `assert!()` is coverage-friendly alternative for `if condition { panic!(...) }`
+  - `.expect()` is useful for unwrapping `Result`/`Option` values
diff --git a/Makefile b/Makefile
new file mode 100644
index 00000000..7fb787e4
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,26 @@
+.PHONY: check clippy test snapshots coverage coverage-lines coverage clean
+
+check:
+	@cargo check --workspace --all-targets
+
+clippy:
+	@cargo clippy --workspace --all-targets -- -D warnings
+
+test:
+	@cargo nextest run --no-fail-fast --hide-progress-bar --status-level none --failure-output final
+
+snapshots:
+	@cargo insta accept
+
+coverage-lines:
+	@cargo llvm-cov --package plotnik-lib --text --show-missing-lines 2>/dev/null | grep '\.rs: [0-9]' | sed 's|.*/crates/|crates/|'
+
+coverage:
+	@cargo +nightly llvm-cov --all-features --workspace --lcov --output-path lcov.info
+
+fmt:
+	@cargo fmt --quiet
+	@npx -y prettier --list-different --write .
+
+clean:
+	@cargo clean