ci: supersede #367 with combined tiered PR pipeline redesign (#369)

* ci: streamline PR pipeline gates

* test: annotate ci-test-scope stderr assertions for lint rule

---------

Co-authored-by: Colin <colin@solvely.net>

tests/ci-test-scope.test.cjs

@@ -0,0 +1,71 @@
+'use strict';
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'ci-test-scope.cjs');
+
+function scopeFor(files) {
+  const r = spawnSync(process.execPath, [SCRIPT, '--files', files.join(' ')], {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+  assert.strictEqual(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
+  return JSON.parse(r.stdout);
+}
+
+describe('ci-test-scope.cjs', () => {
+  test('docs-only changes do not request code matrix work', () => {
+    const result = scopeFor(['docs/usage.md']);
+    assert.strictEqual(result.code_changed, false);
+    assert.strictEqual(result.full_matrix, false);
+    assert.deepStrictEqual(result.targeted_tests, []);
+    assert.deepStrictEqual(result.windows_tests, []);
+  });
+
+  test('workflow changes request full matrix and workflow contract tests', () => {
+    const result = scopeFor(['.github/workflows/test.yml']);
+    assert.strictEqual(result.code_changed, true);
+    assert.strictEqual(result.full_matrix, true);
+    assert.ok(result.targeted_tests.includes('tests/workflow-shell-pinning.test.cjs'));
+    assert.ok(result.targeted_tests.includes('tests/release-tarball-smoke-workflow.test.cjs'));
+    assert.ok(result.windows_tests.includes('tests/workflow-shell-pinning.test.cjs'));
+  });
+
+  test('command changes request command tests without full parity matrix', () => {
+    const result = scopeFor(['commands/gsd/plan-phase.md']);
+    assert.strictEqual(result.code_changed, true);
+    assert.strictEqual(result.full_matrix, false);
+    assert.ok(result.targeted_tests.includes('tests/command-contract.test.cjs'));
+    assert.ok(result.targeted_tests.includes('tests/commands.test.cjs'));
+  });
+
+  test('changed test files are selected directly', () => {
+    const result = scopeFor(['tests/run-tests-harness.test.cjs']);
+    assert.strictEqual(result.code_changed, true);
+    assert.ok(result.targeted_tests.includes('tests/run-tests-harness.test.cjs'));
+  });
+
+  test('installer-sensitive changes request full matrix and install tests', () => {
+    const result = scopeFor(['bin/gsd']);
+    assert.strictEqual(result.code_changed, true);
+    assert.strictEqual(result.full_matrix, true);
+    assert.ok(result.targeted_tests.includes('tests/install.test.cjs'));
+    assert.ok(result.targeted_tests.includes('tests/release-tarball-smoke.install.test.cjs'));
+  });
+
+  test('missing required CLI values fail with usage', () => {
+    const r = spawnSync(process.execPath, [SCRIPT, '--files'], {
+      cwd: ROOT,
+      encoding: 'utf8',
+    });
+    assert.notStrictEqual(r.status, 0);
+    // allow-test-rule: CLI usage failure text is user-facing contract for this parser guard.
+    assert.match(r.stderr, /--files requires a value/);
+    // allow-test-rule: CLI usage banner presence is a user-facing contract.
+    assert.match(r.stderr, /Usage:/);
+  });
+});

tests/run-tests-harness.test.cjs

@@ -93,6 +93,29 @@ describe('run-tests.cjs harness (issue #3597)', () => {
       const r = runHarness(tmpDir, ['--suite=security']);
       assert.strictEqual(r.status, 0, `stderr: ${r.stderr}\nstdout: ${r.stdout}`);
     });
+
+    test('missing --files value exits non-zero', () => {
+      seed(tmpDir, ['a.test.cjs']);
+      const r = runHarness(tmpDir, ['--files']);
+      assert.notStrictEqual(r.status, 0);
+      assert.match(r.stderr, /--files requires a value/i);
+    });
+
+    test('duplicate --files flag is rejected', () => {
+      seed(tmpDir, ['a.test.cjs']);
+      const r = runHarness(tmpDir, ['--files', 'a.test.cjs', '--files', 'a.test.cjs']);
+      assert.notStrictEqual(r.status, 0);
+      assert.match(r.stderr, /duplicate --files/i);
+    });
+
+    test('--files and --files-from cannot be combined', () => {
+      seed(tmpDir, ['a.test.cjs']);
+      const listPath = path.join(tmpDir, 'selected-tests.txt');
+      fs.writeFileSync(listPath, 'a.test.cjs\n', 'utf8');
+      const r = runHarness(tmpDir, ['--files', 'a.test.cjs', '--files-from', listPath]);
+      assert.notStrictEqual(r.status, 0);
+      assert.match(r.stderr, /cannot be combined/i);
+    });
   });
 
   describe('suite filtering', () => {
@@ -192,6 +215,35 @@ describe('run-tests.cjs harness (issue #3597)', () => {
     });
   });
 
+  describe('explicit file selection', () => {
+    test('--files runs only the named tests', () => {
+      seed(tmpDir, ['a.test.cjs', 'b.security.test.cjs', 'c.test.cjs']);
+      const r = runHarness(tmpDir, ['--files', 'a.test.cjs tests/c.test.cjs']);
+      assert.strictEqual(r.status, 0, `stderr: ${r.stderr}`);
+      assert.ok(r.stderr.includes('a.test.cjs'));
+      assert.ok(r.stderr.includes('c.test.cjs'));
+      assert.ok(!r.stderr.includes('b.security.test.cjs'));
+    });
+
+    test('--files-from runs tests listed in a file', () => {
+      seed(tmpDir, ['a.test.cjs', 'b.security.test.cjs', 'c.test.cjs']);
+      const listPath = path.join(tmpDir, 'selected-tests.txt');
+      fs.writeFileSync(listPath, 'a.test.cjs\nb.security.test.cjs\n', 'utf8');
+      const r = runHarness(tmpDir, ['--files-from', listPath]);
+      assert.strictEqual(r.status, 0, `stderr: ${r.stderr}`);
+      assert.ok(r.stderr.includes('a.test.cjs'));
+      assert.ok(r.stderr.includes('b.security.test.cjs'));
+      assert.ok(!r.stderr.includes('c.test.cjs'));
+    });
+
+    test('missing explicit test file exits non-zero', () => {
+      seed(tmpDir, ['a.test.cjs']);
+      const r = runHarness(tmpDir, ['--files', 'a.test.cjs missing.test.cjs']);
+      assert.notStrictEqual(r.status, 0);
+      assert.match(r.stderr, /requested test file\(s\) not found: missing\.test\.cjs/i);
+    });
+  });
+
   describe('failure propagation', () => {
     test('non-zero from node:test propagates through harness', () => {
       const FAIL = `'use strict';