build(linters): forbid direct std::env access

PHP keeps three separate environment storages and docs/dev/env-vars-
porting.md maps each to its own shim construct. Reaching for std::env
silently picks one, so the porting target has to be chosen by reading
the PHP source rather than by whichever Rust call is at hand.

Detect var/var_os/vars/vars_os/set_var/remove_var. current_dir, args,
consts, temp_dir, current_exe and the path split/join helpers are not
environment storage and stay allowed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2 files changed, 83 insertions, 0 deletions

diff --git a/scripts/linters/lint b/scripts/linters/lint
index e90c3e0c..150e1f1a 100755
--- a/scripts/linters/lint
+++ b/scripts/linters/lint
@@ -9,6 +9,7 @@ use Shirabe\Lint\Linters\CargoWorkspaceDependencies;
 use Shirabe\Lint\Linters\ContiguousUseBlock;
 use Shirabe\Lint\Linters\NoBannedUse;
 use Shirabe\Lint\Linters\NoDecorativeSectionComment;
+use Shirabe\Lint\Linters\NoDirectEnvAccess;
 use Shirabe\Lint\Linters\NoExceptionDowncast;
 use Shirabe\Lint\Linters\NoFormatTrailingComma;
 use Shirabe\Lint\Linters\NoHaltCompilerLiteral;
@@ -28,6 +29,13 @@ $runner = new Runner($rootDir, [
     [new NoDecorativeSectionComment(), [
         'crates/shirabe-semver/src/version_parser.rs',
     ]],
+    [new NoDirectEnvAccess(), [
+        // Defines the shim the rule points at.
+        'crates/shirabe-php-shim/src/env.rs',
+        // Build scripts read Cargo's own variables, and run before the shim exists.
+        'crates/shirabe-php-rpc/build.rs',
+        'crates/shirabe/build.rs',
+    ]],
     [new NoExceptionDowncast(), [
         // Defines the box and the walk the rule points at.
         'crates/shirabe-php-shim/src/exception.rs',
diff --git a/scripts/linters/src/Linters/NoDirectEnvAccess.php b/scripts/linters/src/Linters/NoDirectEnvAccess.php
new file mode 100644
index 00000000..5276279a
--- /dev/null
+++ b/scripts/linters/src/Linters/NoDirectEnvAccess.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shirabe\Lint\Linters;
+
+use Shirabe\Lint\Linter;
+use Shirabe\Lint\Support\FileFinder;
+use Shirabe\Lint\Support\Paths;
+
+final class NoDirectEnvAccess implements Linter
+{
+    private const BANNED_ENV_FUNCTIONS = ['var', 'var_os', 'vars', 'vars_os', 'set_var', 'remove_var'];
+
+    public function name(): string
+    {
+        return 'no_direct_env_access';
+    }
+
+    public function failureIntro(): string
+    {
+        return "Found direct access to the process environment.\n"
+            . "PHP reads and writes environment variables through three storages that are not kept in\n"
+            . "sync with each other, and each has its own counterpart in `shirabe_php_shim`:\n"
+            . "`getenv`/`getenv_all`/`putenv`/`putenv_clear`, `PHP_ENV`, and `PHP_SERVER`.\n"
+            . 'Port whichever one the PHP source uses; see `docs/dev/env-vars-porting.md`:';
+    }
+
+    public function check(string $rootDir, array $excludes): array
+    {
+        $errors = [];
+
+        foreach (FileFinder::rustFiles($rootDir) as $path) {
+            $relative = Paths::relativeTo($rootDir, $path);
+            if (in_array($relative, $excludes, true)) {
+                continue;
+            }
+
+            array_push($errors, ...$this->findEnvAccesses($path, $relative));
+        }
+
+        return $errors;
+    }
+
+    /** @return list<string> */
+    private function findEnvAccesses(string $path, string $relative): array
+    {
+        $errors = [];
+        $names = implode('|', self::BANNED_ENV_FUNCTIONS);
+
+        foreach (file($path) as $idx => $raw) {
+            $code = explode('//', $raw, 2)[0];
+
+            if (preg_match_all("/\bstd::env::({$names})\b/", $code, $m)) {
+                foreach ($m[1] as $name) {
+                    $errors[] = "{$relative}:" . ($idx + 1) . ": use of `std::env::{$name}`";
+                }
+            }
+
+            if (preg_match_all('/\bstd::env::\{([^}]*)\}/', $code, $m)) {
+                foreach ($m[1] as $group) {
+                    foreach (explode(',', $group) as $entry) {
+                        $name = preg_split('/\s+as\s+/', trim($entry))[0];
+                        if (!in_array($name, self::BANNED_ENV_FUNCTIONS, true)) {
+                            continue;
+                        }
+                        $errors[] = "{$relative}:" . ($idx + 1) . ": import of `std::env::{$name}`";
+                    }
+                }
+            }
+        }
+
+        return array_values(array_unique($errors));
+    }
+}