olo-read-gates

1import type { EngineInterface, Register } from 'claude-code'
2
3import { ancestors, gateFor, guessRoot, newTestFileNotes, normPath, readGateMessage, relativeTo, resolvePath } from './gates'
4
5const FS_READ_LIMIT = 4 * 1024 * 1024
6
7// Files each loop (main, or a subagent by its id) has read this session, resolved and lower
8// case. Module state: a reload of this mod forgets them, which costs one re-read.
9const readByLoop = new Map<string, Set<string>>()
10// Checkout roots already found, by directory.
11const rootByDir = new Map<string, string | undefined>()
12
13function loopOf(agentId: unknown): string {
14  return typeof agentId === 'string' && agentId.length > 0 ? agentId : 'main'
15}
16
17/** Did this loop read THIS checkout's copy of the guide (not another worktree's)? */
18function hasRead(loop: string, guide: string): boolean {
19  return readByLoop.get(loop)?.has(normPath(guide)) ?? false
20}
21
22export const register: Register = on => {
23  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
24    const ran = await next(e)
25    if (ran.deny === undefined && ran.isError !== true && typeof e.file_path === 'string') {
26      const loop = loopOf(e.agentId)
27      const set = readByLoop.get(loop) ?? new Set<string>()
28      set.add(normPath(e.file_path))
29      readByLoop.set(loop, set)
30    }
31    return ran
32  })
33
34  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
35    const path = typeof e.file_path === 'string' ? resolvePath(e.file_path) : ''
36    const root = path.length === 0 ? undefined : await checkoutRoot($, path)
37    if (root === undefined) {
38      return next(e)
39    }
40    const exists = await $.fs.exists(path)
41    const incoming = e.tool === 'Write' ? e.content : e.tool === 'Edit' ? e.new_string : undefined
42    const needsText = /\.(?:h|hpp)$/i.test(path) && exists
43    const text = needsText ? await readSmall($, path) : undefined
44    const gate = gateFor(path, root, { isNew: !exists, text, incoming })
45
46    if (gate.kind === 'deny') {
47      return { deny: `olo-read-gates refused this edit: ${gate.reason}` }
48    }
49    if (gate.kind === 'requires-read') {
50      const guide = `${root}/${gate.doc}`
51      // A branch older than the guide has nothing to read: do not gate on a file that is not there.
52      if (!hasRead(loopOf(e.agentId), guide) && (await $.fs.exists(guide))) {
53        return { deny: readGateMessage(gate, path, root) }
54      }
55    }
56
57    const ran = await next(e)
58    if (ran.deny !== undefined || ran.isError === true || exists || e.tool !== 'Write') {
59      return ran
60    }
61    // A new test source was just written: is it built, and classified?
62    const rel = relativeTo(path, root) ?? ''
63    if (!rel.startsWith('oloengine/tests/') || !rel.endsWith('.cpp')) {
64      return ran
65    }
66    const notes = newTestFileNotes(
67      path,
68      root,
69      e.content,
70      await readSmall($, `${root}/OloEngine/tests/CMakeLists.txt`),
71      await readSmall($, `${root}/OloEngine/tests/scripts/test_catalogue.json`),
72    )
73    return notes.length === 0 ? ran : { ...ran, context: [...(ran.context ?? []), ...notes] }
74  })
75    // A gate that breaks fails OPEN: these are reminders of the repo's rules, and a bug in
76    // one must not block every edit in the session.
77    .catch(($, e, next) => next(e))
78}
79
80/**
81 * The checkout a file belongs to: the nearest directory holding a `.git` (a directory in the
82 * main checkout, a file in a worktree, either nested under `.claude/worktrees/`), falling back
83 * to the first top-level directory name when the file system cannot be asked.
84 */
85async function checkoutRoot($: EngineInterface, path: string): Promise<string | undefined> {
86  const dirs = ancestors(path)
87  for (const dir of dirs) {
88    const key = normPath(dir)
89    if (rootByDir.has(key)) {
90      return rootByDir.get(key)
91    }
92    try {
93      if (await $.fs.exists(`${dir}/.git`)) {
94        for (const below of dirs.slice(0, dirs.indexOf(dir) + 1)) {
95          rootByDir.set(normPath(below), dir)
96        }
97        return dir
98      }
99    } catch {
100      break
101    }
102  }
103  return guessRoot(path)
104}
105
106async function readSmall($: EngineInterface, path: string): Promise<string | undefined> {
107  try {
108    const stat = await $.fs.stat(path)
109    return stat.kind === 'file' && stat.size <= FS_READ_LIMIT ? await $.fs.read(path) : undefined
110  } catch {
111    return undefined
112  }
113}
114

