mandrel 2.78.0 → 2.79.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/audit-checklists/architecture.md +1 -0
- package/.agents/audit-checklists/clean-code.md +1 -0
- package/.agents/audit-checklists/devops.md +4 -1
- package/.agents/audit-checklists/security.md +1 -1
- package/.agents/docs/configuration.md +1 -1
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/bootstrap.js +87 -16
- 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 +2 -1
- package/.agents/scripts/lib/config-settings-schema.js +2 -1
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
- package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
- package/.agents/scripts/lib/test-run-credit.js +46 -17
- package/.agents/workflows/audit-architecture.md +20 -4
- package/.agents/workflows/audit-clean-code.md +17 -1
- 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/helpers/audit-lens-core.md +48 -2
- package/README.md +13 -1
- package/docs/CHANGELOG.md +15 -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
|
@@ -23,7 +23,10 @@ import path from 'node:path';
|
|
|
23
23
|
import { fileURLToPath } from 'node:url';
|
|
24
24
|
|
|
25
25
|
import { spawnCaptureAsync } from '../child-exec.js';
|
|
26
|
-
import {
|
|
26
|
+
import {
|
|
27
|
+
resolveLintCommand,
|
|
28
|
+
resolveTestGateArgv,
|
|
29
|
+
} from '../close-validation/commands.js';
|
|
27
30
|
import {
|
|
28
31
|
isCrapGateEnabled,
|
|
29
32
|
resolveCreditedDepositor,
|
|
@@ -331,6 +334,15 @@ function selectCreditedDepositor({ config, ...probe }) {
|
|
|
331
334
|
return resolveCreditedDepositor({ config, baseBranch, ...probe });
|
|
332
335
|
}
|
|
333
336
|
|
|
337
|
+
/**
|
|
338
|
+
* @param {object|null|undefined} config
|
|
339
|
+
* @returns {string[]}
|
|
340
|
+
*/
|
|
341
|
+
function testGateArgv(config) {
|
|
342
|
+
const { cmd, args } = resolveTestGateArgv(config);
|
|
343
|
+
return [cmd, ...args];
|
|
344
|
+
}
|
|
345
|
+
|
|
334
346
|
/** @param {object} ctx @returns {Promise<StepResult>} */
|
|
335
347
|
async function stepCreditedRun(ctx) {
|
|
336
348
|
const name = 'credited-run';
|
|
@@ -358,8 +370,8 @@ async function stepCreditedRun(ctx) {
|
|
|
358
370
|
'--worktree',
|
|
359
371
|
ctx.cwd,
|
|
360
372
|
'--',
|
|
361
|
-
'
|
|
362
|
-
|
|
373
|
+
// Close's `test` gate argv, so the deposit keys on its credit identity.
|
|
374
|
+
...testGateArgv(ctx.config),
|
|
363
375
|
]);
|
|
364
376
|
const extra = { evidencePath: run.evidencePath, depositor: ctx.depositor };
|
|
365
377
|
if (run.status !== 0) {
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* manufactures a pass.
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
|
+
import { resolveTestGateArgv } from '../close-validation/commands.js';
|
|
8
9
|
import { getQuality, resolveConfig } from '../config-resolver.js';
|
|
9
10
|
import { isCoverageFresh } from '../coverage-capture.js';
|
|
10
11
|
import { gitSpawn } from '../git-utils.js';
|
|
@@ -134,7 +135,8 @@ export function resolveVerifyCredit(
|
|
|
134
135
|
fullSuite: true,
|
|
135
136
|
warning: FULL_SUITE_SHAPE_WARNING,
|
|
136
137
|
};
|
|
137
|
-
const
|
|
138
|
+
const config = resolveConfigImpl({ cwd: worktree });
|
|
139
|
+
const { crap } = getQualityImpl(config);
|
|
138
140
|
const mode =
|
|
139
141
|
crap?.enabled !== false &&
|
|
140
142
|
hasNpmScriptImpl(readPackageScriptsImpl(worktree), 'test:coverage')
|
|
@@ -163,6 +165,7 @@ export function resolveVerifyCredit(
|
|
|
163
165
|
// A stale stamp is not the last word: a green `npm test` deposits `test`
|
|
164
166
|
// evidence, consulted in both modes before spawning.
|
|
165
167
|
const verdict = readTestEvidence({
|
|
168
|
+
config,
|
|
166
169
|
storyId,
|
|
167
170
|
worktree,
|
|
168
171
|
cwd,
|
|
@@ -184,10 +187,13 @@ export function resolveVerifyCredit(
|
|
|
184
187
|
/**
|
|
185
188
|
* An unreadable HEAD is `no-head`, never a credit.
|
|
186
189
|
*
|
|
187
|
-
*
|
|
190
|
+
* The hashed argv is close's `test` gate argv (`project.commands.test`).
|
|
191
|
+
*
|
|
192
|
+
* @param {{ config: object|null, storyId: number|string, worktree: string, cwd: string, gitSpawnFn: Function, shouldSkipImpl: Function, hashCommandConfigImpl: Function, treeFingerprintImpl: Function }} args
|
|
188
193
|
* @returns {{ skip: boolean, reason: string }}
|
|
189
194
|
*/
|
|
190
195
|
function readTestEvidence({
|
|
196
|
+
config,
|
|
191
197
|
storyId,
|
|
192
198
|
worktree,
|
|
193
199
|
cwd,
|
|
@@ -204,8 +210,7 @@ function readTestEvidence({
|
|
|
204
210
|
gateName: 'test',
|
|
205
211
|
currentSha: headSha,
|
|
206
212
|
configHash: hashCommandConfigImpl({
|
|
207
|
-
|
|
208
|
-
args: ['test'],
|
|
213
|
+
...resolveTestGateArgv(config),
|
|
209
214
|
cwd: worktree,
|
|
210
215
|
}),
|
|
211
216
|
inputFingerprint: treeFingerprintImpl(worktree, gitSpawnFn),
|
|
@@ -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),
|
|
@@ -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
|
|
@@ -27,13 +27,19 @@ Execution strategy.
|
|
|
27
27
|
## Step 1: Detection Battery (Read-Only, Tool-First)
|
|
28
28
|
|
|
29
29
|
Do **not** audit CI/CD from memory. Run the deterministic battery below first
|
|
30
|
-
and let its output ground every finding.
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
30
|
+
and let its output ground every finding. Detect the CI systems and language
|
|
31
|
+
ecosystems first per the core's
|
|
32
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and run
|
|
33
|
+
only the rungs for what is detected. Each tool is **presence-gated**: when the
|
|
34
|
+
binary for a **detected** surface is absent, record the gap as a Low-severity
|
|
35
|
+
`Standardization` finding (recommend adopting the scanner) and continue — a
|
|
36
|
+
missing scanner degrades the audit gracefully, it never aborts it. A tool for
|
|
37
|
+
an **undetected** surface is inapplicable and never a finding — `actionlint`,
|
|
38
|
+
`zizmor` and `gh run list` on a repo with no `.github/workflows/` are skipped,
|
|
39
|
+
not reported missing.
|
|
40
|
+
|
|
41
|
+
1. **Workflow static analysis (`actionlint`, GitHub Actions only).** When
|
|
42
|
+
`.github/workflows/` contains any `*.yml` / `*.yaml`, run:
|
|
37
43
|
|
|
38
44
|
```bash
|
|
39
45
|
command -v actionlint >/dev/null 2>&1 && actionlint -color=never || \
|
|
@@ -76,11 +82,49 @@ degrades the audit gracefully, it never aborts it.
|
|
|
76
82
|
or whose p95 duration is an outlier is a Reliability or Performance finding
|
|
77
83
|
with the observed number cited in **Current State**.
|
|
78
84
|
|
|
85
|
+
5. **Google Cloud Build (gated: `cloudbuild*.yaml` present).** Read each
|
|
86
|
+
definition for unpinned builder images (`gcr.io/cloud-builders/*` without a
|
|
87
|
+
digest/tag), secrets passed as plain `env` instead of `secretEnv` /
|
|
88
|
+
`availableSecrets`, an over-broad build service account, and missing
|
|
89
|
+
`timeout`. Then pull run history the same way step 4 does:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
gcloud builds list --limit 50 --format=json 2>/dev/null || \
|
|
93
|
+
echo "gcloud build history unavailable — Cloud Build findings degrade to config-only reasoning"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Compute failure rate (`FAILURE` + `TIMEOUT` + `CANCELLED` / total) and
|
|
97
|
+
p50/p95 duration (`finishTime − startTime`) per trigger.
|
|
98
|
+
|
|
99
|
+
6. **GitLab CI (gated: `.gitlab-ci.yml` present).** Validate the definition
|
|
100
|
+
and read it for unpinned `image:` tags, `variables:` carrying secrets,
|
|
101
|
+
missing `rules:` / `interruptible:`, and absent `cache:` keys:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
glab ci lint 2>/dev/null || echo "glab: not installed — recommend adding it (Standardization gap)"
|
|
105
|
+
glab ci list --per-page 50 -F json 2>/dev/null || \
|
|
106
|
+
echo "glab pipeline history unavailable — GitLab findings degrade to config-only reasoning"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Compute failure rate and p50/p95 duration per pipeline as in step 4.
|
|
110
|
+
Azure Pipelines (`azure-pipelines.yml`) is read config-only, with
|
|
111
|
+
`az pipelines runs list` as its history source when the CLI is present.
|
|
112
|
+
|
|
113
|
+
7. **Python toolchain (gated: Python manifests present).** Read the build and
|
|
114
|
+
lint configuration the Python manifests declare — `pyproject.toml`
|
|
115
|
+
(`[build-system]`, `[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`),
|
|
116
|
+
`.pre-commit-config.yaml`, a lockfile (`uv.lock`, `poetry.lock`,
|
|
117
|
+
`requirements*.txt` with hashes) — and check that CI runs the linters and
|
|
118
|
+
type-checker the config declares. Validate with
|
|
119
|
+
`pre-commit validate-config` and `ruff check --statistics` where present.
|
|
120
|
+
|
|
79
121
|
Then read the surfaces the battery flags plus the standing config set:
|
|
80
|
-
CI/CD pipelines (`.github/workflows/`, `.gitlab-ci.yml`,
|
|
81
|
-
dependency/script manifests (`package.json`,
|
|
82
|
-
|
|
83
|
-
|
|
122
|
+
CI/CD pipelines (`.github/workflows/`, `cloudbuild*.yaml`, `.gitlab-ci.yml`,
|
|
123
|
+
`azure-pipelines.yml`), dependency/script manifests (`package.json`,
|
|
124
|
+
`pnpm-workspace.yaml`, `pyproject.toml`, `requirements*.txt`), lint/format
|
|
125
|
+
configs (`.eslintrc*`, `.prettierrc*`, `biome.json`, `tsconfig.json`,
|
|
126
|
+
`ruff.toml`, `.pre-commit-config.yaml`), and git hooks / commit standards
|
|
127
|
+
(`.husky/`, `commitlint.config.js`).
|
|
84
128
|
|
|
85
129
|
## Step 2: Analysis Dimensions
|
|
86
130
|
|
|
@@ -92,8 +136,8 @@ when absent, state "not present in scope" and skip.
|
|
|
92
136
|
1. **Redundancy & Duplication:** Overlapping tools or conflicting rules (e.g.,
|
|
93
137
|
Prettier vs. ESLint formatting, duplicated scripts in `package.json` and CI).
|
|
94
138
|
2. **Performance Gaps:** Bottlenecks in CI/CD, slow caching strategies, or
|
|
95
|
-
unoptimized hooks (e.g., missing `lint-staged`) — cite the
|
|
96
|
-
durations from Step 1.
|
|
139
|
+
unoptimized hooks (e.g., missing `lint-staged`) — cite the run-history
|
|
140
|
+
durations from Step 1 (`gh run list`, `gcloud builds list`, `glab ci list`).
|
|
97
141
|
3. **Security & Compliance:** Missing secret scanning, loose permissions (e.g.,
|
|
98
142
|
`GITHUB_TOKEN` scopes), outdated or vulnerable dependency resolution
|
|
99
143
|
strategies — grounded in the `zizmor` output.
|
|
@@ -103,7 +147,7 @@ when absent, state "not present in scope" and skip.
|
|
|
103
147
|
surfaced in Step 1.
|
|
104
148
|
5. **Reliability & Resilience:** Fragile pipeline steps, missing error handling,
|
|
105
149
|
silent failures, or lack of retries for network-dependent tasks — cite the
|
|
106
|
-
|
|
150
|
+
run-history failure rates from Step 1 for every detected CI system.
|
|
107
151
|
|
|
108
152
|
### Sub-step A — Dockerfile hardening (gated: `Dockerfile*` present)
|
|
109
153
|
|
|
@@ -75,6 +75,28 @@ npx vite build --profile # or the repo's own build script
|
|
|
75
75
|
du -sh dist/ && find dist -name '*.js' -exec wc -c {} + | sort -n | tail
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
+
**Non-JS ecosystems.** Detect ecosystems per the core's
|
|
79
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and run
|
|
80
|
+
each detected one's rung (absent profiler = Low `Standardization` gap;
|
|
81
|
+
undetected ecosystem = inapplicable, never a finding). **Python** — timing,
|
|
82
|
+
CPU, memory, and interleaving:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
hyperfine --warmup 1 'python -m <entry> --help' # timing / cold start
|
|
86
|
+
python -X importtime -m <entry> --help 2>&1 | sort -t'|' -k2 -n | tail # import cost
|
|
87
|
+
py-spy record -o temp/audits/pyspy.svg -- python -m <entry> <args> # CPU (sampling)
|
|
88
|
+
python -m cProfile -s cumtime -m <entry> <args> | head -40 # CPU (fallback)
|
|
89
|
+
python -X tracemalloc=5 -m <entry> <args> # memory: tracemalloc snapshot diff (or memray run)
|
|
90
|
+
python -X dev -W error::RuntimeWarning -m <entry> <args> # interleaving: "coroutine was never awaited"
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`py-spy` / `cProfile` hot frames are the Python counterpart of `--cpu-prof`;
|
|
94
|
+
an asyncio "never awaited" warning under `-X dev` is `measured` evidence for
|
|
95
|
+
the interleaving dimension; I/O is read off the same profile (frames in
|
|
96
|
+
`socket` / `ssl` / DB-driver calls) or `strace -c -f`. Payload/bundle stays
|
|
97
|
+
web-gated — a Python web app's shipped frontend is measured by the JS rung.
|
|
98
|
+
Go and Rust use the core's fallback table.
|
|
99
|
+
|
|
78
100
|
**Evidence discipline.** A finding tagged `measured` names the command above
|
|
79
101
|
whose output produced its number. A finding tagged `estimated` (e.g. a
|
|
80
102
|
Big-O argument read off the code without a runnable repro) says so plainly and
|
|
@@ -54,6 +54,36 @@ already compute and commit, rather than prose-scanning the tests:
|
|
|
54
54
|
- `baselines/mutation.json` — mutation-testing survivors where present: tests
|
|
55
55
|
that execute code without asserting on it (coverage without confidence).
|
|
56
56
|
|
|
57
|
+
**When `baselines/*.json` do not exist** (a consumer that does not run
|
|
58
|
+
Mandrel's baseline gates, or a non-JS repo), measure from the ecosystem's own
|
|
59
|
+
tools instead of reporting the missing baseline. Detect ecosystems per the
|
|
60
|
+
core's [Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection)
|
|
61
|
+
(absent scanner = Low `Standardization` gap; undetected ecosystem =
|
|
62
|
+
inapplicable, never a finding). **Python:**
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
coverage report -m # coverage.py, read an existing .coverage file
|
|
66
|
+
coverage json -o - # per-file covered ratio (or coverage.xml from pytest-cov)
|
|
67
|
+
radon cc -s <srcDir> # complexity, to pair with coverage as a CRAP proxy
|
|
68
|
+
mutmut results # mutation survivors, when a mutmut cache exists
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Read an existing `.coverage` / `coverage.xml` / `htmlcov/` artifact; do not run
|
|
72
|
+
`pytest --cov` yourself (the Constraint below forbids suite runs). With no
|
|
73
|
+
coverage artifact at all, record that as a `Coverage` finding — the repo
|
|
74
|
+
publishes no coverage signal. The other Python dimensions read non-running
|
|
75
|
+
instruments:
|
|
76
|
+
|
|
77
|
+
| Dimension | Python instrument |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| Flakiness | `.pytest_cache/v/cache/lastfailed`, `@pytest.mark.flaky` / `pytest-rerunfailures` markers, `time.sleep` in tests |
|
|
80
|
+
| Mocking | `unittest.mock` / `monkeypatch` / `responses` usage density per test file |
|
|
81
|
+
| Test data | `conftest.py` fixture scopes (`scope="session"` shared mutable state) |
|
|
82
|
+
| Performance & execution | `pytest --collect-only -q` (count by tier), `<testcase time=…>` in an existing JUnit XML, `pytest-xdist` presence |
|
|
83
|
+
| Property-based | `hypothesis` in the manifests (dimension 8) |
|
|
84
|
+
|
|
85
|
+
Go and Rust use the core's fallback table.
|
|
86
|
+
|
|
57
87
|
**Rank churn-by-coverage.** Order candidate findings by **churn × coverage
|
|
58
88
|
gap** — frequently-changed files (`git log --format= --name-only -n 200 | sort
|
|
59
89
|
| uniq -c | sort -rn`) that also score low coverage / high CRAP are the
|
|
@@ -41,20 +41,31 @@ baseline is silent — is out of scope for this lens.
|
|
|
41
41
|
## Step 1: Detection Battery (Tool-First, Read-Only)
|
|
42
42
|
|
|
43
43
|
Ground every finding in tool output, not vibes. Run the ladder below; each rung
|
|
44
|
-
is **presence-gated**
|
|
45
|
-
|
|
46
|
-
|
|
44
|
+
is **presence-gated** and **ecosystem-gated** per the core's
|
|
45
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection): when a
|
|
46
|
+
scanner for a detected ecosystem is absent, fall through to the next rung and
|
|
47
|
+
note the missing tool as a `Security Misconfiguration` finding (recommend
|
|
48
|
+
adopting it); a scanner for an undetected ecosystem is inapplicable and never a
|
|
49
|
+
finding.
|
|
47
50
|
|
|
48
|
-
1. **Dependency CVEs
|
|
51
|
+
1. **Dependency CVEs, per detected ecosystem.** Never recall CVEs from memory:
|
|
49
52
|
|
|
50
53
|
```bash
|
|
51
|
-
npm audit --omit=dev --json 2>/dev/null || echo "npm audit unavailable"
|
|
54
|
+
npm audit --omit=dev --json 2>/dev/null || echo "npm audit unavailable" # JS
|
|
55
|
+
pip-audit -r requirements.txt --format json # Python (or bare `pip-audit` in the venv)
|
|
56
|
+
govulncheck ./... # Go
|
|
57
|
+
cargo audit --json # Rust
|
|
52
58
|
```
|
|
53
59
|
|
|
54
|
-
Each advisory reachable in production (`--omit=dev
|
|
55
|
-
|
|
60
|
+
Each advisory reachable in production (`--omit=dev`; for Python, the
|
|
61
|
+
runtime requirements, not dev extras) at `high` or `critical` is a
|
|
62
|
+
_Vulnerable Components_ finding citing the advisory id and the violated
|
|
56
63
|
_Dependency Hygiene_ MUST.
|
|
57
64
|
|
|
65
|
+
**Python static analysis.** On a detected Python ecosystem also run
|
|
66
|
+
`bandit -r <srcDir> -f json` for injection / `eval` / `subprocess(shell=True)`
|
|
67
|
+
/ weak-crypto sinks — the Python counterpart of the grep battery below.
|
|
68
|
+
|
|
58
69
|
2. **Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.** When
|
|
59
70
|
`gitleaks` is installed, prefer it:
|
|
60
71
|
|
|
@@ -76,13 +87,17 @@ adopting it).
|
|
|
76
87
|
rg -n "(SELECT|INSERT|UPDATE|DELETE)\b[^;]*\$\{" -i
|
|
77
88
|
# Committed .env with real values (violates Secrets Management)
|
|
78
89
|
git ls-files | rg "(^|/)\.env($|\.)" | rg -v "\.env\.example$"
|
|
90
|
+
# Python sinks (detected Python only): shell exec, unsafe deserialization, f-string SQL
|
|
91
|
+
rg -n "shell=True|pickle\.loads?\(|yaml\.load\(|\.execute\(f['\"]" --type py
|
|
79
92
|
```
|
|
80
93
|
|
|
81
94
|
4. **Manual surface review.** Then read the surfaces the battery flags plus:
|
|
82
95
|
input-validation edges (API endpoints, form handlers — is input validated at
|
|
83
96
|
the boundary with a strict schema?), auth/session handling (token storage,
|
|
84
97
|
missing ownership checks on sensitive routes), and injection sinks
|
|
85
|
-
(`dangerouslySetInnerHTML`, raw SQL, command execution).
|
|
98
|
+
(`dangerouslySetInnerHTML`, raw SQL, command execution). On Python, read
|
|
99
|
+
the route decorators (Django views / DRF `permission_classes`, Flask /
|
|
100
|
+
FastAPI routes and `Depends` guards) for missing ownership checks.
|
|
86
101
|
|
|
87
102
|
## Step 2: Evaluation Dimensions
|
|
88
103
|
|
|
@@ -43,12 +43,58 @@ with its config-driven target set; navigability always evaluates the whole
|
|
|
43
43
|
route tree regardless of the fence). Those lenses state their deviation in
|
|
44
44
|
their own Scope section; every other lens follows the rule above verbatim.
|
|
45
45
|
|
|
46
|
+
## Ecosystem detection & the absent-vs-inapplicable rule {#ecosystem-detection}
|
|
47
|
+
|
|
48
|
+
A lens's Step 0 instruments are ecosystem-specific, so detect the ecosystems
|
|
49
|
+
from repo-observable manifests **before** running any rung:
|
|
50
|
+
|
|
51
|
+
| Ecosystem | Detected by |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| JS / TS | `package.json` |
|
|
54
|
+
| Python | `pyproject.toml`, `setup.cfg`, `requirements*.txt` |
|
|
55
|
+
| Go | `go.mod` |
|
|
56
|
+
| Rust | `Cargo.toml` |
|
|
57
|
+
| CI — GitHub Actions | `.github/workflows/*.yml` / `*.yaml` |
|
|
58
|
+
| CI — Google Cloud Build | `cloudbuild*.yaml` |
|
|
59
|
+
| CI — GitLab CI | `.gitlab-ci.yml` |
|
|
60
|
+
| CI — Azure Pipelines | `azure-pipelines.yml` |
|
|
61
|
+
|
|
62
|
+
Run the rung for **every** detected ecosystem — a polyglot repo gets more than
|
|
63
|
+
one — and name the detected set in the Executive Summary. Then:
|
|
64
|
+
|
|
65
|
+
- **Absent is a gap.** A scanner for a **detected** ecosystem that is not
|
|
66
|
+
installed is a gap: record it as a Low-severity `Standardization` finding
|
|
67
|
+
(recommend adopting it) and fall through to the next rung or a manual read.
|
|
68
|
+
- **Inapplicable is never a finding.** A scanner for an ecosystem that is
|
|
69
|
+
**not detected** is inapplicable — skip it silently. It is never a finding,
|
|
70
|
+
not even a Low one (`actionlint` on a repo with no `.github/workflows/` is
|
|
71
|
+
inapplicable, not missing).
|
|
72
|
+
- **Non-JS fallback.** Where a lens's JS rung reads a Mandrel-shipped script
|
|
73
|
+
or a committed `baselines/*.json` file that does not exist in the consumer,
|
|
74
|
+
measure with the ecosystem's own instrument instead of reporting the missing
|
|
75
|
+
script or baseline:
|
|
76
|
+
|
|
77
|
+
| Dimension | Python | Go | Rust |
|
|
78
|
+
| --- | --- | --- | --- |
|
|
79
|
+
| Complexity / MI | `radon cc -s -a`, `radon mi -s` | `gocyclo` | `cargo clippy` (cognitive_complexity) |
|
|
80
|
+
| Dead code | `vulture` | `staticcheck` (U1000) | `cargo +nightly udeps`, rustc dead_code warnings |
|
|
81
|
+
| Duplication | `pylint --disable=all --enable=duplicate-code`, or `jscpd` | `jscpd` | `jscpd` |
|
|
82
|
+
| Import graph / cycles | `pydeps --show-cycles`, `import-linter` (`lint-imports`) | `go vet`, `go list -deps` | `cargo modules` |
|
|
83
|
+
| Coverage | `coverage report` / `pytest --cov` (coverage.py, pytest-cov) | `go test -cover` | `cargo llvm-cov`, `cargo tarpaulin` |
|
|
84
|
+
| Dependency CVEs | `pip-audit` | `govulncheck` | `cargo audit` |
|
|
85
|
+
| Profiling | `py-spy record`, `python -m cProfile` | `go test -cpuprofile`, `pprof` | `cargo flamegraph` |
|
|
86
|
+
|
|
46
87
|
## Report envelope & finding-block skeleton {#report-envelope}
|
|
47
88
|
|
|
48
89
|
Each lens writes exactly one structured Markdown report to
|
|
49
90
|
`{{auditOutputDir}}/audit-<lens>-results.md` (the lens preamble names its own
|
|
50
|
-
path).
|
|
51
|
-
|
|
91
|
+
path). A dispatched run gets the anchor substituted; on a manual
|
|
92
|
+
`/audit-<lens>` invocation it renders the literal string `{{auditOutputDir}}`.
|
|
93
|
+
Treat that literal as `<project.paths.tempRoot>/audits` — **`temp/audits` by
|
|
94
|
+
default** — and write the report there, mirroring the `{{changedFiles}}`
|
|
95
|
+
manual-run rule above. The report MUST include every section its lens
|
|
96
|
+
template mandates — write `_No findings._` rather than omitting a section — and
|
|
97
|
+
always an
|
|
52
98
|
`## Executive Summary` and a `## Detailed Findings` section. The Executive
|
|
53
99
|
Summary carries the self-cross-check `kept <k> / dropped <d>` line
|
|
54
100
|
([below](#self-cross-check)) and, beside it, the machine-readable severity
|
package/README.md
CHANGED
|
@@ -70,6 +70,16 @@ explicit `npx mandrel sync` above is the belt-and-suspenders step for
|
|
|
70
70
|
`--ignore-scripts` or sandboxed-CI installs. Run `npx mandrel doctor` any
|
|
71
71
|
time to confirm the install is healthy.
|
|
72
72
|
|
|
73
|
+
Bootstrap also writes a guarded `prepare` script that regenerates both
|
|
74
|
+
`.claude/` projections — `.claude/commands/` (from `.agents/workflows/`) and
|
|
75
|
+
`.claude/agents/` (from `.agents/agents/`). Both are generated and
|
|
76
|
+
gitignored; never commit them. The guard makes `prepare` exit 0 without
|
|
77
|
+
writing anything when `.agents/scripts/` is absent, so a manifest-only
|
|
78
|
+
container layer (`COPY package.json package-lock.json ./` then `npm ci`)
|
|
79
|
+
installs cleanly; once `.agents/` is present it runs both projections.
|
|
80
|
+
Existing installs pick up the guard and the `.claude/agents/` ignore entry
|
|
81
|
+
through the `mandrel update` migration.
|
|
82
|
+
|
|
73
83
|
> **pnpm users — hoist mandrel's runtime deps.** The materialized
|
|
74
84
|
> `./.agents/scripts/*.js` run from your project root and resolve their
|
|
75
85
|
> third-party deps (ajv, js-yaml, …) from your top-level `node_modules`.
|
|
@@ -143,7 +153,9 @@ npx mandrel update
|
|
|
143
153
|
- `--install-cmd "<cmd>"` — override the auto-detected install command. The
|
|
144
154
|
package manager is normally detected from your lockfile
|
|
145
155
|
(`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,
|
|
146
|
-
otherwise `npm install …`),
|
|
156
|
+
otherwise `npm install …`), and it keeps your current pin style: an exact
|
|
157
|
+
pin installs with `--save-exact` (`--exact` on yarn), a tilde pin as
|
|
158
|
+
`mandrel@~<target>`, so an override is rarely needed. When you do
|
|
147
159
|
pass one, a `{target}` placeholder is substituted with the resolved newest
|
|
148
160
|
version — e.g. `--install-cmd "pnpm add -D mandrel@{target} -w"` —
|
|
149
161
|
so the override can still consume the auto-probed version. The registry
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,21 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.78.0...mandrel-v2.79.0) (2026-10-09)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* audit lenses: ecosystem-detected Step 0 rungs for Python and non-GitHub CI, and a stated manual output path ([#5583](https://github.com/dsj1984/mandrel/issues/5583)) ([#5586](https://github.com/dsj1984/mandrel/issues/5586)) ([3c5bf96](https://github.com/dsj1984/mandrel/commit/3c5bf9673b413800deca87e6fc30b956b10154c8))
|
|
24
|
+
* bootstrap: container-safe prepare hook and a gitignored .claude/agents/ projection ([#5581](https://github.com/dsj1984/mandrel/issues/5581)) ([#5590](https://github.com/dsj1984/mandrel/issues/5590)) ([96c4b20](https://github.com/dsj1984/mandrel/commit/96c4b2024724805122ab2b4d3f046cac8b3f7852))
|
|
25
|
+
* bootstrap: skip Projects V2 board creation non-interactively, and continue when project creation is declined ([#5584](https://github.com/dsj1984/mandrel/issues/5584)) ([#5587](https://github.com/dsj1984/mandrel/issues/5587)) ([14db7d3](https://github.com/dsj1984/mandrel/commit/14db7d33a017a314a98d7be2f344988da7e2ef3b))
|
|
26
|
+
* close and doctor honor project.commands.test instead of hardcoding npm test ([#5582](https://github.com/dsj1984/mandrel/issues/5582)) ([#5588](https://github.com/dsj1984/mandrel/issues/5588)) ([7849cf2](https://github.com/dsj1984/mandrel/commit/7849cf2945837631167241d6c30979433f9dcfea))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Fixed
|
|
30
|
+
|
|
31
|
+
* mandrel update preserves the consumer's exact or tilde pin instead of loosening it to a caret ([#5580](https://github.com/dsj1984/mandrel/issues/5580)) ([#5585](https://github.com/dsj1984/mandrel/issues/5585)) ([443c10a](https://github.com/dsj1984/mandrel/commit/443c10a2c0a7a2e6c7597b4196e9f3cb58440d23))
|
|
32
|
+
|
|
18
33
|
## [2.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.77.0...mandrel-v2.78.0) (2026-10-09)
|
|
19
34
|
|
|
20
35
|
|