The fork's complete state, v0.101.0 → v0.131.0

.gitattributes

@@ -1,3 +1,7 @@
+# Normalise text to LF in the repository and on checkout, so a Windows clone
+# does not report every file as modified after a formatter run.
+* text=auto eol=lf
+
 /.github            export-ignore
 /assets             export-ignore
 /bin                export-ignore
@@ -9,4 +13,17 @@
 /rector.php         export-ignore
 /Taskfile.yml       export-ignore
 /testbench.yaml     export-ignore
-/whisky.json        export-ignore
+/dev                export-ignore
+/composer-require-checker.json export-ignore
+
+# /docs itself SHIPS — the docs site renders markdown and the VitePress
+# sidebar out of vendor/particle-academy/prism/docs, and installs with
+# --prefer-dist, so export-ignoring the directory would take that site down.
+# Only the parts nothing reads at runtime are excluded: the 9.6M committed
+# build output, and the dev lockfile that makes dependency scanners flag
+# consumers for advisories in our docs toolchain.
+/docs/.vitepress/dist   export-ignore
+/docs/.vitepress/cache  export-ignore
+/docs/node_modules      export-ignore
+/docs/package.json      export-ignore
+/docs/package-lock.json export-ignore

.github/CODEOWNERS

@@ -0,0 +1,12 @@
+# Every path in this repository is owned by the project owner.
+#
+# Paired with the "main protection" branch ruleset, which requires a pull
+# request carrying an approving review from a code owner before anything can
+# land on the default branch. Outside contributions therefore cannot merge
+# without an explicit human review, and agents cannot approve on the owner's
+# behalf.
+#
+# Repository admins bypass the ruleset, so day-to-day direct pushes by the
+# owner are unaffected.
+
+* @wishborn

.github/RELEASING.md

@@ -0,0 +1,50 @@
+# Prism release preflight
+
+Complete this checklist on the release candidate **before pushing a tag**.
+Packagist publishes from the tag push. The Publish workflow can withhold the
+GitHub release and flag a bad tag; it cannot prevent or undo that publication.
+
+- [ ] Fetch current Prism and prism-parity main branches and Prism tags. Record
+  the full candidate SHA. Do not overwrite another contributor's working files.
+- [ ] Re-read every Prism claim against the candidate code, including unreleased
+  fixes. Use the shared checker's `--map` output as an inventory, and check nearby
+  behavior and numeric statements too: existence checks do not verify prose.
+  Fix drift and record what changed before reconciling. Commit the reviewed
+  Prism changes so the candidate checkout is clean.
+- [ ] If the Prism entry is stale, run the manual command below with the full
+  SHA that was reviewed. Inspect and commit only the Prism changes in the shared
+  lock, describe the reviewed SHA in that commit, and push prism-parity.
+- [ ] Run all four local gates: Pest, PHPStan, Pint plus Rector, and
+  composer-require-checker. Run the factcheck guard tests and the strict checker.
+- [ ] Confirm successful Tests, PHPStan, Formatting, Require Checker and
+  **strict Factcheck** CI runs on the exact candidate SHA. A successful run on a
+  previous commit or a PR merge commit is insufficient. After reconciling the
+  shared lock, rerun Factcheck on the candidate using workflow_dispatch.
+- [ ] Complete the prerelease security audit and obtain release approval.
+  Only the approved candidate may be tagged. Any candidate change repeats the
+  review and CI steps.
+
+From the Prism repository root, with prism-parity checked out beside it:
+
+```sh
+node ../prism-parity/tools/factcheck.mjs --repo . --map
+node .github/scripts/factcheck.mjs reconcile ../prism-parity FULL_REVIEWED_SHA
+node --test .github/scripts/factcheck.test.mjs .github/scripts/release-factcheck.test.mjs
+node .github/scripts/factcheck.mjs check ../prism-parity
+```
+
+The manual helper requires the supplied SHA to equal HEAD and a clean Prism
+checkout. The shared checker's raw `--reconcile` replaces the whole lock even
+with `--repo`; do not use it directly for a Prism-only review. The helper runs
+that operation in a temporary copy and merges only the Prism repo and package
+entries back into `prism-parity/tools/factcheck.lock.json`. Sibling evidence and
+the global reconciliation timestamp remain unchanged. Review the diff and stage
+that file explicitly, never unrelated work in prism-parity. CI never reconciles.
+
+The lock uses the nearest reachable tag, not a content digest. A new tag makes
+the lock stale even when the code is identical: the first push after each
+release will fail strict until its claims are reviewed and reconciled. The
+failure prints the lock path, recorded and current versions, and the manual
+command. Changes on the same tag are not detected by this currency heuristic;
+the pre-tag review remains necessary. A shared content-based attestation is
+separate work, not implemented by these guards.