1// Pure rules for which files may be edited, and which guide must be read first.
2// CLAUDE.md states each of these as prose; this makes them hold.
3
4export type Gate =
5  | { kind: 'deny'; reason: string }
6  | { kind: 'requires-read'; doc: string; why: string }
7  | { kind: 'none' }
8
9const SHADER = /\.(?:glsl|vert|frag|comp|geom|tesc|tese|mesh|task|rgen|rchit|rahit|rmiss|rint|rcall)$/i
10const COMPONENT_DECL = /^\s*struct\s+(?:alignas\([^)]*\)\s+)?\w+Component\b(?!\s*;)/m
11
12export const DOCS = {
13  shaders: 'docs/agent-rules/glsl-shaders.md',
14  components: 'docs/agent-rules/component-serializer-codegen.md',
15  tests: 'docs/agent-rules/testing-architecture.md',
16} as const
17
18/**
19 * Forward slashes and `.` / `..` segments resolved, case kept: `<root>/OloEngine/src/../vendor/x`
20 * is the vendor file it names, whatever the spelling.
21 */
22export function resolvePath(p: string): string {
23  const slashed = p.replace(/\\/g, '/')
24  const drive = /^[A-Za-z]:/.exec(slashed)?.[0] ?? ''
25  const rest = slashed.slice(drive.length)
26  const isAbsolute = rest.startsWith('/')
27  const out: string[] = []
28  for (const part of rest.split('/')) {
29    if (part === '' || part === '.') {
30      continue
31    }
32    if (part === '..') {
33      if (out.length > 0 && out[out.length - 1] !== '..') {
34        out.pop()
35      } else if (!isAbsolute) {
36        out.push('..')
37      }
38      continue
39    }
40    out.push(part)
41  }
42  return `${drive}${isAbsolute ? '/' : ''}${out.join('/')}`
43}
44
45/** Resolved and lower case: how paths are compared here (Windows is case-insensitive). */
46export function normPath(p: string): string {
47  return resolvePath(p).toLowerCase()
48}
49
50/** Every directory above a file, nearest first: where to look for the checkout's `.git`. */
51export function ancestors(path: string): string[] {
52  const parts = resolvePath(path).split('/')
53  const out: string[] = []
54  for (let i = parts.length - 1; i > 0; i -= 1) {
55    const dir = parts.slice(0, i).join('/')
56    if (dir.length > 0 && !/^[A-Za-z]:$/.test(dir)) {
57      out.push(dir)
58    }
59  }
60  return out
61}
62
63/**
64 * A fallback root, for when the file system cannot be asked: the directory above the first
65 * top-level directory this repo has. The engine's own answer is the nearest `.git` (see
66 * register), which also places a nested checkout (`.claude/worktrees/<name>`) right.
67 */
68export function guessRoot(path: string): string | undefined {
69  const m = /^(.*?)\/(?:OloEngine|OloEditor|OloRuntime|OloServer|OloEngine-ScriptCore|docs|tools|cmake|scripts|build[\w-]*|\.github)\//.exec(resolvePath(path))
70  return m?.[1]
71}
72
73/** The path relative to `root`, lower case; undefined when it lies outside. */
74export function relativeTo(path: string, root: string): string | undefined {
75  const p = normPath(path)
76  const r = normPath(root).replace(/\/$/, '')
77  return p.startsWith(`${r}/`) ? p.slice(r.length + 1) : undefined
78}
79
80/**
81 * What an edit of `path` in the checkout at `root` needs. `text` is the file's current text
82 * where it matters (a header that may declare a component), `incoming` the text written.
83 */
84export function gateFor(path: string, root: string, opts: { isNew: boolean; text?: string; incoming?: string }): Gate {
85  const rel = relativeTo(path, root)
86  if (rel === undefined) {
87    return { kind: 'none' }
88  }
89
90  if (rel.startsWith('oloengine/vendor/') || rel.includes('/vcpkg_installed/') || rel.startsWith('vcpkg_installed/')) {
91    return {
92      kind: 'deny',
93      reason:
94        'This is a FetchContent download or a vcpkg port: a reconfigure wipes it, and the build never sees the edit for long. ' +
95        'Patch a vcpkg port through cmake/overlay-ports/, and a FetchContent dependency through its CMake fetch (CLAUDE.md, Architecture).',
96    }
97  }
98
99  if (/(?:^|\/)generated\//.test(rel) || /\.generated\.[a-z]+$/.test(rel)) {
100    return {
101      kind: 'deny',
102      reason:
103        'This file is generated by tools/OloHeaderTool (the GenerateBindings target) and is rewritten on the next build. ' +
104        'Change the source it reads (OloEngine/src) or the generator, build GenerateBindings, and re-stage the output (CLAUDE.md, OloHeaderTool). ' +
105        'A hand-broken generated file is also rewritten green by CI codegen, so it is no negative control either.',
106    }
107  }
108
109  if (/^docs\/test-catalogue\.[^/]*\.md$/.test(rel)) {
110    return {
111      kind: 'deny',
112      reason: 'docs/test-catalogue.*.md is generated and git-ignored: classify a test with `// OLO_TEST_LAYER:` or test_catalogue.json instead (CLAUDE.md, Definition of done).',
113    }
114  }
115
116  if (SHADER.test(rel)) {
117    return {
118      kind: 'requires-read',
119      doc: DOCS.shaders,
120      why: 'what makes a shader fail SPIR-V compile (CLAUDE.md names it a guide to read regardless of subsystem)',
121    }
122  }
123
124  if (rel.startsWith('oloengine/tests/') && rel.endsWith('.cpp') && opts.isNew) {
125    return {
126      kind: 'requires-read',
127      doc: DOCS.tests,
128      why: 'where a new test belongs; pick its classification before writing it (CLAUDE.md, Tests)',
129    }
130  }
131
132  const isHeader = /\.(?:h|hpp)$/.test(rel)
133  const declaresComponent = COMPONENT_DECL.test(opts.text ?? '') || COMPONENT_DECL.test(opts.incoming ?? '')
134  if (isHeader && (rel.startsWith('oloengine/src/') || rel.startsWith('oloeditor/src/')) && declaresComponent) {
135    return {
136      kind: 'requires-read',
137      doc: DOCS.components,
138      why: 'the cross-binding touch-points a component change needs (save-game Serialize + RegisterAll, Lua, the inspector and Add Component menu, a hand-written copy ctor / operator==); §0 is the table (CLAUDE.md, Definition of done 3)',
139    }
140  }
141
142  return { kind: 'none' }
143}
144
145export function readGateMessage(gate: { doc: string; why: string }, path: string, root: string): string {
146  return (
147    `olo-read-gates: read ${resolvePath(root)}/${gate.doc} before editing ${resolvePath(path).split('/').slice(-2).join('/')}. ` +
148    `It covers ${gate.why}. Read that checkout's copy (any part counts; read the part you need), then retry the edit.`
149  )
150}
151
152function escapeRegExp(s: string): string {
153  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
154}
155
156/**
157 * After a new test .cpp is written: is it built and classified? An entry counts only as a
158 * whole source entry (CMakeLists.txt lists paths relative to OloEngine/tests/) or a
159 * file_layer_map key (repo-relative): `OldNewThingTest.cpp` is no entry for `NewThingTest.cpp`.
160 */
161export function newTestFileNotes(path: string, root: string, content: string, cmakeLists: string | undefined, catalogue: string | undefined): string[] {
162  const rel = relativeTo(path, root) ?? ''
163  const relToTests = rel.startsWith('oloengine/tests/') ? rel.slice('oloengine/tests/'.length) : rel
164  const base = resolvePath(path).split('/').pop() ?? path
165  const notes: string[] = []
166
167  if (cmakeLists !== undefined) {
168    const entry = new RegExp(`(?:^|[\\s"(])${escapeRegExp(relToTests)}(?=[\\s")]|$)`, 'im')
169    if (!entry.test(cmakeLists.replace(/\\/g, '/'))) {
170      notes.push(
171        `${base} is not listed in OloEngine/tests/CMakeLists.txt (as \`${relToTests}\`), which names every test source: until it is, the file is never compiled and a --gtest_filter for it runs NOTHING (and the run still says PASSED).`,
172      )
173    }
174  }
175
176  const hasLayer = /^\s*\/\/\s*OLO_TEST_LAYER:\s*\S+/m.test(content)
177  let inCatalogue = false
178  if (catalogue !== undefined) {
179    try {
180      const map = (JSON.parse(catalogue) as { file_layer_map?: Record<string, unknown> }).file_layer_map ?? {}
181      inCatalogue = Object.keys(map).some(key => normPath(key) === rel)
182    } catch {
183      inCatalogue = false
184    }
185  }
186  if (!hasLayer && !inCatalogue) {
187    notes.push(`${base} has no \`// OLO_TEST_LAYER: <id>\` line near the top and no file_layer_map entry in test_catalogue.json: every test .cpp must be classified (CLAUDE.md, Definition of done 2).`)
188  }
189  if (/\bTEST(?:_F|_P)?\s*\(\s*\w+\s*,\s*DISABLED_/.test(content)) {
190    notes.push('A test here is DISABLED_: an evidence test that needs a GL 4.6 context skips cleanly without one instead (CLAUDE.md, Rendering changes must be visually verified).')
191  }
192  return notes.length === 0 ? [] : [`olo-read-gates: ${notes.join(' ')}`]
193}
194