diff --git a/docs/pregate.md b/docs/pregate.md index cfad85a34..58314a53d 100644 --- a/docs/pregate.md +++ b/docs/pregate.md @@ -65,7 +65,7 @@ the byte-pinned `/ship` renders in `test/fixtures/golden/`). | `selection` | `workflow.yml/job` → a command printing the lane's file list, for matrices a planner computes (gstack: `scripts/test-free-shards.ts --list`) | | `warn` | check ids downgraded to warn; `secrets` and required lanes never | | `strays.allow` | intentional root files or new top-level directories | -| `local` | `workflow.yml/job` lanes a local run satisfies: a platform-agnostic toolchain (an `ubuntu-latest` suite that runs the same on a Mac), or a repo whose CI is off. Their tests run here instead of becoming `requires-remote`, except that on a machine under 8 cores with a `remote_gate` or a remote `test_backend` the small-machine rule still records the test tier as a `requires-remote` obligation. `--explain` notes an id that matches no platform lane | +| `local` | `workflow.yml/job` lanes a local run satisfies: a platform-agnostic toolchain (an `ubuntu-latest` suite that runs the same on a Mac), or a repo whose CI is off. Their tests run here instead of becoming `requires-remote`, except that on a machine under 8 cores with a `remote_gate` or a remote `test_backend` the small-machine rule still records the test tier as a `requires-remote` obligation. `--explain` notes an id that matches no workflow lane | | `guards` | `[{ id, when: [globs], command, fix?, timeout_s? }]`: repo commands a lane must pass when a touched file matches `when` (manifest checks, subprocess goldens the import graph cannot see); see [guards](#guards) | | `serial_patterns` | test-file globs the `lanes` check runs one process per file, apart from the unit files (default `**/*.serial.test.*`) | | `sealed` | sealed or eval output that must never reach a public destination; read by the pre-push hook and `gstack-pregate sealed` (see [sealed output](#sealed)) | @@ -77,8 +77,8 @@ Only the `origin/` copy or the user-owned file below is honoured, so a downgrade is reviewed (or is the user's own) before it takes effect. A repo that keeps `.gstack/` out of git (a shared repo where gstack is one contributor's tool) can hold the same file at `/projects//pregate.json`. The -state root is `GSTACK_STATE_ROOT`, else `GSTACK_HOME`, else `~/.gstack` (full -chain in [docs/state-root.md](state-root.md)); `` is what +state root is `GSTACK_STATE_ROOT`, else `GSTACK_HOME`, else `GSTACK_STATE_DIR`, +else a gstack plugin's data directory, else `~/.gstack` ([docs/state-root.md](state-root.md)); `` is what `~/.claude/skills/gstack/bin/gstack-slug` prints as `SLUG=` in the repository (`GSTACK_PROJECT_SLUG` overrides it). It is read only when the base carries none (never under `--policy-from head`), it lives outside the repository so a PR still diff --git a/lib/pregate/config.ts b/lib/pregate/config.ts index 0fc24b78c..e3348f252 100644 --- a/lib/pregate/config.ts +++ b/lib/pregate/config.ts @@ -277,6 +277,6 @@ export function explainConfig(): string { 'price_file: repo-relative path of the GSTACK_EVAL_CALLS v1 call-plan file `gstack-eval-plan price-gate` prices a paid gate from; never executed (docs/eval-calls.md)', 'stall_timeout_s: seconds without test output before the lanes check kills the runner\'s process group and records it incomplete (default 300; 0 disables; --stall-timeout overrides)', 'remote_gate: the repo\'s remote test gate command; under 8 cores the test tier becomes a requires-remote obligation naming it, and gstack-pregate --remote runs it (it must print PREGATE_REMOTE: tree= tests= failed=) (docs/pregate.md#remote-gate)', - 'no .gstack/pregate.json on the base: /projects//pregate.json is read instead (state root: GSTACK_STATE_ROOT, else GSTACK_HOME, else ~/.gstack; outside the repo, so a PR cannot reach it; a path inside the checkout is ignored)', + 'no .gstack/pregate.json on the base: /projects//pregate.json is read instead (state root: GSTACK_STATE_ROOT, else GSTACK_HOME, else GSTACK_STATE_DIR, else a gstack plugin data dir, else ~/.gstack, per docs/state-root.md; run --explain prints the resolved path; outside the repo, so a PR cannot reach it; a path inside the checkout is ignored)', ].join('\n') + '\n'; } diff --git a/lib/pregate/context.ts b/lib/pregate/context.ts index db8d48e1a..480d00b8b 100644 --- a/lib/pregate/context.ts +++ b/lib/pregate/context.ts @@ -106,13 +106,13 @@ export function touchedFiles(repoRoot: string, mergeBase: string): TouchedFile[] return [...out.values()].filter(t => t.path !== 'node_modules' && !t.path.startsWith('node_modules/')).sort((a, b) => a.path.localeCompare(b.path)); } -/** The deepest existing ancestor realpathed, the rest re-joined: a symlinked state root inside the checkout still counts as inside. */ +/** The deepest existing ancestor realpathed (on-disk casing), the rest re-joined: a symlinked state root inside the checkout still counts as inside. */ function realish(p: string): string { let head = path.resolve(p); const tail: string[] = []; while (!fs.existsSync(head) && path.dirname(head) !== head) { tail.unshift(path.basename(head)); head = path.dirname(head); } - try { return path.join(fs.realpathSync(head), ...tail); } catch { return path.resolve(p); } + try { return path.join(fs.realpathSync.native(head), ...tail); } catch { return path.resolve(p); } } -const within = (root: string, p: string) => { const rel = path.relative(root, p); return !rel.startsWith('..') && !path.isAbsolute(rel); }; +const within = (root: string, p: string) => { const rel = path.relative(root, p); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); }; /** Why a user policy path must not be read, or null: a relative path (no HOME) or one a PR could commit is never trusted. */ export function userConfigRejection(repoRoot: string, file: string): string | null { @@ -149,7 +149,7 @@ export function buildContext(o: BuildContextOptions): ContextLoad { const config = configLoad.config as PregateConfig; const lanes = discoverLanes(o.repoRoot, platform); // A lane that exists but is not platform-tier on this host already runs here, so only an unknown id is worth a line. - for (const id of config.local) if (!lanes.some(l => l.id === id)) explain.push(`local: ${id} matches no platform lane; ignored`); + for (const id of config.local) if (!lanes.some(l => l.id === id)) explain.push(`local: ${id} matches no workflow lane; ignored`); return { ctx: { repoRoot: o.repoRoot, base, baseRef, baseSha: baseSha.out, mergeBase, head, wtree, touched: touchedFiles(o.repoRoot, mergeBase), diff --git a/test/pregate-user-policy.test.ts b/test/pregate-user-policy.test.ts index f969c2b0a..461cd88c4 100644 --- a/test/pregate-user-policy.test.ts +++ b/test/pregate-user-policy.test.ts @@ -8,10 +8,11 @@ */ import { afterEach, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; +import * as os from 'node:os'; import * as path from 'node:path'; import { EXIT } from '../lib/headless-artifacts'; import { loadConfigFromUser, validateConfig } from '../lib/pregate/config'; -import { buildContext, sha256 } from '../lib/pregate/context'; +import { buildContext, sha256, userConfigRejection } from '../lib/pregate/context'; import { runPregate } from '../lib/pregate/index'; import { BASE_PREGATE, cleanup, commit, makeFixtureRepo, runBin, type FixtureRepo } from './helpers/pregate-fixture'; @@ -216,7 +217,7 @@ describe('gstack-pregate with a user-owned policy', () => { // Value: protects=a user path inside the checkout (GSTACK_HOME under the repo, or a relative state root when HOME is unset) is // never read, so a PR cannot commit its own "user" policy; fails_when=userConfigRejection is dropped and the in-repo file // becomes the policy; why_new=the trust check is new; seam=none (userConfigPath is an existing buildContext option); - // no_claim=a symlinked state root (realish covers it, untested here) + // no_claim=a symlinked state root (the next test) test('a user path inside the repository or relative is ignored, with an explain line', () => { const { repo } = setup(); const inside = path.join(repo.work, '.gstack', 'projects', 'x', 'pregate.json'); @@ -230,15 +231,31 @@ describe('gstack-pregate with a user-owned policy', () => { } }, 60_000); - // Value: protects=--explain says when the user file was looked for and absent, and names a `local` id that matches no platform lane; + // Value: protects=the containment check sees through a symlinked state root and does not mistake an in-repo `..name` + // directory for a parent; fails_when=the realpath half or the `..`-segment test regresses and a file a PR committed is read + // as the user policy; why_new=both edges are new; seam=none; no_claim=case-only path differences (realpathSync.native) + test('a state root symlinked into the checkout, or under an in-repo ..name directory, is inside', () => { + const { repo } = setup(); + fs.mkdirSync(path.join(repo.work, '.st')); + const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'pregate-sr-')); + try { + const link = path.join(outside, 'root'); + fs.symlinkSync(path.join(repo.work, '.st'), link); + expect(userConfigRejection(repo.work, path.join(link, 'projects', 'x', 'pregate.json'))).toContain('inside the repository'); + expect(userConfigRejection(repo.work, path.join(repo.work, '..st', 'projects', 'x', 'pregate.json'))).toContain('inside the repository'); + expect(userConfigRejection(repo.work, path.join(outside, 'projects', 'x', 'pregate.json'))).toBeNull(); + } finally { fs.rmSync(outside, { recursive: true, force: true }); } + }); + + // Value: protects=--explain says when the user file was looked for and absent, and names a `local` id that matches no workflow lane; // fails_when=either line is dropped and a typo'd slug or lane id silently does nothing; why_new=both lines are new; seam=none; // no_claim=the line wording beyond its path and id - test('--explain names an absent user file and a local id that matches no platform lane', () => { + test('--explain names an absent user file and a local id that matches no workflow lane', () => { const { userPolicy, run } = setup(); expect(run(['--explain']).out).toContain(`user policy: ${userPolicy} (absent)`); writePolicy(userPolicy, { local: [...LOCAL_ALL, 'ci.yml/nope'] }); const r = run(['--explain']); - expect(r.out).toContain('local: ci.yml/nope matches no platform lane; ignored'); + expect(r.out).toContain('local: ci.yml/nope matches no workflow lane; ignored'); expect(r.out).not.toContain('local: free-tests.yml/unit matches'); }, 60_000);