codebook-strategy 1.0.4 → 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 +48 -0
- package/bin/cli.js +9 -0
- package/package.json +1 -1
- package/src/commands/audit.js +180 -0
- package/src/commands/shared.js +39 -0
- package/src/utils/audit-scan.js +335 -0
package/README.md
CHANGED
|
@@ -97,6 +97,54 @@ Checks the book for consistency:
|
|
|
97
97
|
|
|
98
98
|
Prints a warning for each mismatch and exits non-zero if any are found, so it fits in CI.
|
|
99
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
|
+
|
|
100
148
|
## Works with
|
|
101
149
|
|
|
102
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,12 +17,18 @@ ${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
23
|
--tool <list> Which agents to set up: claude, cursor, agents, or all.
|
|
22
24
|
Comma-separated. Default: all (covers every agent).
|
|
23
25
|
--force Overwrite an existing book/ directory
|
|
24
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.
|
|
31
|
+
|
|
25
32
|
${bold('After init')}
|
|
26
33
|
Tell your LLM: ${dim('"Implement the book strategy"')}
|
|
27
34
|
`;
|
|
@@ -38,6 +45,8 @@ function main(argv) {
|
|
|
38
45
|
return status(rest);
|
|
39
46
|
case 'validate':
|
|
40
47
|
return validate(rest);
|
|
48
|
+
case 'audit':
|
|
49
|
+
return audit(rest);
|
|
41
50
|
case '-h':
|
|
42
51
|
case '--help':
|
|
43
52
|
case 'help':
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codebook-strategy",
|
|
3
|
-
"version": "1.0
|
|
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;
|
package/src/commands/shared.js
CHANGED
|
@@ -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
|
+
};
|