WEB-11226: Add worktree-isolated test flow to shared make helpers

[lewissmithweb]

Summary

The shared lickdltd/make helpers bind-mount the main checkout into the CLI container, so tests can't run against a git worktree's code — blocking parallel, multi-worktree development in every repo that inherits them. This adds php_tests_worktree, which runs a worktree's suite against the already-running local services with per-worktree database isolation, resolving composer/vendor drift first. It also introduces the DKR_COMPOSE_SRC parameter and documents the compose convention that lets an isolated run coexist with the main stack. Fully backwards compatible — every existing target renders byte-identical.

Changes

• AC1 — reusable worktree test target: new php_tests_worktree in php.mk; WORKTREE=/path mounts that tree (via DKR_COMPOSE_SRC) and runs the suite (TESTS=phpunit by default, or an arbitrary COMMAND).
• AC2 — per-worktree DB isolation: the run is given DB_DATABASE=test_<worktree> (hyphen-sanitised, overridable) so a worktree run never collides with the main checkout's DB or a concurrent worktree's.
• AC3 — reuse running services: the container runs with --no-deps (not docker compose up), reusing the already-running MySQL / Redis / Elasticsearch instead of duplicating the stack.
• AC4 — composer/vendor drift: before testing, the worktree's composer.lock is compared with the main checkout's; on drift (or missing vendor/) dependencies are installed for the worktree, otherwise the existing vendor/ is reused.
• AC5 — parameterised compose convention: docker.mk gains an exported DKR_COMPOSE_SRC (configurable source-mount path); the documented convention uses ${DKR_COMPOSE_SRC} for the code volume and drops container_name so worktree and main-checkout stacks don't conflict.
• AC6 — lives in the shared helpers & documented: changes are in docker.mk / php.mk (inherited on the next make init) and documented in docs/docker.md and docs/php.md.
• Out of scope (supporting infra): a Docker-free make -n test (test/php_tests_worktree.sh) asserting the flow's behaviour, wired into a new Test workflow so it runs on PRs.

How to test

• Run ./test/php_tests_worktree.sh (needs only make) — all assertions should pass.
• Confirm backwards compatibility: make -n -f docker.mk -f php.mk php_tests_phpunit still renders a full-stack up, and php_composer_install is unchanged.
• Inspect the worktree flow without Docker: make -n -f docker.mk -f php.mk php_tests_worktree WORKTREE=/tmp/foo — the test run uses run --rm --no-deps, --env DB_DATABASE=test_foo, and no up.

Deployment notes

Consuming repos adopt this opt-in when they want the worktree flow: reference ${DKR_COMPOSE_SRC} for the code volume and remove any hardcoded container_name in their compose file (see docs/docker.md). No change is required for existing targets to keep working.

Closes WEB-11226

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4cc62f63-bc52-463d-ac7c-caa36dd524f5

📥 Commits

Reviewing files that changed from the base of the PR and between 342b419 and 8122366.

📒 Files selected for processing (4)

• .github/workflows/test.yaml
• docs/php.md
• php.mk
• test/php_tests_worktree.sh

---

📝 Walkthrough

• Added a new way to run PHP tests from a git “worktree” while still using the same local services already running on your machine.
• Made the Docker setup more flexible by letting you choose which local folder is mounted into the containers.
• Ensured each worktree uses its own isolated test database, so results from different worktrees don’t clash.
• Updated the documentation with clear instructions for the new worktree-based testing approach.
• Added an automated CI check to confirm the new worktree testing flow continues to work.

Walkthrough

Adds a DKR_COMPOSE_SRC compose variable, a new php_tests_worktree Make target for running PHP tests against a git worktree with per-worktree database isolation and composer drift handling, supporting documentation, a dry-run validation shell script, and a CI workflow that executes it.

Changes

Worktree PHP Test Execution

