fix(release): stop slot rotation corrupting self-referential shellcheck paths (#770)

## Summary

Fixes #769. The `env.stub` shellcheck directive in the 8.0.0 init
scripts was written as a repo-relative path carrying a version token (`#
shellcheck source=docker/openemr/8.0.0/env.stub`). Because the scripts
were registered as `current`-slot pins, advancing `current` 8.0.0 →
8.1.0 rewrote that directive to point at a sibling dir that never
exists, breaking shellcheck CI on the auto rotation PR (#760).

A `# shellcheck source=` comment is a path to the script's own sibling
file, not a version pin — it should never carry a rotating token.

## Changes

- `docker/openemr/8.0.0/openemr.sh`, `ssl.sh`: use the version-agnostic
`SCRIPTDIR/env.stub` form (matching the existing convention already used
for `devtoolsLibrary.source`). `SCRIPTDIR` resolves to the script's own
dir at lint time and contains no token for the rotator to match.
- `tools/release/versions.yml`: drop the two `shellcheck_source`
entries. After the change above the files hold no version pin, so the
linter no longer flags them — no `excludes:` entry needed.
- `tools/release/tests/SlotRotatorTest.php`: regression test seeding a
`*.sh` with a `SCRIPTDIR` directive plus a genuine rotating token,
asserting the directive survives rotation byte-for-byte.

## Test plan

- [x] `php bin/lint-versions.php` — `openemr.sh`/`ssl.sh` no longer
flagged (the two remaining `rel_branch_ref` findings pre-exist on
`master`, unrelated)
- [x] `vendor/bin/phpunit` — 175 tests green, including the new
regression
- [x] Dry-run rotation reproducing #760 (`--current=8.1 --dry-run`) no
longer touches the `# shellcheck source=` line in either script
- [x] `shellcheck docker/openemr/8.0.0/openemr.sh ssl.sh` — clean

Author: kojiromike

docker/openemr/8.0.0/openemr.sh

@@ -20,7 +20,7 @@ set -e
 # source-follower without ever running it — BusyBox ash treats `.` as a
 # special builtin and exits the shell on file-not-found even with `|| true`.
 if false; then
-    # shellcheck source=docker/openemr/8.0.0/env.stub
+    # shellcheck source=SCRIPTDIR/env.stub
     . /root/env.stub
 fi
 

docker/openemr/8.0.0/ssl.sh

@@ -16,7 +16,7 @@ set -e
 # source-follower without ever running it — BusyBox ash treats `.` as a
 # special builtin and exits the shell on file-not-found even with `|| true`.
 if false; then
-    # shellcheck source=docker/openemr/8.0.0/env.stub
+    # shellcheck source=SCRIPTDIR/env.stub
     . /root/env.stub
 fi
 

tools/release/tests/SlotRotatorTest.php

@@ -195,6 +195,37 @@ public function testReplacementAvoidsPartialVersionMatches(): void
         self::assertStringContainsString('rel-820', $after);
     }
 
+    public function testRotationLeavesScriptdirShellcheckDirectiveIntact(): void
+    {
+        $rotator = new SlotRotator($this->tmpDir, $this->registryPath);
+
+        $rotator->rotate([
+            'current' => [
+                'minor' => '8.2',
+                'full' => '8.2.0',
+                'branch' => 'rel-820',
+                'docker_dir' => '8.2.0',
+            ],
+        ]);
+
+        $script = (string) file_get_contents($this->tmpDir . '/docker/openemr/8.0.0/openemr.sh');
+        self::assertStringContainsString(
+            '# shellcheck source=SCRIPTDIR/env.stub',
+            $script,
+            'self-referential SCRIPTDIR directive must survive rotation byte-for-byte',
+        );
+        self::assertStringNotContainsString(
+            'source=docker/openemr',
+            $script,
+            'rotation must never inject a version path into a shellcheck source directive',
+        );
+        self::assertStringContainsString(
+            "echo 'init for docker/openemr/8.2.0'",
+            $script,
+            'sanity: the genuine rotating docker_dir token should have been rewritten',
+        );
+    }
+
     private function seedFixtures(): void
     {
         $this->writeFile('tools/release/versions.yml', <<<'YAML'
@@ -230,6 +261,9 @@ private function seedFixtures(): void
           - path: docker/openemr/8.0.0/Dockerfile
             slot: current
             kinds: [docker_clone_branch]
+          - path: docker/openemr/8.0.0/openemr.sh
+            slot: current
+            kinds: [docker_dir_ref]
           - path: docker/openemr/8.1.0/Dockerfile
             slot: next
             kinds: [docker_arg_branch]
@@ -256,6 +290,17 @@ private function seedFixtures(): void
         $this->writeFile('docker/openemr/8.1.0/Dockerfile', "FROM alpine:3.21\nARG OPENEMR_VERSION=rel-810\n");
         $this->writeFile('docker/openemr/8.1.1/Dockerfile', "FROM alpine:3.21\nARG OPENEMR_VERSION=master\n");
 
+        // In-container init script for the current slot. It carries a rotating
+        // docker_dir token (the path in the echo line) alongside a
+        // self-referential `SCRIPTDIR` shellcheck directive that must never be
+        // rewritten.
+        $this->writeFile(
+            'docker/openemr/8.0.0/openemr.sh',
+            "#!/bin/sh\nset -e\n"
+            . "# shellcheck source=SCRIPTDIR/env.stub\n. /root/env.stub\n"
+            . "echo 'init for docker/openemr/8.0.0'\n",
+        );
+
         $this->writeFile(
             'docker/openemr/OVERVIEW.md',
             "| 8.0.0 | latest |\n| 8.1.0 | next |\n| 8.1.1 | dev |\n",

tools/release/versions.yml

@@ -122,17 +122,6 @@ files:
     slot: all
     kinds: [dependabot_directory]
 
-  # In-container init scripts; reference their own dir as shellcheck source
-  # comments, so they rotate with the slot's docker_dir. Only the 8.0.0/*.sh
-  # files currently have these refs; the next/dev variants have no path
-  # comments and will be picked up by the linter only if added later.
-  - path: docker/openemr/8.0.0/openemr.sh
-    slot: current
-    kinds: [shellcheck_source]
-  - path: docker/openemr/8.0.0/ssl.sh
-    slot: current
-    kinds: [shellcheck_source]
-
   # Container-benchmarking docs reference the next-slot version as defaults.
   - path: utilities/container_benchmarking/README.md
     slot: next