codebook-strategy 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -62,17 +62,19 @@ It starts as structure and becomes knowledge. `init` lays down empty templates.
62
62
  ### `init`
63
63
 
64
64
  ```bash
65
- npx codebook-strategy init [--force]
65
+ npx codebook-strategy init [--tool <list>] [--force]
66
66
  ```
67
67
 
68
68
  - Confirms you're in a project (looks for `package.json`, `.git`, or `src/`).
69
- - Detects your LLM tooling and injects the strategy into the right config file:
70
- - `CLAUDE.md` / `.claude/` → **Claude Code**
71
- - `.cursorrules` / `.cursor/` → **Cursor**
72
- - `AGENTS.md` → **Amp / Warp**
73
- - none detected → creates all three
69
+ - **Injects the strategy into every supported agent by default** — `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (Amp / Warp / Codex). That way it doesn't matter which agent — or how many — your team uses; whichever one someone opens, it finds the strategy. The agents it detects in use are marked in the output.
70
+ - Narrow it with `--tool` if you only want specific agents:
71
+ ```bash
72
+ npx codebook-strategy init --tool claude
73
+ npx codebook-strategy init --tool claude,cursor
74
+ npx codebook-strategy init --tool all # explicit default
75
+ ```
74
76
  - Scaffolds `book/` with `PREFACE.md`, `INDEX.md`, `CONNECTIONS.md`, and `chapters/`.
75
- - Existing config files are **appended to**, never overwritten. Existing book files are left untouched unless you pass `--force`.
77
+ - Existing config files are **appended to**, never overwritten (and never double-injected). Existing book files are left untouched unless you pass `--force`.
76
78
 
77
79
  ### `status`
78
80
 
@@ -95,6 +97,54 @@ Checks the book for consistency:
95
97
 
96
98
  Prints a warning for each mismatch and exits non-zero if any are found, so it fits in CI.
97
99
 
100
+ ### `audit`
101
+
102
+ ```bash
103
+ npx codebook-strategy audit [--ci]
104
+ ```
105
+
106
+ A **manual, whole-repo completeness check** for `CONNECTIONS.md`. Where `validate` only checks internal consistency, `audit` scans the actual code and surfaces real dependencies the book is missing — then hands you an instruction block to reconcile them with your LLM. It never edits the book itself.
107
+
108
+ **Why it exists:** `CONNECTIONS.md` normally only grows when an agent happens to read a connection mid-task. That misses *reverse dependencies* — e.g. a reporting module that `SELECT`s from a table the ingestion module `INSERT`s into. The two share data but don't import each other, so nothing surfaces the coupling. `audit` is the deliberate check you run on demand, especially **before a schema change**.
109
+
110
+ What it does:
111
+
112
+ 1. Parses `book/CONNECTIONS.md` into the set of known edges.
113
+ 2. Deterministically scans the repo (Node built-ins only, no new deps), skipping `node_modules`, `.git`, `build/`, `dist/`, etc. It derives edges from:
114
+ - **cross-module imports**, and
115
+ - **shared resources** via configurable regex — by default DB **table** reads/writes and **queue/topic** publish/subscribe.
116
+ 3. Builds **write→read directed edges** as first-class output: the module that *reads* a resource another module *writes* is a real dependency even with no import between them. This reverse/shared-data case is the whole point.
117
+ 4. Diffs code edges against the book and reports **(a)** edges in code but missing from the book, and **(b)** book edges with no code evidence (possibly stale).
118
+ 5. Prints a grouped report plus a copy-paste **agent instruction block** to confirm each finding and update `CONNECTIONS.md` + the affected chapter.
119
+
120
+ **Exit code:** report-only by default (exit `0`). Pass `--ci` (or `--strict`) to exit non-zero when code has edges missing from the book, so it can gate CI. Stale book edges are always warnings only.
121
+
122
+ **Scope — read this:** *shared-resource* detection is language-agnostic (it's just regex over text). *Import-edge* resolution is **JS/TS-only, with partial support for Python relative imports** (`from .mod import x`); imports in other languages are not resolved into edges. Don't rely on import edges outside JS/TS.
123
+
124
+ **Configuration** — optional `book/audit.config.json` (or `.codebook-audit.json` at the repo root):
125
+
126
+ ```json
127
+ {
128
+ "moduleDepth": 2,
129
+ "ignore": ["generated"],
130
+ "extensions": [".js", ".ts", ".go"],
131
+ "enable": ["route", "env"],
132
+ "disable": ["queue"],
133
+ "resources": [
134
+ {
135
+ "kind": "table",
136
+ "write": "\\b(?:INSERT INTO|UPDATE)\\s+([A-Za-z_][A-Za-z0-9_]*)",
137
+ "read": "\\bFROM\\s+([A-Za-z_][A-Za-z0-9_]*)",
138
+ "flags": "gi"
139
+ }
140
+ ]
141
+ }
142
+ ```
143
+
144
+ - `table` and `queue` rules are **on by default**. `route` and `env` are **opt-in** via `enable` — they're undirected `ref`-only rules and get noisy fast (one shared `NODE_ENV` across N files produces N·(N−1)/2 edges), so they never gate CI and aren't a sensible default.
145
+ - `disable` turns off a default kind; `resources` adds custom rules (a rule reusing an existing `kind` replaces it). Each rule's first capture group is the resource id; `write`/`read` are directional, `ref` is undirected.
146
+ - `moduleDepth` (default `2`) sets how many path segments form a "module" (`src/reporting/queries.ts` → `src/reporting`). Files shallower than the cap keep their basename so a flat `src/*.js` layout doesn't collapse into one module.
147
+
98
148
  ## Works with
99
149
 
100
150
  Claude Code, Cursor, Amp, Warp — and any LLM tool that reads a project config file. The book itself is just markdown, so any assistant you point at it can follow along.
package/bin/cli.js CHANGED
@@ -4,6 +4,7 @@
4
4
  const init = require('../src/commands/init');
5
5
  const status = require('../src/commands/status');
6
6
  const validate = require('../src/commands/validate');
7
+ const audit = require('../src/commands/audit');
7
8
  const { red, bold, dim } = require('../src/utils/colors');
8
9
 
9
10
  const HELP = `
@@ -16,9 +17,17 @@ ${bold('Commands')}
16
17
  init Scaffold the /book/ directory and inject strategy instructions
17
18
  status Show which book files exist and their state
18
19
  validate Check the book for index/chapter/connection mismatches
20
+ audit Scan the repo for connections missing from CONNECTIONS.md
19
21
 
20
22
  ${bold('Options for init')}
21
- --force Overwrite an existing book/ directory
23
+ --tool <list> Which agents to set up: claude, cursor, agents, or all.
24
+ Comma-separated. Default: all (covers every agent).
25
+ --force Overwrite an existing book/ directory
26
+
27
+ ${bold('Options for audit')}
28
+ --ci, --strict Exit non-zero when code has edges missing from the book.
29
+ Default is report-only (exit 0). Reads optional
30
+ book/audit.config.json for custom resource rules.
22
31
 
23
32
  ${bold('After init')}
24
33
  Tell your LLM: ${dim('"Implement the book strategy"')}
@@ -36,6 +45,8 @@ function main(argv) {
36
45
  return status(rest);
37
46
  case 'validate':
38
47
  return validate(rest);
48
+ case 'audit':
49
+ return audit(rest);
39
50
  case '-h':
40
51
  case '--help':
41
52
  case 'help':
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codebook-strategy",
3
- "version": "1.0.3",
3
+ "version": "1.1.0",
4
4
  "description": "Your AI coding assistant re-reads your whole codebase every session. codebook-strategy builds a small set of notes it reads instead.",
5
5
  "bin": {
6
6
  "codebook-strategy": "bin/cli.js"
@@ -0,0 +1,180 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const { exists } = require('../utils/file-writer');
7
+ const { green, yellow, red, cyan, dim, bold } = require('../utils/colors');
8
+ const { parseConnectionEdges } = require('./shared');
9
+ const { loadConfig, resolveConfig, scanRepo } = require('../utils/audit-scan');
10
+
11
+ // Normalized word tokens for fuzzy node matching (module paths vs chapter names).
12
+ function tokens(s) {
13
+ return new Set(
14
+ String(s).toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3)
15
+ );
16
+ }
17
+
18
+ function nodesMatch(codeModule, chapterName) {
19
+ const a = tokens(codeModule);
20
+ const b = tokens(chapterName);
21
+ for (const t of a) if (b.has(t)) return true;
22
+ for (const x of a) {
23
+ for (const y of b) {
24
+ if (x.length >= 4 && y.length >= 4 && (x.includes(y) || y.includes(x))) {
25
+ return true;
26
+ }
27
+ }
28
+ }
29
+ return false;
30
+ }
31
+
32
+ function edgeMatch(codeEdge, bookEdge) {
33
+ const direct = nodesMatch(codeEdge.a, bookEdge.a) && nodesMatch(codeEdge.b, bookEdge.b);
34
+ const swap = nodesMatch(codeEdge.a, bookEdge.b) && nodesMatch(codeEdge.b, bookEdge.a);
35
+ return direct || swap;
36
+ }
37
+
38
+ function arrow(directed) {
39
+ return directed ? '→' : '↔';
40
+ }
41
+
42
+ function groupBy(arr, fn) {
43
+ const out = {};
44
+ for (const x of arr) {
45
+ const k = fn(x);
46
+ (out[k] = out[k] || []).push(x);
47
+ }
48
+ return out;
49
+ }
50
+
51
+ function audit(args) {
52
+ const strict = (args || []).some((a) => a === '--ci' || a === '--strict');
53
+ const cwd = process.cwd();
54
+ const bookDir = path.join(cwd, 'book');
55
+ const connPath = path.join(bookDir, 'CONNECTIONS.md');
56
+
57
+ if (!exists(bookDir)) {
58
+ process.stderr.write(
59
+ red('No book/ directory found.') + '\n' +
60
+ dim('Run `npx codebook-strategy init` first.') + '\n'
61
+ );
62
+ return 1;
63
+ }
64
+ if (!exists(connPath)) {
65
+ process.stderr.write(red('book/CONNECTIONS.md is missing.') + '\n');
66
+ return 1;
67
+ }
68
+
69
+ const loaded = loadConfig(cwd);
70
+ if (loaded.error) {
71
+ process.stderr.write(red(loaded.error) + '\n');
72
+ return 1;
73
+ }
74
+ const conf = resolveConfig(loaded.cfg);
75
+
76
+ const bookEdges = parseConnectionEdges(fs.readFileSync(connPath, 'utf8'));
77
+ const { fileCount, edges: codeEdges } = scanRepo(cwd, conf);
78
+
79
+ const missing = codeEdges.filter((ce) => !bookEdges.some((be) => edgeMatch(ce, be)));
80
+ const stale = bookEdges.filter((be) => !codeEdges.some((ce) => edgeMatch(ce, be)));
81
+
82
+ // --- Report ---
83
+ process.stdout.write('\n' + bold('Codebook audit') + '\n');
84
+ process.stdout.write(
85
+ dim(` Scanned ${fileCount} files · ${codeEdges.length} code edges · ` +
86
+ `${bookEdges.length} book edges · ` +
87
+ (loaded.path ? `config ${path.relative(cwd, loaded.path)}` : 'built-in rules') +
88
+ ` · rules: ${conf.rules.map((r) => r.kind).join(', ')}`) + '\n'
89
+ );
90
+
91
+ if (missing.length === 0 && stale.length === 0) {
92
+ process.stdout.write('\n ' + green('✓') + ' Book connections match the code.\n\n');
93
+ return 0;
94
+ }
95
+
96
+ if (missing.length > 0) {
97
+ process.stdout.write('\n' + bold('Edges in code but missing from the book') + '\n');
98
+ const byKind = groupBy(missing, (e) => e.kind);
99
+ for (const kind of Object.keys(byKind).sort()) {
100
+ process.stdout.write(dim(` [${kind}]`) + '\n');
101
+ for (const e of byKind[kind]) {
102
+ const det = e.details.slice(0, 3).join(', ') + (e.details.length > 3 ? '…' : '');
103
+ process.stdout.write(
104
+ ' ' + red('+') + ` ${e.a} ${arrow(e.directed)} ${e.b}` +
105
+ dim(` (${det}; e.g. ${e.evidence})`) + '\n'
106
+ );
107
+ }
108
+ }
109
+ }
110
+
111
+ if (stale.length > 0) {
112
+ process.stdout.write('\n' + bold('Book edges with no code evidence (possibly stale)') + '\n');
113
+ for (const e of stale) {
114
+ process.stdout.write(
115
+ ' ' + yellow('?') + ` ${e.aRaw} ${arrow(e.directed)} ${e.bRaw}` +
116
+ dim(e.reason ? ` (${e.reason})` : '') +
117
+ dim(` [CONNECTIONS.md:${e.line}]`) + '\n'
118
+ );
119
+ }
120
+ }
121
+
122
+ // --- Agent-ready instruction block ---
123
+ process.stdout.write('\n' + bold('Hand this to your LLM to reconcile:') + '\n\n');
124
+ process.stdout.write(dim('--- BEGIN AGENT INSTRUCTIONS ---') + '\n');
125
+ process.stdout.write(buildInstructionBlock(missing, stale));
126
+ process.stdout.write(dim('--- END AGENT INSTRUCTIONS ---') + '\n');
127
+
128
+ if (missing.length > 0 && !strict) {
129
+ process.stdout.write(
130
+ '\n' + dim(' Report-only (exit 0). Pass --ci (or --strict) to fail on missing edges.') + '\n'
131
+ );
132
+ }
133
+ process.stdout.write('\n');
134
+
135
+ // Default is report-only. Only --ci/--strict turns missing edges into a failure.
136
+ return strict && missing.length > 0 ? 1 : 0;
137
+ }
138
+
139
+ function buildInstructionBlock(missing, stale) {
140
+ const lines = [];
141
+ lines.push(
142
+ 'A deterministic scan compared book/CONNECTIONS.md against the code. For each',
143
+ 'candidate below, confirm it against the actual source before changing anything.',
144
+ 'The scan is heuristic — do not trust it blindly.',
145
+ ''
146
+ );
147
+ if (missing.length) {
148
+ lines.push('CANDIDATE CONNECTIONS FOUND IN CODE BUT NOT IN THE BOOK:');
149
+ for (const e of missing) {
150
+ lines.push(
151
+ `- ${e.a} ${arrow(e.directed)} ${e.b} [${e.kind}] evidence: ` +
152
+ `${e.details.slice(0, 3).join(', ')} (see ${e.evidence})`
153
+ );
154
+ }
155
+ lines.push(
156
+ '',
157
+ 'For each confirmed one: map the modules to their chapters, add the edge to',
158
+ 'book/CONNECTIONS.md as `source/topic → target/topic : reason`, and update the',
159
+ 'affected chapter(s). Pay special attention to write→read data edges: a module that',
160
+ 'READS a table/queue another module WRITES is a real dependency even with no import.',
161
+ ''
162
+ );
163
+ }
164
+ if (stale.length) {
165
+ lines.push('BOOK CONNECTIONS WITH NO CODE EVIDENCE (verify, then fix or remove):');
166
+ for (const e of stale) {
167
+ lines.push(`- ${e.aRaw} ${arrow(e.directed)} ${e.bRaw} [CONNECTIONS.md:${e.line}]`);
168
+ }
169
+ lines.push(
170
+ '',
171
+ 'If the relationship genuinely no longer exists, remove the line and note it in the',
172
+ 'chapter. If it exists via a path the scan missed, leave it.',
173
+ ''
174
+ );
175
+ }
176
+ lines.push('After edits, re-run `npx codebook-strategy audit` until it is clean.');
177
+ return lines.join('\n') + '\n';
178
+ }
179
+
180
+ module.exports = audit;
@@ -3,7 +3,12 @@
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
5
 
6
- const { isProject, detectTargets } = require('../utils/detect-environment');
6
+ const {
7
+ isProject,
8
+ detectPresent,
9
+ resolveTargets,
10
+ ALL_KEYS,
11
+ } = require('../utils/detect-environment');
7
12
  const {
8
13
  exists,
9
14
  ensureDir,
@@ -25,8 +30,19 @@ function read(templatePath) {
25
30
  return fs.readFileSync(path.join(TEMPLATES, templatePath), 'utf8');
26
31
  }
27
32
 
33
+ // Read the value of a flag, supporting both `--flag value` and `--flag=value`.
34
+ function getFlagValue(args, name) {
35
+ for (let i = 0; i < args.length; i++) {
36
+ const a = args[i];
37
+ if (a === name) return args[i + 1];
38
+ if (a.startsWith(name + '=')) return a.slice(name.length + 1);
39
+ }
40
+ return undefined;
41
+ }
42
+
28
43
  function init(args) {
29
44
  const force = args.includes('--force');
45
+ const toolArg = getFlagValue(args, '--tool');
30
46
  const cwd = process.cwd();
31
47
 
32
48
  if (!isProject(cwd)) {
@@ -39,6 +55,19 @@ function init(args) {
39
55
  return 1;
40
56
  }
41
57
 
58
+ // Resolve which agents to write to. Default: every supported agent, so it
59
+ // never matters which one (or how many) the developer actually uses.
60
+ const { targets, invalid } = resolveTargets(toolArg);
61
+ if (invalid.length > 0) {
62
+ process.stderr.write(
63
+ red(`Unknown --tool value(s): ${invalid.join(', ')}`) +
64
+ '\n' +
65
+ dim(`Valid tools: ${ALL_KEYS.join(', ')}, or all.`) +
66
+ '\n'
67
+ );
68
+ return 1;
69
+ }
70
+
42
71
  const bookDir = path.join(cwd, 'book');
43
72
 
44
73
  // Handle an existing book/ directory.
@@ -77,14 +106,21 @@ function init(args) {
77
106
  bookResults.push({ name: 'book/chapters/', result: keepResult });
78
107
 
79
108
  // --- Inject strategy into config files --------------------------------
80
- const { detected, targets } = detectTargets(cwd);
109
+ // Which agents actually show signs of use here (for reporting only).
110
+ const present = detectPresent(cwd);
81
111
 
82
112
  const configResults = [];
83
113
  for (const target of targets) {
84
114
  const section = read(target.template);
85
115
  const filePath = path.join(cwd, target.file);
86
116
  const result = appendSection(filePath, section, STRATEGY_MARKER);
87
- configResults.push({ tool: target.tool, file: target.file, result });
117
+ configResults.push({
118
+ key: target.key,
119
+ tool: target.tool,
120
+ file: target.file,
121
+ result,
122
+ detected: present.includes(target.key),
123
+ });
88
124
  }
89
125
 
90
126
  // --- Report -----------------------------------------------------------
@@ -96,18 +132,19 @@ function init(args) {
96
132
  }
97
133
 
98
134
  process.stdout.write('\n' + bold('Config files') + '\n');
99
- if (detected) {
135
+ if (toolArg) {
100
136
  process.stdout.write(
101
- dim(' Detected existing LLM tooling; injected into:') + '\n'
137
+ dim(' Injecting strategy into the tool(s) you selected:') + '\n'
102
138
  );
103
139
  } else {
104
140
  process.stdout.write(
105
- dim(' No LLM tooling detected; created all three config files:') + '\n'
141
+ dim(' Covering every supported agent (pass --tool to narrow):') + '\n'
106
142
  );
107
143
  }
108
- for (const { tool, file, result } of configResults) {
144
+ for (const { tool, file, result, detected } of configResults) {
145
+ const mark = detected ? cyan(' ← in use here') : '';
109
146
  process.stdout.write(
110
- ' ' + formatResult(result) + ' ' + file + dim(` (${tool})`) + '\n'
147
+ ' ' + formatResult(result) + ' ' + file + dim(` (${tool})`) + mark + '\n'
111
148
  );
112
149
  }
113
150
 
@@ -84,8 +84,47 @@ function parseConnectionTopics(content) {
84
84
  return topics;
85
85
  }
86
86
 
87
+ // Extract connection EDGES from CONNECTIONS.md (chapter-level), for the audit
88
+ // command. Like parseConnectionTopics, but keeps each pair as an edge with its
89
+ // direction and reason. A chain `a → b → c` yields edges a-b and b-c.
90
+ //
91
+ // Returns [{ a, b, aRaw, bRaw, directed, reason, line }].
92
+ function parseConnectionEdges(content) {
93
+ const edges = [];
94
+ const withoutComments = content.replace(/<!--[\s\S]*?-->/g, '');
95
+ withoutComments.split('\n').forEach((line, i) => {
96
+ const trimmed = line.trim();
97
+ if (!trimmed || trimmed.startsWith('>') || trimmed.startsWith('#')) return;
98
+ const op = trimmed.match(/(↔|<->|→|->)/);
99
+ if (!op) return;
100
+ const directed = op[1] === '→' || op[1] === '->';
101
+ const beforeReason = trimmed.split(':')[0];
102
+ const sides = beforeReason
103
+ .split(/↔|<->|→|->/)
104
+ .map((s) => s.trim())
105
+ .filter(Boolean);
106
+ if (sides.length < 2) return;
107
+ const reason = trimmed.includes(':')
108
+ ? trimmed.slice(trimmed.indexOf(':') + 1).trim()
109
+ : '';
110
+ for (let k = 0; k < sides.length - 1; k++) {
111
+ edges.push({
112
+ a: sides[k].split('/')[0].trim(),
113
+ b: sides[k + 1].split('/')[0].trim(),
114
+ aRaw: sides[k],
115
+ bRaw: sides[k + 1],
116
+ directed,
117
+ reason,
118
+ line: i + 1,
119
+ });
120
+ }
121
+ });
122
+ return edges;
123
+ }
124
+
87
125
  module.exports = {
88
126
  listChapters,
89
127
  parseIndexChapters,
90
128
  parseConnectionTopics,
129
+ parseConnectionEdges,
91
130
  };
@@ -0,0 +1,335 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ // Directories never scanned.
7
+ const DEFAULT_IGNORE = [
8
+ 'node_modules', '.git', 'dist', 'build', '.next', 'out',
9
+ 'coverage', 'vendor', '.venv', '__pycache__', 'book',
10
+ ];
11
+
12
+ // Extensions scanned by default. Broad on purpose — shared-resource detection
13
+ // is by regex, not by language, so anything textual is fair game.
14
+ const DEFAULT_EXTENSIONS = [
15
+ '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
16
+ '.py', '.rb', '.go', '.rs', '.java', '.kt', '.php',
17
+ '.c', '.h', '.cpp', '.cs', '.swift', '.scala',
18
+ '.sql', '.sh', '.yml', '.yaml', '.json', '.env',
19
+ ];
20
+
21
+ // Default shared-resource rules — ON unless disabled. Each rule names a `kind`
22
+ // and supplies regex strings whose first defined capture group is the resource
23
+ // identifier:
24
+ // write — this module writes/owns the resource (producer side)
25
+ // read — this module reads/consumes it (consumer side)
26
+ // ref — undirected reference when read vs write can't be told apart
27
+ //
28
+ // table/queue are directional (write + read), so they produce the first-class
29
+ // write->read "reverse dependency" edges and no undirected noise.
30
+ //
31
+ // The `table` read rule keeps case-insensitivity (lowercase SQL is common) but
32
+ // excludes a following `import`, so Python's `from models import User` is not
33
+ // mistaken for a table access.
34
+ const DEFAULT_RULES = [
35
+ {
36
+ kind: 'table',
37
+ // INSERT INTO / DELETE FROM / CREATE TABLE are SQL-specific. UPDATE is also
38
+ // an English verb, so it is anchored on the mandatory `SET` clause — that
39
+ // keeps real `UPDATE t SET ...` while rejecting prose like "update the docs".
40
+ write: '\\b(?:INSERT\\s+INTO|DELETE\\s+FROM|CREATE\\s+TABLE(?:\\s+IF\\s+NOT\\s+EXISTS)?)\\s+["\'`]?([A-Za-z_][A-Za-z0-9_]*)|\\bUPDATE\\s+["\'`]?([A-Za-z_][A-Za-z0-9_]*)["\'`]?\\s+SET\\b',
41
+ // FROM/JOIN, excluding a following `import` so Python's `from x import y`
42
+ // isn't read as a table access.
43
+ read: '\\b(?:FROM|JOIN)\\s+["\'`]?([A-Za-z_][A-Za-z0-9_]*)\\b(?!\\s+import\\b)',
44
+ flags: 'gi',
45
+ },
46
+ {
47
+ kind: 'queue',
48
+ write: '\\.(?:publish|produce|send|emit|enqueue)\\(\\s*["\'`]([A-Za-z0-9_.\\-/:]+)',
49
+ read: '\\.(?:subscribe|consume|process|handle)\\(\\s*["\'`]([A-Za-z0-9_.\\-/:]+)',
50
+ flags: 'gi',
51
+ },
52
+ ];
53
+
54
+ // Opt-in rules — OFF unless listed in the config's `enable` array. These are
55
+ // ref-only (undirected) and noisy: one shared var like NODE_ENV across N files
56
+ // yields N(N-1)/2 phantom edges, so they are a poor default and never gate CI.
57
+ const OPTIONAL_RULES = {
58
+ route: {
59
+ kind: 'route',
60
+ ref: '["\'`](/(?:api|v\\d)/[A-Za-z0-9_\\-/:]+)["\'`]',
61
+ flags: 'g',
62
+ },
63
+ env: {
64
+ kind: 'env',
65
+ ref: 'process\\.env\\.([A-Z][A-Z0-9_]+)',
66
+ flags: 'g',
67
+ },
68
+ };
69
+
70
+ // Repo-internal import/require references. Import-edge resolution is JS/TS-only,
71
+ // plus partial support for Python *relative* imports (`from .mod import x`).
72
+ // Bare/absolute specifiers are treated as external and ignored.
73
+ const IMPORT_PATTERNS = [
74
+ '\\bimport\\s+[^\'"]*from\\s+[\'"]([^\'"]+)[\'"]',
75
+ '\\brequire\\(\\s*[\'"]([^\'"]+)[\'"]\\s*\\)',
76
+ '\\bexport\\s+[^\'"]*from\\s+[\'"]([^\'"]+)[\'"]',
77
+ '\\bfrom\\s+(\\.[\\w.]*)\\s+import\\b',
78
+ ];
79
+
80
+ function loadConfig(cwd) {
81
+ const candidates = [
82
+ path.join(cwd, 'book', 'audit.config.json'),
83
+ path.join(cwd, '.codebook-audit.json'),
84
+ ];
85
+ for (const p of candidates) {
86
+ try {
87
+ if (fs.existsSync(p)) {
88
+ return { cfg: JSON.parse(fs.readFileSync(p, 'utf8')), path: p };
89
+ }
90
+ } catch (e) {
91
+ return { error: `Could not parse ${p}: ${e.message}` };
92
+ }
93
+ }
94
+ return { cfg: {} };
95
+ }
96
+
97
+ // Merge config over the built-in defaults.
98
+ // enable: turn on optional built-ins (route, env)
99
+ // disable: turn off default kinds (table, queue)
100
+ // resources: custom rules; a rule with an existing kind replaces it
101
+ function resolveConfig(cfg) {
102
+ const byKind = {};
103
+ for (const r of DEFAULT_RULES) byKind[r.kind] = r;
104
+ for (const k of cfg.enable || []) {
105
+ if (OPTIONAL_RULES[k]) byKind[k] = OPTIONAL_RULES[k];
106
+ }
107
+ for (const k of cfg.disable || []) delete byKind[k];
108
+ if (Array.isArray(cfg.resources)) {
109
+ for (const r of cfg.resources) if (r && r.kind) byKind[r.kind] = r;
110
+ }
111
+ return {
112
+ ignore: DEFAULT_IGNORE.concat(cfg.ignore || []),
113
+ extensions: cfg.extensions || DEFAULT_EXTENSIONS,
114
+ moduleDepth: Number.isInteger(cfg.moduleDepth) ? cfg.moduleDepth : 2,
115
+ rules: Object.values(byKind),
116
+ };
117
+ }
118
+
119
+ function walkFiles(root, conf) {
120
+ const out = [];
121
+ const ignore = new Set(conf.ignore);
122
+ (function recurse(dir) {
123
+ let entries;
124
+ try {
125
+ entries = fs.readdirSync(dir, { withFileTypes: true });
126
+ } catch (e) {
127
+ return;
128
+ }
129
+ for (const ent of entries) {
130
+ const full = path.join(dir, ent.name);
131
+ if (ent.isDirectory()) {
132
+ if (ignore.has(ent.name) || ent.name.startsWith('.')) continue;
133
+ recurse(full);
134
+ } else if (ent.isFile()) {
135
+ const ext = path.extname(ent.name);
136
+ if (conf.extensions.includes(ext) || conf.extensions.includes(ent.name)) {
137
+ out.push(full);
138
+ }
139
+ }
140
+ }
141
+ })(root);
142
+ return out;
143
+ }
144
+
145
+ // A file's module id: its directory relative to root, capped to moduleDepth
146
+ // segments. Two safeguards keep sibling files distinct:
147
+ // - a repo-root file uses its basename (no extension);
148
+ // - a file shallower than the cap (e.g. everything directly under src/) would
149
+ // collapse to one broad bucket, so its basename is appended. Without this a
150
+ // flat `src/*.js` layout maps every file to `src`, and the a===b edge guard
151
+ // then silently drops every edge.
152
+ function moduleOf(relPath, moduleDepth) {
153
+ const segs = relPath.split(path.sep).join('/').split('/');
154
+ const dirSegs = segs.slice(0, -1);
155
+ const baseNoExt = segs[segs.length - 1].replace(/\.[^.]+$/, '');
156
+ if (dirSegs.length === 0) return baseNoExt;
157
+ const depth = moduleDepth > 0 ? moduleDepth : dirSegs.length;
158
+ if (dirSegs.length < depth) {
159
+ return dirSegs.join('/') + '/' + baseNoExt;
160
+ }
161
+ return dirSegs.slice(0, depth).join('/');
162
+ }
163
+
164
+ function firstGroup(match) {
165
+ return match.slice(1).find((g) => g !== undefined);
166
+ }
167
+
168
+ // Maps a rule mode to its bucket on a resource entry.
169
+ const BUCKET = { write: 'writers', read: 'readers', ref: 'refs' };
170
+
171
+ // Resources referenced by one file's content.
172
+ function extractResources(content, rules) {
173
+ const found = [];
174
+ for (const rule of rules) {
175
+ for (const mode of ['write', 'read', 'ref']) {
176
+ if (!rule[mode]) continue;
177
+ let re;
178
+ try {
179
+ re = new RegExp(rule[mode], rule.flags || 'g');
180
+ } catch (e) {
181
+ continue;
182
+ }
183
+ for (const m of content.matchAll(re)) {
184
+ const id = firstGroup(m);
185
+ if (id) found.push({ id: `${rule.kind}:${id}`, kind: rule.kind, mode });
186
+ }
187
+ }
188
+ }
189
+ return found;
190
+ }
191
+
192
+ // Convert an import specifier to a JS-style relative path, or null if external.
193
+ function toRelative(target) {
194
+ if (target.startsWith('./') || target.startsWith('../')) return target;
195
+ // Python dotted relative import: leading dots + dotted name, no slash.
196
+ if (/^\.+([A-Za-z_][\w.]*)?$/.test(target)) {
197
+ let i = 0;
198
+ while (target[i] === '.') i++;
199
+ const rest = target.slice(i).replace(/\./g, '/');
200
+ const prefix = i === 1 ? './' : '../'.repeat(i - 1);
201
+ return prefix + rest;
202
+ }
203
+ return null;
204
+ }
205
+
206
+ function resolveImport(fromAbs, target) {
207
+ const rel = toRelative(target);
208
+ if (rel === null) return null;
209
+ const base = path.resolve(path.dirname(fromAbs), rel);
210
+ const tries = [
211
+ base, base + '.js', base + '.ts', base + '.jsx', base + '.tsx',
212
+ base + '.mjs', base + '.cjs', base + '.py',
213
+ path.join(base, 'index.js'), path.join(base, 'index.ts'),
214
+ path.join(base, '__init__.py'),
215
+ ];
216
+ for (const t of tries) {
217
+ try {
218
+ if (fs.statSync(t).isFile()) return t;
219
+ } catch (e) { /* keep trying */ }
220
+ }
221
+ return null;
222
+ }
223
+
224
+ // Scan the repo and derive module-level edges.
225
+ // Returns { fileCount, edges }. Each edge:
226
+ // { a, b, directed, kind, details:[...], evidence:'relPath' }
227
+ function scanRepo(root, conf) {
228
+ const files = walkFiles(root, conf);
229
+ const fileModule = new Map(); // absPath -> module id
230
+ const contents = new Map(); // absPath -> text
231
+ const resourceMap = new Map(); // resource id -> { writers, readers, refs, kind }
232
+ const edgeMap = new Map(); // key -> edge
233
+ const importRes = IMPORT_PATTERNS.map((p) => new RegExp(p, 'g'));
234
+
235
+ // Pass 1: module of each file + resource references.
236
+ for (const abs of files) {
237
+ const rel = path.relative(root, abs);
238
+ const mod = moduleOf(rel, conf.moduleDepth);
239
+ fileModule.set(abs, mod);
240
+ let text;
241
+ try {
242
+ text = fs.readFileSync(abs, 'utf8');
243
+ } catch (e) {
244
+ continue;
245
+ }
246
+ contents.set(abs, text);
247
+
248
+ for (const r of extractResources(text, conf.rules)) {
249
+ let entry = resourceMap.get(r.id);
250
+ if (!entry) {
251
+ entry = { writers: new Map(), readers: new Map(), refs: new Map(), kind: r.kind };
252
+ resourceMap.set(r.id, entry);
253
+ }
254
+ const bucket = entry[BUCKET[r.mode]];
255
+ if (bucket && !bucket.has(mod)) bucket.set(mod, rel);
256
+ }
257
+ }
258
+
259
+ function addEdge(a, b, directed, kind, detail, evidence) {
260
+ if (a === b) return;
261
+ const key = directed
262
+ ? `${a}=>${b}|${kind}`
263
+ : [a, b].sort().join('--') + `|${kind}`;
264
+ let e = edgeMap.get(key);
265
+ if (!e) {
266
+ const [na, nb] = directed ? [a, b] : [a, b].slice().sort();
267
+ e = { a: na, b: nb, directed, kind, details: new Set(), evidence };
268
+ edgeMap.set(key, e);
269
+ }
270
+ e.details.add(detail);
271
+ }
272
+
273
+ // Pass 2: import edges (JS/TS + partial Python relative).
274
+ for (const abs of files) {
275
+ const text = contents.get(abs);
276
+ if (!text) continue;
277
+ const fromMod = fileModule.get(abs);
278
+ for (const re of importRes) {
279
+ for (const m of text.matchAll(re)) {
280
+ const target = firstGroup(m);
281
+ if (!target) continue;
282
+ const resolved = resolveImport(abs, target);
283
+ if (!resolved || !fileModule.has(resolved)) continue;
284
+ addEdge(fromMod, fileModule.get(resolved), false, 'import', target, path.relative(root, abs));
285
+ }
286
+ }
287
+ }
288
+
289
+ // Pass 3: shared-resource edges, including reverse write->read.
290
+ for (const [id, entry] of resourceMap) {
291
+ const writers = [...entry.writers.keys()];
292
+ const readers = [...entry.readers.keys()];
293
+ const refs = [...entry.refs.keys()];
294
+
295
+ for (const w of writers) {
296
+ for (const r of readers) {
297
+ addEdge(w, r, true, `data:${entry.kind}`, id, entry.writers.get(w));
298
+ }
299
+ }
300
+
301
+ // Undirected coupling among plain references (only when a `ref` side exists;
302
+ // table/queue have no ref mode, so this stays quiet by default).
303
+ const all = [...new Set([...writers, ...readers, ...refs])];
304
+ for (let i = 0; i < all.length; i++) {
305
+ for (let j = i + 1; j < all.length; j++) {
306
+ const directedAlready =
307
+ (entry.writers.has(all[i]) && entry.readers.has(all[j])) ||
308
+ (entry.writers.has(all[j]) && entry.readers.has(all[i]));
309
+ if (directedAlready) continue;
310
+ if (refs.includes(all[i]) || refs.includes(all[j])) {
311
+ addEdge(all[i], all[j], false, `shared:${entry.kind}`, id,
312
+ entry.refs.get(all[i]) || entry.refs.get(all[j]));
313
+ }
314
+ }
315
+ }
316
+ }
317
+
318
+ const edges = [...edgeMap.values()].map((e) => ({
319
+ a: e.a, b: e.b, directed: e.directed, kind: e.kind,
320
+ details: [...e.details], evidence: e.evidence,
321
+ }));
322
+
323
+ return { fileCount: files.length, edges };
324
+ }
325
+
326
+ module.exports = {
327
+ DEFAULT_IGNORE,
328
+ DEFAULT_EXTENSIONS,
329
+ DEFAULT_RULES,
330
+ OPTIONAL_RULES,
331
+ loadConfig,
332
+ resolveConfig,
333
+ scanRepo,
334
+ moduleOf,
335
+ };
@@ -12,38 +12,97 @@ function isProject(cwd) {
12
12
  );