Layer / File(s)	Summary
Compose source path variable docker.mk, docs/docker.md	Adds an overridable, exported DKR_COMPOSE_SRC variable defaulting to $(PWD) for compose bind-mount interpolation, documented with a new "source path" section.
php_tests_worktree make target php.mk, docs/php.md	New target resolves worktree path/id, sets per-worktree DB_DATABASE, reuses running services via --no-deps, detects vendor/composer.lock drift and conditionally runs composer install, then runs tests; documented with usage and mechanics.
Validation script and CI workflow test/php_tests_worktree.sh, .github/workflows/test.yaml	A shell script asserts make -n rendered output for the new target's key behaviours; a new "Test" GitHub Actions workflow checks out the repo and runs this script on push/pull_request.

Sequence Diagram(s)

flowchart TD
DevMakeCall --> ValidateWorktree
ValidateWorktree --> ResolveWorktreeId
ResolveWorktreeId --> SetDbDatabase
SetDbDatabase --> CheckComposerDrift
CheckComposerDrift -->|drift or missing vendor| RunComposerInstall
CheckComposerDrift -->|no drift| ReuseVendor
RunComposerInstall --> RunDkrComposeCmdRun
ReuseVendor --> RunDkrComposeCmdRun

Loading

Estimated code review effort: 3/5 (Medium) — the Makefile logic for drift detection and worktree resolution warrants careful reading.

Related issues: None found in the provided context.

Related PRs: None found in the provided context.

Suggested labels: enhancement, documentation, ci, testing

Suggested reviewers: None found in the provided context.

A young padawan wrote a script, tested with care,
"Do or do not, there is no half-mounted worktree" — fair.
The Force flows through make, through worktrees it glides,
Composer drift checked, isolation besides.
May the CI be with you, on every pull request tide.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/test.yaml:
- Around line 4-8: The workflow trigger in test.yaml currently lacks run
cancellation, so repeated pushes can queue competing jobs. Add a concurrency
block to the workflow definition and key it off the workflow plus ref, using the
existing on: pull_request/push setup, so newer runs cancel superseded ones
instead of contending for runners.
- Line 13: The checkout step in the workflow should be hardened by replacing the
mutable actions/checkout@v4 reference with a full commit SHA and disabling
credential persistence. Update the checkout usage in the workflow so it is
pinned to a specific commit for the checkout action, and add persist-credentials
set to false since the job only runs a local script and does not need the
GITHUB_TOKEN left in git config. Use the actions/checkout step as the unique
locator when making the change.

In `@php.mk`:
- Around line 25-33: The per-worktree database identifier in php_tests_worktree
is too weak because WORKTREE_ID only uses the basename, so different worktrees
with the same folder name can collide and punctuation can produce invalid DB
names. Update the DB_DATABASE derivation to use a collision-resistant, sanitised
identifier based on WORKTREE_SRC or WORKTREE, and adjust the
WORKTREE_ID/DB_DATABASE logic so the resulting database name remains unique and
valid across parent paths and branch-style names.
- Line 37: The composer install path in php_tests_worktree is duplicating the
compose invocation instead of reusing the shared docker.mk composition. Update
the branch that runs composer install to use the same compose command pattern as
DKR_COMPOSE_CMD_RUN, including DKR_COMPOSE_ADDITIONAL and
DKR_COMPOSE_ADDITIONAL_RUN, so php_tests_worktree stays consistent with the rest
of the make-based Docker calls and does not silently diverge when those
variables are set.

In `@test/php_tests_worktree.sh`:
- Line 11: The worktree fixture name in the php_tests_worktree.sh setup is too
session-specific and should be renamed to a neutral, project-agnostic temporary
path. Update the worktree variable assignment in the script to use a generic
fixture name (such as a shared test temp directory) so the helper remains clean
and reusable; the relevant symbol to change is the worktree assignment in
php_tests_worktree.sh.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ae55b54c-cd69-4842-bd2f-9d0e65ad68ae

📥 Commits

Reviewing files that changed from the base of the PR and between 387cb34 and 342b419.

📒 Files selected for processing (6)

• .github/workflows/test.yaml
• docker.mk
• docs/docker.md
• docs/php.md
• php.mk
• test/php_tests_worktree.sh