Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

fix(gate): classify own source checks without a browser [C7]

Corey Olson943376e885d5
diff --git a/src/browser-admission.js b/src/browser-admission.js
index f344a0b6..f8624e8b 100644
--- a/src/browser-admission.js
+++ b/src/browser-admission.js
@@ -29,6 +29,18 @@ const CHROME_FIXTURE = 'test/chrome-fixture.js';
const FIXTURE_CHILD = 'test/fixture-child.js';
const JOURNEYS_TEST = 'test/journeys.test.js';
const TEST_RUNNER = 'bin/run-tests.js';
+/** Fixed source-only entry points belong to this tool's repository, never to a project's labels. */
+const SOURCE_CHECKS = [
+ { args: ['bin/static-style-checks.js'], file: 'bin/static-style-checks.js', doctrine: true },
+ { args: ['--experimental-vm-modules', '--disable-warning=ExperimentalWarning', 'bin/static-style-checks.js'], file: 'bin/static-style-checks.js', doctrine: true },
+ { args: ['bin/pullboard.js', 'doctrine', 'check'], file: 'bin/pullboard.js', doctrine: true },
+ { args: ['bin/pullboard.js', 'spec', 'check'], file: 'bin/pullboard.js' },
+ { args: ['bin/checks/file-size.js'], file: 'bin/checks/file-size.js' },
+ { args: ['bin/checks/empty-catch.js'], file: 'bin/checks/empty-catch.js' },
+ { args: ['bin/checks/test-names.js'], file: 'bin/checks/test-names.js' },
+ { args: ['bin/checks/test-inputs.js'], file: 'bin/checks/test-inputs.js' },
+];
+const DOCTRINE_CHECKS = new Set(['bin/checks/file-size.js', 'bin/checks/empty-catch.js', 'bin/checks/test-names.js', 'bin/checks/test-inputs.js']);
/**
* Chrome fixture exports that neither start a browser nor yield a browser path or launch arguments; any
* other binding, findChromeExecutable and a new export included, counts as a launch. These six only work
@@ -300,10 +312,79 @@ function unclassifiedNodeOptions(value) {
return String(value ?? '').split(/\s+/u).filter(Boolean).some(token => token !== SLOT_GUARD_IMPORT);
}
+/** Identify a real repository root and its shared Git directory without inherited Git selectors. */
+async function sourceRepository(root) {
+ const fields = git(root, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'], {
+ env: cleanGitEnvironment(),
+ }).split('\n');
+ if (fields.length !== 2 || await realpath(fields[0]) !== await realpath(root)) return null;
+ return realpath(fields[1]);
+}
+
+/** Require a regular committed entry or a non-symlink working entry contained in its repository. */
+async function regularCheckSource(root, file, committed) {
+ if (committed) return committedSource(root, committed, file) !== null;
+ const absolute = resolve(root, file);
+ const info = await lstat(absolute);
+ return info.isFile() && !info.isSymbolicLink() && await staysInside(root, absolute);
+}
+
+/** Read the exact executable doctrine rules without running them; only the fixed readers qualify. */
+async function sourceOnlyDoctrine(root, committed, commit, env) {
+ const [{ configFromSource, loadConfig }, { parseSpec }, { checkRule }] = await Promise.all([
+ import('./config.js'), import('./spec.js'), import('./doctrine-checks.js'),
+ ]);
+ const config = commit ? configFromSource(committedSource(root, committed, 'pullboard.json')) : loadConfig(root);
+ let file = config.practice;
+ if (['DOCTRINE.md', 'PRACTICE.md'].includes(file)) {
+ const names = ['DOCTRINE.md', 'PRACTICE.md'].filter(name => committed.has(name));
+ if (names.length !== 1) return false;
+ [file] = names;
+ }
+ if (repositoryPath(root, file) !== file) return false;
+ const source = committedSource(root, committed, file);
+ if (source === null) return false;
+ const parsed = parseSpec(source, { strictGrammarVersion: false });
+ if (parsed.problems.length) return false;
+ for (const row of parsed.rows.filter(row => row.status === 'approved')) {
+ const rule = checkRule(row);
+ if (!rule) {
+ if (/^check(?:\s|$)/u.test(row.gate)) return false;
+ continue;
+ }
+ const words = literalShellWords(rule.command);
+ if (words?.length !== 2 || !DOCTRINE_CHECKS.has(words[1])) return false;
+ const node = resolveExecutable(words[0], env.PATH);
+ if (!node || await realpath(node) !== await realpath(process.execPath)) return false;
+ if (!await regularCheckSource(root, words[1], commit ? committed : null)) return false;
+ }
+ return true;
+}
+
+/** Recognize only this tool's own fixed source commands; every uncertain identity keeps browser admission. */
+async function ownSourceCheck(root, words, { commit, env }) {
+ const known = SOURCE_CHECKS.find(entry => entry.args.length === words.length - 1
+ && entry.args.every((word, index) => word === words[index + 1]));
+ if (!known) return false;
+ try {
+ const node = resolveExecutable(words[0], env.PATH);
+ if (!node || await realpath(node) !== await realpath(process.execPath)) return false;
+ const own = await sourceRepository(resolve(import.meta.dirname, '..'));
+ if (!own || own !== await sourceRepository(root)) return false;
+ const revision = commit ?? git(root, ['rev-parse', '--verify', 'HEAD'], { env: cleanGitEnvironment() });
+ const committed = committedFiles(root, revision);
+ if (!committed || !await regularCheckSource(root, known.file, commit ? committed : null)) return false;
+ return !known.doctrine || await sourceOnlyDoctrine(root, committed, commit, env);
+ } catch {
+ return false; // Missing, foreign or unreadable source must keep the existing browser-required fallback.
+ }
+}
+
/** Parse the frozen check and classify its explicit test files, failing closed on unknown shell. */
export async function checkNeedsBrowser(root, command, { commit, env = process.env, onFallback } = {}) {
if (unclassifiedNodeOptions(env.NODE_OPTIONS)) return browserFallback(onFallback, '<frozen check>', 'NODE_OPTIONS may load an unclassified module');
let words = literalShellWords(command);
+ if (words && await ownSourceCheck(root, words, { commit, env })) return false;
if (!words) {
const inner = capturedRunner(command);
if (!inner) return browserFallback(onFallback, '<frozen check>', 'shell syntax is outside the supported literal capture form');
diff --git a/test/test-resources.test.js b/test/test-resources.test.js
index 1782a478..c6880f64 100644
--- a/test/test-resources.test.js
+++ b/test/test-resources.test.js
@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { delimiter, dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
import { test } from 'node:test';
import { browserBoundFiles, checkNeedsBrowser, testsNeedBrowser } from '../src/browser-admission.js';
import { browserInCall } from '../src/browser-slot-guard.js';
@@ -34,6 +35,98 @@ function commitSourceFixture(root) {
return head.stdout.trim();
}
+test("the repo's own static checks never take a browser slot [C7]", async t => {
+ const root = resolve(import.meta.dirname, '..');
+ const env = { ...process.env, NODE_OPTIONS: '', PATH: [dirname(process.execPath), '/usr/bin', '/bin'].join(delimiter) };
+ const configured = JSON.parse(readFileSync(join(root, 'pullboard.json'), 'utf8')).staticChecks;
+ assert.equal(await checkNeedsBrowser(root, configured, { env }), false, 'the declared static command is browser-free');
+ const commands = [
+ 'node bin/static-style-checks.js',
+ 'node bin/pullboard.js doctrine check',
+ 'node bin/pullboard.js spec check',
+ 'node bin/checks/file-size.js',
+ 'node bin/checks/empty-catch.js',
+ ];
+ for (const command of commands) assert.equal(await checkNeedsBrowser(root, command, { env }), false, command);
+ assert.equal(await checkNeedsBrowser(root, configured, { env: { ...env, NODE_OPTIONS: '--import=unknown.mjs' } }), true);
+ const guard = `--import=${new URL('../src/browser-slot-guard.js', import.meta.url).href}`;
+ assert.equal(await checkNeedsBrowser(root, configured, { env: { ...env, NODE_OPTIONS: `${guard} --require=unknown.cjs` } }), true);
+ for (const command of [
+ 'node bin/unknown.js', 'node bin/pullboard.js view', 'node bin/pullboard.js doctrine check extra',
+ 'node bin/static-style-checks.js extra', 'node bin/checks/file-size.js --browser',
+ 'env node bin/static-style-checks.js', 'nice node bin/static-style-checks.js',
+ 'sh -c "node bin/static-style-checks.js"', 'npm run static',
+ 'node --require=unknown.cjs bin/static-style-checks.js',
+ 'node --import=unknown.mjs bin/static-style-checks.js',
+ 'node --eval="import(\'./browser.mjs\')"',
+ 'node bin/static-style-checks.js; node browser.js',
+ 'node bin/static-style-checks.js && node browser.js',
+ 'node bin/static-style-checks.js | node browser.js',
+ 'node bin/static-style-checks.js > result',
+ 'node bin/static-style-checks.js &',
+ 'node $(printf bin/static-style-checks.js)',
+ 'node bin/static-style-checks.js\nnode browser.js',
+ ]) assert.equal(await checkNeedsBrowser(root, command, { env }), true, command);
+
+ const doctrine = '# Doctrine\n\n## Checks\n'
+ + '- C9 [approved, must] Source files stay bounded. | gate: check node bin/checks/file-size.js | count: 0\n'
+ + '- C8 [approved, must] Empty catches explain their handling. | gate: check node bin/checks/empty-catch.js | count: 0\n';
+ const foreign = sourceFixture(t, {
+ 'package.json': '{"name":"pullboard","type":"module"}\n',
+ 'pullboard.json': readFileSync(join(root, 'pullboard.json'), 'utf8'),
+ 'DOCTRINE.md': doctrine,
+ 'bin/browser-rule.js': "import { writeFileSync } from 'node:fs'; writeFileSync(new URL('../rule-executed', import.meta.url), 'bad');\n",
+ });
+ cpSync(join(root, 'src'), join(foreign, 'src'), { recursive: true });
+ cpSync(join(root, 'bin'), join(foreign, 'bin'), { recursive: true });
+ const good = commitSourceFixture(foreign);
+ for (const command of [configured, ...commands]) {
+ assert.equal(await checkNeedsBrowser(foreign, command, { env }), true, `a foreign project cannot borrow the command name: ${command}`);
+ }
+
+ // A private copy of the production classifier models its own trusted source repository.
+ const { checkNeedsBrowser: classifyPrivate } = await import(pathToFileURL(join(foreign, 'src/browser-admission.js')).href);
+ const aggregates = [configured, 'node bin/pullboard.js doctrine check'];
+ for (const command of aggregates) assert.equal(await classifyPrivate(foreign, command, { env, commit: good }), false, 'the trusted branch accepts only known rules');
+ const unknown = doctrine + '- C10 [approved, must] Run another check. | gate: check node bin/browser-rule.js | count: 0\n';
+ writeFileSync(join(foreign, 'DOCTRINE.md'), unknown);
+ const bad = commitSourceFixture(foreign);
+ writeFileSync(join(foreign, 'DOCTRINE.md'), doctrine);
+ for (const command of aggregates) {
+ assert.equal(await classifyPrivate(foreign, command, { env, commit: bad }), true, 'an unknown committed rule needs a browser even when working doctrine is safe');
+ assert.equal(await classifyPrivate(foreign, command, { env }), true, 'HEAD doctrine, not its uncommitted replacement, controls execution');
+ assert.equal(await classifyPrivate(foreign, command, { env, commit: good }), false, 'an explicit clean revision does not borrow rules from the current HEAD');
+ }
+ const customConfig = JSON.parse(readFileSync(join(foreign, 'pullboard.json'), 'utf8'));
+ customConfig.practice = 'CUSTOM.md';
+ writeFileSync(join(foreign, 'pullboard.json'), `${JSON.stringify(customConfig)}\n`);
+ writeFileSync(join(foreign, 'CUSTOM.md'), unknown);
+ const custom = commitSourceFixture(foreign);
+ for (const command of aggregates) assert.equal(await classifyPrivate(foreign, command, { env, commit: custom }), true, 'a configured doctrine path cannot hide its arbitrary rule');
+ assert.equal(existsSync(join(foreign, 'rule-executed')), false, 'classification never executes a rule or its script');
+ customConfig.practice = 'DOCTRINE.md';
+ writeFileSync(join(foreign, 'pullboard.json'), `${JSON.stringify(customConfig)}\n`);
+ writeFileSync(join(foreign, 'DOCTRINE.md'), doctrine);
+ commitSourceFixture(foreign);
+ assert.equal(await classifyPrivate(foreign, configured, { env }), false, 'the later path controls begin with a known browser-free aggregate');
+ assert.equal(await classifyPrivate(foreign, configured, { env, commit: '0'.repeat(40) }), true, 'missing committed sources fail closed');
+
+ const shadow = join(foreign, 'shadow');
+ mkdirSync(shadow);
+ writeFileSync(join(shadow, 'node'), '#!/bin/sh\nexit 0\n');
+ chmodSync(join(shadow, 'node'), 0o755);
+ assert.equal(await checkNeedsBrowser(root, configured, { env: { ...env, PATH: [shadow, env.PATH].join(delimiter) } }), true, 'a shadow Node is not the current runtime');
+ const entry = join(foreign, 'bin/static-style-checks.js');
+ rmSync(entry);
+ symlinkSync(join(root, 'bin/static-style-checks.js'), entry);
+ assert.equal(await classifyPrivate(foreign, 'node bin/static-style-checks.js', { env }), true, 'a symlinked static entry point is uncertain');
+ rmSync(entry);
+ mkdirSync(entry);
+ assert.equal(await classifyPrivate(foreign, 'node bin/static-style-checks.js', { env }), true, 'a directory is not the static script');
+ rmSync(entry, { recursive: true });
+ assert.equal(await classifyPrivate(foreign, 'node bin/static-style-checks.js', { env }), true, 'a missing static script is uncertain');
+});
+
test('ordinary focused tests need no browser and admission never executes their modules [C7]', async t => {
const root = sourceFixture(t, {
'test/plain.test.js': "import '../helper.js'; import assert from 'node:assert/strict';",