monkeyshape 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +54 -2
- package/config/biome.base.json +71 -0
- package/config/tsconfig.base.json +31 -0
- package/docs/workflow.md +131 -0
- package/package.json +68 -4
- package/skills/handoff/SKILL.md +54 -0
- package/skills/milestone/SKILL.md +107 -0
- package/skills/review-pr/SKILL.md +135 -0
- package/skills/roadmap/SKILL.md +66 -0
- package/skills/track/SKILL.md +75 -0
- package/src/adapters/baseline.ts +55 -0
- package/src/adapters/config.ts +25 -0
- package/src/adapters/init.ts +176 -0
- package/src/adapters/process.ts +38 -0
- package/src/adapters/reviews.ts +170 -0
- package/src/adapters/skills.ts +113 -0
- package/src/adapters/tracks.ts +616 -0
- package/src/adapters/workspace.ts +281 -0
- package/src/api/monkeyshape.ts +8 -0
- package/src/cli/main.ts +359 -0
- package/src/core/arch.ts +224 -0
- package/src/core/budgets.ts +187 -0
- package/src/core/check.ts +122 -0
- package/src/core/coverage.ts +118 -0
- package/src/core/decisions.ts +65 -0
- package/src/core/garden.ts +41 -0
- package/src/core/glob.ts +22 -0
- package/src/core/handoff.ts +183 -0
- package/src/core/hooks.ts +60 -0
- package/src/core/jsonc.ts +26 -0
- package/src/core/layout.ts +123 -0
- package/src/core/markdown.ts +93 -0
- package/src/core/model.ts +100 -0
- package/src/core/parse.ts +41 -0
- package/src/core/paths.ts +19 -0
- package/src/core/ratchet.ts +75 -0
- package/src/core/refs.ts +214 -0
- package/src/core/report.ts +67 -0
- package/src/core/rules/ast.ts +50 -0
- package/src/core/rules/decodeStrict.ts +60 -0
- package/src/core/rules/effectRunAtEdge.ts +33 -0
- package/src/core/rules/engine.ts +150 -0
- package/src/core/rules/noErrorSpread.ts +28 -0
- package/src/core/rules/noNondeterminism.ts +65 -0
- package/src/core/rules/noThrow.ts +79 -0
- package/src/core/rules/registry.ts +15 -0
- package/src/core/scaffold.ts +90 -0
- package/src/core/scope.ts +120 -0
- package/src/core/skills.ts +291 -0
- package/src/core/tracks.ts +358 -0
- package/src/helpers/decodeStrict.ts +8 -0
- package/src/schemas/config.ts +221 -0
- package/src/schemas/errors.ts +31 -0
- package/template/.github/pull_request_template.md +11 -0
- package/template/.github/workflows/ci.yml +22 -0
- package/template/AGENTS.md +37 -0
- package/template/CLAUDE.md +1 -0
- package/template/DECISIONS.md +8 -0
- package/template/README.md +14 -0
- package/template/docs/roadmap.md +14 -0
- package/template/gitignore +7 -0
- package/template/notes/.gitkeep +0 -0
- package/template/plan/.gitkeep +0 -0
- package/template/shape.config.ts +26 -0
- package/template/test/toolchain.test.ts +7 -0
package/src/core/arch.ts
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Module layering as data. Every source file under `arch.root` belongs to exactly one
|
|
3
|
+
* module (the longest matching key in `arch.modules`). A module may import itself and the
|
|
4
|
+
* modules in its `mayImport`; host APIs only with `hostAccess`; third-party packages only
|
|
5
|
+
* from the allowlists. Adding an edge is a deliberate edit to `shape.config.ts`.
|
|
6
|
+
*
|
|
7
|
+
* Host access needs no import in Bun: `Bun.file`, `process`, `fetch` are globals. Direct
|
|
8
|
+
* uses of those are checked too, respecting lexical shadowing. This is static analysis of
|
|
9
|
+
* the common paths, not a sandbox: `globalThis.fetch`, `const { file } = Bun`, aliasing a
|
|
10
|
+
* global to another name or `eval` still get through. It catches the habit, not an attacker.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { Visitor } from "oxc-parser";
|
|
14
|
+
import type { ResolvedConfig } from "../schemas/config.ts";
|
|
15
|
+
import { isTsSource, lineAt, type Snapshot, type Violation } from "./model.ts";
|
|
16
|
+
import { type Parsed, parse } from "./parse.ts";
|
|
17
|
+
import { dirname, join } from "./paths.ts";
|
|
18
|
+
import { scopes } from "./scope.ts";
|
|
19
|
+
|
|
20
|
+
type Arch = NonNullable<ResolvedConfig["arch"]>;
|
|
21
|
+
|
|
22
|
+
const MANIFEST = "package.json";
|
|
23
|
+
|
|
24
|
+
const violation = (rule: string, file: string, message: string, line?: number): Violation => ({
|
|
25
|
+
check: "arch",
|
|
26
|
+
rule: `arch/${rule}`,
|
|
27
|
+
file,
|
|
28
|
+
...(line === undefined ? {} : { line }),
|
|
29
|
+
message,
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
/** Bun's pure utilities: string and data functions with no I/O. */
|
|
33
|
+
const PURE_BUN = new Set(["Glob", "deepEquals", "escapeHTML", "stringWidth", "hash", "inspect"]);
|
|
34
|
+
const HOST_OBJECTS = new Set(["Bun", "process", "Deno"]);
|
|
35
|
+
const HOST_FUNCTIONS = new Set(["fetch", "require"]);
|
|
36
|
+
|
|
37
|
+
/** Uses of host globals: `Bun.file(...)`, `process.cwd()`, `fetch(...)`, unless shadowed there. */
|
|
38
|
+
export const hostGlobals = (parsed: Parsed): ReadonlyArray<{ offset: number; name: string }> => {
|
|
39
|
+
const found: Array<{ offset: number; name: string }> = [];
|
|
40
|
+
const local = scopes(parsed.program);
|
|
41
|
+
new Visitor({
|
|
42
|
+
MemberExpression: (node) => {
|
|
43
|
+
if (node.object.type !== "Identifier" || !HOST_OBJECTS.has(node.object.name)) return;
|
|
44
|
+
if (local.isLocal(node.object.name, node.start)) return;
|
|
45
|
+
const property =
|
|
46
|
+
!node.computed && node.property.type === "Identifier" ? node.property.name : "";
|
|
47
|
+
if (node.object.name === "Bun" && PURE_BUN.has(property)) return;
|
|
48
|
+
found.push({ offset: node.start, name: `${node.object.name}.${property || "[...]"}` });
|
|
49
|
+
},
|
|
50
|
+
CallExpression: (node) => {
|
|
51
|
+
if (
|
|
52
|
+
node.callee.type === "Identifier" &&
|
|
53
|
+
HOST_FUNCTIONS.has(node.callee.name) &&
|
|
54
|
+
!local.isLocal(node.callee.name, node.start)
|
|
55
|
+
)
|
|
56
|
+
found.push({ offset: node.start, name: `${node.callee.name}()` });
|
|
57
|
+
},
|
|
58
|
+
}).visit(parsed.program);
|
|
59
|
+
return found;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
export const moduleOf = (arch: Arch, path: string): string | undefined => {
|
|
63
|
+
const prefix = `${arch.root}/`;
|
|
64
|
+
if (!path.startsWith(prefix)) return undefined;
|
|
65
|
+
const rest = path.slice(prefix.length);
|
|
66
|
+
let best: string | undefined;
|
|
67
|
+
for (const name of Object.keys(arch.modules))
|
|
68
|
+
if (
|
|
69
|
+
(rest === name || rest.startsWith(`${name}/`)) &&
|
|
70
|
+
(best === undefined || name.length > best.length)
|
|
71
|
+
)
|
|
72
|
+
best = name;
|
|
73
|
+
return best;
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
const packageName = (specifier: string): string => {
|
|
77
|
+
const parts = specifier.split("/");
|
|
78
|
+
return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? specifier);
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
/** `node:*` matches `node:fs/promises`: a trailing `*` is a prefix, not a path glob. */
|
|
82
|
+
export const matchesSpecifier = (specifier: string, pattern: string): boolean =>
|
|
83
|
+
pattern.endsWith("*") ? specifier.startsWith(pattern.slice(0, -1)) : specifier === pattern;
|
|
84
|
+
|
|
85
|
+
const isRelative = (specifier: string): boolean =>
|
|
86
|
+
specifier.startsWith("./") || specifier.startsWith("../");
|
|
87
|
+
|
|
88
|
+
export const checkArch = (config: ResolvedConfig, snapshot: Snapshot): ReadonlyArray<Violation> => {
|
|
89
|
+
const arch = config.arch;
|
|
90
|
+
if (arch === undefined)
|
|
91
|
+
return [
|
|
92
|
+
violation(
|
|
93
|
+
"no-module-map",
|
|
94
|
+
"shape.config.ts",
|
|
95
|
+
"declares no `arch.modules`. Layering is the cheapest structure to enforce; map every source directory to a module.",
|
|
96
|
+
),
|
|
97
|
+
];
|
|
98
|
+
|
|
99
|
+
const violations: Array<Violation> = [];
|
|
100
|
+
for (const [name, rule] of Object.entries(arch.modules))
|
|
101
|
+
for (const target of rule.mayImport ?? [])
|
|
102
|
+
if (!Object.hasOwn(arch.modules, target))
|
|
103
|
+
violations.push(
|
|
104
|
+
violation(
|
|
105
|
+
"config",
|
|
106
|
+
"shape.config.ts",
|
|
107
|
+
`module '${name}' lists unknown module '${target}' in mayImport`,
|
|
108
|
+
),
|
|
109
|
+
);
|
|
110
|
+
|
|
111
|
+
const files = snapshot.files.filter(
|
|
112
|
+
(file) => file.startsWith(`${arch.root}/`) && isTsSource(file),
|
|
113
|
+
);
|
|
114
|
+
const known = new Set(snapshot.files);
|
|
115
|
+
const edges = new Map<string, Array<string>>();
|
|
116
|
+
|
|
117
|
+
for (const file of files) {
|
|
118
|
+
const from = moduleOf(arch, file);
|
|
119
|
+
if (from === undefined) {
|
|
120
|
+
violations.push(
|
|
121
|
+
violation(
|
|
122
|
+
"unknown-module",
|
|
123
|
+
file,
|
|
124
|
+
"is not inside any module in `arch.modules` (shape.config.ts)",
|
|
125
|
+
),
|
|
126
|
+
);
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
129
|
+
const rule = arch.modules[from];
|
|
130
|
+
const text = snapshot.texts.get(file);
|
|
131
|
+
if (rule === undefined || text === undefined) continue;
|
|
132
|
+
const targets: Array<string> = [];
|
|
133
|
+
const parsed = parse(file, text);
|
|
134
|
+
|
|
135
|
+
if (rule.hostAccess !== true)
|
|
136
|
+
for (const use of hostGlobals(parsed))
|
|
137
|
+
violations.push(
|
|
138
|
+
violation(
|
|
139
|
+
"host-access",
|
|
140
|
+
file,
|
|
141
|
+
`uses ${use.name}, but module '${from}' has no hostAccess. Reach the host through a service in an adapter module.`,
|
|
142
|
+
lineAt(text, use.offset),
|
|
143
|
+
),
|
|
144
|
+
);
|
|
145
|
+
|
|
146
|
+
for (const specifier of parsed.imports) {
|
|
147
|
+
if (!isRelative(specifier)) {
|
|
148
|
+
const host = arch.hostSpecifiers.some((pattern) => matchesSpecifier(specifier, pattern));
|
|
149
|
+
const allowed = host
|
|
150
|
+
? rule.hostAccess === true
|
|
151
|
+
: arch.allowedPackages.includes(packageName(specifier)) ||
|
|
152
|
+
(rule.packages ?? []).includes(packageName(specifier));
|
|
153
|
+
if (!allowed)
|
|
154
|
+
violations.push(
|
|
155
|
+
violation(
|
|
156
|
+
host ? "host-access" : "forbidden-package",
|
|
157
|
+
file,
|
|
158
|
+
host
|
|
159
|
+
? `imports '${specifier}', but module '${from}' has no hostAccess. Reach the host through a service in an adapter module.`
|
|
160
|
+
: `imports '${specifier}', which module '${from}' may not use. Add it to the module's packages deliberately, or keep it behind an adapter.`,
|
|
161
|
+
),
|
|
162
|
+
);
|
|
163
|
+
continue;
|
|
164
|
+
}
|
|
165
|
+
const target = join(dirname(file), specifier);
|
|
166
|
+
if (target === MANIFEST) {
|
|
167
|
+
if (rule.manifest !== true)
|
|
168
|
+
violations.push(
|
|
169
|
+
violation("manifest", file, `module '${from}' may not import package.json`),
|
|
170
|
+
);
|
|
171
|
+
continue;
|
|
172
|
+
}
|
|
173
|
+
if (!known.has(target)) {
|
|
174
|
+
violations.push(
|
|
175
|
+
violation(
|
|
176
|
+
"unresolved-import",
|
|
177
|
+
file,
|
|
178
|
+
`cannot resolve '${specifier}' (use explicit .ts extensions)`,
|
|
179
|
+
),
|
|
180
|
+
);
|
|
181
|
+
continue;
|
|
182
|
+
}
|
|
183
|
+
targets.push(target);
|
|
184
|
+
const to = moduleOf(arch, target);
|
|
185
|
+
if (to !== undefined && to !== from && !(rule.mayImport ?? []).includes(to))
|
|
186
|
+
violations.push(
|
|
187
|
+
violation(
|
|
188
|
+
"forbidden-import",
|
|
189
|
+
file,
|
|
190
|
+
`module '${from}' may not import module '${to}' ('${specifier}')`,
|
|
191
|
+
),
|
|
192
|
+
);
|
|
193
|
+
}
|
|
194
|
+
edges.set(file, targets);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
for (const cycle of findCycles(edges))
|
|
198
|
+
violations.push(violation("cycle", cycle[0] ?? "", `import cycle: ${cycle.join(" -> ")}`));
|
|
199
|
+
return violations;
|
|
200
|
+
};
|
|
201
|
+
|
|
202
|
+
/** Depth-first search reporting each back edge as a cycle (file-level). */
|
|
203
|
+
export const findCycles = (
|
|
204
|
+
edges: ReadonlyMap<string, ReadonlyArray<string>>,
|
|
205
|
+
): ReadonlyArray<ReadonlyArray<string>> => {
|
|
206
|
+
const cycles: Array<ReadonlyArray<string>> = [];
|
|
207
|
+
const state = new Map<string, "visiting" | "done">();
|
|
208
|
+
const stack: Array<string> = [];
|
|
209
|
+
|
|
210
|
+
const visit = (node: string): void => {
|
|
211
|
+
state.set(node, "visiting");
|
|
212
|
+
stack.push(node);
|
|
213
|
+
for (const next of edges.get(node) ?? []) {
|
|
214
|
+
const nextState = state.get(next);
|
|
215
|
+
if (nextState === "visiting") cycles.push([...stack.slice(stack.indexOf(next)), next]);
|
|
216
|
+
else if (nextState === undefined) visit(next);
|
|
217
|
+
}
|
|
218
|
+
stack.pop();
|
|
219
|
+
state.set(node, "done");
|
|
220
|
+
};
|
|
221
|
+
|
|
222
|
+
for (const node of [...edges.keys()].sort()) if (!state.has(node)) visit(node);
|
|
223
|
+
return cycles;
|
|
224
|
+
};
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Caps on everything loaded automatically, and the shape of DECISIONS.md. Prose costs
|
|
3
|
+
* every session, so these fail the gate rather than warn.
|
|
4
|
+
*/
|
|
5
|
+
import type { ResolvedConfig } from "../schemas/config.ts";
|
|
6
|
+
import { EVIDENCE_KINDS, FIELDS, parseDecisions, SLUG } from "./decisions.ts";
|
|
7
|
+
import { matchesAny } from "./glob.ts";
|
|
8
|
+
import { isTsSource, lineCount, pathIndex, type Snapshot, type Violation } from "./model.ts";
|
|
9
|
+
|
|
10
|
+
const violation = (rule: string, file: string, message: string, line?: number): Violation => ({
|
|
11
|
+
check: "budgets",
|
|
12
|
+
rule: `budgets/${rule}`,
|
|
13
|
+
file,
|
|
14
|
+
...(line === undefined ? {} : { line }),
|
|
15
|
+
message,
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
export interface Metrics {
|
|
19
|
+
readonly agentsLines: number | undefined;
|
|
20
|
+
readonly readmeLines: number | undefined;
|
|
21
|
+
readonly decisions: number;
|
|
22
|
+
readonly policyOnlyDecisions: number;
|
|
23
|
+
readonly memories: number | undefined;
|
|
24
|
+
readonly memoryBytes: number | undefined;
|
|
25
|
+
/** Source files over the warning size, largest first. */
|
|
26
|
+
readonly largeFiles: ReadonlyArray<{ readonly file: string; readonly lines: number }>;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export const measure = (config: ResolvedConfig, snapshot: Snapshot): Metrics => {
|
|
30
|
+
const agents = snapshot.texts.get("AGENTS.md");
|
|
31
|
+
const readme = snapshot.texts.get("README.md");
|
|
32
|
+
const decisions = parseDecisions(snapshot.texts.get("DECISIONS.md") ?? "");
|
|
33
|
+
const memories = snapshot.memories === undefined ? undefined : [...snapshot.memories.values()];
|
|
34
|
+
const largeFiles = snapshot.files
|
|
35
|
+
.filter(isTsSource)
|
|
36
|
+
.map((file) => ({ file, lines: lineCount(snapshot.texts.get(file) ?? "") }))
|
|
37
|
+
.filter((entry) => entry.lines > config.budgets.fileWarnLines)
|
|
38
|
+
.sort((a, b) => b.lines - a.lines);
|
|
39
|
+
return {
|
|
40
|
+
agentsLines: agents === undefined ? undefined : lineCount(agents),
|
|
41
|
+
readmeLines: readme === undefined ? undefined : lineCount(readme),
|
|
42
|
+
decisions: decisions.length,
|
|
43
|
+
policyOnlyDecisions: decisions.filter((d) => d.evidence === "policy").length,
|
|
44
|
+
memories: memories?.length,
|
|
45
|
+
memoryBytes: memories?.reduce((sum, text) => sum + new TextEncoder().encode(text).length, 0),
|
|
46
|
+
largeFiles,
|
|
47
|
+
};
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
export const checkBudgets = (
|
|
51
|
+
config: ResolvedConfig,
|
|
52
|
+
snapshot: Snapshot,
|
|
53
|
+
): ReadonlyArray<Violation> => {
|
|
54
|
+
const budgets = config.budgets;
|
|
55
|
+
const metrics = measure(config, snapshot);
|
|
56
|
+
const violations: Array<Violation> = [];
|
|
57
|
+
|
|
58
|
+
if (metrics.agentsLines === undefined)
|
|
59
|
+
violations.push(
|
|
60
|
+
violation(
|
|
61
|
+
"agents-missing",
|
|
62
|
+
"AGENTS.md",
|
|
63
|
+
"is missing: agents need commands, gotchas and decision authority somewhere",
|
|
64
|
+
),
|
|
65
|
+
);
|
|
66
|
+
else if (metrics.agentsLines > budgets.agentsLines)
|
|
67
|
+
violations.push(
|
|
68
|
+
violation(
|
|
69
|
+
"agents-lines",
|
|
70
|
+
"AGENTS.md",
|
|
71
|
+
`has ${metrics.agentsLines} lines (budget ${budgets.agentsLines}). Turn a rule into a check, or delete what a check already enforces.`,
|
|
72
|
+
),
|
|
73
|
+
);
|
|
74
|
+
|
|
75
|
+
const claude = snapshot.texts.get("CLAUDE.md");
|
|
76
|
+
if (claude !== undefined && claude.trim() !== "@AGENTS.md")
|
|
77
|
+
violations.push(
|
|
78
|
+
violation(
|
|
79
|
+
"claude-md",
|
|
80
|
+
"CLAUDE.md",
|
|
81
|
+
"must contain only `@AGENTS.md`: one instruction source, not two",
|
|
82
|
+
),
|
|
83
|
+
);
|
|
84
|
+
|
|
85
|
+
if (metrics.readmeLines !== undefined && metrics.readmeLines > budgets.readmeLines)
|
|
86
|
+
violations.push(
|
|
87
|
+
violation(
|
|
88
|
+
"readme-lines",
|
|
89
|
+
"README.md",
|
|
90
|
+
`has ${metrics.readmeLines} lines (budget ${budgets.readmeLines})`,
|
|
91
|
+
),
|
|
92
|
+
);
|
|
93
|
+
|
|
94
|
+
const decisions = parseDecisions(snapshot.texts.get("DECISIONS.md") ?? "");
|
|
95
|
+
if (decisions.length > budgets.decisions)
|
|
96
|
+
violations.push(
|
|
97
|
+
violation(
|
|
98
|
+
"decisions-count",
|
|
99
|
+
"DECISIONS.md",
|
|
100
|
+
`has ${decisions.length} entries (budget ${budgets.decisions}). Retire one: enforce it as a check and delete it, or drop it.`,
|
|
101
|
+
),
|
|
102
|
+
);
|
|
103
|
+
const index = pathIndex(snapshot.files);
|
|
104
|
+
const seen = new Set<string>();
|
|
105
|
+
for (const decision of decisions) {
|
|
106
|
+
const at = (rule: string, message: string) =>
|
|
107
|
+
violations.push(
|
|
108
|
+
violation(rule, "DECISIONS.md", `${decision.slug} ${message}`, decision.line),
|
|
109
|
+
);
|
|
110
|
+
if (!SLUG.test(decision.slug)) at("decision-slug", "is not a slug like D-address-space");
|
|
111
|
+
if (seen.has(decision.slug)) at("decision-duplicate", "appears twice");
|
|
112
|
+
seen.add(decision.slug);
|
|
113
|
+
if (decision.words > budgets.decisionWords)
|
|
114
|
+
at(
|
|
115
|
+
"decision-words",
|
|
116
|
+
`has ${decision.words} words (budget ${budgets.decisionWords}). Overwrite it shorter; history lives in git.`,
|
|
117
|
+
);
|
|
118
|
+
for (const field of FIELDS)
|
|
119
|
+
if (!decision.fields.has(field)) at("decision-field", `is missing "${field}:"`);
|
|
120
|
+
if (
|
|
121
|
+
decision.evidence !== undefined &&
|
|
122
|
+
!(EVIDENCE_KINDS as ReadonlyArray<string>).includes(decision.evidence)
|
|
123
|
+
)
|
|
124
|
+
at(
|
|
125
|
+
"decision-evidence",
|
|
126
|
+
`has evidence '${decision.evidence}'; use measured, verified or policy`,
|
|
127
|
+
);
|
|
128
|
+
if (decision.evidence !== "policy" && decision.fields.has("Enforced by")) {
|
|
129
|
+
if (decision.enforcedBy.length === 0)
|
|
130
|
+
at(
|
|
131
|
+
"decision-unenforced",
|
|
132
|
+
'names nothing in "Enforced by". Point at the test or check, or mark the evidence policy.',
|
|
133
|
+
);
|
|
134
|
+
for (const path of decision.enforcedBy)
|
|
135
|
+
if (!index.has(path.replace(/\/$/, "")))
|
|
136
|
+
at("decision-unenforced", `is enforced by '${path}', which does not exist`);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
if (metrics.memories !== undefined && metrics.memories > budgets.memories)
|
|
141
|
+
violations.push(
|
|
142
|
+
violation(
|
|
143
|
+
"memories-count",
|
|
144
|
+
".beads",
|
|
145
|
+
`has ${metrics.memories} bd memories (budget ${budgets.memories}). Keep principles; move gotchas next to their checks.`,
|
|
146
|
+
),
|
|
147
|
+
);
|
|
148
|
+
if (metrics.memoryBytes !== undefined && metrics.memoryBytes > budgets.memoryBytes)
|
|
149
|
+
violations.push(
|
|
150
|
+
violation(
|
|
151
|
+
"memories-bytes",
|
|
152
|
+
".beads",
|
|
153
|
+
`bd memories total ${metrics.memoryBytes} bytes (budget ${budgets.memoryBytes})`,
|
|
154
|
+
),
|
|
155
|
+
);
|
|
156
|
+
|
|
157
|
+
const allowed = budgets.largeFiles;
|
|
158
|
+
for (const { file, lines } of metrics.largeFiles)
|
|
159
|
+
if (
|
|
160
|
+
lines > budgets.fileFailLines &&
|
|
161
|
+
!matchesAny(
|
|
162
|
+
file,
|
|
163
|
+
allowed.map((a) => a.path),
|
|
164
|
+
)
|
|
165
|
+
)
|
|
166
|
+
violations.push(
|
|
167
|
+
violation(
|
|
168
|
+
"file-lines",
|
|
169
|
+
file,
|
|
170
|
+
`has ${lines} lines (budget ${budgets.fileFailLines}). Split it, or allow it in budgets.largeFiles with a reason.`,
|
|
171
|
+
),
|
|
172
|
+
);
|
|
173
|
+
for (const allowance of allowed)
|
|
174
|
+
if (
|
|
175
|
+
!metrics.largeFiles.some(
|
|
176
|
+
(f) => f.lines > budgets.fileFailLines && matchesAny(f.file, [allowance.path]),
|
|
177
|
+
)
|
|
178
|
+
)
|
|
179
|
+
violations.push(
|
|
180
|
+
violation(
|
|
181
|
+
"unused-allowance",
|
|
182
|
+
"shape.config.ts",
|
|
183
|
+
`budgets.largeFiles '${allowance.path}' allows nothing; delete it`,
|
|
184
|
+
),
|
|
185
|
+
);
|
|
186
|
+
return violations;
|
|
187
|
+
};
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/** Runs the selected checks over a snapshot. Pure: the CLI loads, this decides. */
|
|
2
|
+
import type { ResolvedConfig } from "../schemas/config.ts";
|
|
3
|
+
import { checkArch } from "./arch.ts";
|
|
4
|
+
import { checkBudgets } from "./budgets.ts";
|
|
5
|
+
import { checkCoverage } from "./coverage.ts";
|
|
6
|
+
import type { CheckName, Integration, Snapshot, Violation } from "./model.ts";
|
|
7
|
+
import { checkRefs } from "./refs.ts";
|
|
8
|
+
import { checkRules } from "./rules/engine.ts";
|
|
9
|
+
import { RULES } from "./rules/registry.ts";
|
|
10
|
+
import { checkSkills } from "./skills.ts";
|
|
11
|
+
|
|
12
|
+
export const CHECKS: ReadonlyArray<CheckName> = [
|
|
13
|
+
"arch",
|
|
14
|
+
"refs",
|
|
15
|
+
"budgets",
|
|
16
|
+
"coverage",
|
|
17
|
+
"rules",
|
|
18
|
+
"skills",
|
|
19
|
+
];
|
|
20
|
+
|
|
21
|
+
const run: Record<
|
|
22
|
+
CheckName,
|
|
23
|
+
(config: ResolvedConfig, snapshot: Snapshot) => ReadonlyArray<Violation>
|
|
24
|
+
> = {
|
|
25
|
+
arch: checkArch,
|
|
26
|
+
refs: checkRefs,
|
|
27
|
+
budgets: checkBudgets,
|
|
28
|
+
coverage: checkCoverage,
|
|
29
|
+
rules: (config, snapshot) => checkRules(config, snapshot, RULES),
|
|
30
|
+
skills: checkSkills,
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
const BEADS_RULES = ["refs/bead-in-code", "budgets/memories-count", "budgets/memories-bytes"];
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Rules this run didn't evaluate: their check wasn't selected (`--only`), or they need data
|
|
37
|
+
* this machine lacks (bd isn't installed in CI). Their findings weren't counted, so a
|
|
38
|
+
* baseline entry for them must not read as a loose ratchet, nor be tightened away.
|
|
39
|
+
*/
|
|
40
|
+
export const unevaluated = (
|
|
41
|
+
snapshot: Snapshot,
|
|
42
|
+
only: ReadonlyArray<CheckName> = CHECKS,
|
|
43
|
+
baselineRules: Iterable<string> = [],
|
|
44
|
+
): ReadonlySet<string> =>
|
|
45
|
+
new Set([
|
|
46
|
+
...(snapshot.integrations.beads.state === "ok" ? [] : BEADS_RULES),
|
|
47
|
+
...[...baselineRules].filter(
|
|
48
|
+
(rule) => !(only as ReadonlyArray<string>).includes(rule.split("/")[0] ?? ""),
|
|
49
|
+
),
|
|
50
|
+
]);
|
|
51
|
+
|
|
52
|
+
/** What this run could not do, said out loud so a green result has one meaning. */
|
|
53
|
+
export const notices = (config: ResolvedConfig, snapshot: Snapshot): ReadonlyArray<string> => {
|
|
54
|
+
const out: Array<string> = [];
|
|
55
|
+
const { beads, tsc, biome } = snapshot.integrations;
|
|
56
|
+
if (beads.state === "unavailable" && config.beads === "optional")
|
|
57
|
+
out.push(`skipped ${BEADS_RULES.join(", ")}: ${beads.reason}`);
|
|
58
|
+
for (const [name, integration] of [
|
|
59
|
+
["tsc", tsc],
|
|
60
|
+
["biome", biome],
|
|
61
|
+
] as const)
|
|
62
|
+
if (integration.state === "unavailable" || integration.state === "failed")
|
|
63
|
+
out.push(
|
|
64
|
+
`coverage approximated ${name}'s file list from its config (${integration.reason}): inheritance and project references are not resolved`,
|
|
65
|
+
);
|
|
66
|
+
return out;
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
const prerequisite = (rule: string, message: string): Violation => ({
|
|
70
|
+
check: "prerequisites",
|
|
71
|
+
rule: `prerequisites/${rule}`,
|
|
72
|
+
file: ".beads",
|
|
73
|
+
message,
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* When beads can't be trusted, whatever asks it: `failed` when bd ran and failed, whatever the
|
|
78
|
+
* config says; `required` when `beads: "required"` and beads isn't ok. `check` and
|
|
79
|
+
* `track rm` both decide with this, so a beads failure means one thing everywhere.
|
|
80
|
+
*/
|
|
81
|
+
export const beadsBlocker = (
|
|
82
|
+
setting: ResolvedConfig["beads"],
|
|
83
|
+
beads: Integration,
|
|
84
|
+
): "failed" | "required" | undefined =>
|
|
85
|
+
beads.state === "failed"
|
|
86
|
+
? "failed"
|
|
87
|
+
: setting === "required" && beads.state !== "ok"
|
|
88
|
+
? "required"
|
|
89
|
+
: undefined;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Integrations that must work for a result to mean anything: bd failing outright, or bd
|
|
93
|
+
* unavailable when `beads: "required"`. These are facts about the environment, not the code,
|
|
94
|
+
* so no baseline can accept them and no `--only` selection skips them.
|
|
95
|
+
*/
|
|
96
|
+
export const prerequisites = (
|
|
97
|
+
config: ResolvedConfig,
|
|
98
|
+
snapshot: Snapshot,
|
|
99
|
+
): ReadonlyArray<Violation> => {
|
|
100
|
+
const beads = snapshot.integrations.beads;
|
|
101
|
+
const blocker = beadsBlocker(config.beads, beads);
|
|
102
|
+
if (blocker === "failed" && beads.state === "failed")
|
|
103
|
+
return [
|
|
104
|
+
prerequisite("beads-failed", `bd failed, so beads checks did not run: ${beads.reason}`),
|
|
105
|
+
];
|
|
106
|
+
if (blocker === "required" && beads.state !== "ok")
|
|
107
|
+
return [
|
|
108
|
+
prerequisite(
|
|
109
|
+
"beads-required",
|
|
110
|
+
beads.state === "absent"
|
|
111
|
+
? "shape.config.ts requires beads, but the repo has no .beads/config.yaml"
|
|
112
|
+
: `shape.config.ts requires beads, but ${beads.reason}`,
|
|
113
|
+
),
|
|
114
|
+
];
|
|
115
|
+
return [];
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
export const runChecks = (
|
|
119
|
+
config: ResolvedConfig,
|
|
120
|
+
snapshot: Snapshot,
|
|
121
|
+
only: ReadonlyArray<CheckName> = CHECKS,
|
|
122
|
+
): ReadonlyArray<Violation> => only.flatMap((name) => run[name](config, snapshot));
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Code outside the gate rots silently. Every TypeScript file must be typechecked by some
|
|
3
|
+
* tsconfig and linted by biome, unless it sits under an exempt segment (generated or
|
|
4
|
+
* vendored code). Excluding real code needs a config change a reviewer will see.
|
|
5
|
+
*
|
|
6
|
+
* The tools are the authority: when the adapter could run them, `snapshot.typechecked` and
|
|
7
|
+
* `snapshot.linted` are their own file lists, with inheritance and project references
|
|
8
|
+
* resolved. Reading the configs here is the fallback, and approximates both.
|
|
9
|
+
*/
|
|
10
|
+
import type { ResolvedConfig } from "../schemas/config.ts";
|
|
11
|
+
import { matchesPathOrBelow } from "./glob.ts";
|
|
12
|
+
import { stripJsonc } from "./jsonc.ts";
|
|
13
|
+
import { isTsSource, type Snapshot, type Violation } from "./model.ts";
|
|
14
|
+
import { dirname } from "./paths.ts";
|
|
15
|
+
|
|
16
|
+
const violation = (rule: string, file: string, message: string): Violation => ({
|
|
17
|
+
check: "coverage",
|
|
18
|
+
rule: `coverage/${rule}`,
|
|
19
|
+
file,
|
|
20
|
+
message,
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
export const parseJsonc = (text: string): unknown => {
|
|
24
|
+
try {
|
|
25
|
+
return JSON.parse(stripJsonc(text));
|
|
26
|
+
} catch {
|
|
27
|
+
return undefined;
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const field = (value: unknown, key: string): unknown =>
|
|
32
|
+
typeof value === "object" && value !== null && key in value
|
|
33
|
+
? (value as Record<string, unknown>)[key]
|
|
34
|
+
: undefined;
|
|
35
|
+
|
|
36
|
+
const strings = (value: unknown): ReadonlyArray<string> | undefined =>
|
|
37
|
+
Array.isArray(value)
|
|
38
|
+
? value.filter((item): item is string => typeof item === "string")
|
|
39
|
+
: undefined;
|
|
40
|
+
|
|
41
|
+
/** Whether one tsconfig's program includes `file` (repo-relative). */
|
|
42
|
+
export const tsconfigCovers = (tsconfigPath: string, tsconfig: unknown, file: string): boolean => {
|
|
43
|
+
const base = dirname(tsconfigPath);
|
|
44
|
+
const relative =
|
|
45
|
+
base === "" ? file : file.startsWith(`${base}/`) ? file.slice(base.length + 1) : undefined;
|
|
46
|
+
if (relative === undefined) return false;
|
|
47
|
+
const files = strings(field(tsconfig, "files"));
|
|
48
|
+
if (files?.some((entry) => entry.replace(/^\.\//, "") === relative)) return true;
|
|
49
|
+
// Absent `include` defaults to everything only when `files` is absent too; `files: []`
|
|
50
|
+
// (a solution-style config) includes nothing.
|
|
51
|
+
const include = strings(field(tsconfig, "include")) ?? (files === undefined ? ["**/*"] : []);
|
|
52
|
+
const exclude = strings(field(tsconfig, "exclude")) ?? [];
|
|
53
|
+
return (
|
|
54
|
+
include.some((pattern) => matchesPathOrBelow(relative, pattern)) &&
|
|
55
|
+
!exclude.some((pattern) => matchesPathOrBelow(relative, pattern))
|
|
56
|
+
);
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
/** Biome `files.includes`, in order: a later pattern overrides an earlier one. */
|
|
60
|
+
export const biomeCovers = (biome: unknown, file: string): boolean => {
|
|
61
|
+
const includes = strings(field(field(biome, "files"), "includes"));
|
|
62
|
+
if (includes === undefined) return true;
|
|
63
|
+
let included = false;
|
|
64
|
+
for (const pattern of includes) {
|
|
65
|
+
const negated = pattern.startsWith("!");
|
|
66
|
+
if (matchesPathOrBelow(file, pattern.replace(/^!+/, ""))) included = !negated;
|
|
67
|
+
}
|
|
68
|
+
return included;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
export const checkCoverage = (
|
|
72
|
+
config: ResolvedConfig,
|
|
73
|
+
snapshot: Snapshot,
|
|
74
|
+
): ReadonlyArray<Violation> => {
|
|
75
|
+
const violations: Array<Violation> = [];
|
|
76
|
+
const tsconfigs: Array<{ path: string; value: unknown }> = [];
|
|
77
|
+
const typechecked = snapshot.typechecked;
|
|
78
|
+
const linted = snapshot.linted;
|
|
79
|
+
for (const path of typechecked === undefined ? config.coverage.tsconfigs : []) {
|
|
80
|
+
const text = snapshot.texts.get(path);
|
|
81
|
+
const value = text === undefined ? undefined : parseJsonc(text);
|
|
82
|
+
if (value === undefined)
|
|
83
|
+
violations.push(violation("config", path, "is missing or not valid JSON"));
|
|
84
|
+
else tsconfigs.push({ path, value });
|
|
85
|
+
}
|
|
86
|
+
const biomeText = snapshot.texts.get(config.coverage.biome);
|
|
87
|
+
const biome = biomeText === undefined ? undefined : parseJsonc(biomeText);
|
|
88
|
+
if (linted === undefined && biome === undefined)
|
|
89
|
+
violations.push(violation("config", config.coverage.biome, "is missing or not valid JSON"));
|
|
90
|
+
const isTypechecked = (file: string) =>
|
|
91
|
+
typechecked !== undefined
|
|
92
|
+
? typechecked.has(file)
|
|
93
|
+
: tsconfigs.length === 0 || tsconfigs.some((t) => tsconfigCovers(t.path, t.value, file));
|
|
94
|
+
const isLinted = (file: string) =>
|
|
95
|
+
linted !== undefined ? linted.has(file) : biome === undefined || biomeCovers(biome, file);
|
|
96
|
+
|
|
97
|
+
const exempt = new Set(config.coverage.exempt);
|
|
98
|
+
for (const file of snapshot.files) {
|
|
99
|
+
if (!isTsSource(file) || file.split("/").some((segment) => exempt.has(segment))) continue;
|
|
100
|
+
if (!isTypechecked(file))
|
|
101
|
+
violations.push(
|
|
102
|
+
violation(
|
|
103
|
+
"typecheck",
|
|
104
|
+
file,
|
|
105
|
+
"is not in any tsconfig program. Include it, or move it under an exempt directory if it is generated.",
|
|
106
|
+
),
|
|
107
|
+
);
|
|
108
|
+
if (!isLinted(file))
|
|
109
|
+
violations.push(
|
|
110
|
+
violation(
|
|
111
|
+
"lint",
|
|
112
|
+
file,
|
|
113
|
+
"is not in biome's files.includes. Include it, or move it under an exempt directory if it is generated.",
|
|
114
|
+
),
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
return violations;
|
|
118
|
+
};
|