|
| 1 | +#!/usr/bin/env node |
| 2 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 3 | + |
| 4 | +/** |
| 5 | + * Call-site census of the vouched-reference mark. |
| 6 | + * |
| 7 | + * node scripts/check-vouch-for-reference-callers.mjs |
| 8 | + * node scripts/check-vouch-for-reference-callers.mjs --self-test |
| 9 | + * |
| 10 | + * ## The rule it holds |
| 11 | + * |
| 12 | + * A write that is not a system write may name, in a `lookup`, `user` or |
| 13 | + * `master_detail` field, only a record its caller's own read door returns |
| 14 | + * (`assertReferencesResolve`, objectql). The one exception is a reference a |
| 15 | + * service verb vouches for on its own write (`vouchForReference`, |
| 16 | + * `@objectstack/core`): a record the same call authorized for the caller, set |
| 17 | + * only after that verb's own authorization, and never on a context a request, |
| 18 | + * an import, a flow or an agent tool hands the engine. Whether a call site |
| 19 | + * honours that is a judgement a reviewer makes once, when the call site is |
| 20 | + * written. This gate makes sure no call site arrives without that review: every |
| 21 | + * production source file that sets the mark is named in {@link ALLOWED_CALLERS} |
| 22 | + * with the exact number of call sites it holds, and the gate is red when a file |
| 23 | + * outside the list sets it, when a listed file holds more or fewer call sites |
| 24 | + * than its row, and when a row names a file that no longer sets it. |
| 25 | + * |
| 26 | + * "Sets the mark" is decided three ways, each a spelling that reaches the same |
| 27 | + * context key: |
| 28 | + * |
| 29 | + * 1. a call `vouchForReference(` (not a mention in a comment or in backticks); |
| 30 | + * 2. an import that renames it (`vouchForReference as …`), which would hide |
| 31 | + * every later call from (1); |
| 32 | + * 3. the key itself, outside the module that defines it — `VOUCHED_REFERENCES` |
| 33 | + * used as a computed property, or `Symbol.for('objectstack.core.vouchedReferences')` |
| 34 | + * spelled anywhere else — a context built with the key by hand. |
| 35 | + * |
| 36 | + * Test files (`*.test.*`, `*.spec.*`, `*.testkit.*`, `__tests__/`) are outside |
| 37 | + * the census: they set the mark on purpose to pin what it admits. |
| 38 | + * |
| 39 | + * The scan surface is git's (`git ls-files --cached --others --exclude-standard` |
| 40 | + * under `packages/`), so build output never reads as a call site. |
| 41 | + * |
| 42 | + * Adding a caller is an edit to {@link ALLOWED_CALLERS} in the same change, |
| 43 | + * with the reason in the row: what the verb created or authorized for the |
| 44 | + * caller, and which authorization it asked first. |
| 45 | + */ |
| 46 | + |
| 47 | +import { execFileSync } from 'node:child_process'; |
| 48 | +import { readFileSync } from 'node:fs'; |
| 49 | +import { dirname, join } from 'node:path'; |
| 50 | +import { fileURLToPath } from 'node:url'; |
| 51 | +import { isEntrypoint } from './invoked-as.mjs'; |
| 52 | + |
| 53 | +const REPO = join(dirname(fileURLToPath(import.meta.url)), '..'); |
| 54 | + |
| 55 | +/** The module that defines the mark; its own spellings are not call sites. */ |
| 56 | +const DEFINING_MODULE = 'packages/core/src/security/vouched-reference.ts'; |
| 57 | + |
| 58 | +/** |
| 59 | + * Every production file that sets the mark, with its exact call-site count and |
| 60 | + * the reason it may. Equality, not a ceiling: one more call site is a new |
| 61 | + * vouch nobody reviewed, one fewer is a row that no longer says what the file |
| 62 | + * does. |
| 63 | + */ |
| 64 | +export const ALLOWED_CALLERS = Object.freeze({ |
| 65 | + 'packages/services/service-storage/src/file-attachment-service.ts': { |
| 66 | + count: 2, |
| 67 | + reason: |
| 68 | + 'the file-attachments writer: attachFileAs vouches for the sys_file it created in the same call, and ' + |
| 69 | + "attachUploadAs for the caller's own unheld pending upload it commits in the same unit — each only for " + |
| 70 | + 'sys_attachment.file_id, after that verb\'s own attach authorization', |
| 71 | + }, |
| 72 | +}); |
| 73 | + |
| 74 | +const SOURCE_FILE = /\.(?:[cm]?ts|tsx|[cm]?js|jsx)$/; |
| 75 | +const TEST_FILE = /(?:\.test\.|\.spec\.|\.testkit\.|\/__tests__\/|\/__fixtures__\/)/; |
| 76 | + |
| 77 | +/** A line that is a comment, by its first non-blank characters. */ |
| 78 | +const isCommentLine = (line) => /^\s*(?:\/\/|\/\*|\*)/.test(line); |
| 79 | + |
| 80 | +/** Strip backtick-quoted spans, so prose naming `vouchForReference(` is no call. */ |
| 81 | +const withoutBacktickSpans = (line) => line.replace(/`[^`]*`/g, '``'); |
| 82 | + |
| 83 | +/** |
| 84 | + * The census of one file's text: its call sites and the spellings that would |
| 85 | + * hide or bypass one. |
| 86 | + */ |
| 87 | +export function censusOf(path, text) { |
| 88 | + let calls = 0; |
| 89 | + const findings = []; |
| 90 | + const lines = String(text).split('\n'); |
| 91 | + lines.forEach((raw, index) => { |
| 92 | + if (isCommentLine(raw)) return; |
| 93 | + const line = withoutBacktickSpans(raw.replace(/\/\/.*$/, '')); |
| 94 | + const where = `${path}:${index + 1}`; |
| 95 | + const callHits = line.match(/\bvouchForReference\s*\(/g); |
| 96 | + if (callHits && path !== DEFINING_MODULE) calls += callHits.length; |
| 97 | + if (/\bvouchForReference\s+as\s+\w/.test(line)) { |
| 98 | + findings.push(`${where}: renames vouchForReference on import — every later call would hide from this census`); |
| 99 | + } |
| 100 | + if (path === DEFINING_MODULE) return; |
| 101 | + if (/\[\s*VOUCHED_REFERENCES\s*\]/.test(line)) { |
| 102 | + findings.push(`${where}: builds the mark's key by hand ([VOUCHED_REFERENCES]) — call vouchForReference instead`); |
| 103 | + } |
| 104 | + if (/Symbol\.for\(\s*['"]objectstack\.core\.vouchedReferences['"]\s*\)/.test(line)) { |
| 105 | + findings.push(`${where}: spells the mark's symbol by hand — call vouchForReference instead`); |
| 106 | + } |
| 107 | + }); |
| 108 | + return { calls, findings }; |
| 109 | +} |
| 110 | + |
| 111 | +/** The verdict over a set of `{ path, text }` files against `allowed`. */ |
| 112 | +export function check(files, allowed = ALLOWED_CALLERS) { |
| 113 | + const problems = []; |
| 114 | + if (files.length === 0) { |
| 115 | + problems.push('the scan found no source files at all — an empty scan proves nothing, so it is refused'); |
| 116 | + return { problems, counts: new Map() }; |
| 117 | + } |
| 118 | + const counts = new Map(); |
| 119 | + for (const { path, text } of files) { |
| 120 | + if (!SOURCE_FILE.test(path) || TEST_FILE.test(path)) continue; |
| 121 | + const { calls, findings } = censusOf(path, text); |
| 122 | + problems.push(...findings); |
| 123 | + if (calls > 0) counts.set(path, calls); |
| 124 | + } |
| 125 | + for (const [path, calls] of counts) { |
| 126 | + const row = allowed[path]; |
| 127 | + if (!row) { |
| 128 | + problems.push( |
| 129 | + `${path}: sets the vouched-reference mark ${calls} time(s) and is not in ALLOWED_CALLERS. A vouch lets one ` + |
| 130 | + "reference skip the caller's read door; add the row with its reason only after review, or write as the caller.", |
| 131 | + ); |
| 132 | + } else if (row.count !== calls) { |
| 133 | + problems.push( |
| 134 | + `${path}: sets the vouched-reference mark ${calls} time(s); its ALLOWED_CALLERS row pins ${row.count}. ` + |
| 135 | + 'Every call site is reviewed on its own: update the row (and its reason) in the same change.', |
| 136 | + ); |
| 137 | + } |
| 138 | + } |
| 139 | + for (const path of Object.keys(allowed)) { |
| 140 | + if (!counts.has(path)) { |
| 141 | + problems.push(`${path}: is in ALLOWED_CALLERS and no longer sets the mark — remove the stale row.`); |
| 142 | + } |
| 143 | + } |
| 144 | + return { problems, counts }; |
| 145 | +} |
| 146 | + |
| 147 | +/** The files the census reads: what git sees under `packages/`, never build output. */ |
| 148 | +function readTree() { |
| 149 | + const out = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', 'packages'], { |
| 150 | + cwd: REPO, |
| 151 | + encoding: 'utf8', |
| 152 | + maxBuffer: 256 * 1024 * 1024, |
| 153 | + }); |
| 154 | + const files = []; |
| 155 | + for (const path of out.split('\0')) { |
| 156 | + if (!path || !SOURCE_FILE.test(path) || TEST_FILE.test(path)) continue; |
| 157 | + let text; |
| 158 | + try { |
| 159 | + text = readFileSync(join(REPO, path), 'utf8'); |
| 160 | + } catch { |
| 161 | + continue; // listed by git, deleted in the working tree |
| 162 | + } |
| 163 | + if (!text.includes('vouchForReference') && !text.includes('VOUCHED_REFERENCES') && !text.includes('vouchedReferences')) { |
| 164 | + text = ''; |
| 165 | + } |
| 166 | + files.push({ path, text }); |
| 167 | + } |
| 168 | + return files; |
| 169 | +} |
| 170 | + |
| 171 | +// ── Self-test ────────────────────────────────────────────────────────────── |
| 172 | +// |
| 173 | +// Table-driven, as `check-agent-model-declared.mjs`'s: each row LABEL is a |
| 174 | +// declared battery with a floor of 1, registered as the first statement of the |
| 175 | +// loop body; the roster's own size is pinned; and the verdict sets a flag the |
| 176 | +// dispatch refuses without (AGENTS.md, "Writing a --self-test"). |
| 177 | + |
| 178 | +let selfTestReachedVerdict = false; |
| 179 | + |
| 180 | +const SELF_TEST_BATTERIES = Object.freeze({ |
| 181 | + 'an allow-listed file with exactly its pinned call sites → GREEN': 1, |
| 182 | + 'a call from a file outside the allow-list → RED': 1, |
| 183 | + 'an allow-listed file with one more call site than its row → RED': 1, |
| 184 | + 'an allow-listed file with one fewer call site than its row → RED': 1, |
| 185 | + 'a row naming a file that no longer sets the mark → RED (stale row)': 1, |
| 186 | + 'an import that renames vouchForReference → RED': 1, |
| 187 | + 'the key built by hand as [VOUCHED_REFERENCES] → RED': 1, |
| 188 | + "the symbol spelled by hand with Symbol.for → RED": 1, |
| 189 | + 'a test file that sets the mark → GREEN (outside the census)': 1, |
| 190 | + 'a comment or backtick mention is no call site → GREEN': 1, |
| 191 | + 'the defining module’s own spellings → GREEN': 1, |
| 192 | + 'an empty scan → RED, never a green skip': 1, |
| 193 | +}); |
| 194 | +const SELF_TEST_BATTERY_FLOOR = 12; |
| 195 | + |
| 196 | +function selfTest() { |
| 197 | + const VERB = 'packages/services/demo/src/verb.ts'; |
| 198 | + const OTHER = 'packages/rest/src/door.ts'; |
| 199 | + const ALLOW = { [VERB]: { count: 1, reason: 'demo' } }; |
| 200 | + const call = " const ctx = vouchForReference(context, { object: 'o', field: 'f', id });\n"; |
| 201 | + const filler = { path: 'packages/core/src/other.ts', text: 'export const x = 1;\n' }; |
| 202 | + |
| 203 | + const cases = [ |
| 204 | + { label: 'an allow-listed file with exactly its pinned call sites → GREEN', files: [{ path: VERB, text: call }], expect: 'green' }, |
| 205 | + { label: 'a call from a file outside the allow-list → RED', files: [{ path: VERB, text: call }, { path: OTHER, text: call }], expect: 'red', names: OTHER }, |
| 206 | + { label: 'an allow-listed file with one more call site than its row → RED', files: [{ path: VERB, text: call + call }], expect: 'red', names: VERB }, |
| 207 | + { label: 'an allow-listed file with one fewer call site than its row → RED', files: [{ path: VERB, text: call }], allow: { [VERB]: { count: 2, reason: 'demo' } }, expect: 'red', names: VERB }, |
| 208 | + { label: 'a row naming a file that no longer sets the mark → RED (stale row)', files: [filler], expect: 'red', names: VERB }, |
| 209 | + { label: 'an import that renames vouchForReference → RED', files: [{ path: VERB, text: call }, { path: OTHER, text: "import { vouchForReference as vouch } from '@objectstack/core';\n" }], expect: 'red', names: OTHER }, |
| 210 | + { label: 'the key built by hand as [VOUCHED_REFERENCES] → RED', files: [{ path: VERB, text: call }, { path: OTHER, text: ' const ctx = { ...context, [VOUCHED_REFERENCES]: [ref] };\n' }], expect: 'red', names: OTHER }, |
| 211 | + { label: "the symbol spelled by hand with Symbol.for → RED", files: [{ path: VERB, text: call }, { path: OTHER, text: " const k = Symbol.for('objectstack.core.vouchedReferences');\n" }], expect: 'red', names: OTHER }, |
| 212 | + { label: 'a test file that sets the mark → GREEN (outside the census)', files: [{ path: VERB, text: call }, { path: 'packages/rest/src/door.test.ts', text: call + ' ({ [VOUCHED_REFERENCES]: [] });\n' }], expect: 'green' }, |
| 213 | + { label: 'a comment or backtick mention is no call site → GREEN', files: [{ path: VERB, text: call }, { path: OTHER, text: '// vouchForReference(context, ref) is the verb\'s\n * see vouchForReference( here\nconst s = `vouchForReference(x)`;\n' }], expect: 'green' }, |
| 214 | + { label: 'the defining module’s own spellings → GREEN', files: [{ path: VERB, text: call }, { path: DEFINING_MODULE, text: "export const VOUCHED_REFERENCES = Symbol.for('objectstack.core.vouchedReferences');\nexport function vouchForReference(context, reference) {\n return { ...context, [VOUCHED_REFERENCES]: [] };\n}\n" }], expect: 'green' }, |
| 215 | + { label: 'an empty scan → RED, never a green skip', files: [], expect: 'red', names: 'no source files' }, |
| 216 | + ]; |
| 217 | + |
| 218 | + const batterySeen = new Map(); |
| 219 | + let failed = 0; |
| 220 | + for (const c of cases) { |
| 221 | + batterySeen.set(c.label, (batterySeen.get(c.label) ?? 0) + 1); |
| 222 | + const { problems } = check(c.files, c.allow ?? ALLOW); |
| 223 | + const red = problems.length > 0; |
| 224 | + const ok = |
| 225 | + (c.expect === 'green' && !red) || |
| 226 | + (c.expect === 'red' && red && (!c.names || problems.some((p) => p.includes(c.names)))); |
| 227 | + if (!ok) { |
| 228 | + failed += 1; |
| 229 | + console.error(`✗ ${c.label}\n expected ${c.expect}${c.names ? ` naming ${c.names}` : ''}, got: ${red ? problems.join(' | ') : 'green'}`); |
| 230 | + } |
| 231 | + } |
| 232 | + |
| 233 | + const declared = Object.keys(SELF_TEST_BATTERIES); |
| 234 | + const floorFailure = (message) => { |
| 235 | + console.error(`✗ self-test floor: ${message}`); |
| 236 | + failed += 1; |
| 237 | + }; |
| 238 | + if (declared.length < SELF_TEST_BATTERY_FLOOR) { |
| 239 | + floorFailure(`SELF_TEST_BATTERIES declares ${declared.length} batteries, below the pinned ${SELF_TEST_BATTERY_FLOOR}.`); |
| 240 | + } |
| 241 | + const labels = cases.map((c) => c.label); |
| 242 | + const duplicated = [...new Set(labels.filter((l, i) => labels.indexOf(l) !== i))]; |
| 243 | + if (duplicated.length > 0) floorFailure(`row label(s) used more than once: ${duplicated.join(', ')}`); |
| 244 | + for (const [name] of batterySeen) { |
| 245 | + if (!declared.includes(name)) floorFailure(`battery "${name}" ran but is not declared in SELF_TEST_BATTERIES.`); |
| 246 | + } |
| 247 | + for (const name of declared) { |
| 248 | + const seen = batterySeen.get(name) ?? 0; |
| 249 | + if (seen < SELF_TEST_BATTERIES[name]) { |
| 250 | + floorFailure(`battery "${name}" DID NOT RUN — ${seen} case(s) registered, ${SELF_TEST_BATTERIES[name]} pinned.`); |
| 251 | + } |
| 252 | + } |
| 253 | + |
| 254 | + if (failed > 0) { |
| 255 | + console.error(`\n✗ check-vouch-for-reference-callers self-test: ${failed} failure(s) (cases and floor).`); |
| 256 | + process.exit(1); |
| 257 | + } |
| 258 | + console.log(`✓ check-vouch-for-reference-callers self-test: ${cases.length} cases pass.`); |
| 259 | + selfTestReachedVerdict = true; |
| 260 | +} |
| 261 | + |
| 262 | +function main() { |
| 263 | + if (process.argv.includes('--self-test')) { |
| 264 | + selfTest(); |
| 265 | + if (!selfTestReachedVerdict) { |
| 266 | + console.error( |
| 267 | + '✗ check-vouch-for-reference-callers self-test: selfTest() returned without reaching its verdict, so no ' + |
| 268 | + 'success line was printed; exiting 0 would report a self-test that never finished as one that passed.', |
| 269 | + ); |
| 270 | + process.exit(1); |
| 271 | + } |
| 272 | + return; |
| 273 | + } |
| 274 | + const { problems, counts } = check(readTree()); |
| 275 | + if (problems.length > 0) { |
| 276 | + console.error(`✗ check-vouch-for-reference-callers: ${problems.length} finding(s)\n`); |
| 277 | + for (const p of problems) console.error(` - ${p}`); |
| 278 | + process.exit(1); |
| 279 | + } |
| 280 | + const listed = [...counts].map(([path, n]) => `${path} (${n})`).join(', '); |
| 281 | + console.log(`✓ check-vouch-for-reference-callers: every call site that sets the vouched-reference mark is allow-listed — ${listed}.`); |
| 282 | +} |
| 283 | + |
| 284 | +if (isEntrypoint(import.meta.url)) { |
| 285 | + main(); |
| 286 | +} |
0 commit comments