Add MCP_RECTOR_WARM_SESSION_IGNORE and cover TrackingParser directly

[fdaviddpt]

Two low-priority follow-ups, both scoped and verified independently.

#200 -- exclude runtime-written directories from the session watch

Adds MCP_RECTOR_WARM_SESSION_IGNORE, the mirror of MCP_RECTOR_WARM_SESSION_WATCH: a PATH-separated list of directories the warm session never walks or lists. Declaring a project's own runtime-written directory (a cache, logs, uploads) there stops it from forcing a session respawn on every call, per the measurement in #200's own issue body.

RectorRunner::sessionWatchPaths() and the new sessionIgnorePaths() now share a splitPathListEnv() helper -- byte-identical parsing behaviour for the pre-existing watch var, confirmed by diffing against the pre-change body. SessionHooks::directorySnapshot() gained a third $ignorePaths parameter, reusing the existing CONTAINS-a-root guard so a misdeclared ignore path can never silently un-watch a real root.

Scope check: traced every dryRun:false write path and every LSP write-shaped dry run -- all routed around the session entirely via forkAndExecute(). directorySnapshot()'s new parameter can only affect WHEN a session is deemed stale, never what any call computes or writes, so this does not need CLAUDE.md's independent warm==cold E2E check; worst case is a stale read-only dry-run diagnostic, which CI already backstops.

Documented in docs/how-it-works.md, including the correctness caveat: never declare a source directory, since its contents feed analysis and a stale listing would serve stale answers with no warning.

#227 -- cover TrackingParser directly; document the rector-warm-lsp coverage gap

No production code changed. A dedicated TrackingParserTest now exercises all three of TrackingParser's methods directly via a hand-built recording fake Parser, asserting both halves the maintainer's own follow-up comment on #227 asked about: the hook fires before the inner parser runs for parseFile() (must-fire), and never fires for parseString() (must-not-fire) -- each test is the other's control.

bin/rector-warm-lsp's 0% coverage (only E2E jobs start it, and they do not set the coverage env vars) is now documented as an accepted, known gap in CONTRIBUTING.md, per the issue's own accept-and-document option; wiring coverage into the E2E jobs is a separate, larger CI change and stays out of scope.

Review

Two reviewers (Explore, oss:auditor) ran against the first two commits. The auditor found one real gap: the new CONTAINS-a-root guard branch for ignore paths had no test exercising the branch where it actually fires. Fixed in the third commit, verified red (guard deliberately broken) then green (restored).

Closes #200, closes #227.

🤖 Generated with Claude Code

[fdaviddpt]

Independent end-to-end check (CLAUDE.md gate)

Ran against head SHA 6ff1c7f8c75c31a3a810ec7d9fda21a0e323898e, in a fresh, independent clone checked out at that commit (separate from the lane's own worktree/tests), with composer install run fresh.

Verdict: PASS.

What was built and run

A new, independent pytest harness (not part of this PR's own test suite) reusing tests/E2E/mcp_harness.py / tests/E2E/test_lsp_initialize.py plumbing to drive the real bin/mcp-rector-warm (MCP) and the LSP binary over real stdio, on fixture projects built fresh for this check:

1. MCP, session-path exercise of the new var. A plain (non-ignored) write of a .php file under a runtime-cache/ directory inside the project root forces a session respawn (positive control — confirms the harness can see a respawn at all). The identical write, with MCP_RECTOR_WARM_SESSION_IGNORE=runtime-cache set, produces serve only — no respawn. This is the first time the new parameter was actually exercised end-to-end rather than only at the unit level.
2. MCP, write-path independence. With MCP_RECTOR_WARM_SESSION_IGNORE set AND the session gone stale on an undeclared custom-rule input (config/map.json, same shape as test_warm_session_watch.py), a dryRun:false call via the real MCP tool was applied to the fixture file and compared byte-for-byte against a fresh cold vendor/bin/rector process run on an identically-edited copy. Equal.
3. MCP, ordinary write sanity. A plain fixture tree, MCP_RECTOR_WARM_SESSION_IGNORE set, dryRun:false tool call applied, full resulting file tree diffed byte-for-byte against a cold rector process run on an identical copy (tree_contents() comparison, not just the one changed file). Equal.
4. LSP code-action write. Drove the real LSP binary over stdio with MCP_RECTOR_WARM_SESSION_IGNORE=runtime-cache in the server's environment, textDocument/didOpen then textDocument/codeAction, applied the returned WorkspaceEdit to the original file, and compared against a fresh cold vendor/bin/rector process run. Equal (sayHello rename applied identically).

All four cases passed. Also spot-ran ./vendor/bin/phpunit --filter 'SessionHooksTest|RectorRunnerSessionTest' (22 tests, 91 assertions) — green — and the lane's own test_warm_session_watch.py (3 tests) and a baseline scenario (readme-example) — green, confirming the harness and environment are sound independent of this PR's own assertions.

Scope note

This confirms the maintainer's ruling in the PR context was the right call to enforce mechanically: the write paths checked here (#2 -#4) are unaffected by MCP_RECTOR_WARM_SESSION_IGNORE, consistent with sessionCandidate()'s unconditional !$dryRun guard — but that was verified fresh here with an independent harness, not assumed from the scoping argument.

No code was modified or merged; this comment is the only write performed by this check.