@vaubaan/harness 2.4.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +207 -83
- package/dist/cli/index.js +4165 -843
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/harn-canvas.cmd.md +23 -0
- package/dist/commands/{decision.cmd.md → harn-decision.cmd.md} +6 -6
- package/dist/commands/{doc-audit.cmd.md → harn-doc-audit.cmd.md} +7 -7
- package/dist/commands/{drift.cmd.md → harn-drift.cmd.md} +6 -6
- package/dist/commands/{handbook.cmd.md → harn-handbook.cmd.md} +6 -6
- package/dist/commands/harn-improve.cmd.md +20 -0
- package/dist/commands/{intent.cmd.md → harn-intent.cmd.md} +9 -9
- package/dist/commands/{readme.cmd.md → harn-readme.cmd.md} +6 -6
- package/dist/commands/{spec.cmd.md → harn-spec.cmd.md} +6 -6
- package/dist/commands/{test-plan.cmd.md → harn-test-plan.cmd.md} +6 -6
- package/dist/commands/harn-upgrade.cmd.md +22 -0
- package/dist/commands/{workflow.cmd.md → harn-workflow.cmd.md} +6 -6
- package/dist/index.d.ts +32 -3
- package/dist/index.js +533 -96
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +468 -93
- package/dist/init.js.map +1 -1
- package/dist/linters/index.d.ts +3 -34
- package/dist/linters/index.js +996 -554
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +96 -6
- package/dist/parser/index.js +220 -10
- package/dist/parser/index.js.map +1 -1
- package/dist/render-BhUar2gf.d.ts +81 -0
- package/dist/render.d.ts +1 -1
- package/dist/render.js +233 -22
- package/dist/render.js.map +1 -1
- package/dist/skills/harn-canvas-review.skill.md +87 -0
- package/dist/skills/{decision-record-writer.skill.md → harn-decision-record-writer.skill.md} +2 -1
- package/dist/skills/{doc-audit.skill.md → harn-doc-audit.skill.md} +75 -26
- package/dist/skills/{drift-detector.skill.md → harn-drift-detector.skill.md} +15 -14
- package/dist/skills/harn-guide.skill.md +137 -0
- package/dist/skills/{handbook-writer.skill.md → harn-handbook-writer.skill.md} +2 -1
- package/dist/skills/{intent-writer.skill.md → harn-intent-writer.skill.md} +83 -16
- package/dist/skills/{readme-writer.skill.md → harn-readme-writer.skill.md} +4 -4
- package/dist/skills/harn-self-improve.skill.md +84 -0
- package/dist/skills/{spec-writer.skill.md → harn-spec-writer.skill.md} +8 -8
- package/dist/skills/{test-plan-writer.skill.md → harn-test-plan-writer.skill.md} +6 -5
- package/dist/skills/harn-upgrade.skill.md +171 -0
- package/dist/skills/{workflow-writer.skill.md → harn-workflow-writer.skill.md} +6 -5
- package/dist/templates/decisions-index.md.tmpl +11 -0
- package/dist/templates/handbook-index.md.tmpl +8 -0
- package/dist/templates/profile.md.tmpl +30 -0
- package/dist/types-CfUByAIr.d.ts +35 -0
- package/dist/view/index.d.ts +117 -0
- package/dist/view/index.js +3987 -0
- package/dist/view/index.js.map +1 -0
- package/package.json +5 -1
- package/dist/render-CTx7VNOK.d.ts +0 -45
package/dist/linters/index.js
CHANGED
|
@@ -81,7 +81,7 @@ var adrNoTracks = {
|
|
|
81
81
|
id: "lint:adr-no-tracks",
|
|
82
82
|
pillars: ["decisions"],
|
|
83
83
|
defaultSeverity: "error",
|
|
84
|
-
suggestedSkills: ["/decision"],
|
|
84
|
+
suggestedSkills: ["/harn-decision"],
|
|
85
85
|
run(repoRoot) {
|
|
86
86
|
const issues = [];
|
|
87
87
|
const files = listMarkdown(repoRoot, ADR_DIR);
|
|
@@ -104,25 +104,27 @@ var adrNoTracks = {
|
|
|
104
104
|
|
|
105
105
|
// src/linters/cardinal-files.ts
|
|
106
106
|
var REQUIRED_FILES = [
|
|
107
|
-
"docs/tests/integration-tests.md",
|
|
108
|
-
"docs/
|
|
109
|
-
"docs/workflow/coding-workflow.md"
|
|
107
|
+
{ dir: "docs/tests", files: ["docs/tests/integration-tests.md", "docs/tests/e2e-tests.md"] },
|
|
108
|
+
{ dir: "docs/workflow", files: ["docs/workflow/coding-workflow.md"] }
|
|
110
109
|
];
|
|
111
110
|
var cardinalFiles = {
|
|
112
111
|
id: "lint:cardinal-files",
|
|
113
112
|
pillars: ["tests", "workflow"],
|
|
114
113
|
defaultSeverity: "error",
|
|
115
|
-
suggestedSkills: ["/test-plan", "/workflow"],
|
|
114
|
+
suggestedSkills: ["/harn-test-plan", "/harn-workflow"],
|
|
116
115
|
run(repoRoot) {
|
|
117
116
|
const issues = [];
|
|
118
|
-
for (const
|
|
119
|
-
if (!
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
117
|
+
for (const { dir, files } of REQUIRED_FILES) {
|
|
118
|
+
if (!dirExists(repoRoot, dir)) continue;
|
|
119
|
+
for (const f of files) {
|
|
120
|
+
if (!fileExists(repoRoot, f)) {
|
|
121
|
+
issues.push({
|
|
122
|
+
linter: this.id,
|
|
123
|
+
severity: "error",
|
|
124
|
+
file: f,
|
|
125
|
+
message: `missing required cardinal file: ${f}`
|
|
126
|
+
});
|
|
127
|
+
}
|
|
126
128
|
}
|
|
127
129
|
}
|
|
128
130
|
return issues;
|
|
@@ -156,27 +158,509 @@ function loadLintConfig(repoRoot) {
|
|
|
156
158
|
}
|
|
157
159
|
|
|
158
160
|
// src/linters/cross-links.ts
|
|
159
|
-
import { existsSync as
|
|
160
|
-
import { dirname, isAbsolute, join as
|
|
161
|
+
import { existsSync as existsSync4 } from "fs";
|
|
162
|
+
import { dirname, isAbsolute, join as join4, resolve } from "path";
|
|
161
163
|
import fg2 from "fast-glob";
|
|
164
|
+
|
|
165
|
+
// src/parser/intent.ts
|
|
166
|
+
import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
|
|
167
|
+
import { basename, join as join3 } from "path";
|
|
168
|
+
import matter2 from "gray-matter";
|
|
169
|
+
|
|
170
|
+
// src/parser/schemas.ts
|
|
171
|
+
import { z } from "zod";
|
|
172
|
+
|
|
173
|
+
// src/pillars.ts
|
|
174
|
+
import { existsSync as existsSync2, readdirSync, statSync as statSync2 } from "fs";
|
|
175
|
+
import { join as join2 } from "path";
|
|
176
|
+
var PILLAR_IDS = [
|
|
177
|
+
"readme",
|
|
178
|
+
"spec",
|
|
179
|
+
"decisions",
|
|
180
|
+
"handbook",
|
|
181
|
+
"tests",
|
|
182
|
+
"workflow",
|
|
183
|
+
"quality",
|
|
184
|
+
"skills",
|
|
185
|
+
"intents",
|
|
186
|
+
"profiles"
|
|
187
|
+
];
|
|
188
|
+
var PILLARS = [
|
|
189
|
+
{ id: "readme", core: true },
|
|
190
|
+
{ id: "spec", dir: "docs/spec", core: true },
|
|
191
|
+
{
|
|
192
|
+
id: "decisions",
|
|
193
|
+
dir: "docs/decisions",
|
|
194
|
+
core: false,
|
|
195
|
+
starters: [{ template: "decisions-index.md.tmpl", path: "docs/decisions/README.md" }],
|
|
196
|
+
next: "write the first decision with the `harn-decision-record-writer` skill (`/harn-decision`)"
|
|
197
|
+
},
|
|
198
|
+
{
|
|
199
|
+
id: "handbook",
|
|
200
|
+
dir: "docs/handbook",
|
|
201
|
+
core: false,
|
|
202
|
+
starters: [{ template: "handbook-index.md.tmpl", path: "docs/handbook/README.md" }],
|
|
203
|
+
next: "write the first handbook with the `harn-handbook-writer` skill (`/harn-handbook`)"
|
|
204
|
+
},
|
|
205
|
+
{
|
|
206
|
+
id: "tests",
|
|
207
|
+
dir: "docs/tests",
|
|
208
|
+
core: false,
|
|
209
|
+
starters: [
|
|
210
|
+
{ template: "integration-tests.md.tmpl", path: "docs/tests/integration-tests.md" },
|
|
211
|
+
{ template: "e2e-tests.md.tmpl", path: "docs/tests/e2e-tests.md" }
|
|
212
|
+
],
|
|
213
|
+
next: "fill both test plans with the `harn-test-plan-writer` skill (`/harn-test-plan`); the lint fails on their placeholders until then"
|
|
214
|
+
},
|
|
215
|
+
{
|
|
216
|
+
id: "workflow",
|
|
217
|
+
dir: "docs/workflow",
|
|
218
|
+
core: false,
|
|
219
|
+
starters: [{ template: "coding-workflow.md.tmpl", path: "docs/workflow/coding-workflow.md" }],
|
|
220
|
+
next: "fill the workflow with the `harn-workflow-writer` skill (`/harn-workflow`); the lint fails on its placeholders until then"
|
|
221
|
+
},
|
|
222
|
+
{
|
|
223
|
+
id: "quality",
|
|
224
|
+
dir: "docs/quality",
|
|
225
|
+
core: false,
|
|
226
|
+
starters: [{ template: "code-quality.md.tmpl", path: "docs/quality/code-quality.md" }],
|
|
227
|
+
next: "fill docs/quality/code-quality.md by hand: the tools, the project's rules, the accepted deviations"
|
|
228
|
+
},
|
|
229
|
+
// Active as soon as it holds a `*.skill.md`: nothing to add.
|
|
230
|
+
{ id: "skills", dir: "docs/skills", core: false },
|
|
231
|
+
{
|
|
232
|
+
id: "intents",
|
|
233
|
+
dir: "docs/intents",
|
|
234
|
+
core: false,
|
|
235
|
+
starters: [],
|
|
236
|
+
next: "write the first intent with the `harn-intent-writer` skill (`/harn-intent <verb + object>`)"
|
|
237
|
+
},
|
|
238
|
+
{
|
|
239
|
+
id: "profiles",
|
|
240
|
+
dir: "docs/profiles",
|
|
241
|
+
core: false,
|
|
242
|
+
starters: [],
|
|
243
|
+
next: "describe the first profile with the `harn-intent-writer` skill, from the research you point it to"
|
|
244
|
+
}
|
|
245
|
+
];
|
|
246
|
+
var ADDABLE_PILLARS = PILLARS.filter(
|
|
247
|
+
(pillar) => pillar.starters !== void 0
|
|
248
|
+
);
|
|
249
|
+
function getPillar(id) {
|
|
250
|
+
return PILLARS.find((pillar) => pillar.id === id);
|
|
251
|
+
}
|
|
252
|
+
function isDirectory(path) {
|
|
253
|
+
return existsSync2(path) && statSync2(path).isDirectory();
|
|
254
|
+
}
|
|
255
|
+
function isPillarActive(repoRoot, id) {
|
|
256
|
+
const pillar = getPillar(id);
|
|
257
|
+
if (!pillar) return false;
|
|
258
|
+
if (pillar.core) return true;
|
|
259
|
+
return pillar.dir !== void 0 && isDirectory(join2(repoRoot, pillar.dir));
|
|
260
|
+
}
|
|
261
|
+
function activePillars(repoRoot) {
|
|
262
|
+
return new Set(PILLARS.filter((p) => isPillarActive(repoRoot, p.id)).map((p) => p.id));
|
|
263
|
+
}
|
|
264
|
+
function allPillars() {
|
|
265
|
+
return new Set(PILLAR_IDS);
|
|
266
|
+
}
|
|
267
|
+
function emptyPillarDirs(repoRoot) {
|
|
268
|
+
const holdsFile = (dir) => readdirSync(dir, { withFileTypes: true }).some(
|
|
269
|
+
(entry) => entry.isDirectory() ? holdsFile(join2(dir, entry.name)) : true
|
|
270
|
+
);
|
|
271
|
+
return PILLARS.flatMap((pillar) => {
|
|
272
|
+
if (!pillar.dir) return [];
|
|
273
|
+
const full = join2(repoRoot, pillar.dir);
|
|
274
|
+
return isDirectory(full) && !holdsFile(full) ? [pillar.dir] : [];
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
// src/types.ts
|
|
279
|
+
var ENGINES = ["claude-code", "codex-cli", "opencode"];
|
|
280
|
+
var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
|
|
281
|
+
var CAPABILITIES_MATRIX = {
|
|
282
|
+
"claude-code": ["multi-step", "slash-command", "inline-exec"],
|
|
283
|
+
"codex-cli": ["multi-step", "slash-command", "inline-exec"],
|
|
284
|
+
opencode: ["multi-step", "slash-command", "inline-exec"]
|
|
285
|
+
};
|
|
286
|
+
var DEGRADED_CAPABILITIES = {
|
|
287
|
+
"codex-cli": ["multi-step"]
|
|
288
|
+
};
|
|
289
|
+
|
|
290
|
+
// src/parser/schemas.ts
|
|
291
|
+
var IdSchema = z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
|
|
292
|
+
var SkillFrontmatterSchema = z.object({
|
|
293
|
+
id: IdSchema,
|
|
294
|
+
description: z.string().min(1),
|
|
295
|
+
engines: z.array(z.enum(ENGINES)).min(1).optional(),
|
|
296
|
+
requires: z.array(z.enum(CAPABILITIES)).optional(),
|
|
297
|
+
/** Rendered while one of these pillars is active; omitted = always. */
|
|
298
|
+
pillars: z.array(z.enum(PILLAR_IDS)).min(1).optional(),
|
|
299
|
+
tags: z.array(z.string()).optional()
|
|
300
|
+
}).strict();
|
|
301
|
+
var CmdArgEnumSchema = z.object({
|
|
302
|
+
name: z.string().min(1),
|
|
303
|
+
type: z.literal("enum"),
|
|
304
|
+
values: z.array(z.string()).min(1),
|
|
305
|
+
default: z.string().optional(),
|
|
306
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
307
|
+
required: z.boolean().optional()
|
|
308
|
+
}).strict();
|
|
309
|
+
var CmdArgStringSchema = z.object({
|
|
310
|
+
name: z.string().min(1),
|
|
311
|
+
type: z.literal("string"),
|
|
312
|
+
default: z.string().optional(),
|
|
313
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
314
|
+
required: z.boolean().optional()
|
|
315
|
+
}).strict();
|
|
316
|
+
var CmdArgSchema = z.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
317
|
+
var CmdFrontmatterSchema = z.object({
|
|
318
|
+
id: IdSchema,
|
|
319
|
+
trigger: z.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
|
|
320
|
+
invokes_skill: IdSchema,
|
|
321
|
+
args: z.array(CmdArgSchema).optional(),
|
|
322
|
+
description: z.string().min(1)
|
|
323
|
+
}).strict();
|
|
324
|
+
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
325
|
+
var IntentFrontmatterSchema = z.object({
|
|
326
|
+
title: z.string().min(1),
|
|
327
|
+
status: z.enum(INTENT_STATUSES),
|
|
328
|
+
actors: z.array(z.string().min(1)).min(1),
|
|
329
|
+
spec: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
|
|
330
|
+
last_reviewed: z.union([z.date(), z.string().min(1)])
|
|
331
|
+
}).strict();
|
|
332
|
+
var PROFILE_STATUSES = ["hypothesis", "validated"];
|
|
333
|
+
var ProfileFrontmatterSchema = z.object({
|
|
334
|
+
title: z.string().min(1),
|
|
335
|
+
status: z.enum(PROFILE_STATUSES),
|
|
336
|
+
evidence: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
|
|
337
|
+
last_reviewed: z.union([z.date(), z.string().min(1)])
|
|
338
|
+
}).strict();
|
|
339
|
+
var Schemas = {
|
|
340
|
+
Skill: SkillFrontmatterSchema,
|
|
341
|
+
Cmd: CmdFrontmatterSchema,
|
|
342
|
+
Intent: IntentFrontmatterSchema,
|
|
343
|
+
Profile: ProfileFrontmatterSchema
|
|
344
|
+
};
|
|
345
|
+
var ParseError = class extends Error {
|
|
346
|
+
constructor(file, issues) {
|
|
347
|
+
const messages = issues.map((i) => ` - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
|
|
348
|
+
super(`Frontmatter validation failed for ${file}:
|
|
349
|
+
${messages}`);
|
|
350
|
+
this.file = file;
|
|
351
|
+
this.issues = issues;
|
|
352
|
+
this.name = "ParseError";
|
|
353
|
+
}
|
|
354
|
+
file;
|
|
355
|
+
issues;
|
|
356
|
+
};
|
|
357
|
+
|
|
358
|
+
// src/parser/intent.ts
|
|
359
|
+
var INTENTS_DIR = "docs/intents";
|
|
360
|
+
var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
|
|
361
|
+
var NODE_FIELDS = [
|
|
362
|
+
"status",
|
|
363
|
+
"spec",
|
|
364
|
+
"anchors",
|
|
365
|
+
"acceptance",
|
|
366
|
+
"requires",
|
|
367
|
+
"creates",
|
|
368
|
+
"relieves",
|
|
369
|
+
"delivers"
|
|
370
|
+
];
|
|
371
|
+
var TERMINAL_FIELDS = [
|
|
372
|
+
"anchors",
|
|
373
|
+
"acceptance",
|
|
374
|
+
"requires",
|
|
375
|
+
"creates",
|
|
376
|
+
"relieves",
|
|
377
|
+
"delivers"
|
|
378
|
+
];
|
|
379
|
+
var MASKED_LINE = "\0";
|
|
380
|
+
var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
|
|
381
|
+
var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
|
|
382
|
+
var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
|
|
383
|
+
var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
|
|
384
|
+
function maskFencedCode(lines) {
|
|
385
|
+
let fence;
|
|
386
|
+
return lines.map((line) => {
|
|
387
|
+
const m = FENCE_RE.exec(line);
|
|
388
|
+
if (fence !== void 0) {
|
|
389
|
+
if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
|
|
390
|
+
return MASKED_LINE;
|
|
391
|
+
}
|
|
392
|
+
if (m?.[1]) {
|
|
393
|
+
fence = m[1];
|
|
394
|
+
return MASKED_LINE;
|
|
395
|
+
}
|
|
396
|
+
return line;
|
|
397
|
+
});
|
|
398
|
+
}
|
|
399
|
+
function parseHeading(line) {
|
|
400
|
+
const m = HEADING_RE.exec(line);
|
|
401
|
+
if (!m?.[1] || !m[2]) return void 0;
|
|
402
|
+
return { depth: m[1].length, title: m[2] };
|
|
403
|
+
}
|
|
404
|
+
function splitList(value) {
|
|
405
|
+
return value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
406
|
+
}
|
|
407
|
+
function bodyStart(lines) {
|
|
408
|
+
if (lines[0]?.trim() !== "---") return 0;
|
|
409
|
+
for (let i = 1; i < lines.length; i++) {
|
|
410
|
+
const l = lines[i]?.trim();
|
|
411
|
+
if (l === "---" || l === "...") return i + 1;
|
|
412
|
+
}
|
|
413
|
+
return lines.length;
|
|
414
|
+
}
|
|
415
|
+
function parseFrontmatter2(text, errors) {
|
|
416
|
+
let data;
|
|
417
|
+
try {
|
|
418
|
+
data = matter2(text).data;
|
|
419
|
+
} catch (error) {
|
|
420
|
+
const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
|
|
421
|
+
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
422
|
+
return void 0;
|
|
423
|
+
}
|
|
424
|
+
const result = Schemas.Intent.safeParse(data);
|
|
425
|
+
if (result.success) return result.data;
|
|
426
|
+
for (const issue of result.error.issues) {
|
|
427
|
+
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
428
|
+
errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
|
|
429
|
+
}
|
|
430
|
+
return void 0;
|
|
431
|
+
}
|
|
432
|
+
function newNode(title, level, line) {
|
|
433
|
+
return {
|
|
434
|
+
title,
|
|
435
|
+
level,
|
|
436
|
+
line,
|
|
437
|
+
isTerminal: true,
|
|
438
|
+
fieldLines: {},
|
|
439
|
+
anchors: [],
|
|
440
|
+
acceptance: [],
|
|
441
|
+
requires: [],
|
|
442
|
+
creates: [],
|
|
443
|
+
relieves: [],
|
|
444
|
+
delivers: [],
|
|
445
|
+
unknownFields: []
|
|
446
|
+
};
|
|
447
|
+
}
|
|
448
|
+
function parseFields(node, lines, from, to, errors) {
|
|
449
|
+
let lastKey;
|
|
450
|
+
for (let i = from; i < to; i++) {
|
|
451
|
+
const line = lines[i] ?? "";
|
|
452
|
+
if (line.trim() === "") continue;
|
|
453
|
+
const lineNo = i + 1;
|
|
454
|
+
const field = FIELD_RE.exec(line.trimEnd());
|
|
455
|
+
if (field?.[1] !== void 0) {
|
|
456
|
+
const key = field[1];
|
|
457
|
+
const value = (field[2] ?? "").trim();
|
|
458
|
+
lastKey = key;
|
|
459
|
+
if (!NODE_FIELDS.includes(key)) {
|
|
460
|
+
node.unknownFields.push({ key, line: lineNo });
|
|
461
|
+
continue;
|
|
462
|
+
}
|
|
463
|
+
const known = key;
|
|
464
|
+
node.fieldLines[known] = lineNo;
|
|
465
|
+
if (known === "status") {
|
|
466
|
+
if (INTENT_STATUSES.includes(value)) {
|
|
467
|
+
node.status = value;
|
|
468
|
+
} else {
|
|
469
|
+
errors.push({
|
|
470
|
+
line: lineNo,
|
|
471
|
+
message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
|
|
472
|
+
});
|
|
473
|
+
}
|
|
474
|
+
} else if (known === "spec") {
|
|
475
|
+
node.spec = value;
|
|
476
|
+
} else if (known === "acceptance") {
|
|
477
|
+
if (value) node.acceptance.push(value);
|
|
478
|
+
} else {
|
|
479
|
+
node[known] = splitList(value);
|
|
480
|
+
}
|
|
481
|
+
continue;
|
|
482
|
+
}
|
|
483
|
+
const item = LIST_ITEM_RE.exec(line);
|
|
484
|
+
if (lastKey === "acceptance" && item) {
|
|
485
|
+
const text = (item[1] ?? "").trim();
|
|
486
|
+
if (text) node.acceptance.push(text);
|
|
487
|
+
continue;
|
|
488
|
+
}
|
|
489
|
+
return;
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
function parseIntentFile(relPath, text) {
|
|
493
|
+
const errors = [];
|
|
494
|
+
const meta = parseFrontmatter2(text, errors);
|
|
495
|
+
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
496
|
+
const start = bodyStart(lines);
|
|
497
|
+
const headings = [];
|
|
498
|
+
for (let i = start; i < lines.length; i++) {
|
|
499
|
+
const h = parseHeading(lines[i] ?? "");
|
|
500
|
+
if (h) headings.push({ index: i, ...h });
|
|
501
|
+
}
|
|
502
|
+
const h1 = headings.find((h) => h.depth === 1);
|
|
503
|
+
let statement;
|
|
504
|
+
if (h1) {
|
|
505
|
+
const paragraph = [];
|
|
506
|
+
for (let i = h1.index + 1; i < lines.length; i++) {
|
|
507
|
+
const line = lines[i] ?? "";
|
|
508
|
+
if (line.trim() === "") {
|
|
509
|
+
if (paragraph.length) break;
|
|
510
|
+
continue;
|
|
511
|
+
}
|
|
512
|
+
if (line === MASKED_LINE || parseHeading(line)) break;
|
|
513
|
+
paragraph.push(line.trim());
|
|
514
|
+
}
|
|
515
|
+
if (paragraph.length) statement = paragraph.join(" ");
|
|
516
|
+
}
|
|
517
|
+
const nodes = [];
|
|
518
|
+
const stack = [];
|
|
519
|
+
for (const [k, h] of headings.entries()) {
|
|
520
|
+
if (h.depth < 2) continue;
|
|
521
|
+
const node = newNode(h.title, h.depth - 1, h.index + 1);
|
|
522
|
+
while (stack.length) {
|
|
523
|
+
const top = nodes[stack[stack.length - 1]];
|
|
524
|
+
if (top && top.level < node.level) break;
|
|
525
|
+
stack.pop();
|
|
526
|
+
}
|
|
527
|
+
const parentIndex = stack[stack.length - 1];
|
|
528
|
+
if (parentIndex !== void 0) {
|
|
529
|
+
node.parent = parentIndex;
|
|
530
|
+
const parent = nodes[parentIndex];
|
|
531
|
+
if (parent) parent.isTerminal = false;
|
|
532
|
+
}
|
|
533
|
+
const next = headings[k + 1];
|
|
534
|
+
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
535
|
+
const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
|
|
536
|
+
node.effectiveStatus = node.status ?? inherited;
|
|
537
|
+
stack.push(nodes.length);
|
|
538
|
+
nodes.push(node);
|
|
539
|
+
}
|
|
540
|
+
const title = meta?.title ?? h1?.title ?? basename(relPath, ".md");
|
|
541
|
+
return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
|
|
542
|
+
}
|
|
543
|
+
function listIntentFiles(targetDir) {
|
|
544
|
+
const dir = join3(targetDir, INTENTS_DIR);
|
|
545
|
+
if (!existsSync3(dir) || !statSync3(dir).isDirectory()) return [];
|
|
546
|
+
return readdirSync2(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join3(dir, f)).isFile()).sort();
|
|
547
|
+
}
|
|
548
|
+
function readIntentFiles(targetDir) {
|
|
549
|
+
return listIntentFiles(targetDir).map((file) => {
|
|
550
|
+
const path = `${INTENTS_DIR}/${file}`;
|
|
551
|
+
const text = readFileSync2(join3(targetDir, path), "utf8");
|
|
552
|
+
return { path, file, ...parseIntentFile(path, text) };
|
|
553
|
+
});
|
|
554
|
+
}
|
|
555
|
+
function loadIntentFiles(targetDir) {
|
|
556
|
+
const intentFiles = readIntentFiles(targetDir);
|
|
557
|
+
const problems = intentFiles.flatMap(
|
|
558
|
+
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
559
|
+
);
|
|
560
|
+
if (problems.length) {
|
|
561
|
+
throw new Error(
|
|
562
|
+
`invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
|
|
563
|
+
${problems.join("\n")}`
|
|
564
|
+
);
|
|
565
|
+
}
|
|
566
|
+
return intentFiles;
|
|
567
|
+
}
|
|
568
|
+
|
|
569
|
+
// src/parser/docs.ts
|
|
570
|
+
var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
|
|
571
|
+
var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*\s*(?:[—–:-]+\s*)?(.*)$/;
|
|
572
|
+
var TABLE_ROW = /^\s*\|(.+)\|\s*$/;
|
|
573
|
+
var TABLE_SEPARATOR = /^\s*\|?\s*:?-{3,}/;
|
|
574
|
+
function entitySlug(term) {
|
|
575
|
+
return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
576
|
+
}
|
|
577
|
+
function tableTerm(line, next) {
|
|
578
|
+
const row = TABLE_ROW.exec(line)?.[1];
|
|
579
|
+
if (row === void 0 || TABLE_SEPARATOR.test(line)) return void 0;
|
|
580
|
+
if (next !== void 0 && TABLE_SEPARATOR.test(next)) return void 0;
|
|
581
|
+
const cells = row.split("|").map((c) => c.trim());
|
|
582
|
+
const cell = (cells[0] ?? "").replace(/[*_`]/g, "").trim();
|
|
583
|
+
if (!cell || /^<.*>$/.test(cell)) return void 0;
|
|
584
|
+
return [cell, cells[1] ?? ""];
|
|
585
|
+
}
|
|
586
|
+
function vocabularyTerms(specText) {
|
|
587
|
+
const lines = maskFencedCode(specText.split(/\r?\n/));
|
|
588
|
+
let depth;
|
|
589
|
+
let terms;
|
|
590
|
+
for (const [i, line] of lines.entries()) {
|
|
591
|
+
const heading = parseHeading(line);
|
|
592
|
+
if (depth !== void 0) {
|
|
593
|
+
if (heading && heading.depth <= depth) break;
|
|
594
|
+
const bullet = TERM.exec(line);
|
|
595
|
+
const found = bullet?.[1] ? [bullet[1], bullet[2] ?? ""] : tableTerm(line, lines[i + 1]);
|
|
596
|
+
if (found) {
|
|
597
|
+
const [term, definition] = found;
|
|
598
|
+
terms?.push({ term: term.trim(), slug: entitySlug(term), line: i + 1, definition });
|
|
599
|
+
}
|
|
600
|
+
continue;
|
|
601
|
+
}
|
|
602
|
+
if (heading && VOCABULARY_HEADING.test(line)) {
|
|
603
|
+
depth = heading.depth;
|
|
604
|
+
terms = [];
|
|
605
|
+
}
|
|
606
|
+
}
|
|
607
|
+
return terms;
|
|
608
|
+
}
|
|
609
|
+
function vocabularyOf(specText) {
|
|
610
|
+
const terms = vocabularyTerms(specText);
|
|
611
|
+
return terms ? new Set(terms.map((t) => t.slug)) : void 0;
|
|
612
|
+
}
|
|
162
613
|
var LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
|
|
163
614
|
function maskCodeSpans(text) {
|
|
164
615
|
return text.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, " ")).replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length));
|
|
165
616
|
}
|
|
617
|
+
function readLinks(text) {
|
|
618
|
+
const lines = maskCodeSpans(text).split("\n");
|
|
619
|
+
const out = [];
|
|
620
|
+
for (const [i, line] of lines.entries()) {
|
|
621
|
+
LINK_REGEX.lastIndex = 0;
|
|
622
|
+
let match = LINK_REGEX.exec(line);
|
|
623
|
+
while (match !== null) {
|
|
624
|
+
if (match[2]) out.push({ url: match[2], line: i + 1 });
|
|
625
|
+
match = LINK_REGEX.exec(line);
|
|
626
|
+
}
|
|
627
|
+
}
|
|
628
|
+
return out;
|
|
629
|
+
}
|
|
166
630
|
function isExternalOrAnchor(url) {
|
|
167
|
-
|
|
168
|
-
if (url.startsWith("mailto:")) return true;
|
|
169
|
-
if (url.startsWith("#")) return true;
|
|
170
|
-
return false;
|
|
631
|
+
return /^(https?:|mailto:|#)/.test(url);
|
|
171
632
|
}
|
|
172
633
|
function stripFragment(url) {
|
|
173
634
|
const i = url.indexOf("#");
|
|
174
635
|
return i < 0 ? url : url.slice(0, i);
|
|
175
636
|
}
|
|
637
|
+
var ADR_SECTIONS = [
|
|
638
|
+
{ label: "Context", pattern: /^##\s+(Context|Contexte)\b/m },
|
|
639
|
+
{ label: "Decision", pattern: /^##\s+(Decision|D[ée]cision)\b/m },
|
|
640
|
+
{ label: "Consequences", pattern: /^##\s+(Consequences|Cons[ée]quences)\b/m },
|
|
641
|
+
{
|
|
642
|
+
label: "Rejected alternatives",
|
|
643
|
+
pattern: /^##\s+(Rejected\s+alternatives|Alternatives(\s+rejet[ée]es)?)\b/im
|
|
644
|
+
}
|
|
645
|
+
];
|
|
646
|
+
|
|
647
|
+
// src/linters/cross-links.ts
|
|
648
|
+
var LINKED_DOC_IGNORES = [
|
|
649
|
+
"**/node_modules/**",
|
|
650
|
+
"**/dist/**",
|
|
651
|
+
".harness-overrides/**",
|
|
652
|
+
"skills/**",
|
|
653
|
+
"agents/**",
|
|
654
|
+
"commands/**",
|
|
655
|
+
"templates/**",
|
|
656
|
+
"**/*.skill.md",
|
|
657
|
+
"**/*.cmd.md",
|
|
658
|
+
"**/*.agent.md"
|
|
659
|
+
];
|
|
176
660
|
function resolveLink(repoRoot, sourceFile, link) {
|
|
177
661
|
const noFrag = stripFragment(link);
|
|
178
|
-
if (isAbsolute(noFrag)) return
|
|
179
|
-
return resolve(dirname(
|
|
662
|
+
if (isAbsolute(noFrag)) return join4(repoRoot, noFrag);
|
|
663
|
+
return resolve(dirname(join4(repoRoot, sourceFile)), noFrag);
|
|
180
664
|
}
|
|
181
665
|
var crossLinks = {
|
|
182
666
|
id: "lint:cross-links",
|
|
@@ -188,46 +672,21 @@ var crossLinks = {
|
|
|
188
672
|
const allDocs = fg2.sync("**/*.md", {
|
|
189
673
|
cwd: repoRoot,
|
|
190
674
|
absolute: false,
|
|
191
|
-
ignore: [
|
|
192
|
-
"**/node_modules/**",
|
|
193
|
-
"**/dist/**",
|
|
194
|
-
".harness-overrides/**",
|
|
195
|
-
"skills/**",
|
|
196
|
-
"agents/**",
|
|
197
|
-
"commands/**",
|
|
198
|
-
"templates/**",
|
|
199
|
-
"**/*.skill.md",
|
|
200
|
-
"**/*.cmd.md",
|
|
201
|
-
"**/*.agent.md",
|
|
202
|
-
...extra
|
|
203
|
-
]
|
|
675
|
+
ignore: [...LINKED_DOC_IGNORES, ...extra]
|
|
204
676
|
});
|
|
205
677
|
for (const f of allDocs) {
|
|
206
|
-
const
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
const target = resolveLink(repoRoot, f, url);
|
|
219
|
-
if (!existsSync2(target)) {
|
|
220
|
-
issues.push({
|
|
221
|
-
linter: this.id,
|
|
222
|
-
severity: "error",
|
|
223
|
-
file: f,
|
|
224
|
-
line: lineNo + 1,
|
|
225
|
-
message: `broken link: ${url}`
|
|
226
|
-
});
|
|
227
|
-
}
|
|
228
|
-
}
|
|
229
|
-
}
|
|
230
|
-
match = LINK_REGEX.exec(line);
|
|
678
|
+
for (const { url, line } of readLinks(readText(repoRoot, f))) {
|
|
679
|
+
if (isExternalOrAnchor(url)) continue;
|
|
680
|
+
const noFrag = stripFragment(url);
|
|
681
|
+
if (noFrag === "" || noFrag.startsWith("data:")) continue;
|
|
682
|
+
if (!existsSync4(resolveLink(repoRoot, f, url))) {
|
|
683
|
+
issues.push({
|
|
684
|
+
linter: this.id,
|
|
685
|
+
severity: "error",
|
|
686
|
+
file: f,
|
|
687
|
+
line,
|
|
688
|
+
message: `broken link: ${url}`
|
|
689
|
+
});
|
|
231
690
|
}
|
|
232
691
|
}
|
|
233
692
|
}
|
|
@@ -236,26 +695,17 @@ var crossLinks = {
|
|
|
236
695
|
};
|
|
237
696
|
|
|
238
697
|
// src/linters/decision-schema.ts
|
|
239
|
-
var REQUIRED_SECTIONS = [
|
|
240
|
-
{ label: "Context", pattern: /^##\s+(Context|Contexte)\b/m },
|
|
241
|
-
{ label: "Decision", pattern: /^##\s+(Decision|D[ée]cision)\b/m },
|
|
242
|
-
{ label: "Consequences", pattern: /^##\s+(Consequences|Cons[ée]quences)\b/m },
|
|
243
|
-
{
|
|
244
|
-
label: "Rejected alternatives",
|
|
245
|
-
pattern: /^##\s+(Rejected\s+alternatives|Alternatives(\s+rejet[ée]es)?)\b/im
|
|
246
|
-
}
|
|
247
|
-
];
|
|
248
698
|
var decisionSchema = {
|
|
249
699
|
id: "lint:decision-schema",
|
|
250
700
|
pillars: ["decisions"],
|
|
251
701
|
defaultSeverity: "error",
|
|
252
|
-
suggestedSkills: ["/decision"],
|
|
702
|
+
suggestedSkills: ["/harn-decision"],
|
|
253
703
|
run(repoRoot) {
|
|
254
704
|
const issues = [];
|
|
255
705
|
const files = listMarkdown(repoRoot, "docs/decisions");
|
|
256
706
|
for (const f of files) {
|
|
257
707
|
const text = readText(repoRoot, f);
|
|
258
|
-
for (const { label, pattern } of
|
|
708
|
+
for (const { label, pattern } of ADR_SECTIONS) {
|
|
259
709
|
if (!pattern.test(text)) {
|
|
260
710
|
issues.push({
|
|
261
711
|
linter: this.id,
|
|
@@ -271,30 +721,17 @@ var decisionSchema = {
|
|
|
271
721
|
};
|
|
272
722
|
|
|
273
723
|
// src/linters/doc-layout.ts
|
|
274
|
-
var REQUIRED_DIRS = [
|
|
275
|
-
"docs/spec",
|
|
276
|
-
"docs/decisions",
|
|
277
|
-
"docs/handbook",
|
|
278
|
-
"docs/tests",
|
|
279
|
-
"docs/workflow"
|
|
280
|
-
];
|
|
281
724
|
var docLayout = {
|
|
282
725
|
id: "lint:doc-layout",
|
|
283
726
|
pillars: ["all"],
|
|
284
727
|
defaultSeverity: "error",
|
|
285
728
|
run(repoRoot) {
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
file: dir,
|
|
293
|
-
message: `missing required directory: ${dir}/`
|
|
294
|
-
});
|
|
295
|
-
}
|
|
296
|
-
}
|
|
297
|
-
return issues;
|
|
729
|
+
return emptyPillarDirs(repoRoot).map((dir) => ({
|
|
730
|
+
linter: this.id,
|
|
731
|
+
severity: "error",
|
|
732
|
+
file: dir,
|
|
733
|
+
message: `empty pillar folder: git does not record ${dir}/, so the pillar would be active on this machine only \u2014 fill it (\`npx @vaubaan/harness add ${dir.replace("docs/", "")}\`) or remove it`
|
|
734
|
+
}));
|
|
298
735
|
}
|
|
299
736
|
};
|
|
300
737
|
|
|
@@ -304,7 +741,7 @@ var frontmatterTracks = {
|
|
|
304
741
|
id: "lint:frontmatter-tracks",
|
|
305
742
|
pillars: ["handbook", "tests", "workflow"],
|
|
306
743
|
defaultSeverity: "error",
|
|
307
|
-
suggestedSkills: ["/handbook", "/test-plan", "/workflow"],
|
|
744
|
+
suggestedSkills: ["/harn-handbook", "/harn-test-plan", "/harn-workflow"],
|
|
308
745
|
run(repoRoot) {
|
|
309
746
|
const issues = [];
|
|
310
747
|
for (const dir of TRACKED_DIRS) {
|
|
@@ -347,18 +784,19 @@ var frontmatterTracks = {
|
|
|
347
784
|
};
|
|
348
785
|
|
|
349
786
|
// src/linters/generated-fresh.ts
|
|
350
|
-
import { existsSync as
|
|
351
|
-
import { join as
|
|
787
|
+
import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
|
|
788
|
+
import { join as join10, resolve as resolve4 } from "path";
|
|
352
789
|
|
|
353
790
|
// src/cli/managed-paths.ts
|
|
354
|
-
import { lstatSync, realpathSync, statSync as
|
|
355
|
-
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as
|
|
791
|
+
import { lstatSync, realpathSync, statSync as statSync4 } from "fs";
|
|
792
|
+
import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute2, join as join5, resolve as resolve2, win32 } from "path";
|
|
356
793
|
var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
357
794
|
"AGENTS.md",
|
|
358
795
|
"CLAUDE.md",
|
|
359
796
|
".harness-manifest.json",
|
|
360
|
-
//
|
|
797
|
+
// Indexes of the intents and profiles pillars, rendered while the pillar is active.
|
|
361
798
|
"docs/intents/README.md",
|
|
799
|
+
"docs/profiles/README.md",
|
|
362
800
|
// Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
|
|
363
801
|
"docs/journeys/README.md"
|
|
364
802
|
]);
|
|
@@ -387,14 +825,14 @@ function canonicalTargetRoot(root) {
|
|
|
387
825
|
let ancestor = resolve2(root);
|
|
388
826
|
const missing = [];
|
|
389
827
|
while (!lstatSync(ancestor, { throwIfNoEntry: false })) {
|
|
390
|
-
missing.unshift(
|
|
828
|
+
missing.unshift(basename2(ancestor));
|
|
391
829
|
ancestor = dirname2(ancestor);
|
|
392
830
|
}
|
|
393
831
|
const canonical = realpathSync(ancestor);
|
|
394
|
-
if (!
|
|
832
|
+
if (!statSync4(canonical).isDirectory()) {
|
|
395
833
|
throw new Error(`harness target is not a directory: ${root}`);
|
|
396
834
|
}
|
|
397
|
-
return
|
|
835
|
+
return join5(canonical, ...missing);
|
|
398
836
|
}
|
|
399
837
|
function assertManagedLocation(path) {
|
|
400
838
|
const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
|
|
@@ -409,7 +847,7 @@ function assertNoSymbolicComponents(root, path) {
|
|
|
409
847
|
const parts = path.split("/");
|
|
410
848
|
let current = root;
|
|
411
849
|
for (const [index, part] of parts.entries()) {
|
|
412
|
-
current =
|
|
850
|
+
current = join5(current, part);
|
|
413
851
|
const info = lstatSync(current, { throwIfNoEntry: false });
|
|
414
852
|
if (!info) return;
|
|
415
853
|
if (info.isSymbolicLink()) {
|
|
@@ -429,123 +867,48 @@ function assertManagedPaths(root, files) {
|
|
|
429
867
|
|
|
430
868
|
// src/cli/manifest.ts
|
|
431
869
|
import { createHash } from "crypto";
|
|
432
|
-
import { chmodSync, existsSync as
|
|
433
|
-
import { join as
|
|
434
|
-
import { z } from "zod";
|
|
870
|
+
import { chmodSync, existsSync as existsSync5, readFileSync as readFileSync3, writeFileSync } from "fs";
|
|
871
|
+
import { join as join6 } from "path";
|
|
872
|
+
import { z as z2 } from "zod";
|
|
435
873
|
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
436
874
|
var MANIFEST_VERSION = "6";
|
|
437
|
-
var ManifestSchema =
|
|
438
|
-
version:
|
|
439
|
-
engines:
|
|
440
|
-
renderedAt:
|
|
441
|
-
files:
|
|
442
|
-
harnessVersion:
|
|
443
|
-
overridesDir:
|
|
444
|
-
fileHashes:
|
|
445
|
-
preservedFiles:
|
|
875
|
+
var ManifestSchema = z2.object({
|
|
876
|
+
version: z2.enum(["4", "5", MANIFEST_VERSION]),
|
|
877
|
+
engines: z2.array(z2.string()),
|
|
878
|
+
renderedAt: z2.string(),
|
|
879
|
+
files: z2.array(z2.string()),
|
|
880
|
+
harnessVersion: z2.string().optional(),
|
|
881
|
+
overridesDir: z2.string().optional(),
|
|
882
|
+
fileHashes: z2.record(z2.string().regex(/^[a-f0-9]{64}$/)).optional(),
|
|
883
|
+
preservedFiles: z2.array(z2.string()).optional()
|
|
446
884
|
});
|
|
447
885
|
function manifestPath(targetDir) {
|
|
448
|
-
return
|
|
886
|
+
return join6(targetDir, MANIFEST_FILENAME);
|
|
449
887
|
}
|
|
450
888
|
function readManifest(targetDir) {
|
|
451
889
|
assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
|
|
452
890
|
const path = manifestPath(targetDir);
|
|
453
|
-
if (!
|
|
454
|
-
const raw = JSON.parse(
|
|
891
|
+
if (!existsSync5(path)) return null;
|
|
892
|
+
const raw = JSON.parse(readFileSync3(path, "utf8"));
|
|
455
893
|
return ManifestSchema.parse(raw);
|
|
456
894
|
}
|
|
457
895
|
|
|
458
896
|
// src/cli/plan-render.ts
|
|
459
|
-
import { existsSync as
|
|
460
|
-
import { dirname as dirname3, join as
|
|
897
|
+
import { existsSync as existsSync8 } from "fs";
|
|
898
|
+
import { dirname as dirname3, join as join9, resolve as resolve3 } from "path";
|
|
461
899
|
import { fileURLToPath } from "url";
|
|
462
900
|
|
|
463
901
|
// src/loader.ts
|
|
464
|
-
import { existsSync as
|
|
465
|
-
import { join as
|
|
902
|
+
import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
|
|
903
|
+
import { join as join7 } from "path";
|
|
466
904
|
import fg3 from "fast-glob";
|
|
467
905
|
import { z as z3 } from "zod";
|
|
468
906
|
|
|
469
907
|
// src/parser/common.ts
|
|
470
|
-
import { readFileSync as
|
|
471
|
-
import
|
|
472
|
-
|
|
473
|
-
// src/parser/schemas.ts
|
|
474
|
-
import { z as z2 } from "zod";
|
|
475
|
-
|
|
476
|
-
// src/types.ts
|
|
477
|
-
var ENGINES = ["claude-code", "codex-cli", "opencode"];
|
|
478
|
-
var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
|
|
479
|
-
var CAPABILITIES_MATRIX = {
|
|
480
|
-
"claude-code": ["multi-step", "slash-command", "inline-exec"],
|
|
481
|
-
"codex-cli": ["multi-step", "slash-command", "inline-exec"],
|
|
482
|
-
opencode: ["multi-step", "slash-command", "inline-exec"]
|
|
483
|
-
};
|
|
484
|
-
var DEGRADED_CAPABILITIES = {
|
|
485
|
-
"codex-cli": ["multi-step"]
|
|
486
|
-
};
|
|
487
|
-
|
|
488
|
-
// src/parser/schemas.ts
|
|
489
|
-
var IdSchema = z2.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
|
|
490
|
-
var SkillFrontmatterSchema = z2.object({
|
|
491
|
-
id: IdSchema,
|
|
492
|
-
description: z2.string().min(1),
|
|
493
|
-
engines: z2.array(z2.enum(ENGINES)).min(1).optional(),
|
|
494
|
-
requires: z2.array(z2.enum(CAPABILITIES)).optional(),
|
|
495
|
-
tags: z2.array(z2.string()).optional()
|
|
496
|
-
}).strict();
|
|
497
|
-
var CmdArgEnumSchema = z2.object({
|
|
498
|
-
name: z2.string().min(1),
|
|
499
|
-
type: z2.literal("enum"),
|
|
500
|
-
values: z2.array(z2.string()).min(1),
|
|
501
|
-
default: z2.string().optional(),
|
|
502
|
-
/** False when the command runs without the argument. Defaults to true. */
|
|
503
|
-
required: z2.boolean().optional()
|
|
504
|
-
}).strict();
|
|
505
|
-
var CmdArgStringSchema = z2.object({
|
|
506
|
-
name: z2.string().min(1),
|
|
507
|
-
type: z2.literal("string"),
|
|
508
|
-
default: z2.string().optional(),
|
|
509
|
-
/** False when the command runs without the argument. Defaults to true. */
|
|
510
|
-
required: z2.boolean().optional()
|
|
511
|
-
}).strict();
|
|
512
|
-
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
513
|
-
var CmdFrontmatterSchema = z2.object({
|
|
514
|
-
id: IdSchema,
|
|
515
|
-
trigger: z2.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
|
|
516
|
-
invokes_skill: IdSchema,
|
|
517
|
-
args: z2.array(CmdArgSchema).optional(),
|
|
518
|
-
description: z2.string().min(1)
|
|
519
|
-
}).strict();
|
|
520
|
-
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
521
|
-
var IntentFrontmatterSchema = z2.object({
|
|
522
|
-
title: z2.string().min(1),
|
|
523
|
-
status: z2.enum(INTENT_STATUSES),
|
|
524
|
-
actors: z2.array(z2.string().min(1)).min(1),
|
|
525
|
-
spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
|
|
526
|
-
last_reviewed: z2.union([z2.date(), z2.string().min(1)])
|
|
527
|
-
}).strict();
|
|
528
|
-
var Schemas = {
|
|
529
|
-
Skill: SkillFrontmatterSchema,
|
|
530
|
-
Cmd: CmdFrontmatterSchema,
|
|
531
|
-
Intent: IntentFrontmatterSchema
|
|
532
|
-
};
|
|
533
|
-
var ParseError = class extends Error {
|
|
534
|
-
constructor(file, issues) {
|
|
535
|
-
const messages = issues.map((i) => ` - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
|
|
536
|
-
super(`Frontmatter validation failed for ${file}:
|
|
537
|
-
${messages}`);
|
|
538
|
-
this.file = file;
|
|
539
|
-
this.issues = issues;
|
|
540
|
-
this.name = "ParseError";
|
|
541
|
-
}
|
|
542
|
-
file;
|
|
543
|
-
issues;
|
|
544
|
-
};
|
|
545
|
-
|
|
546
|
-
// src/parser/common.ts
|
|
908
|
+
import { readFileSync as readFileSync4 } from "fs";
|
|
909
|
+
import matter3 from "gray-matter";
|
|
547
910
|
function parseWithSchema(filePath, source, schema) {
|
|
548
|
-
const parsed =
|
|
911
|
+
const parsed = matter3(source);
|
|
549
912
|
const result = schema.safeParse(parsed.data);
|
|
550
913
|
if (!result.success) {
|
|
551
914
|
throw new ParseError(filePath, result.error.issues);
|
|
@@ -576,33 +939,33 @@ function parseYAML(source) {
|
|
|
576
939
|
// src/loader.ts
|
|
577
940
|
var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
|
|
578
941
|
function loadHarness(packageDir, opts = {}) {
|
|
579
|
-
const skillsDir = opts.skillsDir ??
|
|
580
|
-
const commandsDir = opts.commandsDir ??
|
|
942
|
+
const skillsDir = opts.skillsDir ?? join7(packageDir, "skills");
|
|
943
|
+
const commandsDir = opts.commandsDir ?? join7(packageDir, "commands");
|
|
581
944
|
const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
582
945
|
const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
|
|
583
946
|
return {
|
|
584
|
-
skills: skillFiles.map((f) => parseSkill(f,
|
|
585
|
-
cmds: cmdFiles.map((f) => parseCmd(f,
|
|
947
|
+
skills: skillFiles.map((f) => parseSkill(f, readFileSync5(f, "utf8"))),
|
|
948
|
+
cmds: cmdFiles.map((f) => parseCmd(f, readFileSync5(f, "utf8")))
|
|
586
949
|
};
|
|
587
950
|
}
|
|
588
951
|
function loadProjectSkills(targetDir) {
|
|
589
|
-
const skillsDir =
|
|
590
|
-
if (!
|
|
952
|
+
const skillsDir = join7(targetDir, "docs", "skills");
|
|
953
|
+
if (!existsSync6(skillsDir)) return [];
|
|
591
954
|
const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
592
|
-
return skillFiles.map((f) => parseSkill(f,
|
|
955
|
+
return skillFiles.map((f) => parseSkill(f, readFileSync5(f, "utf8")));
|
|
593
956
|
}
|
|
594
957
|
function loadOverrides(worktreeDir) {
|
|
595
|
-
const overridesDir =
|
|
596
|
-
if (!
|
|
958
|
+
const overridesDir = join7(worktreeDir, ".harness-overrides");
|
|
959
|
+
if (!existsSync6(overridesDir)) return void 0;
|
|
597
960
|
const added = loadHarness(overridesDir, {
|
|
598
|
-
skillsDir:
|
|
599
|
-
commandsDir:
|
|
961
|
+
skillsDir: join7(overridesDir, "skills"),
|
|
962
|
+
commandsDir: join7(overridesDir, "commands")
|
|
600
963
|
});
|
|
601
|
-
const disablePath =
|
|
964
|
+
const disablePath = join7(overridesDir, "disable.yaml");
|
|
602
965
|
let disable = [];
|
|
603
|
-
if (
|
|
966
|
+
if (existsSync6(disablePath)) {
|
|
604
967
|
try {
|
|
605
|
-
const parsed = DisableYamlSchema.safeParse(parseYAML(
|
|
968
|
+
const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync5(disablePath, "utf8")));
|
|
606
969
|
if (parsed.success && parsed.data.disable) {
|
|
607
970
|
disable = parsed.data.disable;
|
|
608
971
|
}
|
|
@@ -612,212 +975,157 @@ function loadOverrides(worktreeDir) {
|
|
|
612
975
|
return { add: added, disable };
|
|
613
976
|
}
|
|
614
977
|
|
|
615
|
-
// src/parser/
|
|
616
|
-
import { existsSync as
|
|
617
|
-
import { basename as
|
|
618
|
-
import
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
"
|
|
625
|
-
"acceptance",
|
|
626
|
-
"requires",
|
|
627
|
-
"creates"
|
|
628
|
-
];
|
|
629
|
-
var TERMINAL_FIELDS = [
|
|
630
|
-
"anchors",
|
|
631
|
-
"acceptance",
|
|
632
|
-
"requires",
|
|
633
|
-
"creates"
|
|
634
|
-
];
|
|
635
|
-
var MASKED_LINE = "\0";
|
|
636
|
-
var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
|
|
637
|
-
var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
|
|
638
|
-
var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
|
|
639
|
-
var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
|
|
640
|
-
function maskFencedCode(lines) {
|
|
641
|
-
let fence;
|
|
642
|
-
return lines.map((line) => {
|
|
643
|
-
const m = FENCE_RE.exec(line);
|
|
644
|
-
if (fence !== void 0) {
|
|
645
|
-
if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
|
|
646
|
-
return MASKED_LINE;
|
|
647
|
-
}
|
|
648
|
-
if (m?.[1]) {
|
|
649
|
-
fence = m[1];
|
|
650
|
-
return MASKED_LINE;
|
|
651
|
-
}
|
|
652
|
-
return line;
|
|
653
|
-
});
|
|
654
|
-
}
|
|
655
|
-
function parseHeading(line) {
|
|
656
|
-
const m = HEADING_RE.exec(line);
|
|
657
|
-
if (!m?.[1] || !m[2]) return void 0;
|
|
658
|
-
return { depth: m[1].length, title: m[2] };
|
|
659
|
-
}
|
|
660
|
-
function splitList(value) {
|
|
661
|
-
return value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
662
|
-
}
|
|
663
|
-
function bodyStart(lines) {
|
|
664
|
-
if (lines[0]?.trim() !== "---") return 0;
|
|
665
|
-
for (let i = 1; i < lines.length; i++) {
|
|
666
|
-
const l = lines[i]?.trim();
|
|
667
|
-
if (l === "---" || l === "...") return i + 1;
|
|
668
|
-
}
|
|
669
|
-
return lines.length;
|
|
670
|
-
}
|
|
671
|
-
function parseFrontmatter2(text, errors) {
|
|
672
|
-
let data;
|
|
673
|
-
try {
|
|
674
|
-
data = matter3(text).data;
|
|
675
|
-
} catch (error) {
|
|
676
|
-
const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
|
|
677
|
-
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
678
|
-
return void 0;
|
|
679
|
-
}
|
|
680
|
-
const result = Schemas.Intent.safeParse(data);
|
|
681
|
-
if (result.success) return result.data;
|
|
682
|
-
for (const issue of result.error.issues) {
|
|
683
|
-
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
684
|
-
errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
|
|
685
|
-
}
|
|
686
|
-
return void 0;
|
|
978
|
+
// src/parser/profile.ts
|
|
979
|
+
import { existsSync as existsSync7, readFileSync as readFileSync6, readdirSync as readdirSync3, statSync as statSync5 } from "fs";
|
|
980
|
+
import { basename as basename3, join as join8 } from "path";
|
|
981
|
+
import matter4 from "gray-matter";
|
|
982
|
+
|
|
983
|
+
// src/linters/intent-util.ts
|
|
984
|
+
import { posix } from "path";
|
|
985
|
+
function intentFileSpecs(meta) {
|
|
986
|
+
if (!meta) return [];
|
|
987
|
+
return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
|
|
687
988
|
}
|
|
688
|
-
function
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
level,
|
|
692
|
-
line,
|
|
693
|
-
isTerminal: true,
|
|
694
|
-
fieldLines: {},
|
|
695
|
-
anchors: [],
|
|
696
|
-
acceptance: [],
|
|
697
|
-
requires: [],
|
|
698
|
-
creates: [],
|
|
699
|
-
unknownFields: []
|
|
700
|
-
};
|
|
989
|
+
function resolveSpecPath(filePath, spec) {
|
|
990
|
+
const withoutFragment = spec.split("#")[0] ?? "";
|
|
991
|
+
return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
|
|
701
992
|
}
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
993
|
+
|
|
994
|
+
// src/linters/intent-vocabulary.ts
|
|
995
|
+
var intentVocabulary = {
|
|
996
|
+
id: "lint:intent-vocabulary",
|
|
997
|
+
pillars: ["intents"],
|
|
998
|
+
defaultSeverity: "error",
|
|
999
|
+
suggestedSkills: ["/harn-spec"],
|
|
1000
|
+
run(repoRoot) {
|
|
1001
|
+
const issues = [];
|
|
1002
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1003
|
+
const used = intentFile.nodes.flatMap(
|
|
1004
|
+
(node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
|
|
1005
|
+
);
|
|
1006
|
+
if (used.length === 0) continue;
|
|
1007
|
+
const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
|
|
1008
|
+
if (specs.length === 0) continue;
|
|
1009
|
+
const entities = /* @__PURE__ */ new Set();
|
|
1010
|
+
let hasVocabulary = false;
|
|
1011
|
+
for (const spec of specs) {
|
|
1012
|
+
const terms = vocabularyOf(readText(repoRoot, spec));
|
|
1013
|
+
if (!terms) continue;
|
|
1014
|
+
hasVocabulary = true;
|
|
1015
|
+
for (const term of terms) entities.add(term);
|
|
716
1016
|
}
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
1017
|
+
if (!hasVocabulary) {
|
|
1018
|
+
issues.push({
|
|
1019
|
+
linter: this.id,
|
|
1020
|
+
severity: "warning",
|
|
1021
|
+
file: intentFile.path,
|
|
1022
|
+
message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
|
|
1023
|
+
});
|
|
1024
|
+
continue;
|
|
1025
|
+
}
|
|
1026
|
+
for (const { entity, node } of used) {
|
|
1027
|
+
if (entities.has(entity)) continue;
|
|
1028
|
+
issues.push({
|
|
1029
|
+
linter: this.id,
|
|
1030
|
+
severity: "error",
|
|
1031
|
+
file: intentFile.path,
|
|
1032
|
+
line: node.line,
|
|
1033
|
+
message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
|
|
1034
|
+
});
|
|
734
1035
|
}
|
|
735
|
-
continue;
|
|
736
|
-
}
|
|
737
|
-
const item = LIST_ITEM_RE.exec(line);
|
|
738
|
-
if (lastKey === "acceptance" && item) {
|
|
739
|
-
const text = (item[1] ?? "").trim();
|
|
740
|
-
if (text) node.acceptance.push(text);
|
|
741
|
-
continue;
|
|
742
1036
|
}
|
|
743
|
-
return;
|
|
1037
|
+
return issues;
|
|
1038
|
+
}
|
|
1039
|
+
};
|
|
1040
|
+
|
|
1041
|
+
// src/parser/profile.ts
|
|
1042
|
+
var PROFILES_DIR = "docs/profiles";
|
|
1043
|
+
var PROFILES_INDEX_PATH = `${PROFILES_DIR}/README.md`;
|
|
1044
|
+
var PAINS_HEADING = /^(Pains|Irritants|Douleurs)\s*$/i;
|
|
1045
|
+
var GAINS_HEADING = /^(Gains|B[ée]n[ée]fices)\s*$/i;
|
|
1046
|
+
var BULLET = /^[-*]\s+(.*)$/;
|
|
1047
|
+
var NAMED = /^\*\*([^*]+)\*\*/;
|
|
1048
|
+
function parseFrontmatter3(text, errors) {
|
|
1049
|
+
let data;
|
|
1050
|
+
try {
|
|
1051
|
+
data = matter4(text).data;
|
|
1052
|
+
} catch (error) {
|
|
1053
|
+
const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
|
|
1054
|
+
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
1055
|
+
return void 0;
|
|
1056
|
+
}
|
|
1057
|
+
const result = Schemas.Profile.safeParse(data);
|
|
1058
|
+
if (result.success) return result.data;
|
|
1059
|
+
for (const issue of result.error.issues) {
|
|
1060
|
+
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
1061
|
+
errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
|
|
744
1062
|
}
|
|
1063
|
+
return void 0;
|
|
745
1064
|
}
|
|
746
|
-
function
|
|
1065
|
+
function parseProfileFile(relPath, text) {
|
|
747
1066
|
const errors = [];
|
|
748
|
-
const meta =
|
|
1067
|
+
const meta = parseFrontmatter3(text, errors);
|
|
749
1068
|
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
750
|
-
const
|
|
751
|
-
const
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
1069
|
+
const pains = [];
|
|
1070
|
+
const gains = [];
|
|
1071
|
+
let h1;
|
|
1072
|
+
let current;
|
|
1073
|
+
let start = 0;
|
|
1074
|
+
if (lines[0]?.trim() === "---") {
|
|
1075
|
+
const end = lines.findIndex((line, i) => i > 0 && /^(---|\.\.\.)\s*$/.test(line));
|
|
1076
|
+
start = end < 0 ? lines.length : end + 1;
|
|
755
1077
|
}
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
if (
|
|
763
|
-
|
|
764
|
-
|
|
1078
|
+
for (let i = start; i < lines.length; i++) {
|
|
1079
|
+
const line = lines[i] ?? "";
|
|
1080
|
+
const heading = parseHeading(line);
|
|
1081
|
+
if (heading) {
|
|
1082
|
+
if (heading.depth === 1 && h1 === void 0) h1 = heading.title;
|
|
1083
|
+
if (current && heading.depth > current.depth) continue;
|
|
1084
|
+
if (PAINS_HEADING.test(heading.title)) {
|
|
1085
|
+
current = { kind: "pain", depth: heading.depth, items: pains };
|
|
1086
|
+
} else if (GAINS_HEADING.test(heading.title)) {
|
|
1087
|
+
current = { kind: "gain", depth: heading.depth, items: gains };
|
|
1088
|
+
} else {
|
|
1089
|
+
current = void 0;
|
|
765
1090
|
}
|
|
766
|
-
|
|
767
|
-
paragraph.push(line.trim());
|
|
1091
|
+
continue;
|
|
768
1092
|
}
|
|
769
|
-
if (
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
if (
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
const top = nodes[stack[stack.length - 1]];
|
|
778
|
-
if (top && top.level < node.level) break;
|
|
779
|
-
stack.pop();
|
|
1093
|
+
if (!current) continue;
|
|
1094
|
+
const bullet = BULLET.exec(line)?.[1];
|
|
1095
|
+
if (bullet === void 0) continue;
|
|
1096
|
+
const name = NAMED.exec(bullet)?.[1]?.trim();
|
|
1097
|
+
const slug = name ? entitySlug(name) : "";
|
|
1098
|
+
if (!name || !slug) {
|
|
1099
|
+
errors.push({ line: i + 1, message: `a ${current.kind} opens with its name in bold` });
|
|
1100
|
+
continue;
|
|
780
1101
|
}
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
const parent = nodes[parentIndex];
|
|
785
|
-
if (parent) parent.isTerminal = false;
|
|
1102
|
+
if (current.items.some((item) => item.slug === slug)) {
|
|
1103
|
+
errors.push({ line: i + 1, message: `duplicate ${current.kind} \`${slug}\`` });
|
|
1104
|
+
continue;
|
|
786
1105
|
}
|
|
787
|
-
|
|
788
|
-
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
789
|
-
const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
|
|
790
|
-
node.effectiveStatus = node.status ?? inherited;
|
|
791
|
-
stack.push(nodes.length);
|
|
792
|
-
nodes.push(node);
|
|
1106
|
+
current.items.push({ name, slug, line: i + 1 });
|
|
793
1107
|
}
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
}
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
return
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
1108
|
+
if (pains.length === 0 && gains.length === 0) {
|
|
1109
|
+
errors.push({ message: "a profile names at least one pain or one gain" });
|
|
1110
|
+
}
|
|
1111
|
+
const title = meta?.title ?? h1 ?? basename3(relPath, ".md");
|
|
1112
|
+
return { ...meta ? { meta } : {}, title, pains, gains, errors };
|
|
1113
|
+
}
|
|
1114
|
+
function listProfileFiles(targetDir) {
|
|
1115
|
+
const dir = join8(targetDir, PROFILES_DIR);
|
|
1116
|
+
if (!existsSync7(dir) || !statSync5(dir).isDirectory()) return [];
|
|
1117
|
+
return readdirSync3(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync5(join8(dir, f)).isFile()).sort();
|
|
1118
|
+
}
|
|
1119
|
+
function readProfileFiles(targetDir) {
|
|
1120
|
+
return listProfileFiles(targetDir).map((file) => {
|
|
1121
|
+
const path = `${PROFILES_DIR}/${file}`;
|
|
1122
|
+
const text = readFileSync6(join8(targetDir, path), "utf8");
|
|
1123
|
+
return { path, file, slug: basename3(file, ".md"), ...parseProfileFile(path, text) };
|
|
807
1124
|
});
|
|
808
1125
|
}
|
|
809
|
-
function
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
813
|
-
);
|
|
814
|
-
if (problems.length) {
|
|
815
|
-
throw new Error(
|
|
816
|
-
`invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
|
|
817
|
-
${problems.join("\n")}`
|
|
818
|
-
);
|
|
819
|
-
}
|
|
820
|
-
return intentFiles;
|
|
1126
|
+
function profileEvidence(meta) {
|
|
1127
|
+
if (!meta?.evidence) return [];
|
|
1128
|
+
return typeof meta.evidence === "string" ? [meta.evidence] : [...meta.evidence];
|
|
821
1129
|
}
|
|
822
1130
|
|
|
823
1131
|
// src/renderers/common.ts
|
|
@@ -889,6 +1197,10 @@ function buildUmbrellaBody(extras) {
|
|
|
889
1197
|
const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
|
|
890
1198
|
return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
|
|
891
1199
|
});
|
|
1200
|
+
const has = (pillar) => extras.activePillars.has(pillar);
|
|
1201
|
+
const exposes = (id) => extras.availableSkills.some((s) => s.meta.id === id);
|
|
1202
|
+
const when = (condition, ...lines) => condition ? lines : [];
|
|
1203
|
+
const inactive = ADDABLE_PILLARS.filter((pillar) => !has(pillar.id)).map((p) => `\`${p.id}\``);
|
|
892
1204
|
const sections = [
|
|
893
1205
|
"# How we work",
|
|
894
1206
|
"",
|
|
@@ -898,29 +1210,65 @@ function buildUmbrellaBody(extras) {
|
|
|
898
1210
|
"",
|
|
899
1211
|
"- `README.md` \u2014 pitch, quick start, scripts. Entry point.",
|
|
900
1212
|
"- `docs/spec/<subsystem>.md` \u2014 *what* and *why* (tech-agnostic).",
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
...
|
|
906
|
-
|
|
1213
|
+
...when(
|
|
1214
|
+
has("handbook"),
|
|
1215
|
+
"- `docs/handbook/<feature>.md` \u2014 what the code does not say: entry points, traps, settings outside the repo, manual procedures."
|
|
1216
|
+
),
|
|
1217
|
+
...when(
|
|
1218
|
+
has("decisions"),
|
|
1219
|
+
"- `docs/decisions/<slug>.md` \u2014 ADRs: structural choices and rejected alternatives."
|
|
1220
|
+
),
|
|
1221
|
+
...when(
|
|
1222
|
+
has("tests"),
|
|
1223
|
+
"- `docs/tests/integration-tests.md` & `e2e-tests.md` \u2014 test scope, stack, conventions, known gaps."
|
|
1224
|
+
),
|
|
1225
|
+
...when(
|
|
1226
|
+
has("workflow"),
|
|
1227
|
+
"- `docs/workflow/coding-workflow.md` \u2014 CI, branches, PR, release. How this team works: follow it."
|
|
1228
|
+
),
|
|
1229
|
+
...when(
|
|
1230
|
+
extras.hasProjectSkills === true,
|
|
1231
|
+
"- `docs/skills/*.skill.md` \u2014 the project's domain skills."
|
|
1232
|
+
),
|
|
1233
|
+
...when(
|
|
1234
|
+
has("quality"),
|
|
907
1235
|
"- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
|
|
908
|
-
|
|
909
|
-
...
|
|
1236
|
+
),
|
|
1237
|
+
...when(
|
|
1238
|
+
has("intents"),
|
|
910
1239
|
"- `docs/intents/<intent>.md` \u2014 user intents, one tree per level-1 intent, anchored to the code. `docs/intents/README.md` is the generated index."
|
|
911
|
-
|
|
1240
|
+
),
|
|
1241
|
+
...when(
|
|
1242
|
+
has("profiles"),
|
|
1243
|
+
"- `docs/profiles/<profile>.md` \u2014 who the project serves, their pains and gains. `docs/profiles/README.md` is the generated index: which intent serves which pain."
|
|
1244
|
+
),
|
|
1245
|
+
...when(
|
|
1246
|
+
inactive.length > 0,
|
|
1247
|
+
"",
|
|
1248
|
+
`Not in this project yet: ${inactive.join(", ")}. A pillar is added the day the project needs it, with \`npx @vaubaan/harness add <pillar>\`${exposes("harn-guide") ? "; the `harn-guide` skill says when each one is worth it" : ""}. Propose it to the human, never create the folder unasked.`
|
|
1249
|
+
),
|
|
912
1250
|
"",
|
|
913
1251
|
"## Doc-first",
|
|
914
1252
|
"",
|
|
915
1253
|
"The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
|
|
916
1254
|
"",
|
|
917
|
-
...
|
|
918
|
-
"
|
|
919
|
-
|
|
1255
|
+
...when(
|
|
1256
|
+
has("intents"),
|
|
1257
|
+
"- Visible change of behavior \u2192 a `proposed` intent first (`/harn-intent <verb + object>`), never the code first."
|
|
1258
|
+
),
|
|
920
1259
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
1260
|
+
...when(
|
|
1261
|
+
has("decisions"),
|
|
1262
|
+
"- Implicit structural decision in your changes \u2192 an ADR (`/harn-decision`)."
|
|
1263
|
+
),
|
|
1264
|
+
...when(
|
|
1265
|
+
has("handbook"),
|
|
1266
|
+
"- Changed feature behavior \u2192 update the matching handbook (`/harn-handbook`)."
|
|
1267
|
+
),
|
|
1268
|
+
...when(
|
|
1269
|
+
exposes("harn-drift-detector"),
|
|
1270
|
+
"- Suspected code \u2194 doc drift \u2192 `/harn-drift` before moving on."
|
|
1271
|
+
),
|
|
924
1272
|
"",
|
|
925
1273
|
"## Checks",
|
|
926
1274
|
"",
|
|
@@ -929,7 +1277,7 @@ function buildUmbrellaBody(extras) {
|
|
|
929
1277
|
"The files the harness generates (`AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.agents/` and `.opencode/` folders, `.harness-manifest.json`) are committed. Never edit them by hand: change their source in `docs/` or `.harness-overrides/`, run `npx @vaubaan/harness update .`, and commit the result. The linter fails when a generated file no longer matches its render."
|
|
930
1278
|
];
|
|
931
1279
|
if (skillLines.length > 0) {
|
|
932
|
-
sections.push("", "##
|
|
1280
|
+
sections.push("", "## Skills", "", skillLines.join("\n"));
|
|
933
1281
|
}
|
|
934
1282
|
return `${sections.join("\n")}
|
|
935
1283
|
`;
|
|
@@ -1047,8 +1395,10 @@ function getRenderer(engine) {
|
|
|
1047
1395
|
|
|
1048
1396
|
// src/renderers/intents-index.ts
|
|
1049
1397
|
var INTRO = "User intents of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/intents/*.md`: edit the intents, not this file, then run `npx @vaubaan/harness update .`.";
|
|
1398
|
+
var EMPTY = "No intent yet. `/harn-intent <verb + object>` writes the first one, before the code.";
|
|
1050
1399
|
function buildIntentsIndex(intentFiles) {
|
|
1051
1400
|
const lines = ["# Intents", "", INTRO, ""];
|
|
1401
|
+
if (intentFiles.length === 0) lines.push(EMPTY);
|
|
1052
1402
|
const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
1053
1403
|
for (const intentFile of sorted) {
|
|
1054
1404
|
const status = intentFile.meta?.status ?? "proposed";
|
|
@@ -1062,6 +1412,54 @@ function buildIntentsIndex(intentFiles) {
|
|
|
1062
1412
|
`;
|
|
1063
1413
|
}
|
|
1064
1414
|
|
|
1415
|
+
// src/renderers/profiles-index.ts
|
|
1416
|
+
var INTRO2 = "Who this project serves, and what the intents do for them. Generated by `@vaubaan/harness` from `docs/profiles/*.md` and `docs/intents/*.md`: edit those, not this file, then run `npx @vaubaan/harness update .`.";
|
|
1417
|
+
var EMPTY2 = "No profile yet. The `harn-intent-writer` skill writes the first one from the research you point it to.";
|
|
1418
|
+
function buildProfilesIndex(profiles, intentFiles = []) {
|
|
1419
|
+
const lines = ["# Profiles", "", INTRO2];
|
|
1420
|
+
if (profiles.length === 0) lines.push("", EMPTY2);
|
|
1421
|
+
const sortedIntents = [...intentFiles].sort(
|
|
1422
|
+
(a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0
|
|
1423
|
+
);
|
|
1424
|
+
for (const profile of [...profiles].sort((a, b) => a.file < b.file ? -1 : 1)) {
|
|
1425
|
+
const theirs = sortedIntents.filter((file) => file.meta?.actors.includes(profile.slug));
|
|
1426
|
+
lines.push(
|
|
1427
|
+
"",
|
|
1428
|
+
`## [${profile.title}](./${profile.file}) \u2014 ${profile.meta?.status ?? "hypothesis"}`,
|
|
1429
|
+
""
|
|
1430
|
+
);
|
|
1431
|
+
lines.push(
|
|
1432
|
+
theirs.length ? `Intents: ${theirs.map((f) => `[${f.title}](../intents/${f.file})`).join(", ")}.` : "Intents: none names this profile yet."
|
|
1433
|
+
);
|
|
1434
|
+
const served = (kind, item) => {
|
|
1435
|
+
const by = [];
|
|
1436
|
+
for (const file of theirs) {
|
|
1437
|
+
for (const node of file.nodes) {
|
|
1438
|
+
if (node[kind].includes(item.slug)) {
|
|
1439
|
+
by.push(`[${node.title}](../intents/${file.file})`);
|
|
1440
|
+
}
|
|
1441
|
+
}
|
|
1442
|
+
}
|
|
1443
|
+
if (by.length) return by.join(", ");
|
|
1444
|
+
return kind === "relieves" ? "*no intent relieves it yet*" : "*no intent delivers it yet*";
|
|
1445
|
+
};
|
|
1446
|
+
if (profile.pains.length) {
|
|
1447
|
+
lines.push("", "Pains, most severe first:", "");
|
|
1448
|
+
for (const pain of profile.pains) {
|
|
1449
|
+
lines.push(`- **${pain.name}** (\`${pain.slug}\`) \u2014 ${served("relieves", pain)}`);
|
|
1450
|
+
}
|
|
1451
|
+
}
|
|
1452
|
+
if (profile.gains.length) {
|
|
1453
|
+
lines.push("", "Gains:", "");
|
|
1454
|
+
for (const gain of profile.gains) {
|
|
1455
|
+
lines.push(`- **${gain.name}** (\`${gain.slug}\`) \u2014 ${served("delivers", gain)}`);
|
|
1456
|
+
}
|
|
1457
|
+
}
|
|
1458
|
+
}
|
|
1459
|
+
return `${lines.join("\n")}
|
|
1460
|
+
`;
|
|
1461
|
+
}
|
|
1462
|
+
|
|
1065
1463
|
// src/render.ts
|
|
1066
1464
|
var RenderError = class extends Error {
|
|
1067
1465
|
constructor(message) {
|
|
@@ -1093,13 +1491,21 @@ var CLAUDE_MD_STUB = "@AGENTS.md\n";
|
|
|
1093
1491
|
function opencodeLast(engines) {
|
|
1094
1492
|
return [...engines].sort((a, b) => Number(a === "opencode") - Number(b === "opencode"));
|
|
1095
1493
|
}
|
|
1494
|
+
function servesAnActivePillar(skill, active) {
|
|
1495
|
+
return !skill.meta.pillars || skill.meta.pillars.some((pillar) => active.has(pillar));
|
|
1496
|
+
}
|
|
1096
1497
|
function render(input) {
|
|
1097
1498
|
const { engines } = input;
|
|
1098
1499
|
if (engines.length === 0) {
|
|
1099
1500
|
throw new RenderError("at least one engine must be selected");
|
|
1100
1501
|
}
|
|
1101
1502
|
const base = input.projectSkills?.length ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) } : input.harness;
|
|
1102
|
-
const
|
|
1503
|
+
const active = input.activePillars ?? allPillars();
|
|
1504
|
+
const merged = applyOverrides(base, input.overrides);
|
|
1505
|
+
const harness = {
|
|
1506
|
+
...merged,
|
|
1507
|
+
skills: merged.skills.filter((skill) => servesAnActivePillar(skill, active))
|
|
1508
|
+
};
|
|
1103
1509
|
const files = [];
|
|
1104
1510
|
const warnings = [];
|
|
1105
1511
|
const exposedSkills = /* @__PURE__ */ new Map();
|
|
@@ -1131,21 +1537,25 @@ function render(input) {
|
|
|
1131
1537
|
availableSkills: Array.from(exposedSkills.values()),
|
|
1132
1538
|
availableCommands: Array.from(exposedCmds.values()),
|
|
1133
1539
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
1134
|
-
|
|
1135
|
-
hasIntents: (input.intentFiles?.length ?? 0) > 0
|
|
1540
|
+
activePillars: active
|
|
1136
1541
|
});
|
|
1137
1542
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
1138
1543
|
if (engines.includes("claude-code")) {
|
|
1139
1544
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
1140
1545
|
}
|
|
1141
|
-
if (input.intentFiles
|
|
1546
|
+
if (input.intentFiles) {
|
|
1142
1547
|
files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
|
|
1143
1548
|
}
|
|
1549
|
+
if (input.profileFiles) {
|
|
1550
|
+
files.push({
|
|
1551
|
+
path: PROFILES_INDEX_PATH,
|
|
1552
|
+
content: buildProfilesIndex(input.profileFiles, input.intentFiles ?? [])
|
|
1553
|
+
});
|
|
1554
|
+
}
|
|
1144
1555
|
return { files, warnings };
|
|
1145
1556
|
}
|
|
1146
1557
|
|
|
1147
1558
|
// src/cli/plan-render.ts
|
|
1148
|
-
var QUALITY_DOC_PATH = "docs/quality/code-quality.md";
|
|
1149
1559
|
function resolveEngineList(requested) {
|
|
1150
1560
|
if (!requested || requested.length === 0) {
|
|
1151
1561
|
throw new Error(
|
|
@@ -1162,7 +1572,7 @@ function resolveEngineList(requested) {
|
|
|
1162
1572
|
}
|
|
1163
1573
|
function defaultPackageDir() {
|
|
1164
1574
|
const here = dirname3(fileURLToPath(import.meta.url));
|
|
1165
|
-
if (
|
|
1575
|
+
if (existsSync8(join9(here, "skills"))) return here;
|
|
1166
1576
|
return resolve3(here, "..");
|
|
1167
1577
|
}
|
|
1168
1578
|
function planInit(args) {
|
|
@@ -1171,9 +1581,16 @@ function planInit(args) {
|
|
|
1171
1581
|
const harness = loadHarness(packageDir);
|
|
1172
1582
|
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
1173
1583
|
const projectSkills = loadProjectSkills(args.targetDir);
|
|
1174
|
-
const
|
|
1175
|
-
const
|
|
1176
|
-
|
|
1584
|
+
const active = activePillars(args.targetDir);
|
|
1585
|
+
const output = render({
|
|
1586
|
+
harness,
|
|
1587
|
+
engines,
|
|
1588
|
+
overrides,
|
|
1589
|
+
projectSkills,
|
|
1590
|
+
activePillars: active,
|
|
1591
|
+
...active.has("intents") ? { intentFiles: loadIntentFiles(args.targetDir) } : {},
|
|
1592
|
+
...active.has("profiles") ? { profileFiles: readProfileFiles(args.targetDir) } : {}
|
|
1593
|
+
});
|
|
1177
1594
|
return { engines, output };
|
|
1178
1595
|
}
|
|
1179
1596
|
|
|
@@ -1199,7 +1616,7 @@ var generatedFresh = {
|
|
|
1199
1616
|
}
|
|
1200
1617
|
if (!manifest) return [];
|
|
1201
1618
|
const overridesParent = manifest.overridesDir ? resolve4(repoRoot, manifest.overridesDir) : repoRoot;
|
|
1202
|
-
const hasOverrides =
|
|
1619
|
+
const hasOverrides = existsSync9(join10(overridesParent, ".harness-overrides"));
|
|
1203
1620
|
let rendered;
|
|
1204
1621
|
try {
|
|
1205
1622
|
rendered = planInit({
|
|
@@ -1217,10 +1634,10 @@ var generatedFresh = {
|
|
|
1217
1634
|
for (const file of rendered.output.files) {
|
|
1218
1635
|
if (preserved.has(file.path)) continue;
|
|
1219
1636
|
renderedPaths.add(file.path);
|
|
1220
|
-
const full =
|
|
1221
|
-
if (!
|
|
1637
|
+
const full = join10(repoRoot, file.path);
|
|
1638
|
+
if (!existsSync9(full)) {
|
|
1222
1639
|
issues.push(issue(file.path, `generated file is missing; ${FIX}`));
|
|
1223
|
-
} else if (
|
|
1640
|
+
} else if (readFileSync7(full, "utf8") !== file.content) {
|
|
1224
1641
|
issues.push(
|
|
1225
1642
|
issue(
|
|
1226
1643
|
file.path,
|
|
@@ -1231,7 +1648,7 @@ var generatedFresh = {
|
|
|
1231
1648
|
}
|
|
1232
1649
|
for (const path of manifest.files) {
|
|
1233
1650
|
if (renderedPaths.has(path) || preserved.has(path) || RELEASED_PATHS.includes(path)) continue;
|
|
1234
|
-
if (
|
|
1651
|
+
if (existsSync9(join10(repoRoot, path))) {
|
|
1235
1652
|
issues.push(issue(path, `stale generated file, no longer rendered; ${FIX}`));
|
|
1236
1653
|
}
|
|
1237
1654
|
}
|
|
@@ -1252,7 +1669,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
|
1252
1669
|
".agents/",
|
|
1253
1670
|
".opencode/",
|
|
1254
1671
|
".harness-manifest.json",
|
|
1255
|
-
"docs/intents/README.md"
|
|
1672
|
+
"docs/intents/README.md",
|
|
1673
|
+
"docs/profiles/README.md"
|
|
1256
1674
|
];
|
|
1257
1675
|
function gitignoreEntries(text) {
|
|
1258
1676
|
const entries = /* @__PURE__ */ new Set();
|
|
@@ -1316,7 +1734,7 @@ var intentAnchors = {
|
|
|
1316
1734
|
id: "lint:intent-anchors",
|
|
1317
1735
|
pillars: ["intents"],
|
|
1318
1736
|
defaultSeverity: "error",
|
|
1319
|
-
suggestedSkills: ["/intent"],
|
|
1737
|
+
suggestedSkills: ["/harn-intent"],
|
|
1320
1738
|
run(repoRoot) {
|
|
1321
1739
|
const issues = [];
|
|
1322
1740
|
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
@@ -1343,7 +1761,7 @@ var intentGraph = {
|
|
|
1343
1761
|
id: "lint:intent-graph",
|
|
1344
1762
|
pillars: ["intents"],
|
|
1345
1763
|
defaultSeverity: "warning",
|
|
1346
|
-
suggestedSkills: ["/intent"],
|
|
1764
|
+
suggestedSkills: ["/harn-intent"],
|
|
1347
1765
|
run(repoRoot) {
|
|
1348
1766
|
const intentFiles = readIntentFiles(repoRoot);
|
|
1349
1767
|
const terminals = intentFiles.flatMap(
|
|
@@ -1367,16 +1785,67 @@ var intentGraph = {
|
|
|
1367
1785
|
}
|
|
1368
1786
|
};
|
|
1369
1787
|
|
|
1370
|
-
// src/linters/intent-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1788
|
+
// src/linters/intent-profiles.ts
|
|
1789
|
+
var intentProfiles = {
|
|
1790
|
+
id: "lint:intent-profiles",
|
|
1791
|
+
pillars: ["intents", "profiles"],
|
|
1792
|
+
defaultSeverity: "error",
|
|
1793
|
+
suggestedSkills: ["/harn-intent"],
|
|
1794
|
+
run(repoRoot) {
|
|
1795
|
+
const issues = [];
|
|
1796
|
+
const intentFiles = readIntentFiles(repoRoot);
|
|
1797
|
+
const profilesActive = dirExists(repoRoot, PROFILES_DIR);
|
|
1798
|
+
const profiles = new Map(readProfileFiles(repoRoot).map((p) => [p.slug, p]));
|
|
1799
|
+
for (const intentFile of intentFiles) {
|
|
1800
|
+
const report = (message, line) => {
|
|
1801
|
+
issues.push({
|
|
1802
|
+
linter: this.id,
|
|
1803
|
+
severity: "error",
|
|
1804
|
+
file: intentFile.path,
|
|
1805
|
+
...line !== void 0 ? { line } : {},
|
|
1806
|
+
message
|
|
1807
|
+
});
|
|
1808
|
+
};
|
|
1809
|
+
const actors = intentFile.meta?.actors ?? [];
|
|
1810
|
+
if (profilesActive) {
|
|
1811
|
+
for (const actor of actors) {
|
|
1812
|
+
if (!profiles.has(actor)) {
|
|
1813
|
+
report(`actor \`${actor}\` is not a profile: no ${PROFILES_DIR}/${actor}.md`, 1);
|
|
1814
|
+
}
|
|
1815
|
+
}
|
|
1816
|
+
}
|
|
1817
|
+
const theirs = actors.flatMap((actor) => profiles.get(actor) ?? []);
|
|
1818
|
+
const pains = new Set(theirs.flatMap((p) => p.pains.map((item) => item.slug)));
|
|
1819
|
+
const gains = new Set(theirs.flatMap((p) => p.gains.map((item) => item.slug)));
|
|
1820
|
+
for (const node of intentFile.nodes) {
|
|
1821
|
+
const fields = [
|
|
1822
|
+
{ key: "relieves", values: node.relieves, known: pains, kind: "pain" },
|
|
1823
|
+
{ key: "delivers", values: node.delivers, known: gains, kind: "gain" }
|
|
1824
|
+
];
|
|
1825
|
+
for (const { key, values, known, kind } of fields) {
|
|
1826
|
+
if (values.length === 0) continue;
|
|
1827
|
+
const line = node.fieldLines[key] ?? node.line;
|
|
1828
|
+
if (!profilesActive) {
|
|
1829
|
+
report(
|
|
1830
|
+
`"${node.title}": \`${key}:\` needs the profiles pillar \u2014 \`npx @vaubaan/harness add profiles\``,
|
|
1831
|
+
line
|
|
1832
|
+
);
|
|
1833
|
+
continue;
|
|
1834
|
+
}
|
|
1835
|
+
for (const slug of values) {
|
|
1836
|
+
if (!known.has(slug)) {
|
|
1837
|
+
report(
|
|
1838
|
+
`"${node.title}": \`${slug}\` is not a ${kind} of ${actors.length ? actors.map((a) => `\`${a}\``).join(", ") : "any actor"}`,
|
|
1839
|
+
line
|
|
1840
|
+
);
|
|
1841
|
+
}
|
|
1842
|
+
}
|
|
1843
|
+
}
|
|
1844
|
+
}
|
|
1845
|
+
}
|
|
1846
|
+
return issues;
|
|
1847
|
+
}
|
|
1848
|
+
};
|
|
1380
1849
|
|
|
1381
1850
|
// src/linters/intent-schema.ts
|
|
1382
1851
|
var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
|
|
@@ -1384,7 +1853,7 @@ var intentSchema = {
|
|
|
1384
1853
|
id: "lint:intent-schema",
|
|
1385
1854
|
pillars: ["intents"],
|
|
1386
1855
|
defaultSeverity: "error",
|
|
1387
|
-
suggestedSkills: ["/intent"],
|
|
1856
|
+
suggestedSkills: ["/harn-intent"],
|
|
1388
1857
|
run(repoRoot) {
|
|
1389
1858
|
const issues = [];
|
|
1390
1859
|
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
@@ -1442,85 +1911,14 @@ var intentSchema = {
|
|
|
1442
1911
|
}
|
|
1443
1912
|
};
|
|
1444
1913
|
|
|
1445
|
-
// src/linters/intent-vocabulary.ts
|
|
1446
|
-
var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
|
|
1447
|
-
var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
|
|
1448
|
-
function entitySlug(term) {
|
|
1449
|
-
return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
1450
|
-
}
|
|
1451
|
-
function vocabularyOf(specText) {
|
|
1452
|
-
const lines = maskFencedCode(specText.split(/\r?\n/));
|
|
1453
|
-
let depth;
|
|
1454
|
-
let terms;
|
|
1455
|
-
for (const line of lines) {
|
|
1456
|
-
const heading = parseHeading(line);
|
|
1457
|
-
if (depth !== void 0) {
|
|
1458
|
-
if (heading && heading.depth <= depth) break;
|
|
1459
|
-
const term = TERM.exec(line)?.[1];
|
|
1460
|
-
if (term) terms?.add(entitySlug(term));
|
|
1461
|
-
continue;
|
|
1462
|
-
}
|
|
1463
|
-
if (heading && VOCABULARY_HEADING.test(line)) {
|
|
1464
|
-
depth = heading.depth;
|
|
1465
|
-
terms = /* @__PURE__ */ new Set();
|
|
1466
|
-
}
|
|
1467
|
-
}
|
|
1468
|
-
return terms;
|
|
1469
|
-
}
|
|
1470
|
-
var intentVocabulary = {
|
|
1471
|
-
id: "lint:intent-vocabulary",
|
|
1472
|
-
pillars: ["intents"],
|
|
1473
|
-
defaultSeverity: "error",
|
|
1474
|
-
suggestedSkills: ["/spec"],
|
|
1475
|
-
run(repoRoot) {
|
|
1476
|
-
const issues = [];
|
|
1477
|
-
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1478
|
-
const used = intentFile.nodes.flatMap(
|
|
1479
|
-
(node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
|
|
1480
|
-
);
|
|
1481
|
-
if (used.length === 0) continue;
|
|
1482
|
-
const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
|
|
1483
|
-
if (specs.length === 0) continue;
|
|
1484
|
-
const entities = /* @__PURE__ */ new Set();
|
|
1485
|
-
let hasVocabulary = false;
|
|
1486
|
-
for (const spec of specs) {
|
|
1487
|
-
const terms = vocabularyOf(readText(repoRoot, spec));
|
|
1488
|
-
if (!terms) continue;
|
|
1489
|
-
hasVocabulary = true;
|
|
1490
|
-
for (const term of terms) entities.add(term);
|
|
1491
|
-
}
|
|
1492
|
-
if (!hasVocabulary) {
|
|
1493
|
-
issues.push({
|
|
1494
|
-
linter: this.id,
|
|
1495
|
-
severity: "warning",
|
|
1496
|
-
file: intentFile.path,
|
|
1497
|
-
message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
|
|
1498
|
-
});
|
|
1499
|
-
continue;
|
|
1500
|
-
}
|
|
1501
|
-
for (const { entity, node } of used) {
|
|
1502
|
-
if (entities.has(entity)) continue;
|
|
1503
|
-
issues.push({
|
|
1504
|
-
linter: this.id,
|
|
1505
|
-
severity: "error",
|
|
1506
|
-
file: intentFile.path,
|
|
1507
|
-
line: node.line,
|
|
1508
|
-
message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
|
|
1509
|
-
});
|
|
1510
|
-
}
|
|
1511
|
-
}
|
|
1512
|
-
return issues;
|
|
1513
|
-
}
|
|
1514
|
-
};
|
|
1515
|
-
|
|
1516
1914
|
// src/linters/orphan-decisions.ts
|
|
1517
|
-
import { basename as
|
|
1915
|
+
import { basename as basename4 } from "path";
|
|
1518
1916
|
import fg4 from "fast-glob";
|
|
1519
1917
|
var orphanDecisions = {
|
|
1520
1918
|
id: "lint:orphan-decisions",
|
|
1521
1919
|
pillars: ["decisions"],
|
|
1522
1920
|
defaultSeverity: "warning",
|
|
1523
|
-
suggestedSkills: ["/handbook"],
|
|
1921
|
+
suggestedSkills: ["/harn-handbook"],
|
|
1524
1922
|
run(repoRoot, ctx) {
|
|
1525
1923
|
const extra = ctx?.config.ignore ?? [];
|
|
1526
1924
|
const issues = [];
|
|
@@ -1543,7 +1941,7 @@ var orphanDecisions = {
|
|
|
1543
1941
|
});
|
|
1544
1942
|
const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
|
|
1545
1943
|
for (const adr of adrs) {
|
|
1546
|
-
const filename =
|
|
1944
|
+
const filename = basename4(adr);
|
|
1547
1945
|
const stem = filename.replace(/\.md$/, "");
|
|
1548
1946
|
const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
|
|
1549
1947
|
if (!referenced) {
|
|
@@ -1559,10 +1957,47 @@ var orphanDecisions = {
|
|
|
1559
1957
|
}
|
|
1560
1958
|
};
|
|
1561
1959
|
|
|
1960
|
+
// src/linters/profile-schema.ts
|
|
1961
|
+
import { posix as posix2 } from "path";
|
|
1962
|
+
var EXTERNAL = /^[a-z][a-z0-9+.-]*:/i;
|
|
1963
|
+
var profileSchema = {
|
|
1964
|
+
id: "lint:profile-schema",
|
|
1965
|
+
pillars: ["profiles"],
|
|
1966
|
+
defaultSeverity: "error",
|
|
1967
|
+
suggestedSkills: ["/harn-intent"],
|
|
1968
|
+
run(repoRoot) {
|
|
1969
|
+
const issues = [];
|
|
1970
|
+
for (const profile of readProfileFiles(repoRoot)) {
|
|
1971
|
+
const report = (message, line) => {
|
|
1972
|
+
issues.push({
|
|
1973
|
+
linter: this.id,
|
|
1974
|
+
severity: "error",
|
|
1975
|
+
file: profile.path,
|
|
1976
|
+
...line !== void 0 ? { line } : {},
|
|
1977
|
+
message
|
|
1978
|
+
});
|
|
1979
|
+
};
|
|
1980
|
+
for (const error of profile.errors) report(error.message, error.line);
|
|
1981
|
+
const evidence = profileEvidence(profile.meta);
|
|
1982
|
+
if (profile.meta?.status === "validated" && evidence.length === 0) {
|
|
1983
|
+
report("a `validated` profile needs `evidence:` \u2014 without it, it is a `hypothesis`", 1);
|
|
1984
|
+
}
|
|
1985
|
+
for (const link of evidence) {
|
|
1986
|
+
if (EXTERNAL.test(link)) continue;
|
|
1987
|
+
const target = posix2.normalize(
|
|
1988
|
+
posix2.join(posix2.dirname(profile.path), link.split("#")[0] ?? "")
|
|
1989
|
+
);
|
|
1990
|
+
if (!fileExists(repoRoot, target)) report(`\`evidence\` does not resolve: ${link}`, 1);
|
|
1991
|
+
}
|
|
1992
|
+
}
|
|
1993
|
+
return issues;
|
|
1994
|
+
}
|
|
1995
|
+
};
|
|
1996
|
+
|
|
1562
1997
|
// src/linters/quality-schema.ts
|
|
1563
1998
|
var QUALITY_DIR = "docs/quality";
|
|
1564
1999
|
var CARDINAL_FILE = `${QUALITY_DIR}/code-quality.md`;
|
|
1565
|
-
var
|
|
2000
|
+
var REQUIRED_SECTIONS = [
|
|
1566
2001
|
{
|
|
1567
2002
|
label: "Mechanical checks",
|
|
1568
2003
|
pattern: /^##\s+(Mechanical\s+checks|V[ée]rifications\s+m[ée]caniques)\s*$/im
|
|
@@ -1590,7 +2025,7 @@ var qualitySchema = {
|
|
|
1590
2025
|
];
|
|
1591
2026
|
}
|
|
1592
2027
|
const text = readText(repoRoot, CARDINAL_FILE);
|
|
1593
|
-
return
|
|
2028
|
+
return REQUIRED_SECTIONS.filter(({ pattern }) => !pattern.test(text)).map(({ label }) => ({
|
|
1594
2029
|
linter: this.id,
|
|
1595
2030
|
severity: "error",
|
|
1596
2031
|
file: CARDINAL_FILE,
|
|
@@ -1604,7 +2039,7 @@ var readmePresence = {
|
|
|
1604
2039
|
id: "lint:readme-presence",
|
|
1605
2040
|
pillars: ["readme"],
|
|
1606
2041
|
defaultSeverity: "error",
|
|
1607
|
-
suggestedSkills: ["/readme"],
|
|
2042
|
+
suggestedSkills: ["/harn-readme"],
|
|
1608
2043
|
run(repoRoot) {
|
|
1609
2044
|
if (fileExists(repoRoot, "README.md")) return [];
|
|
1610
2045
|
return [
|
|
@@ -1619,7 +2054,7 @@ var readmePresence = {
|
|
|
1619
2054
|
};
|
|
1620
2055
|
|
|
1621
2056
|
// src/linters/readme-sections.ts
|
|
1622
|
-
var
|
|
2057
|
+
var REQUIRED_SECTIONS2 = [
|
|
1623
2058
|
/^#\s+\S/m,
|
|
1624
2059
|
/^##?\s+(What is this|Quick start)/im,
|
|
1625
2060
|
/^##?\s+(Quick start|Install|Getting started)/im
|
|
@@ -1629,13 +2064,13 @@ var readmeSections = {
|
|
|
1629
2064
|
id: "lint:readme-sections",
|
|
1630
2065
|
pillars: ["readme"],
|
|
1631
2066
|
defaultSeverity: "error",
|
|
1632
|
-
suggestedSkills: ["/readme"],
|
|
2067
|
+
suggestedSkills: ["/harn-readme"],
|
|
1633
2068
|
run(repoRoot) {
|
|
1634
2069
|
if (!fileExists(repoRoot, "README.md")) return [];
|
|
1635
2070
|
const text = readText(repoRoot, "README.md");
|
|
1636
2071
|
const issues = [];
|
|
1637
|
-
for (let i = 0; i <
|
|
1638
|
-
const pattern =
|
|
2072
|
+
for (let i = 0; i < REQUIRED_SECTIONS2.length; i++) {
|
|
2073
|
+
const pattern = REQUIRED_SECTIONS2[i];
|
|
1639
2074
|
const label = REQUIRED_LABELS[i];
|
|
1640
2075
|
if (pattern && !pattern.test(text)) {
|
|
1641
2076
|
issues.push({
|
|
@@ -1655,9 +2090,8 @@ var specHasContent = {
|
|
|
1655
2090
|
id: "lint:spec-has-content",
|
|
1656
2091
|
pillars: ["spec"],
|
|
1657
2092
|
defaultSeverity: "warning",
|
|
1658
|
-
suggestedSkills: ["/spec"],
|
|
2093
|
+
suggestedSkills: ["/harn-spec"],
|
|
1659
2094
|
run(repoRoot) {
|
|
1660
|
-
if (!dirExists(repoRoot, "docs/spec")) return [];
|
|
1661
2095
|
const files = listMarkdown(repoRoot, "docs/spec");
|
|
1662
2096
|
if (files.length > 0) return [];
|
|
1663
2097
|
return [
|
|
@@ -1665,7 +2099,7 @@ var specHasContent = {
|
|
|
1665
2099
|
linter: this.id,
|
|
1666
2100
|
severity: "warning",
|
|
1667
2101
|
file: "docs/spec",
|
|
1668
|
-
message: "docs/spec/ has no markdown
|
|
2102
|
+
message: "no spec yet: docs/spec/ has no markdown file \u2014 write the first spec document"
|
|
1669
2103
|
}
|
|
1670
2104
|
];
|
|
1671
2105
|
}
|
|
@@ -1694,7 +2128,7 @@ var specTechAgnostic = {
|
|
|
1694
2128
|
id: "lint:spec-tech-agnostic",
|
|
1695
2129
|
pillars: ["spec"],
|
|
1696
2130
|
defaultSeverity: "error",
|
|
1697
|
-
suggestedSkills: ["/spec"],
|
|
2131
|
+
suggestedSkills: ["/harn-spec"],
|
|
1698
2132
|
run(repoRoot) {
|
|
1699
2133
|
const issues = [];
|
|
1700
2134
|
const files = listMarkdown(repoRoot, "docs/spec");
|
|
@@ -1736,39 +2170,45 @@ function trackedPaths(dir, file, text, data) {
|
|
|
1736
2170
|
}
|
|
1737
2171
|
return Array.isArray(data.tracks) ? data.tracks : void 0;
|
|
1738
2172
|
}
|
|
2173
|
+
function driftOf(repoRoot, file) {
|
|
2174
|
+
const dir = TRACKED_DIRS2.find((d) => file.startsWith(`${d}/`)) ?? (file.startsWith(`${INTENTS_DIR2}/`) ? INTENTS_DIR2 : void 0);
|
|
2175
|
+
if (!dir) return void 0;
|
|
2176
|
+
const text = readText(repoRoot, file);
|
|
2177
|
+
const { data } = parseFrontmatter(text);
|
|
2178
|
+
const tracks = trackedPaths(dir, file, text, data);
|
|
2179
|
+
if (!tracks) return void 0;
|
|
2180
|
+
const docCommit = gitLastCommitForPath(repoRoot, file);
|
|
2181
|
+
if (!docCommit) return void 0;
|
|
2182
|
+
const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
|
|
2183
|
+
let commits = 0;
|
|
2184
|
+
const tracked = [];
|
|
2185
|
+
for (const entry of tracks) {
|
|
2186
|
+
if (typeof entry !== "string") continue;
|
|
2187
|
+
tracked.push(entry);
|
|
2188
|
+
const targets = expandGlob(repoRoot, entry);
|
|
2189
|
+
for (const t of targets.length > 0 ? targets : [entry]) {
|
|
2190
|
+
commits += gitCommitsSince(repoRoot, t, docCommit.hash);
|
|
2191
|
+
}
|
|
2192
|
+
}
|
|
2193
|
+
return { commits, threshold, tracked };
|
|
2194
|
+
}
|
|
1739
2195
|
var tracksDrift = {
|
|
1740
2196
|
id: "lint:tracks-drift",
|
|
1741
2197
|
pillars: ["handbook", "tests", "workflow", "intents"],
|
|
1742
2198
|
defaultSeverity: "warning",
|
|
1743
|
-
suggestedSkills: ["/drift", "/handbook"],
|
|
2199
|
+
suggestedSkills: ["/harn-drift", "/harn-handbook"],
|
|
1744
2200
|
run(repoRoot) {
|
|
1745
2201
|
const issues = [];
|
|
1746
2202
|
for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
|
|
1747
|
-
const
|
|
1748
|
-
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1756
|
-
let driftCount = 0;
|
|
1757
|
-
for (const tracked of tracks) {
|
|
1758
|
-
if (typeof tracked !== "string") continue;
|
|
1759
|
-
const targets = expandGlob(repoRoot, tracked);
|
|
1760
|
-
for (const t of targets.length > 0 ? targets : [tracked]) {
|
|
1761
|
-
driftCount += gitCommitsSince(repoRoot, t, docCommit.hash);
|
|
1762
|
-
}
|
|
1763
|
-
}
|
|
1764
|
-
if (driftCount > threshold) {
|
|
1765
|
-
issues.push({
|
|
1766
|
-
linter: this.id,
|
|
1767
|
-
severity: "warning",
|
|
1768
|
-
file: f,
|
|
1769
|
-
message: `tracked files changed in ${driftCount} commits since doc last edit (threshold ${threshold})`
|
|
1770
|
-
});
|
|
1771
|
-
}
|
|
2203
|
+
for (const f of listMarkdown(repoRoot, dir)) {
|
|
2204
|
+
const drift = driftOf(repoRoot, f);
|
|
2205
|
+
if (!drift || drift.commits <= drift.threshold) continue;
|
|
2206
|
+
issues.push({
|
|
2207
|
+
linter: this.id,
|
|
2208
|
+
severity: "warning",
|
|
2209
|
+
file: f,
|
|
2210
|
+
message: `tracked files changed in ${drift.commits} commits since doc last edit (threshold ${drift.threshold})`
|
|
2211
|
+
});
|
|
1772
2212
|
}
|
|
1773
2213
|
}
|
|
1774
2214
|
return issues;
|
|
@@ -1795,6 +2235,8 @@ var ALL_LINTERS = [
|
|
|
1795
2235
|
intentAnchors,
|
|
1796
2236
|
intentVocabulary,
|
|
1797
2237
|
intentGraph,
|
|
2238
|
+
intentProfiles,
|
|
2239
|
+
profileSchema,
|
|
1798
2240
|
generatedFresh
|
|
1799
2241
|
];
|
|
1800
2242
|
function runLinters(repoRoot, opts = {}) {
|