13
13
  }
14
14
 
15
- // Detect which LLM tool config files/directories are present.
16
- // Returns a list of target descriptors. Each descriptor names the config file
17
- // the strategy should be injected into and the template it comes from.
15
+ // The coding agents we support. Each entry names the config file the strategy
16
+ // is injected into, the template it comes from, and the filesystem "signals"
17
+ // that hint the agent is in use here.
18
+ const TOOLS = {
19
+ claude: {
20
+ key: 'claude',
21
+ tool: 'Claude Code',
22
+ file: 'CLAUDE.md',
23
+ template: 'CLAUDE.md',
24
+ signals: ['CLAUDE.md', '.claude'],
25
+ },
26
+ cursor: {
27
+ key: 'cursor',
28
+ tool: 'Cursor',
29
+ file: '.cursorrules',
30
+ template: 'cursorrules',
31
+ signals: ['.cursorrules', '.cursor'],
32
+ },
33
+ agents: {
34
+ key: 'agents',
35
+ tool: 'Amp / Warp / Codex (AGENTS.md)',
36
+ file: 'AGENTS.md',
37
+ template: 'AGENTS.md',
38
+ signals: ['AGENTS.md'],
39
+ },
40
+ };
41
+
42
+ const ALL_KEYS = ['claude', 'cursor', 'agents'];
43
+
44
+ // Accept a few friendly spellings for the --tool flag.
45
+ const ALIASES = {
46
+ claude: 'claude',
47
+ 'claude-code': 'claude',
48
+ claudecode: 'claude',
49
+ cc: 'claude',
50
+ cursor: 'cursor',
51
+ agents: 'agents',
52
+ agent: 'agents',
53
+ 'agents.md': 'agents',
54
+ amp: 'agents',
55
+ warp: 'agents',
56
+ codex: 'agents',
57
+ };
58
+
59
+ // Which agents show signs of being used in this project. Informational only —
60
+ // by default we still write to every agent so nothing is missed.
61
+ function detectPresent(cwd) {
62
+ return ALL_KEYS.filter((key) =>
63
+ TOOLS[key].signals.some((s) => exists(path.join(cwd, s)))
64
+ );
65
+ }
66
+
67
+ // Resolve which config files to write to.
68
+ //
69
+ // toolArg undefined / null -> all agents (the safe default)
70
+ // toolArg 'all' -> all agents
71
+ // toolArg 'claude,cursor' -> just those (comma- or space-separated, aliases ok)
18
72
  //
