vibeqm-check 0.4.4 → 0.4.7
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 +31 -16
- package/dist/src/checks/basics.js +56 -18
- package/dist/src/checks/level2.js +105 -25
- package/dist/src/checks/level3.js +2 -0
- package/dist/src/cli.js +12 -7
- package/dist/src/fixes.js +155 -50
- package/dist/src/host.js +23 -0
- package/dist/src/init.js +88 -10
- package/dist/src/proof.js +3 -1
- package/dist/src/report.js +128 -40
- package/dist/src/terminal.js +26 -33
- package/dist/src/types.js +1 -1
- package/package.json +1 -1
- package/templates/level-2/.githooks/pre-commit +7 -0
- package/templates/level-2/AGENTS.md +2 -0
- package/templates/level-2/VibeQM/tailoring/TAILORING.md +4 -2
package/README.md
CHANGED
|
@@ -38,8 +38,8 @@ answers to both names.
|
|
|
38
38
|
- **It sends nothing to us.** There is no account, no telemetry and no server of ours
|
|
39
39
|
involved: the checks run on your machine, and the report is printed there.
|
|
40
40
|
- **The one outside call is optional and yours.** If the GitHub CLI (`gh`) is logged
|
|
41
|
-
in, the tool asks GitHub, with your own login, for this repository's CI runs
|
|
42
|
-
merged pull requests, read-only, to see checks that failed
|
|
41
|
+
in, the tool asks GitHub, with your own login, for this repository's CI runs,
|
|
42
|
+
merged pull requests and branch rules, read-only, to see checks that failed, reviews that
|
|
43
43
|
happened. `--offline` turns that off.
|
|
44
44
|
- The AI prompt it prints goes nowhere by itself; you decide whether to give it to
|
|
45
45
|
your coding agent.
|
|
@@ -50,28 +50,42 @@ Inside an AI coding agent, run it as a shell command (in Claude Code:
|
|
|
50
50
|
## Start from the templates
|
|
51
51
|
|
|
52
52
|
`npx vibeqm-check init` creates the files a repository needs for Level 2: a rules file
|
|
53
|
-
for AI agents (`AGENTS.md`), agent permissions, a
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
53
|
+
for AI agents (`AGENTS.md`), agent permissions, a blocking pre-commit hook
|
|
54
|
+
(`.githooks/pre-commit`, enabled with `git config core.hooksPath .githooks`), a CI
|
|
55
|
+
workflow with secret scanning and static security analysis, issue and pull request
|
|
56
|
+
templates, and short requirements, decisions and plan files under `VibeQM/`. It
|
|
57
|
+
shows the list first, skips files that already exist, and writes only after you say
|
|
58
|
+
yes (`--yes` when not run in a terminal). The blanks your repository answers (the
|
|
59
|
+
test and build commands, the description) are filled; fill the rest of the `<...>`
|
|
60
|
+
with your repository's facts, or let your agent do it. The checks don't count a file
|
|
61
|
+
that still has blanks. The templates come from the
|
|
59
62
|
[companion repository](https://github.com/vibeqm/vqm).
|
|
60
63
|
|
|
61
64
|
## What you get
|
|
62
65
|
|
|
63
66
|
- **The level** your repository's evidence supports, Level 1 to 3. Levels 4 and 5
|
|
64
67
|
need measurements over time, which this version does not yet compute.
|
|
65
|
-
- **
|
|
68
|
+
- **How far the next level is, and who does what.** The result leads with the
|
|
69
|
+
distance ("Level 2 is 4 items away"), what is already met, how many of the open
|
|
70
|
+
items your AI agent can do alone and how many need an answer from you, today's
|
|
71
|
+
level, and the autonomy the next level earns.
|
|
72
|
+
- **Every check, with one of four results:**
|
|
66
73
|
- **Met:** the evidence exists, and the report names it (a file, a setting, a hook,
|
|
67
74
|
a commit).
|
|
68
75
|
- **Not met:** the tool looked and the evidence is absent.
|
|
69
76
|
- **Not visible:** the evidence lives outside the repository (for example settings
|
|
70
|
-
on your code host). It counts as not met until a person attaches proof.
|
|
77
|
+
on your code host). It counts as not met until a person attaches proof. With the
|
|
78
|
+
GitHub CLI logged in, the tool reads branch protection and required checks
|
|
79
|
+
itself.
|
|
80
|
+
- **In place:** the practice is set up and recorded but counts with use (peer
|
|
81
|
+
review counts after 20 reviewed changes; one unreviewed push restarts the count).
|
|
82
|
+
The result shows the count, so you see when it will be met.
|
|
71
83
|
- **For every open check:** why it matters, concrete steps for this repository, how to
|
|
72
|
-
confirm it worked,
|
|
84
|
+
confirm it worked, an estimate in minutes, and who it needs: your agent alone, an
|
|
85
|
+
answer from you, a setting on the code host, or use.
|
|
73
86
|
- **A prompt** at the end that your AI coding agent can follow to close the gaps,
|
|
74
|
-
cheapest first. The prompt tells the agent to
|
|
87
|
+
cheapest first. The prompt tells the agent to do everything it can alone first and
|
|
88
|
+
then ask you for the rest in one message, to produce real evidence, and to ask you
|
|
75
89
|
before writing any proof on your behalf.
|
|
76
90
|
|
|
77
91
|
## What counts as a peer review
|
|
@@ -118,7 +132,8 @@ apart. Record it in a `vqm-proof.json` file, in the repository or any parent fol
|
|
|
118
132
|
}
|
|
119
133
|
```
|
|
120
134
|
|
|
121
|
-
A proof only turns **Not visible**
|
|
135
|
+
A proof only turns **Not visible** (or **In place**, for history the tool does not
|
|
136
|
+
claim) into **Met (attested)**. It never overrides **Not
|
|
122
137
|
met**, because what the tool saw outranks what anyone says. Proof is signed by a
|
|
123
138
|
named person and expires after a year.
|
|
124
139
|
|
|
@@ -130,12 +145,12 @@ that caused it. The report appears on the run's summary page.
|
|
|
130
145
|
```yaml
|
|
131
146
|
- uses: actions/checkout@v4
|
|
132
147
|
with: { fetch-depth: 0 } # the checks sample history
|
|
133
|
-
- uses: vibeqm/vibeqm-check@v0.4.
|
|
148
|
+
- uses: vibeqm/vibeqm-check@v0.4.7
|
|
134
149
|
with: { min-level: 2 } # optional: fail the run below this level
|
|
135
150
|
```
|
|
136
151
|
|
|
137
|
-
To let the action read the repository's CI runs
|
|
138
|
-
read access (`permissions: { contents: read, actions: read, pull-requests: read }`).
|
|
152
|
+
To let the action read the repository's CI runs, pull requests and branch rules,
|
|
153
|
+
give the job read access (`permissions: { contents: read, actions: read, pull-requests: read }`).
|
|
139
154
|
Pass `offline: true` to read the repository only.
|
|
140
155
|
|
|
141
156
|
## What it is, and what it is not
|
|
@@ -110,7 +110,7 @@ export function requirementsFirst(root) {
|
|
|
110
110
|
// and not filled in yet: it doesn't carry the gate alone.
|
|
111
111
|
const filledDocs = found.filter((f) => !f.startsWith(".github/ISSUE_TEMPLATE/"));
|
|
112
112
|
if (found.length && (filledDocs.length || !unfilled.length))
|
|
113
|
-
return r(2, gate, "met", `requirements or issue templates in the repository: ${found.slice(0, 3).join(", ")}${found.length > 3 ? "…" : ""}${note ? `; ${note}` : ""}`);
|
|
113
|
+
return r(2, gate, "met", `requirements or issue templates in the repository: ${found.slice(0, 3).join(", ")}${found.length > 3 ? "…" : ""}${note ? `; ${note}` : ""}. Whether each change traces to one is a judgment question of the full assessment`);
|
|
114
114
|
if (unfilled.length)
|
|
115
115
|
return r(2, gate, "not-met", `${note}: fill it with this project's requirements, or delete it`);
|
|
116
116
|
return r(2, gate, "not-visible", "no requirements file or issue templates in the repository; if requirements live in an issue tracker, attach proof that every change traces to one and that unclear requests get clarifying questions with options");
|
|
@@ -208,15 +208,34 @@ export function peerReview(root) {
|
|
|
208
208
|
const trailers = commits.filter((c) => c.trailer).length;
|
|
209
209
|
return r(2, gate, "not-visible", `${trailers ? `${trailers} of the last ${commits.length} commits carry a \`Reviewed-by:\` trailer, but none has a matching review record (a review file in the commit, or one naming it)` : `no reviewed changes found in the last ${commits.length} commits (a \`Reviewed-by:\` trailer plus a review record, or a reviewed pull request)`}; ${need}`);
|
|
210
210
|
}
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
const
|
|
215
|
-
const
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
if (
|
|
219
|
-
|
|
211
|
+
// One unreviewed pushed change after adoption restarts the count at the next
|
|
212
|
+
// reviewed change (DEC-148): the gate names the change that broke the run, and the
|
|
213
|
+
// person recovers by reviewing from then on, instead of waiting for the sample to forget.
|
|
214
|
+
const window = commits.slice(0, firstAt + 1);
|
|
215
|
+
const brokeAt = window.findIndex((c) => !c.recordsOnly && due(c) && !c.reviewed);
|
|
216
|
+
let startAt = firstAt;
|
|
217
|
+
let restart = "";
|
|
218
|
+
if (brokeAt >= 0) {
|
|
219
|
+
const broke = window[brokeAt];
|
|
220
|
+
const resumed = window.slice(0, brokeAt).map((c) => c.reviewed && !c.recordsOnly).lastIndexOf(true);
|
|
221
|
+
const note = `${broke.short} (${broke.date}${broke.trailer ? ", trailer but no review record" : ""})`;
|
|
222
|
+
if (resumed < 0)
|
|
223
|
+
return r(2, gate, "not-met", `review began at ${commits[firstAt].short} (${commits[firstAt].date}), but the latest pushed change was not reviewed: ${note}; the count restarts at the next reviewed change`);
|
|
224
|
+
startAt = resumed;
|
|
225
|
+
restart = ` (restarted at ${window[resumed].short} after the unreviewed change ${note})`;
|
|
226
|
+
}
|
|
227
|
+
const first = commits[startAt];
|
|
228
|
+
const since = commits.slice(0, startAt + 1).filter((c) => !c.recordsOnly && due(c));
|
|
229
|
+
const waiting = commits.slice(0, startAt + 1).filter((c) => !c.recordsOnly && !due(c) && !c.reviewed).length;
|
|
230
|
+
const head = `since review began (${first.short}, ${first.date})${restart}, ${since.length} of ${since.length} pushed changes were covered by a review${waiting ? ` (${waiting} not pushed yet, due at the next push)` : ""}`;
|
|
231
|
+
if (since.length < MIN_SINCE) {
|
|
232
|
+
// Review is set up and every pushed change since has one: the gate is in place
|
|
233
|
+
// and counts once 20 reviewed changes have followed adoption (ASSESSOR §2, DEC-087).
|
|
234
|
+
return {
|
|
235
|
+
...r(2, gate, "in-place", `${head}; counts after ${MIN_SINCE} reviewed changes since adoption, ${since.length} so far; one unreviewed push restarts the count (earlier history needs proof)`),
|
|
236
|
+
progress: { done: since.length, needed: MIN_SINCE, unit: "reviewed changes" },
|
|
237
|
+
};
|
|
238
|
+
}
|
|
220
239
|
return r(2, gate, "met", `${head} (a push review, a reviewed pull request, or a trailer with a review record); earlier history is not claimed`);
|
|
221
240
|
}
|
|
222
241
|
export function verificationTools(root) {
|
|
@@ -226,7 +245,11 @@ export function verificationTools(root) {
|
|
|
226
245
|
const pkg = files.includes("package.json") && /"(lint|typecheck)"\s*:/.test(read(root, "package.json"));
|
|
227
246
|
const cargo = files.filter((f) => /(^|\/)Cargo\.toml$/.test(f)).some((f) => /^\[(workspace\.)?lints/m.test(read(root, f)));
|
|
228
247
|
const tsStrict = files.filter((f) => /(^|\/)tsconfig[^/]*\.json$/.test(f)).some((f) => /"strict"\s*:\s*true/.test(read(root, f)));
|
|
229
|
-
const
|
|
248
|
+
const wired = code(ciText(root, files) + "\n" + hookText(root));
|
|
249
|
+
const run = wired.match(ANALYZE_COMMANDS)?.[0];
|
|
250
|
+
// The gate is that the checks run on every change: a hook or CI job must run the
|
|
251
|
+
// analyzer, or at least the project's test or lint command, beside the configuration.
|
|
252
|
+
const runs = wired.match(CHECK_COMMANDS)?.[0];
|
|
230
253
|
const gate = "Verification on every change";
|
|
231
254
|
const ev = [
|
|
232
255
|
...lint.slice(0, 3),
|
|
@@ -236,8 +259,10 @@ export function verificationTools(root) {
|
|
|
236
259
|
...(tsStrict ? ["tsconfig strict mode"] : []),
|
|
237
260
|
...(run ? [`\`${run.trim()}\` runs in a hook or CI`] : []),
|
|
238
261
|
];
|
|
262
|
+
if (ev.length && (run || runs))
|
|
263
|
+
return r(2, gate, "met", `linter or static-analysis configuration: ${ev.join(", ")}; a hook or CI job runs \`${(run ?? runs ?? "").trim()}\` (that a failure blocks the change is the "Checks before merge" gate)`);
|
|
239
264
|
if (ev.length)
|
|
240
|
-
return r(2, gate, "met", `linter or static-analysis configuration: ${ev.join(", ")}
|
|
265
|
+
return r(2, gate, "not-met", `linter or static-analysis configuration: ${ev.join(", ")}, but no enabled hook or CI job runs it or the tests: add the command to .githooks/pre-commit (enabled with \`git config core.hooksPath .githooks\`) or to the CI workflow`);
|
|
241
266
|
return r(2, gate, "not-met", "no linter or static-analysis configuration found, and no analyzer command in a hook or CI. If the project uses an analyzer this tool does not recognise, run it from the pre-commit hook or CI (e.g. `dart analyze`, `cargo clippy`, `tsc --noEmit`) and it will be found");
|
|
242
267
|
}
|
|
243
268
|
export function securityBeforePush(root) {
|
|
@@ -258,7 +283,13 @@ export function securityBeforePush(root) {
|
|
|
258
283
|
const thinShare = code_.length ? code_.filter((f) => thin.some((e) => f.endsWith(e))).length / code_.length : 0;
|
|
259
284
|
const reviewTools = ["security-review", "codeql", "semgrep", "snyk", "bandit", "ruff security rules (bandit)"].filter((x) => tools.includes(x));
|
|
260
285
|
const note = reviewTools.length === 1 && reviewTools[0] === "semgrep" && thinShare > 0.3 ? " (note: Semgrep's rules barely cover this repository's main language; an AI security review of each push covers it better)" : "";
|
|
261
|
-
const
|
|
286
|
+
const secretTools = tools.filter((x) => ["gitleaks", "trufflehog", "detect-secrets", "git-secrets"].includes(x));
|
|
287
|
+
const depTools = [...tools.filter((x) => ["osv-scanner", "npm audit", "pip-audit", "trivy", "dependency-review", "snyk"].includes(x)), ...(dependabot ? ["dependabot"] : [])];
|
|
288
|
+
const ev = [
|
|
289
|
+
`secret scanning: ${secretTools.join(", ") || "none"}`,
|
|
290
|
+
`security review of each change (an AI review or static security analysis): ${reviewTools.join(", ") || "none"}${note}`,
|
|
291
|
+
`dependency scan: ${depTools.join(", ") || "none"}${depTools.length ? " (whether it blocks on critical findings is a CI or host setting, not checked)" : ""}`,
|
|
292
|
+
].join("; ");
|
|
262
293
|
if (hasSecrets && hasReview)
|
|
263
294
|
return r(2, gate, "met", ev);
|
|
264
295
|
return r(2, gate, "not-met", `${ev}; missing ${[!hasReview ? "an AI or static security review of each change" : "", !hasSecrets ? "secret scanning" : ""].filter(Boolean).join(" and ")}`);
|
|
@@ -357,10 +388,12 @@ export function committedSettings(root) {
|
|
|
357
388
|
return null;
|
|
358
389
|
}
|
|
359
390
|
};
|
|
391
|
+
// A committed file is named by its path in the repository, never by this machine's
|
|
392
|
+
// absolute path: the evidence goes into reports people share.
|
|
360
393
|
return [
|
|
361
|
-
...project.map((f) => (inHead.has(f) ? { file:
|
|
394
|
+
...project.map((f) => (inHead.has(f) ? { file: f, committed: true, text: git(root, ["show", `HEAD:${f}`]) } : { file: f, committed: false, text: disk(join(root, f)) })),
|
|
362
395
|
{ file: join(homedir(), ".claude", "settings.json"), committed: false, text: disk(join(homedir(), ".claude", "settings.json")) },
|
|
363
|
-
].filter((s) => s.committed || existsSync(s.file));
|
|
396
|
+
].filter((s) => s.committed || existsSync(s.file.startsWith("/") ? s.file : join(root, s.file)));
|
|
364
397
|
}
|
|
365
398
|
/** Where the agent is told, or made, to ask before publishing live. */
|
|
366
399
|
function confirmationRule(root) {
|
|
@@ -383,7 +416,7 @@ function confirmationRule(root) {
|
|
|
383
416
|
continue;
|
|
384
417
|
const list = `${hits.slice(0, 3).join(", ")}${hits.length > 3 ? "…" : ""}`;
|
|
385
418
|
if (committed)
|
|
386
|
-
found.push(`publish commands that stop for the person or are refused in ${file
|
|
419
|
+
found.push(`publish commands that stop for the person or are refused in ${file}: ${list}`);
|
|
387
420
|
else
|
|
388
421
|
machineOnly.push(`${file} (this machine's settings, not committed): ${list}`);
|
|
389
422
|
}
|
|
@@ -467,8 +500,13 @@ export function configurationBasics(root) {
|
|
|
467
500
|
const tags = (git(root, ["tag", "--list"]) ?? "").split("\n").filter(Boolean);
|
|
468
501
|
const remote = tags.length ? hostTags(root) : null;
|
|
469
502
|
const versions = tags.filter((t) => /^v?\d+(\.\d+)+/.test(t));
|
|
470
|
-
|
|
471
|
-
|
|
503
|
+
// Nothing released yet, said in the rules file or the README, needs no tag (DEC-147);
|
|
504
|
+
// the first release is tagged. A template's blank is a choice, not a statement.
|
|
505
|
+
const notLive = [...RULES_FILES, "README.md"].map((f) => read(root, f).split("\n").find((l) => NOT_LIVE.test(l) && !placeholders(l).length)).find(Boolean);
|
|
506
|
+
if (!tags.length && notLive)
|
|
507
|
+
ok.push(`no release tags yet, and the repository says nothing is released: "${notLive.trim().slice(0, 60)}" (tag the first release)`);
|
|
508
|
+
else if (!tags.length)
|
|
509
|
+
problems.push("no release tags (if nothing is released yet, say so in the rules file or the README: \"nothing is live yet\")");
|
|
472
510
|
else if (remote && !tags.some((t) => remote.includes(t)))
|
|
473
511
|
problems.push(`${tags.length} release tag(s) here, none pushed to the host`);
|
|
474
512
|
else
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
|
|
4
4
|
import { join, relative } from "node:path";
|
|
5
5
|
import { commitSizes, git, median } from "../git.js";
|
|
6
|
-
import { defaultBranchRuns, mergedPullRequests } from "../host.js";
|
|
6
|
+
import { branchRules, defaultBranchRuns, mergedPullRequests } from "../host.js";
|
|
7
7
|
import { blanksNote, CHECK_COMMANDS, code, committedSettings, delegated, placeholders, RULES_FILES } from "./basics.js";
|
|
8
8
|
const SMALL_BATCH_LIMIT = 400; // ASSESSOR §2: median changed lines per merged change
|
|
9
9
|
const SAMPLE = 100;
|
|
@@ -31,6 +31,50 @@ export function agentRulesFile(root) {
|
|
|
31
31
|
const lines = filled.map((f) => `${f} (${text(f).split("\n").length} lines)`);
|
|
32
32
|
return { level: 2, gate, status: "met", evidence: [...lines, ...blanks].join("; ") };
|
|
33
33
|
}
|
|
34
|
+
/** The accepted equivalent of pull requests for a one-person repository (VQM_SPEC §6,
|
|
35
|
+
* DEC-147): a committed blocking hook, the bypass denied in committed agent settings,
|
|
36
|
+
* and a tailoring row that records it. Each part is named, so the evidence says what
|
|
37
|
+
* is missing when it is not met. */
|
|
38
|
+
function soloEquivalent(root) {
|
|
39
|
+
const authors = new Set((git(root, ["log", `-${SAMPLE}`, "--format=%ae"]) ?? "").split("\n").filter(Boolean));
|
|
40
|
+
const solo = authors.size === 1;
|
|
41
|
+
const have = [];
|
|
42
|
+
const missing = [];
|
|
43
|
+
const hook = blockingHooks(root).find((h) => h.committed);
|
|
44
|
+
if (hook)
|
|
45
|
+
have.push(`the committed blocking ${hook.name} hook (${hook.rel})`);
|
|
46
|
+
else
|
|
47
|
+
missing.push("a committed blocking pre-commit or pre-push hook (see Checks before merge)");
|
|
48
|
+
const denied = committedSettings(root).find(({ committed, text }) => {
|
|
49
|
+
if (!committed)
|
|
50
|
+
return false;
|
|
51
|
+
try {
|
|
52
|
+
return (JSON.parse(text ?? "")?.permissions?.deny ?? []).some((d) => typeof d === "string" && /--no-verify|-n /.test(d));
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return false;
|
|
56
|
+
}
|
|
57
|
+
});
|
|
58
|
+
if (denied)
|
|
59
|
+
have.push(`\`--no-verify\` denied in ${denied.file}`);
|
|
60
|
+
else
|
|
61
|
+
missing.push("a deny rule on `git commit --no-verify` in .claude/settings.json, committed");
|
|
62
|
+
const tailoring = (git(root, ["ls-files", "--", "VibeQM/tailoring/", "tailoring/"]) ?? "")
|
|
63
|
+
.split("\n")
|
|
64
|
+
.filter((f) => /\.md$/i.test(f))
|
|
65
|
+
.map((f) => {
|
|
66
|
+
const row = readFileSync(join(root, f), "utf8")
|
|
67
|
+
.split("\n")
|
|
68
|
+
.find((l) => /^\|\s*TLR-\d+/.test(l) && /pull request|merge path|branch protection/i.test(l) && !placeholders(l).length);
|
|
69
|
+
return row ? `${f} (${row.match(/TLR-\d+/)?.[0]})` : null;
|
|
70
|
+
})
|
|
71
|
+
.find(Boolean);
|
|
72
|
+
if (tailoring)
|
|
73
|
+
have.push(`recorded as tailoring in ${tailoring}`);
|
|
74
|
+
else
|
|
75
|
+
missing.push("a tailoring row (VibeQM/tailoring/TAILORING.md) saying the hook stands in for pull requests, approved by the owner");
|
|
76
|
+
return { solo, have, missing };
|
|
77
|
+
}
|
|
34
78
|
export function versionControl(root) {
|
|
35
79
|
const gate = "Version control + merge path";
|
|
36
80
|
if (git(root, ["rev-parse", "--git-dir"]) === null) {
|
|
@@ -44,11 +88,27 @@ export function versionControl(root) {
|
|
|
44
88
|
if (prs?.length) {
|
|
45
89
|
return { level: 2, gate, status: "met", evidence: `${prs.length} pull requests merged on the host (e.g. #${prs[0].number}, ${prs[0].mergedAt.slice(0, 10)})` };
|
|
46
90
|
}
|
|
91
|
+
const rules = branchRules(root);
|
|
92
|
+
if (rules?.pullRequest) {
|
|
93
|
+
return { level: 2, gate, status: "met", evidence: `the host requires a pull request before merging into ${rules.branch} (read from the host with your login)` };
|
|
94
|
+
}
|
|
95
|
+
const { solo, have, missing } = soloEquivalent(root);
|
|
96
|
+
if (solo && !missing.length) {
|
|
97
|
+
return { level: 2, gate, status: "met", evidence: `one author in the sample; changes reach the main branch behind ${have.join(", ")}: the accepted equivalent of pull requests for a one-person repository` };
|
|
98
|
+
}
|
|
99
|
+
if (solo) {
|
|
100
|
+
return {
|
|
101
|
+
level: 2,
|
|
102
|
+
gate,
|
|
103
|
+
status: "not-visible",
|
|
104
|
+
evidence: `git repository with one author and no merge commits. For one person, the accepted equivalent of pull requests needs ${missing.join("; ")}${have.length ? ` (already there: ${have.join(", ")})` : ""}. Or branch protection on the host, which this tool reads when the GitHub CLI is logged in`,
|
|
105
|
+
};
|
|
106
|
+
}
|
|
47
107
|
return {
|
|
48
108
|
level: 2,
|
|
49
109
|
gate,
|
|
50
110
|
status: "not-visible",
|
|
51
|
-
evidence: "git repository, but no merge commits in the sample. Branch protection is set on the host (e.g. GitHub)
|
|
111
|
+
evidence: "git repository, but no merge commits in the sample. Branch protection is set on the host (e.g. GitHub); this tool reads it when the GitHub CLI is logged in, otherwise attach proof",
|
|
52
112
|
};
|
|
53
113
|
}
|
|
54
114
|
function hooksDir(root) {
|
|
@@ -58,24 +118,12 @@ function hooksDir(root) {
|
|
|
58
118
|
const gitDir = git(root, ["rev-parse", "--absolute-git-dir"])?.trim();
|
|
59
119
|
return gitDir ? join(gitDir, "hooks") : null;
|
|
60
120
|
}
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
if (existsSync(workflows)) {
|
|
66
|
-
const files = readdirSync(workflows).filter((f) => /\.ya?ml$/.test(f));
|
|
67
|
-
if (files.length)
|
|
68
|
-
evidence.push(`CI workflows: ${files.join(", ")}`);
|
|
69
|
-
}
|
|
70
|
-
for (const f of [".gitlab-ci.yml", ".circleci/config.yml", "azure-pipelines.yml"]) {
|
|
71
|
-
if (existsSync(join(root, f)))
|
|
72
|
-
evidence.push(`CI config: ${f}`);
|
|
73
|
-
}
|
|
74
|
-
// A hook counts when it runs a test, lint or analyze command (itself or through
|
|
75
|
-
// the Makefile or a repository script it calls); `exit 0` is not a gate.
|
|
76
|
-
// core.hooksPath is per-clone config, so say where the hook lives.
|
|
121
|
+
/** The executable pre-commit and pre-push hooks that run a test, lint or analyze
|
|
122
|
+
* command (themselves or through the Makefile or a repository script they call);
|
|
123
|
+
* `exit 0` is not a gate. `idle` names hooks that run nothing recognisable. */
|
|
124
|
+
function blockingHooks(root, idle = []) {
|
|
77
125
|
const hooks = hooksDir(root);
|
|
78
|
-
const
|
|
126
|
+
const found = [];
|
|
79
127
|
for (const name of ["pre-commit", "pre-push"]) {
|
|
80
128
|
const p = hooks ? join(hooks, name) : null;
|
|
81
129
|
if (!p || !existsSync(p) || !(statSync(p).mode & 0o111))
|
|
@@ -87,26 +135,58 @@ export function checksBeforeMerge(root) {
|
|
|
87
135
|
continue;
|
|
88
136
|
}
|
|
89
137
|
const rel = relative(realpathSync(root), realpathSync(p));
|
|
138
|
+
const committed = !rel.startsWith("..") && !!(git(root, ["ls-files", "--", rel]) ?? "").trim();
|
|
90
139
|
const where = rel.startsWith("..")
|
|
91
140
|
? "a shared hook outside the repository, enabled on this machine"
|
|
92
|
-
:
|
|
141
|
+
: committed
|
|
93
142
|
? `committed in the repository (${rel}); each clone enables it with \`git config core.hooksPath\``
|
|
94
143
|
: "enabled on this machine only, not committed";
|
|
95
|
-
|
|
144
|
+
found.push({ name, runs: runs.trim(), rel, committed, where });
|
|
96
145
|
}
|
|
146
|
+
return found;
|
|
147
|
+
}
|
|
148
|
+
export function checksBeforeMerge(root) {
|
|
149
|
+
const gate = "Checks before merge";
|
|
150
|
+
const evidence = [];
|
|
151
|
+
const workflows = join(root, ".github", "workflows");
|
|
152
|
+
if (existsSync(workflows)) {
|
|
153
|
+
const files = readdirSync(workflows).filter((f) => /\.ya?ml$/.test(f));
|
|
154
|
+
if (files.length)
|
|
155
|
+
evidence.push(`CI workflows: ${files.join(", ")}`);
|
|
156
|
+
}
|
|
157
|
+
for (const f of [".gitlab-ci.yml", ".circleci/config.yml", "azure-pipelines.yml"]) {
|
|
158
|
+
if (existsSync(join(root, f)))
|
|
159
|
+
evidence.push(`CI config: ${f}`);
|
|
160
|
+
}
|
|
161
|
+
// core.hooksPath is per-clone config, so say where the hook lives.
|
|
162
|
+
const idle = [];
|
|
163
|
+
for (const h of blockingHooks(root, idle))
|
|
164
|
+
evidence.push(`blocking git hook ${h.name} runs \`${h.runs}\`: ${h.where}`);
|
|
165
|
+
// A committed hook that this clone has not enabled (core.hooksPath unset) blocks
|
|
166
|
+
// nothing yet; say so, since enabling it is one command.
|
|
167
|
+
const dormant = ["pre-commit", "pre-push"]
|
|
168
|
+
.map((n) => `.githooks/${n}`)
|
|
169
|
+
.filter((f) => (git(root, ["ls-files", "--", f]) ?? "").trim() && existsSync(join(root, f)) && code(readFileSync(join(root, f), "utf8")).match(CHECK_COMMANDS));
|
|
170
|
+
const enabled = git(root, ["config", "core.hooksPath"])?.trim();
|
|
171
|
+
const notEnabled = dormant.length && !enabled ? `; ${dormant.join(" and ")} is committed but not enabled on this clone: run \`git config core.hooksPath .githooks\`` : "";
|
|
97
172
|
if (idle.length && !evidence.length) {
|
|
98
|
-
return { level: 2, gate, status: "not-met", evidence: `${idle.join(" and ")} hook found, but it runs no test, lint or analyze command this tool recognises` };
|
|
173
|
+
return { level: 2, gate, status: "not-met", evidence: `${idle.join(" and ")} hook found, but it runs no test, lint or analyze command this tool recognises${notEnabled}` };
|
|
99
174
|
}
|
|
100
175
|
if (!evidence.length) {
|
|
101
|
-
return { level: 2, gate, status: "not-met", evidence:
|
|
176
|
+
return { level: 2, gate, status: "not-met", evidence: `no CI configuration and no executable pre-commit/pre-push hook${notEnabled}` };
|
|
102
177
|
}
|
|
103
|
-
// CI that runs is not the same as CI that blocks: required status checks live on the
|
|
178
|
+
// CI that runs is not the same as CI that blocks: required status checks live on the
|
|
179
|
+
// host, read here when the GitHub CLI is logged in.
|
|
104
180
|
const onlyCi = !evidence.some((e) => e.startsWith("blocking git hook"));
|
|
181
|
+
const required = onlyCi ? branchRules(root)?.requiredChecks ?? [] : [];
|
|
182
|
+
if (onlyCi && required.length) {
|
|
183
|
+
return { level: 2, gate, status: "met", evidence: `${evidence.join("; ")}; the host requires ${required.slice(0, 3).join(", ")}${required.length > 3 ? "…" : ""} to pass before merging (read from the host with your login)` };
|
|
184
|
+
}
|
|
105
185
|
return {
|
|
106
186
|
level: 2,
|
|
107
187
|
gate,
|
|
108
188
|
status: onlyCi ? "not-visible" : "met",
|
|
109
|
-
evidence: evidence.join("; ") + (onlyCi ?
|
|
189
|
+
evidence: evidence.join("; ") + (onlyCi ? `. Whether failing CI blocks the merge is a host setting: this tool reads it when the GitHub CLI is logged in; otherwise a committed blocking hook makes it visible, or attach proof${notEnabled}` : ""),
|
|
110
190
|
};
|
|
111
191
|
}
|
|
112
192
|
export function smallBatches(root) {
|
|
@@ -194,4 +194,6 @@ export const level3 = [
|
|
|
194
194
|
notVisible("Agent plug-ins and tools", "outside plug-ins, tool servers and skills must be pinned and added as high-risk changes; attach proof"),
|
|
195
195
|
notVisible("Parallel agents and rollback", "agents on separate branches through the same checks, and a tried rollback; attach proof"),
|
|
196
196
|
notVisible("Generated-code licensing", "a license check on new code; attach proof"),
|
|
197
|
+
notVisible("Reviewer proven", "the AI peer reviewer's model and version need a record of catching a planted-fault set (at least five known-bad changes, including a weakened test and a prompt-injection case), kept where the agent can't edit it; attach proof"),
|
|
198
|
+
notVisible("Service-bound items (applicability)", "a product with no live production service states an equivalent or a not-applicable reason for each service-bound item, recorded as tailoring; attach proof"),
|
|
197
199
|
];
|
package/dist/src/cli.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// run the VibeQM fact checks on a repository. vibeqm-check init [path] [--yes]: create the
|
|
4
4
|
// Level 2 template files.
|
|
5
5
|
import { existsSync, statSync, writeFileSync } from "node:fs";
|
|
6
|
-
import { resolve } from "node:path";
|
|
6
|
+
import { relative, resolve } from "node:path";
|
|
7
7
|
import { level2 } from "./checks/level2.js";
|
|
8
8
|
import { level3 } from "./checks/level3.js";
|
|
9
9
|
import { basics2, basics3 } from "./checks/basics.js";
|
|
@@ -22,11 +22,14 @@ if (args[0] === "init") {
|
|
|
22
22
|
console.log(`vibeqm-check init [path] [--yes]
|
|
23
23
|
|
|
24
24
|
Create the VibeQM Level 2 template files in a repository: a rules file for AI agents,
|
|
25
|
-
agent permissions, a CI workflow with security checks,
|
|
26
|
-
templates, and short requirements, decisions and plan files
|
|
25
|
+
agent permissions, a blocking pre-commit hook, a CI workflow with security checks,
|
|
26
|
+
issue and pull request templates, and short requirements, decisions and plan files
|
|
27
|
+
under VibeQM/. Blanks the repository answers (the test and build commands, the
|
|
28
|
+
description) are filled; the rest are left as <...> for you or your agent.
|
|
27
29
|
|
|
28
30
|
It lists every file first, skips files that already exist, and writes only after you
|
|
29
|
-
say yes. It never overwrites a file, never commits, and
|
|
31
|
+
say yes. It never overwrites a file, never commits, and enables no hook (the hook it
|
|
32
|
+
writes is enabled with one command, git config core.hooksPath .githooks).
|
|
30
33
|
|
|
31
34
|
path the repository (default: the current directory)
|
|
32
35
|
--yes create the files without asking (needed when not run in a terminal)
|
|
@@ -117,7 +120,9 @@ if (oi >= 0 && (!outArg || outArg.startsWith("-"))) {
|
|
|
117
120
|
const root = resolve(args.find((a, i) => !a.startsWith("--") && (pi < 0 || i !== pi + 1) && (oi < 0 || i !== oi + 1)) ?? ".");
|
|
118
121
|
let results = [...level2, ...basics2, ...level3, ...basics3].map((check) => check(root));
|
|
119
122
|
const proofFiles = proofArg ? [resolve(proofArg)] : findProofFiles(root);
|
|
120
|
-
|
|
123
|
+
// Named by their path in the repository when inside it: the report is for sharing, and
|
|
124
|
+
// an absolute path carries the machine's layout and the account name.
|
|
125
|
+
const proofFile = proofFiles.length ? proofFiles.map((f) => (f.startsWith(`${root}/`) ? relative(root, f) : f)).join(", ") : null;
|
|
121
126
|
if (proofFiles.length) {
|
|
122
127
|
try {
|
|
123
128
|
const merged = mergeProofs(proofFiles);
|
|
@@ -187,10 +192,10 @@ else if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--all"))
|
|
|
187
192
|
const prompt = aiPrompt(results);
|
|
188
193
|
// With nothing open at the next level there is no to-do list to wait for.
|
|
189
194
|
if (prompt)
|
|
190
|
-
await ask("Press Enter
|
|
195
|
+
await ask("Press Enter for the list of what to do (q quits). ");
|
|
191
196
|
console.log(`\n${terminalDetails(results, proofFile, style)}\n`);
|
|
192
197
|
if (prompt) {
|
|
193
|
-
await ask("Press Enter
|
|
198
|
+
await ask("Press Enter for the prompt to paste into your AI coding agent (q quits). ");
|
|
194
199
|
console.log(`\n${prompt}\n`);
|
|
195
200
|
}
|
|
196
201
|
rl.close();
|