mandrel 2.78.0 → 2.80.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/.agents/README.md +6 -1
- package/.agents/agents/auditor.md +8 -3
- package/.agents/audit-checklists/architecture.md +1 -0
- package/.agents/audit-checklists/clean-code.md +1 -0
- package/.agents/audit-checklists/data-model.md +9 -1
- package/.agents/audit-checklists/devops.md +4 -1
- package/.agents/audit-checklists/security.md +1 -1
- package/.agents/docs/agentrc-reference.json +3 -0
- package/.agents/docs/configuration.md +2 -2
- package/.agents/docs/workflows.md +1 -1
- package/.agents/schemas/agentrc.schema.json +20 -2
- package/.agents/schemas/audit-rules.json +5 -1
- package/.agents/scripts/bootstrap.js +87 -16
- package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
- package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
- package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
- package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
- package/.agents/scripts/lib/close-validation/commands.js +33 -0
- package/.agents/scripts/lib/close-validation/gates.js +11 -4
- package/.agents/scripts/lib/config/explain.js +3 -2
- package/.agents/scripts/lib/config-settings-schema.js +20 -2
- package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
- package/.agents/scripts/lib/findings/route-finding.js +4 -3
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
- package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
- package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
- package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
- package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
- package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
- package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
- package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
- package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
- package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
- package/.agents/scripts/lib/test-run-credit.js +46 -17
- package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
- package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
- package/.agents/workflows/audit-architecture.md +20 -4
- package/.agents/workflows/audit-clean-code.md +17 -1
- package/.agents/workflows/audit-data-model.md +94 -10
- package/.agents/workflows/audit-devops.md +58 -14
- package/.agents/workflows/audit-performance.md +22 -0
- package/.agents/workflows/audit-quality.md +30 -0
- package/.agents/workflows/audit-security.md +23 -8
- package/.agents/workflows/audit-to-stories.md +22 -7
- package/.agents/workflows/helpers/audit-lens-core.md +56 -7
- package/.agents/workflows/helpers/plan-reference.md +11 -3
- package/README.md +13 -1
- package/docs/CHANGELOG.md +24 -0
- package/lib/cli/registry.js +85 -12
- package/lib/cli/uninstall.js +34 -18
- package/lib/cli/update.js +37 -6
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
- package/package.json +1 -1
|
@@ -9,6 +9,11 @@
|
|
|
9
9
|
|
|
10
10
|
import path from 'node:path';
|
|
11
11
|
|
|
12
|
+
import {
|
|
13
|
+
resolveTestCommand,
|
|
14
|
+
resolveTestGateArgv,
|
|
15
|
+
} from './close-validation/commands.js';
|
|
16
|
+
import { resolveConfig } from './config-resolver.js';
|
|
12
17
|
import { gitSpawn as defaultGitSpawn } from './git-utils.js';
|
|
13
18
|
import {
|
|
14
19
|
recordPass as defaultRecordPass,
|
|
@@ -19,11 +24,36 @@ import {
|
|
|
19
24
|
|
|
20
25
|
const GATE_NAME = 'test';
|
|
21
26
|
|
|
22
|
-
/**
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
/**
|
|
28
|
+
* The `test` credit identity. It must hash identically to the argv close
|
|
29
|
+
* spawns, so both derive from {@link resolveTestGateArgv}
|
|
30
|
+
* (`project.commands.test`, default `npm test`).
|
|
31
|
+
*
|
|
32
|
+
* @param {object|null|undefined} config - Resolved config; null → the default.
|
|
33
|
+
* @param {string} cwd
|
|
34
|
+
* @returns {string}
|
|
35
|
+
*/
|
|
36
|
+
function testGateConfigHash(config, cwd) {
|
|
37
|
+
const { cmd, args } = resolveTestGateArgv(config);
|
|
38
|
+
return hashCommandConfig({ cmd, args, cwd: path.resolve(cwd) });
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The injected config, else the checkout's resolved config, or null (→ the
|
|
43
|
+
* `npm test` default) when it cannot be read — a deposit never fails the run.
|
|
44
|
+
*
|
|
45
|
+
* @param {object|null|undefined} config
|
|
46
|
+
* @param {string} cwd
|
|
47
|
+
* @returns {object|null}
|
|
48
|
+
*/
|
|
49
|
+
function depositConfig(config, cwd) {
|
|
50
|
+
if (config !== undefined) return config;
|
|
51
|
+
try {
|
|
52
|
+
return resolveConfig({ cwd });
|
|
53
|
+
} catch {
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
27
57
|
|
|
28
58
|
/**
|
|
29
59
|
* @param {Function} gitSpawnFn
|
|
@@ -73,9 +103,11 @@ export function resolveEvidenceRoot(cwd, gitSpawnFn) {
|
|
|
73
103
|
* tier?: string,
|
|
74
104
|
* status?: number,
|
|
75
105
|
* durationMs?: number|null,
|
|
106
|
+
* config?: object|null,
|
|
76
107
|
* gitSpawnFn?: typeof defaultGitSpawn,
|
|
77
108
|
* recordPassFn?: typeof defaultRecordPass,
|
|
78
109
|
* }} args
|
|
110
|
+
* `config` defaults to the checkout's resolved config.
|
|
79
111
|
* @returns {{ deposited: boolean, reason: string, storyId?: number, sha?: string }}
|
|
80
112
|
*/
|
|
81
113
|
export function depositTestRunCredit({
|
|
@@ -83,6 +115,7 @@ export function depositTestRunCredit({
|
|
|
83
115
|
tier = 'full',
|
|
84
116
|
status = 0,
|
|
85
117
|
durationMs = null,
|
|
118
|
+
config,
|
|
86
119
|
gitSpawnFn = defaultGitSpawn,
|
|
87
120
|
recordPassFn = defaultRecordPass,
|
|
88
121
|
} = {}) {
|
|
@@ -102,6 +135,7 @@ export function depositTestRunCredit({
|
|
|
102
135
|
storyId,
|
|
103
136
|
sha,
|
|
104
137
|
cwd,
|
|
138
|
+
config: depositConfig(config, cwd),
|
|
105
139
|
evidenceRoot,
|
|
106
140
|
durationMs,
|
|
107
141
|
gitSpawnFn,
|
|
@@ -134,6 +168,7 @@ export function reportTestRunCredit({
|
|
|
134
168
|
* Every uncertainty resolves `false`.
|
|
135
169
|
*
|
|
136
170
|
* @param {{
|
|
171
|
+
* config?: object|null,
|
|
137
172
|
* storyId?: number|null,
|
|
138
173
|
* cwd?: string,
|
|
139
174
|
* evidenceCwd?: string|null,
|
|
@@ -144,6 +179,7 @@ export function reportTestRunCredit({
|
|
|
144
179
|
* @returns {boolean}
|
|
145
180
|
*/
|
|
146
181
|
export function predictsTestEvidenceCredit({
|
|
182
|
+
config,
|
|
147
183
|
storyId,
|
|
148
184
|
cwd,
|
|
149
185
|
evidenceCwd,
|
|
@@ -161,18 +197,14 @@ export function predictsTestEvidenceCredit({
|
|
|
161
197
|
storyId,
|
|
162
198
|
gateName: GATE_NAME,
|
|
163
199
|
currentSha: sha,
|
|
164
|
-
configHash:
|
|
165
|
-
cmd: GATE_COMMAND.cmd,
|
|
166
|
-
args: [...GATE_COMMAND.args],
|
|
167
|
-
cwd: path.resolve(cwd),
|
|
168
|
-
}),
|
|
200
|
+
configHash: testGateConfigHash(config, cwd),
|
|
169
201
|
inputFingerprint: treeFingerprint(cwd, gitSpawnImpl),
|
|
170
202
|
},
|
|
171
203
|
{ cwd: evidenceCwd ?? cwd, standalone: true },
|
|
172
204
|
);
|
|
173
205
|
if (verdict.skip !== true) return false;
|
|
174
206
|
log?.(
|
|
175
|
-
|
|
207
|
+
`[close-validation] a green \`${resolveTestCommand(config)}\` already deposited the test credit for this tree — registering the plain \`test\` gate so close reports it as credited.`,
|
|
176
208
|
);
|
|
177
209
|
return true;
|
|
178
210
|
} catch {
|
|
@@ -181,13 +213,14 @@ export function predictsTestEvidenceCredit({
|
|
|
181
213
|
}
|
|
182
214
|
|
|
183
215
|
/**
|
|
184
|
-
* @param {{ storyId: number, sha: string, cwd: string, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
|
|
216
|
+
* @param {{ storyId: number, sha: string, cwd: string, config: object|null, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
|
|
185
217
|
* @returns {{ deposited: boolean, reason: string, storyId: number, sha: string }}
|
|
186
218
|
*/
|
|
187
219
|
function writeRecord({
|
|
188
220
|
storyId,
|
|
189
221
|
sha,
|
|
190
222
|
cwd,
|
|
223
|
+
config,
|
|
191
224
|
evidenceRoot,
|
|
192
225
|
durationMs,
|
|
193
226
|
gitSpawnFn,
|
|
@@ -199,11 +232,7 @@ function writeRecord({
|
|
|
199
232
|
storyId,
|
|
200
233
|
gateName: GATE_NAME,
|
|
201
234
|
sha,
|
|
202
|
-
configHash:
|
|
203
|
-
cmd: GATE_COMMAND.cmd,
|
|
204
|
-
args: [...GATE_COMMAND.args],
|
|
205
|
-
cwd: path.resolve(cwd),
|
|
206
|
-
}),
|
|
235
|
+
configHash: testGateConfigHash(config, cwd),
|
|
207
236
|
exitCode: 0,
|
|
208
237
|
durationMs,
|
|
209
238
|
inputFingerprint: treeFingerprint(cwd, gitSpawnFn),
|
|
@@ -2,12 +2,15 @@
|
|
|
2
2
|
* lib/wave-runner/footprint.js — whether two Stories' declared footprints
|
|
3
3
|
* intersect. The footprint is the declaration only: paths scraped from
|
|
4
4
|
* titles, specs or prose manufactured far more serialisation than they
|
|
5
|
-
* prevented, so two Stories collide only when both declare a path
|
|
6
|
-
* declares a glob
|
|
5
|
+
* prevented, so two Stories collide only when both declare a path, one
|
|
6
|
+
* declares a glob covering the other's path, or both declare globs whose
|
|
7
|
+
* static bases overlap. Reads and mutates nothing.
|
|
7
8
|
*
|
|
8
9
|
* @module lib/wave-runner/footprint
|
|
9
10
|
*/
|
|
10
11
|
|
|
12
|
+
import picomatch from 'picomatch';
|
|
13
|
+
|
|
11
14
|
/**
|
|
12
15
|
* One class today; kept on the envelope so consumers keyed on `source` stay
|
|
13
16
|
* stable if a second class appears.
|
|
@@ -45,37 +48,118 @@ export function storyFootprint(story) {
|
|
|
45
48
|
* @param {string} path
|
|
46
49
|
* @returns {boolean}
|
|
47
50
|
*/
|
|
48
|
-
function isGlobPath(path) {
|
|
51
|
+
export function isGlobPath(path) {
|
|
49
52
|
return path.includes('*') || path.includes('?') || path.includes('{');
|
|
50
53
|
}
|
|
51
54
|
|
|
55
|
+
const GLOB_OPTIONS = Object.freeze({ dot: true });
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The glob's static directory prefix — `''` for a glob such as `**` or
|
|
59
|
+
* `*.md` that is rooted nowhere.
|
|
60
|
+
*
|
|
61
|
+
* @param {string} glob
|
|
62
|
+
* @returns {string}
|
|
63
|
+
*/
|
|
64
|
+
function globBase(glob) {
|
|
65
|
+
return picomatch.scan(glob).base;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Whole-segment prefix overlap: `lib` covers `lib/x`, never `libs`. An empty
|
|
70
|
+
* base overlaps everything.
|
|
71
|
+
*
|
|
72
|
+
* @param {string} x
|
|
73
|
+
* @param {string} y
|
|
74
|
+
* @returns {boolean}
|
|
75
|
+
*/
|
|
76
|
+
function basesOverlap(x, y) {
|
|
77
|
+
if (x === '' || y === '' || x === y) return true;
|
|
78
|
+
const [short, long] = x.length < y.length ? [x, y] : [y, x];
|
|
79
|
+
return long.startsWith(`${short}/`);
|
|
80
|
+
}
|
|
81
|
+
|
|
52
82
|
/**
|
|
53
|
-
*
|
|
54
|
-
*
|
|
83
|
+
* Whether two globs may match a common path, judged by their static bases.
|
|
84
|
+
* Conservative by design: two globs sharing a base may still be disjoint
|
|
85
|
+
* (`lib/*.js` vs `lib/*.md`), and the predicate serializes them anyway.
|
|
55
86
|
*
|
|
56
|
-
* @param {
|
|
57
|
-
* @param {
|
|
87
|
+
* @param {string} g
|
|
88
|
+
* @param {string} h
|
|
89
|
+
* @returns {boolean}
|
|
58
90
|
*/
|
|
59
|
-
function
|
|
60
|
-
|
|
61
|
-
|
|
91
|
+
export function globsOverlap(g, h) {
|
|
92
|
+
return basesOverlap(globBase(g), globBase(h));
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Record that `side` declared `path` as a colliding path.
|
|
97
|
+
*
|
|
98
|
+
* @param {Map<string, Set<string>>} hits
|
|
99
|
+
* @param {string} path
|
|
100
|
+
* @param {'a'|'b'} side
|
|
101
|
+
*/
|
|
102
|
+
function addHit(hits, path, side) {
|
|
103
|
+
const sides = hits.get(path) ?? new Set();
|
|
104
|
+
sides.add(side);
|
|
105
|
+
hits.set(path, sides);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Collect the globs on `globSide` that cover a concrete path or overlap a
|
|
110
|
+
* glob on `otherSide`. A glob hit reports the glob — the thing an author
|
|
111
|
+
* edits — never the concrete path it matched.
|
|
112
|
+
*
|
|
113
|
+
* @param {Map<string, Set<string>>} hits
|
|
114
|
+
* @param {{ globs: string[], concrete: string[] }} mine
|
|
115
|
+
* @param {{ globs: string[], concrete: string[] }} theirs
|
|
116
|
+
* @param {'a'|'b'} side
|
|
117
|
+
*/
|
|
118
|
+
function collectGlobHits(hits, mine, theirs, side) {
|
|
119
|
+
for (const glob of mine.globs) {
|
|
120
|
+
const matches = picomatch(glob, GLOB_OPTIONS);
|
|
121
|
+
const covers =
|
|
122
|
+
theirs.concrete.some((path) => matches(path)) ||
|
|
123
|
+
theirs.globs.some((other) => globsOverlap(glob, other));
|
|
124
|
+
if (covers) addHit(hits, glob, side);
|
|
62
125
|
}
|
|
63
126
|
}
|
|
64
127
|
|
|
128
|
+
/**
|
|
129
|
+
* @param {Set<string>} footprint
|
|
130
|
+
* @returns {{ globs: string[], concrete: string[] }}
|
|
131
|
+
*/
|
|
132
|
+
function partition(footprint) {
|
|
133
|
+
const globs = [];
|
|
134
|
+
const concrete = [];
|
|
135
|
+
for (const path of footprint)
|
|
136
|
+
(isGlobPath(path) ? globs : concrete).push(path);
|
|
137
|
+
return { globs, concrete };
|
|
138
|
+
}
|
|
139
|
+
|
|
65
140
|
/**
|
|
66
141
|
* Colliding paths, or `null`. An empty footprint never collides —
|
|
67
142
|
* withholding on absence would serialize every run.
|
|
68
143
|
*
|
|
144
|
+
* Two footprints collide on a concrete path both declare, on a glob that
|
|
145
|
+
* matches a concrete path the other side declares, or on two globs whose
|
|
146
|
+
* static bases overlap. The `**` UNKNOWN sentinel therefore collides with
|
|
147
|
+
* every non-empty footprint by construction: it matches every concrete path
|
|
148
|
+
* and its empty base overlaps every glob.
|
|
149
|
+
*
|
|
69
150
|
* `concreteOnly` is for the cross-beat reservation: an in-flight Story holds
|
|
70
151
|
* its footprint for hours, and unparseable bodies resolve to an UNKNOWN glob
|
|
71
152
|
* sentinel, so honouring globs there would make one bad Story serialize the
|
|
72
153
|
* whole run. The beat-local guard honours globs.
|
|
73
154
|
*
|
|
155
|
+
* `declaredBy` maps each colliding path to the side that declared it —
|
|
156
|
+
* `'a'`, `'b'` or `'both'` — so a refusal can name its declarer.
|
|
157
|
+
*
|
|
74
158
|
* @param {object} a
|
|
75
159
|
* @param {object} b
|
|
76
160
|
* @param {object} [options]
|
|
77
161
|
* @param {boolean} [options.concreteOnly=false] Skip glob paths on both sides.
|
|
78
|
-
* @returns {{ paths: string[], source: string }|null}
|
|
162
|
+
* @returns {{ paths: string[], source: string, declaredBy: Record<string, 'a'|'b'|'both'> }|null}
|
|
79
163
|
*/
|
|
80
164
|
export function detectCollision(a, b, { concreteOnly = false } = {}) {
|
|
81
165
|
const fa = storyFootprint(a);
|
|
@@ -83,14 +167,27 @@ export function detectCollision(a, b, { concreteOnly = false } = {}) {
|
|
|
83
167
|
const fb = storyFootprint(b);
|
|
84
168
|
if (fb.size === 0) return null;
|
|
85
169
|
|
|
86
|
-
const
|
|
87
|
-
|
|
88
|
-
|
|
170
|
+
const pa = partition(fa);
|
|
171
|
+
const pb = partition(fb);
|
|
172
|
+
/** @type {Map<string, Set<string>>} */
|
|
173
|
+
const hits = new Map();
|
|
174
|
+
for (const path of pa.concrete) {
|
|
175
|
+
if (fb.has(path)) {
|
|
176
|
+
addHit(hits, path, 'a');
|
|
177
|
+
addHit(hits, path, 'b');
|
|
178
|
+
}
|
|
89
179
|
}
|
|
90
180
|
if (!concreteOnly) {
|
|
91
|
-
|
|
92
|
-
|
|
181
|
+
collectGlobHits(hits, pa, pb, 'a');
|
|
182
|
+
collectGlobHits(hits, pb, pa, 'b');
|
|
93
183
|
}
|
|
94
184
|
if (hits.size === 0) return null;
|
|
95
|
-
|
|
185
|
+
const paths = [...hits.keys()].sort();
|
|
186
|
+
const declaredBy = Object.fromEntries(
|
|
187
|
+
paths.map((path) => {
|
|
188
|
+
const sides = hits.get(path);
|
|
189
|
+
return [path, sides.size === 2 ? 'both' : [...sides][0]];
|
|
190
|
+
}),
|
|
191
|
+
);
|
|
192
|
+
return { paths, source: OVERLAP_SOURCES.DECLARED, declaredBy };
|
|
96
193
|
}
|
|
@@ -83,9 +83,9 @@ export function classifyStory(story) {
|
|
|
83
83
|
|
|
84
84
|
/**
|
|
85
85
|
* Beat-local overlap guard: `true` when two footprints intersect. A glob
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
* only.
|
|
86
|
+
* collides with every path it can match and with any glob whose static base
|
|
87
|
+
* overlaps its own, so the `**` UNKNOWN sentinel still collides with every
|
|
88
|
+
* declared footprint; honouring globs is beat-local only.
|
|
89
89
|
*
|
|
90
90
|
* @param {StoryRecord} a
|
|
91
91
|
* @param {StoryRecord} b
|
|
@@ -282,6 +282,17 @@ function blockingCollision({ rec, id, selected, reserved, evidence }) {
|
|
|
282
282
|
return peer ? { ...peer, scope: WITHHOLD_SCOPES.BEAT } : null;
|
|
283
283
|
}
|
|
284
284
|
|
|
285
|
+
/**
|
|
286
|
+
* A withhold row keeps `paths` and `source` only — the ledger shape predates
|
|
287
|
+
* the collision's `declaredBy` attribution.
|
|
288
|
+
*
|
|
289
|
+
* @param {number|null} blockedBy
|
|
290
|
+
* @param {{ paths: string[], source: string }} collision
|
|
291
|
+
*/
|
|
292
|
+
function blockerRow(blockedBy, { paths, source }) {
|
|
293
|
+
return { blockedBy, paths, source };
|
|
294
|
+
}
|
|
295
|
+
|
|
285
296
|
/**
|
|
286
297
|
* The same-beat peer this candidate would race, with the colliding paths, so
|
|
287
298
|
* an unfilled slot is never unexplained.
|
|
@@ -294,7 +305,7 @@ function blockingCollision({ rec, id, selected, reserved, evidence }) {
|
|
|
294
305
|
function findBeatBlocker(candidate, selected, options = {}) {
|
|
295
306
|
for (const picked of selected) {
|
|
296
307
|
const collision = detectCollision(picked, candidate, options);
|
|
297
|
-
if (collision) return
|
|
308
|
+
if (collision) return blockerRow(storyIdOf(picked), collision);
|
|
298
309
|
}
|
|
299
310
|
return null;
|
|
300
311
|
}
|
|
@@ -315,7 +326,7 @@ function findInFlightBlocker(candidate, candidateId, reserved, options = {}) {
|
|
|
315
326
|
const heldId = storyIdOf(held);
|
|
316
327
|
if (heldId === null || heldId === candidateId) continue;
|
|
317
328
|
const collision = reservesConcretePath(held, candidate, options);
|
|
318
|
-
if (collision) return
|
|
329
|
+
if (collision) return blockerRow(heldId, collision);
|
|
319
330
|
}
|
|
320
331
|
return null;
|
|
321
332
|
}
|
|
@@ -75,14 +75,30 @@ the failure mode this lens exists to prevent.
|
|
|
75
75
|
that is both heavily depended upon and frequently churned is the
|
|
76
76
|
highest-priority structural hotspot; lead the Triage Summary with it.
|
|
77
77
|
|
|
78
|
-
4. **
|
|
78
|
+
4. **Non-JS ecosystems.** Detect ecosystems per the core's
|
|
79
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and
|
|
80
|
+
run each detected one's rung (absent scanner = Low `Standardization` gap;
|
|
81
|
+
undetected ecosystem = inapplicable, never a finding). **Python:**
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pydeps <package> --show-cycles --no-output # import graph / cycles
|
|
85
|
+
lint-imports # import-linter layer contracts
|
|
86
|
+
vulture <srcDir> # dead-export / dead-wiring candidates
|
|
87
|
+
radon cc -s -n C <srcDir> # testable surface: complex units to check for interleaved I/O
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Rank Python hotspots by fan-in / fan-out from the `pydeps` graph exactly as
|
|
91
|
+
step 3 does. Go and Rust use the core's fallback table.
|
|
92
|
+
|
|
93
|
+
5. **LLM triage on top.** Only after the tools have run do you apply the Step 2
|
|
79
94
|
dimensions to interpret, rank, and phrase the findings. A structural claim
|
|
80
95
|
that no tool grounds and no Step 2 dimension covers does not belong in this
|
|
81
96
|
report — route it to the ceded clean-code dimensions instead.
|
|
82
97
|
|
|
83
|
-
When a
|
|
84
|
-
**Automated Architecture Guardrails** finding (the
|
|
85
|
-
broken) rather than skipping the step silently.
|
|
98
|
+
When a checker for a **detected** ecosystem exits non-zero or is genuinely
|
|
99
|
+
absent, record that as an **Automated Architecture Guardrails** finding (the
|
|
100
|
+
guardrail is missing or broken) rather than skipping the step silently. A
|
|
101
|
+
checker for an undetected ecosystem is inapplicable and never a finding.
|
|
86
102
|
|
|
87
103
|
## Step 1: Context Gathering (Read-Only Scan)
|
|
88
104
|
|
|
@@ -81,7 +81,23 @@ run the tools first.
|
|
|
81
81
|
files auto-loaded by convention (globbed listener/plugin dirs): reachable
|
|
82
82
|
via the framework, not the import graph.
|
|
83
83
|
|
|
84
|
-
5. **
|
|
84
|
+
5. **Non-JS ecosystems.** Detect ecosystems per the core's
|
|
85
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and
|
|
86
|
+
run each detected one's rung (absent scanner = Low `Standardization` gap;
|
|
87
|
+
undetected ecosystem = inapplicable, never a finding). **Python:**
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
radon cc -s -a <srcDir> && radon mi -s <srcDir> # complexity / MI
|
|
91
|
+
pylint --disable=all --enable=duplicate-code <srcDir> # duplication (or jscpd)
|
|
92
|
+
vulture <srcDir> # dead code
|
|
93
|
+
ruff check --select E722,BLE,S110,N <srcDir> # silent failures, naming
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Apply the dead-code exclusion taxonomy above to `vulture` output too
|
|
97
|
+
(entry points, `__all__` exports, decorator-registered hooks). Go and Rust
|
|
98
|
+
use the core's fallback table.
|
|
99
|
+
|
|
100
|
+
6. **Churn-by-complexity hotspot cap.** Rank candidate hotspots by
|
|
85
101
|
**churn × complexity** (frequently-changed files that also score poorly on
|
|
86
102
|
MI/CRAP) and **cap the Detailed Findings at the top ~15 hotspots** so the
|
|
87
103
|
report stays a ranked, actionable batch rather than an exhaustive dump. Note
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity,
|
|
2
|
+
description: Audit the persistence layer as a first-class artifact — model↔migration↔seed drift, constraint completeness, migration hygiene, type fidelity, access-pattern fit, and dead schema — with an opt-in read-only live-schema pass; gated by a persistence-layer applicability probe so DB-less repos skip cleanly.
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Data Model & Persistence Audit
|
|
@@ -8,11 +8,15 @@ You are a Data Modeler & Database Reliability Engineer analyzing the persistence
|
|
|
8
8
|
layer — ORM model definitions, the migrations they should produce, and the seed
|
|
9
9
|
data — as a first-class artifact, finding where model, migrations, and runtime
|
|
10
10
|
schema silently disagree, where an assumed invariant is not enforced by a
|
|
11
|
-
constraint,
|
|
11
|
+
constraint, where a migration is unsafe against a live database, and where
|
|
12
|
+
schema exists that nothing uses. The shared lens machinery lives in
|
|
12
13
|
[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
|
|
13
14
|
`{{auditOutputDir}}/audit-data-model-results.md`. Dimension values:
|
|
14
15
|
`Drift | Constraint Completeness | Migration Hygiene | Type Fidelity |
|
|
15
|
-
Access-Pattern Fit
|
|
16
|
+
Access-Pattern Fit | Dead Schema`. Extra finding field: **Evidence:** (a
|
|
17
|
+
reference-count or introspection command plus a `measured`, `static`, or
|
|
18
|
+
`provisional` tag). The report adds a **Low-Hanging Fruit** section and a
|
|
19
|
+
**Live Schema Verification** section.
|
|
16
20
|
|
|
17
21
|
## Applicability
|
|
18
22
|
|
|
@@ -54,9 +58,13 @@ the consumer ships the tooling:
|
|
|
54
58
|
|
|
55
59
|
- **ORM drift tooling (preferred):** When the consumer ships an ORM CLI, run its
|
|
56
60
|
read-only drift/status command and treat its output as primary evidence —
|
|
57
|
-
`prisma migrate diff` / `prisma migrate status`, `
|
|
58
|
-
`
|
|
59
|
-
|
|
61
|
+
`prisma migrate diff` / `prisma migrate status`, or `typeorm schema:log`. On
|
|
62
|
+
Drizzle, run `drizzle-kit generate --out <temp dir>` with the output pointed
|
|
63
|
+
under `{{auditOutputDir}}`: a non-empty generated migration is exactly the
|
|
64
|
+
model↔migration drift, and the repo's own migrations directory is never
|
|
65
|
+
written. Drizzle's snapshot-consistency check validates the snapshot chain,
|
|
66
|
+
not drift, so it is not drift evidence. None of these needs a live
|
|
67
|
+
database.
|
|
60
68
|
- **Read-only file fallback:** When no ORM CLI is present (or it needs a live
|
|
61
69
|
database this audit must not touch), fall back to reading the model
|
|
62
70
|
definitions, the migration files, and the seed scripts directly. This
|
|
@@ -96,6 +104,73 @@ Evaluate the persistence layer along these five dimensions:
|
|
|
96
104
|
unindexed foreign keys and unindexed frequent filter columns, relations that
|
|
97
105
|
force N+1 access, and soft-delete rows that leak through default queries
|
|
98
106
|
because no default scope excludes them.
|
|
107
|
+
6. **Dead schema:** Is every table, column, index, and enum the schema defines
|
|
108
|
+
actually used, and does everything the code uses actually exist?
|
|
109
|
+
- **Unused schema:** a schema symbol with zero references in the **query
|
|
110
|
+
surface** — every source file minus the schema files themselves,
|
|
111
|
+
`**/migrations/**`, and seed/fixture files. A symbol referenced only from
|
|
112
|
+
tests is still reported, with that fact in Current State. Cite the
|
|
113
|
+
reference-count command in **Evidence**.
|
|
114
|
+
- **Schema gap:** the reverse — a table or column the code references that the
|
|
115
|
+
schema lacks. Unindexed foreign keys stay under Access-Pattern Fit.
|
|
116
|
+
- **Provisional until corroborated:** raw SQL strings, `select *`, and
|
|
117
|
+
JSON/builder access hide references from a static count, so a zero-count
|
|
118
|
+
finding is tagged `provisional` and never graded above Medium until the
|
|
119
|
+
live pass corroborates it.
|
|
120
|
+
- **Common identifiers are runtime-only:** a column whose name is a common
|
|
121
|
+
identifier (`id`, `name`, `createdAt`, `updatedAt`, and the like) matches
|
|
122
|
+
unrelated code, so the static pass never reports it.
|
|
123
|
+
|
|
124
|
+
The core's **Entry points & public API surface** and **Dynamic / framework
|
|
125
|
+
reachability** exclusions apply unchanged.
|
|
126
|
+
|
|
127
|
+
## Step 3: Live Schema Verification (opt-in, manual runs only)
|
|
128
|
+
|
|
129
|
+
Static detection always runs; this pass corroborates it against a live
|
|
130
|
+
database. It reuses the shared scaffold in
|
|
131
|
+
[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md#runtime-pass) for
|
|
132
|
+
target resolution and the skip-never-fake rule. Scaffold steps 2 (route
|
|
133
|
+
sampling) and 4 (median-of-3) do not apply: schema introspection is
|
|
134
|
+
deterministic and has no routes.
|
|
135
|
+
|
|
136
|
+
**When it runs.** Only on a manual invocation — when the `{{changedFiles}}`
|
|
137
|
+
fence above is the literal token. A populated fence (a `/mandrel-deliver` close
|
|
138
|
+
lens or a plan-run audit) always reports `skipped — change-set scoped run`; a
|
|
139
|
+
database connection never enters the close gate.
|
|
140
|
+
|
|
141
|
+
**The target.** The resolved environment's `qa.environments.<env>.database`
|
|
142
|
+
block names the environment variable holding the connection string
|
|
143
|
+
(`urlEnv`) and opts the environment in (`allowAudit`). Read the connection
|
|
144
|
+
string from that variable only; never print, log, or write it into the report.
|
|
145
|
+
|
|
146
|
+
**The probe.** Run only these read-only steps:
|
|
147
|
+
|
|
148
|
+
- **Introspection diff:** introspect the live schema into
|
|
149
|
+
`{{auditOutputDir}}/live-schema/` with the ORM's read-only introspection
|
|
150
|
+
command (`drizzle-kit introspect`, or `prisma db pull` against a temp copy of
|
|
151
|
+
the schema file), then diff it against the committed schema. Each hunk is a
|
|
152
|
+
model↔live **Drift** finding tagged `measured`.
|
|
153
|
+
- **Migration ledger:** compare the repo's migration journal to the live
|
|
154
|
+
migrations table. Report applied-but-absent-from-repo, pending, and
|
|
155
|
+
hash-mismatched entries under **Migration Hygiene**.
|
|
156
|
+
- **Catalog statistics (Postgres):** read `pg_stat_user_tables` and
|
|
157
|
+
`pg_stat_user_indexes`. A table never scanned or an index never used
|
|
158
|
+
graduates the matching provisional **Dead Schema** finding to `measured`.
|
|
159
|
+
Columns have no catalog statistic and stay static. Note the statistics reset
|
|
160
|
+
time, since a recent reset makes zero scans meaningless.
|
|
161
|
+
|
|
162
|
+
**Skip reasons.** The pass is skipped, never faked, and the Executive Summary
|
|
163
|
+
names which:
|
|
164
|
+
|
|
165
|
+
| Condition | Reported as |
|
|
166
|
+
| --- | --- |
|
|
167
|
+
| The fence carries a change set | `skipped — change-set scoped run` |
|
|
168
|
+
| No `database` block on the resolved environment, or `allowAudit` is false | `skipped — no database target configured` |
|
|
169
|
+
| The variable is unset or the connection fails | `skipped — database unreachable` |
|
|
170
|
+
| No ORM introspection command is available | `skipped — ORM introspection unavailable` |
|
|
171
|
+
|
|
172
|
+
When no SQL client is on PATH, the catalog step alone reports `catalog client
|
|
173
|
+
unavailable` and Dead Schema findings stay provisional.
|
|
99
174
|
|
|
100
175
|
## Not-applicable report
|
|
101
176
|
|
|
@@ -118,9 +193,18 @@ _None — lens not applicable._
|
|
|
118
193
|
|
|
119
194
|
## Constraint (lens-specific carve-out)
|
|
120
195
|
|
|
121
|
-
This lens is read-only over
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
196
|
+
This lens is read-only over repo-observable state — schema files, migrations,
|
|
197
|
+
ORM config, and read-only ORM drift/status commands — plus, in Step 3 only, an
|
|
198
|
+
opted-in database:
|
|
199
|
+
|
|
200
|
+
- It MUST NOT connect to a **production** database, under any configuration.
|
|
201
|
+
- It connects to any other database **only** when that environment opts in via
|
|
202
|
+
`allowAudit`, **only** through the environment variable named by `urlEnv`,
|
|
203
|
+
and **only** with read-only introspection and catalog `SELECT`s. Any direct
|
|
204
|
+
session it opens sets `default_transaction_read_only=on` first.
|
|
205
|
+
- It MUST NOT run a migration, a `push` / `migrate` / `generate` against the
|
|
206
|
+
live target, a destructive ORM command, or any statement that writes.
|
|
207
|
+
- Besides the report, its only writes are the generated drift output and the
|
|
208
|
+
introspected schema under `{{auditOutputDir}}`. API-contract/serialization coverage is
|
|
125
209
|
out of scope (deferred `audit-contract-compat` territory), and runtime query
|
|
126
210
|
profiling belongs to `audit-performance`, which owns measured behavior.
|