19
- // If nothing is detected, all three targets are returned so the book works with
20
- // whichever tool the developer uses.
21
- function detectTargets(cwd) {
22
- const claude =
23
- exists(path.join(cwd, 'CLAUDE.md')) || exists(path.join(cwd, '.claude'));
24
- const cursor =
25
- exists(path.join(cwd, '.cursorrules')) || exists(path.join(cwd, '.cursor'));
26
- const agents = exists(path.join(cwd, 'AGENTS.md'));
27
-
28
- const all = {
29
- claude: { tool: 'Claude Code', file: 'CLAUDE.md', template: 'CLAUDE.md' },
30
- cursor: { tool: 'Cursor', file: '.cursorrules', template: 'cursorrules' },
31
- agents: { tool: 'Amp/Warp', file: 'AGENTS.md', template: 'AGENTS.md' },
32
- };
33
-
34
- const detected = [];
35
- if (claude) detected.push(all.claude);
36
- if (cursor) detected.push(all.cursor);
37
- if (agents) detected.push(all.agents);
38
-
39
- if (detected.length > 0) {
40
- return { detected: true, targets: detected };
73
+ // Returns { targets: [toolDescriptor], invalid: [badToken] }.
74
+ function resolveTargets(toolArg) {
75
+ if (!toolArg || String(toolArg).trim().toLowerCase() === 'all') {
76
+ return { targets: ALL_KEYS.map((k) => TOOLS[k]), invalid: [] };
77
+ }
78
+
79
+ const tokens = String(toolArg)
80
+ .split(/[,\s]+/)
81
+ .map((t) => t.trim().toLowerCase())
82
+ .filter(Boolean);
83
+
84
+ const keys = [];
85
+ const invalid = [];
86
+ for (const t of tokens) {
87
+ if (t === 'all') {
88
+ for (const k of ALL_KEYS) if (!keys.includes(k)) keys.push(k);
89
+ continue;
90
+ }
91
+ const k = ALIASES[t];
92
+ if (!k) {
93
+ invalid.push(t);
94
+ } else if (!keys.includes(k)) {
95
+ keys.push(k);
96
+ }
41
97
  }
42
98
 
43
- return { detected: false, targets: [all.claude, all.cursor, all.agents] };
99
+ return { targets: keys.map((k) => TOOLS[k]), invalid };
44
100
  }
45
101
 
46
102
  module.exports = {
47
103
  isProject,
48
- detectTargets,
104
+ detectPresent,
105
+ resolveTargets,
106
+ TOOLS,
107
+ ALL_KEYS,
49
108
  };