.github/scripts/factcheck.mjs

@@ -0,0 +1,86 @@
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const [mode, parityArg, reviewedSha] = process.argv.slice(2);
+const repo = process.cwd();
+const parity = resolve(parityArg ?? '.parity');
+const lockPath = join(parity, 'tools/factcheck.lock.json');
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const read = path => JSON.parse(readFileSync(path, 'utf8'));
+const run = (root, ...args) => {
+  const result = spawnSync(process.execPath, [join(root, 'tools/factcheck.mjs'), '--repo', repo, ...args], { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+};
+
+/**
+ * Manual only: the shared --reconcile is not scope-safe, even with --repo.
+ * Run it in a temporary copy, then merge only repos.prism and
+ * packages['particle-academy/prism']; never replace any sibling's evidence.
+ * A reviewed SHA is an explicit operator assertion, not proof of a review.
+ */
+function reconcile() {
+  if (!reviewedSha || !/^[a-f0-9]{40}$/.test(reviewedSha) || reviewedSha !== git('rev-parse', 'HEAD')) {
+    throw new Error('Supply the full reviewed SHA, equal to HEAD, after re-reading every claim.');
+  }
+  if (git('status', '--porcelain', '--untracked-files=normal')) {
+    throw new Error('Reconciliation requires a clean Prism checkout; commit the reviewed changes first.');
+  }
+  const before = readFileSync(lockPath, 'utf8');
+  const original = JSON.parse(before);
+  if (original.contract !== '1.0' || !original.repos?.prism || !original.packages?.['particle-academy/prism']) {
+    throw new Error('Expected the existing contract 1.0 Prism entries; refusing to replace an unknown lock.');
+  }
+  const temp = mkdtempSync(join(tmpdir(), 'prism-reconcile-'));
+  try {
+    mkdirSync(join(temp, 'tools'));
+    cpSync(join(parity, 'tools/factcheck.mjs'), join(temp, 'tools/factcheck.mjs'));
+    cpSync(join(parity, 'docs/decisions'), join(temp, 'docs/decisions'), { recursive: true });
+    writeFileSync(join(temp, 'tools/factcheck.lock.json'), before);
+    if (run(temp, '--reconcile') !== 0) throw new Error('Reconciliation refused; the shared lock is unchanged.');
+    const updated = read(join(temp, 'tools/factcheck.lock.json'));
+    if (updated.packages?.['particle-academy/prism']?.published !== true) {
+      throw new Error('Could not confirm Prism publication; the shared lock is unchanged. Retry with network access.');
+    }
+    original.repos.prism = updated.repos.prism;
+    original.packages['particle-academy/prism'] = updated.packages['particle-academy/prism'];
+    // Validate the actual merged result, including preserved sibling publication
+    // evidence used by Prism's companion-package install documentation.
+    writeFileSync(join(temp, 'tools/factcheck.lock.json'), JSON.stringify(original, null, 2) + '\n');
+    if (run(temp, '--strict') !== 0) throw new Error('Reconciled claims still fail; the shared lock is unchanged.');
+    if (readFileSync(lockPath, 'utf8') !== before || git('rev-parse', 'HEAD') !== reviewedSha || git('status', '--porcelain', '--untracked-files=normal')) {
+      throw new Error('The lock or reviewed checkout changed during reconciliation. Re-read and retry.');
+    }
+    writeFileSync(lockPath, JSON.stringify(original, null, 2) + '\n');
+    console.log(`Reconciled only Prism at reviewed SHA ${reviewedSha} into ${lockPath}.`);
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+try {
+  if (basename(repo) !== 'prism' || read(join(repo, 'composer.json')).name !== 'particle-academy/prism') {
+    throw new Error('Run this command from the prism repository root.');
+  }
+  if (mode === 'reconcile') {
+    reconcile();
+  } else if (mode === 'check') {
+    const status = run(parity, '--strict');
+    if (status !== 0) {
+      console.error(`\nVerification lock: ${lockPath}`);
+      console.error(`Recorded Prism version: ${read(lockPath).repos?.prism?.version ?? 'unrecorded'}`);
+      console.error(`Current Prism version: ${git('describe', '--tags', '--abbrev=0')}`);
+      console.error('Fix findings and re-read the claims against current code BEFORE reconciling. From a clean Prism checkout with prism-parity beside it, run:');
+      console.error(`node .github/scripts/factcheck.mjs reconcile ../prism-parity ${git('rev-parse', 'HEAD')}`);
+      console.error('Review and commit only the Prism lock entry in prism-parity, push it, then rerun Factcheck. See .github/RELEASING.md. CI never reconciles.');
+    }
+    process.exitCode = status;
+  } else {
+    throw new Error('Usage: node .github/scripts/factcheck.mjs check <parity-path> | reconcile <parity-path> <reviewed-sha>');
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

.github/scripts/factcheck.test.mjs

@@ -0,0 +1,139 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const source = existsSync(join(root, '.parity/tools/factcheck.mjs'))
+  ? join(root, '.parity') : resolve(root, '../prism-parity');
+
+function fixture(t) {
+  const dir = mkdtempSync(join(tmpdir(), 'prism-factcheck-'));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const repo = join(dir, 'prism');
+  const parity = join(dir, 'prism-parity');
+  mkdirSync(join(repo, 'src'), { recursive: true });
+  mkdirSync(join(parity, 'tools'), { recursive: true });
+  cpSync(join(source, 'tools/factcheck.mjs'), join(parity, 'tools/factcheck.mjs'));
+  cpSync(join(source, 'docs/decisions'), join(parity, 'docs/decisions'), { recursive: true });
+  writeFileSync(join(repo, 'composer.json'), JSON.stringify({
+    name: 'particle-academy/prism', autoload: { 'psr-4': { 'Prism\\Prism\\': 'src/' } },
+  }));
+  writeFileSync(join(repo, 'src/Example.php'), '<?php namespace Prism\\Prism; class Example {}');
+  writeFileSync(join(repo, 'README.md'), '```php\nuse Prism\\Prism\\Example;\n```\n');
+  const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  git('init', '-q');
+  git('add', '.');
+  git('-c', 'user.name=Test', '-c', 'user.email=test@example.invalid', 'commit', '-qm', 'fixture');
+  git('tag', 'v0.130.0');
+  const sha = git('rev-parse', 'HEAD');
+  const lock = join(parity, 'tools/factcheck.lock.json');
+  const initial = {
+    contract: '1.0', reconciledAt: 'original timestamp', note: 'preserve this',
+    packages: { 'particle-academy/prism': { published: true }, 'particle-academy/sibling': { published: false, sentinel: 1 } },
+    repos: { prism: { version: 'v0.121.0', census: { 'php-class': 1 } }, sibling: { version: 'v9.9.9', census: { 'local-link': 42 } } },
+  };
+  writeFileSync(lock, JSON.stringify(initial, null, 2) + '\n');
+  // Only the test process tree stubs publication lookup; no network is needed.
+  const preload = join(dir, 'fetch.mjs');
+  writeFileSync(preload, 'globalThis.fetch = async () => ({status: 200});');
+  const run = (mode, reviewed = sha) => spawnSync(process.execPath,
+    [join(root, '.github/scripts/factcheck.mjs'), mode, parity, ...(mode === 'reconcile' ? [reviewed] : [])],
+    { cwd: repo, encoding: 'utf8', env: { ...process.env, NODE_OPTIONS: `--import=${pathToFileURL(preload).href}` } });
+  return { repo, parity, sha, lock, initial, run, git, preload };
+}
+
+test('stale claims fail with versions, lock path and a manual command; checking never writes', t => {
+  const f = fixture(t);
+  const before = readFileSync(f.lock, 'utf8');
+  const result = f.run('check');
+  assert.equal(result.status, 1);
+  const output = result.stdout + result.stderr;
+  for (const value of ['v0.121.0', 'v0.130.0', 'factcheck.lock.json', 'reconcile', f.sha]) assert.ok(output.includes(value), output);
+  assert.equal(readFileSync(f.lock, 'utf8'), before);
+});
+
+test('reviewed reconciliation preserves every sibling entry and unrelated lock field', t => {
+  const f = fixture(t);
+  const result = f.run('reconcile');
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  const after = JSON.parse(readFileSync(f.lock, 'utf8'));
+  assert.equal(after.repos.prism.version, 'v0.130.0');
+  assert.deepEqual(after.repos.prism.census, { 'php-class': 1 });
+  assert.equal(after.packages['particle-academy/prism'].published, true);
+  after.repos.prism = f.initial.repos.prism;
+  after.packages['particle-academy/prism'] = f.initial.packages['particle-academy/prism'];
+  assert.deepEqual(after, f.initial);
+  const checked = f.run('check');
+  assert.equal(checked.status, 0, checked.stdout + checked.stderr);
+});
+
+test('a wrong or absent reviewed SHA cannot change the lock', t => {
+  const f = fixture(t);
+  const before = readFileSync(f.lock, 'utf8');
+  for (const reviewed of ['', '0'.repeat(40)]) {
+    const result = f.run('reconcile', reviewed);
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /reviewed.*SHA/i);
+    assert.equal(readFileSync(f.lock, 'utf8'), before);
+  }
+});
+
+test('uncommitted claim edits cannot be attested by a committed SHA', t => {
+  const f = fixture(t);
+  const before = readFileSync(f.lock, 'utf8');
+  writeFileSync(join(f.repo, 'README.md'), 'Edited after review');
+  const result = f.run('reconcile');
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /clean|uncommitted/i);
+  assert.equal(readFileSync(f.lock, 'utf8'), before);
+});
+
+test('a broken documented class refuses reconciliation and preserves the entire lock', t => {
+  const f = fixture(t);
+  writeFileSync(join(f.repo, 'README.md'), '```php\nuse Prism\\Prism\\Missing;\n```\n');
+  f.git('add', 'README.md');
+  f.git('-c', 'user.name=Test', '-c', 'user.email=test@example.invalid', 'commit', '-qm', 'broken claim');
+  const before = readFileSync(f.lock, 'utf8');
+  const result = f.run('reconcile', f.git('rev-parse', 'HEAD'));
+  assert.notEqual(result.status, 0);
+  assert.match(result.stdout + result.stderr, /unresolved finding|No such class/);
+  assert.equal(readFileSync(f.lock, 'utf8'), before);
+});
+
+test('an unavailable publication lookup cannot overwrite verified publication data', t => {
+  const f = fixture(t);
+  writeFileSync(f.preload, 'globalThis.fetch = async () => { throw new Error("offline"); };');
+  const before = readFileSync(f.lock, 'utf8');
+  const result = f.run('reconcile');
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /publication/i);
+  assert.equal(readFileSync(f.lock, 'utf8'), before);
+});
+
+test('a concurrent shared-lock edit is preserved instead of overwritten', t => {
+  const f = fixture(t);
+  const concurrent = JSON.stringify({ ...f.initial, note: 'another review landed' }, null, 2) + '\n';
+  writeFileSync(f.preload, `import {writeFileSync} from 'node:fs'; globalThis.fetch = async () => {
+    writeFileSync(${JSON.stringify(f.lock)}, ${JSON.stringify(concurrent)}); return {status: 200};
+  };`);
+  const result = f.run('reconcile');
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /changed during reconciliation/);
+  assert.equal(readFileSync(f.lock, 'utf8'), concurrent);
+});
+
+test('post-reconcile verification uses the preserved sibling publication evidence', t => {
+  const f = fixture(t);
+  f.initial.packages['particle-academy/sibling'].published = true;
+  writeFileSync(f.lock, JSON.stringify(f.initial));
+  writeFileSync(join(f.repo, 'README.md'), '```sh\ncomposer require particle-academy/sibling\n```\n');
+  f.git('add', 'README.md');
+  f.git('-c', 'user.name=Test', '-c', 'user.email=test@example.invalid', 'commit', '-qm', 'sibling install');
+  const result = f.run('reconcile', f.git('rev-parse', 'HEAD'));
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.doesNotMatch(result.stdout + result.stderr, /Not in the published census/);
+});

.github/scripts/release-factcheck.mjs

@@ -0,0 +1,24 @@
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+export function requireFactcheck(runs, sha) {
+  // PR workflows can execute a synthetic merge commit instead of head_sha.
+  const found = runs.some(run => run.head_sha === sha && run.status === 'completed'
+    && run.conclusion === 'success' && ['push', 'workflow_dispatch', 'schedule'].includes(run.event));
+  if (!found) throw new Error(`No successful strict Factcheck run for ${sha}. Refusing to release.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const { GITHUB_REPOSITORY: repo, GITHUB_SHA: sha } = process.env;
+    if (!repo || !/^[a-f0-9]{40}$/.test(sha ?? '')) throw new Error('GITHUB_REPOSITORY and full GITHUB_SHA are required.');
+    const pages = JSON.parse(execFileSync('gh', ['api', '--paginate', '--slurp',
+      `repos/${repo}/actions/workflows/factcheck.yml/runs?head_sha=${sha}&per_page=100`,
+    ], { encoding: 'utf8' }));
+    requireFactcheck(pages.flatMap(page => page.workflow_runs), sha);
+    console.log(`Strict Factcheck succeeded for ${sha}.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

.github/scripts/release-factcheck.test.mjs

@@ -0,0 +1,19 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { requireFactcheck } from './release-factcheck.mjs';
+
+const sha = 'a'.repeat(40);
+const success = { head_sha: sha, status: 'completed', conclusion: 'success', event: 'push' };
+
+test('only completed successful checks on the exact commit qualify', () => {
+  assert.doesNotThrow(() => requireFactcheck([success], sha));
+  for (const runs of [[], [{ ...success, head_sha: 'b'.repeat(40) }], [{ ...success, status: 'in_progress' }], [{ ...success, conclusion: 'failure' }], [{ ...success, conclusion: 'skipped' }], [{ ...success, event: 'pull_request' }]]) {
+    assert.throws(() => requireFactcheck(runs, sha), /No successful strict Factcheck/);
+  }
+});
+
+test('manual and nightly runs can prove the exact candidate, regardless of unrelated runs', () => {
+  for (const event of ['workflow_dispatch', 'schedule']) {
+    assert.doesNotThrow(() => requireFactcheck([{ ...success, head_sha: 'b'.repeat(40) }, { ...success, event }], sha));
+  }
+});