@vaubaan/harness 2.0.0 → 2.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/README.md +25 -21
- package/dist/cli/index.js +543 -76
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/handbook.cmd.md +4 -3
- package/dist/commands/journey.cmd.md +22 -0
- package/dist/commands/story.cmd.md +24 -0
- package/dist/commands/test-plan.cmd.md +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +304 -56
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +2 -3
- package/dist/init.js +301 -53
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +523 -56
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +110 -1
- package/dist/parser/index.js +229 -2
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-BzrBb_l4.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +89 -10
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +93 -130
- package/dist/skills/doc-audit.skill.md +37 -7
- package/dist/skills/drift-detector.skill.md +41 -11
- package/dist/skills/handbook-writer.skill.md +71 -159
- package/dist/skills/journey-writer.skill.md +159 -0
- package/dist/skills/spec-writer.skill.md +25 -3
- package/dist/skills/test-plan-writer.skill.md +46 -53
- package/dist/skills/workflow-writer.skill.md +20 -3
- package/dist/templates/decision.md.tmpl +20 -47
- package/dist/templates/e2e-tests.md.tmpl +16 -45
- package/dist/templates/handbook.md.tmpl +20 -38
- package/dist/templates/integration-tests.md.tmpl +16 -34
- package/dist/templates/journey.md.tmpl +45 -0
- package/package.json +1 -1
package/dist/cli/index.js
CHANGED
|
@@ -17,6 +17,12 @@ function fileExists(repoRoot, relativePath) {
|
|
|
17
17
|
function readText(repoRoot, relativePath) {
|
|
18
18
|
return readFileSync(join(repoRoot, relativePath), "utf8");
|
|
19
19
|
}
|
|
20
|
+
function trackedPathExists(repoRoot, pattern) {
|
|
21
|
+
if (pattern.includes("*")) {
|
|
22
|
+
return fg.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
|
|
23
|
+
}
|
|
24
|
+
return existsSync(join(repoRoot, pattern));
|
|
25
|
+
}
|
|
20
26
|
function listMarkdown(repoRoot, dir) {
|
|
21
27
|
const cwd = join(repoRoot, dir);
|
|
22
28
|
if (!existsSync(cwd)) return [];
|
|
@@ -300,16 +306,7 @@ var docLayout = {
|
|
|
300
306
|
};
|
|
301
307
|
|
|
302
308
|
// src/linters/frontmatter-tracks.ts
|
|
303
|
-
import { existsSync as existsSync3 } from "fs";
|
|
304
|
-
import { join as join3 } from "path";
|
|
305
|
-
import fg3 from "fast-glob";
|
|
306
309
|
var TRACKED_DIRS = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
307
|
-
function trackedPathExists(repoRoot, pattern) {
|
|
308
|
-
if (pattern.includes("*")) {
|
|
309
|
-
return fg3.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
|
|
310
|
-
}
|
|
311
|
-
return existsSync3(join3(repoRoot, pattern));
|
|
312
|
-
}
|
|
313
310
|
var frontmatterTracks = {
|
|
314
311
|
id: "lint:frontmatter-tracks",
|
|
315
312
|
pillars: ["handbook", "tests", "workflow"],
|
|
@@ -357,13 +354,19 @@ var frontmatterTracks = {
|
|
|
357
354
|
};
|
|
358
355
|
|
|
359
356
|
// src/linters/generated-fresh.ts
|
|
360
|
-
import { existsSync as existsSync7, readFileSync as
|
|
357
|
+
import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
|
|
361
358
|
import { join as join8, resolve as resolve4 } from "path";
|
|
362
359
|
|
|
363
360
|
// src/cli/managed-paths.ts
|
|
364
361
|
import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
|
|
365
|
-
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as
|
|
366
|
-
var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
362
|
+
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2, win32 } from "path";
|
|
363
|
+
var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
364
|
+
"AGENTS.md",
|
|
365
|
+
"CLAUDE.md",
|
|
366
|
+
".harness-manifest.json",
|
|
367
|
+
// Index of the optional journeys pillar, rendered while a journey exists.
|
|
368
|
+
"docs/journeys/README.md"
|
|
369
|
+
]);
|
|
367
370
|
var RELEASED_PATHS = [
|
|
368
371
|
".mcp.json",
|
|
369
372
|
".codex/config.toml",
|
|
@@ -396,7 +399,7 @@ function canonicalTargetRoot(root) {
|
|
|
396
399
|
if (!statSync2(canonical).isDirectory()) {
|
|
397
400
|
throw new Error(`harness target is not a directory: ${root}`);
|
|
398
401
|
}
|
|
399
|
-
return
|
|
402
|
+
return join3(canonical, ...missing);
|
|
400
403
|
}
|
|
401
404
|
function assertManagedLocation(path) {
|
|
402
405
|
const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
|
|
@@ -411,7 +414,7 @@ function assertNoSymbolicComponents(root, path) {
|
|
|
411
414
|
const parts = path.split("/");
|
|
412
415
|
let current = root;
|
|
413
416
|
for (const [index, part] of parts.entries()) {
|
|
414
|
-
current =
|
|
417
|
+
current = join3(current, part);
|
|
415
418
|
const info = lstatSync(current, { throwIfNoEntry: false });
|
|
416
419
|
if (!info) return;
|
|
417
420
|
if (info.isSymbolicLink()) {
|
|
@@ -431,12 +434,12 @@ function assertManagedPaths(root, files) {
|
|
|
431
434
|
|
|
432
435
|
// src/cli/manifest.ts
|
|
433
436
|
import { createHash } from "crypto";
|
|
434
|
-
import { chmodSync, existsSync as
|
|
435
|
-
import { join as
|
|
437
|
+
import { chmodSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
|
|
438
|
+
import { join as join4 } from "path";
|
|
436
439
|
import { z } from "zod";
|
|
437
440
|
|
|
438
441
|
// src/version.ts
|
|
439
|
-
var VERSION = "2.
|
|
442
|
+
var VERSION = "2.2.0";
|
|
440
443
|
|
|
441
444
|
// src/cli/manifest.ts
|
|
442
445
|
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
@@ -452,7 +455,7 @@ var ManifestSchema = z.object({
|
|
|
452
455
|
preservedFiles: z.array(z.string()).optional()
|
|
453
456
|
});
|
|
454
457
|
function manifestPath(targetDir) {
|
|
455
|
-
return
|
|
458
|
+
return join4(targetDir, MANIFEST_FILENAME);
|
|
456
459
|
}
|
|
457
460
|
function hashContent(content) {
|
|
458
461
|
return createHash("sha256").update(content).digest("hex");
|
|
@@ -460,7 +463,7 @@ function hashContent(content) {
|
|
|
460
463
|
function readManifest(targetDir) {
|
|
461
464
|
assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
|
|
462
465
|
const path = manifestPath(targetDir);
|
|
463
|
-
if (!
|
|
466
|
+
if (!existsSync3(path)) return null;
|
|
464
467
|
const raw = JSON.parse(readFileSync2(path, "utf8"));
|
|
465
468
|
return ManifestSchema.parse(raw);
|
|
466
469
|
}
|
|
@@ -471,9 +474,9 @@ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
|
|
|
471
474
|
import { fileURLToPath } from "url";
|
|
472
475
|
|
|
473
476
|
// src/loader.ts
|
|
474
|
-
import { existsSync as
|
|
475
|
-
import { join as
|
|
476
|
-
import
|
|
477
|
+
import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
|
|
478
|
+
import { join as join5 } from "path";
|
|
479
|
+
import fg3 from "fast-glob";
|
|
477
480
|
import { z as z3 } from "zod";
|
|
478
481
|
|
|
479
482
|
// src/parser/common.ts
|
|
@@ -523,9 +526,18 @@ var CmdFrontmatterSchema = z2.object({
|
|
|
523
526
|
args: z2.array(CmdArgSchema).optional(),
|
|
524
527
|
description: z2.string().min(1)
|
|
525
528
|
}).strict();
|
|
529
|
+
var JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
530
|
+
var JourneyFrontmatterSchema = z2.object({
|
|
531
|
+
title: z2.string().min(1),
|
|
532
|
+
status: z2.enum(JOURNEY_STATUSES),
|
|
533
|
+
actors: z2.array(z2.string().min(1)).min(1),
|
|
534
|
+
spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
|
|
535
|
+
last_reviewed: z2.union([z2.date(), z2.string().min(1)])
|
|
536
|
+
}).strict();
|
|
526
537
|
var Schemas = {
|
|
527
538
|
Skill: SkillFrontmatterSchema,
|
|
528
|
-
Cmd: CmdFrontmatterSchema
|
|
539
|
+
Cmd: CmdFrontmatterSchema,
|
|
540
|
+
Journey: JourneyFrontmatterSchema
|
|
529
541
|
};
|
|
530
542
|
var ParseError = class extends Error {
|
|
531
543
|
constructor(file, issues) {
|
|
@@ -573,31 +585,31 @@ function parseYAML(source) {
|
|
|
573
585
|
// src/loader.ts
|
|
574
586
|
var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
|
|
575
587
|
function loadHarness(packageDir, opts = {}) {
|
|
576
|
-
const skillsDir = opts.skillsDir ??
|
|
577
|
-
const commandsDir = opts.commandsDir ??
|
|
578
|
-
const skillFiles =
|
|
579
|
-
const cmdFiles =
|
|
588
|
+
const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
|
|
589
|
+
const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
|
|
590
|
+
const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
591
|
+
const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
|
|
580
592
|
return {
|
|
581
593
|
skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
|
|
582
594
|
cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
|
|
583
595
|
};
|
|
584
596
|
}
|
|
585
597
|
function loadProjectSkills(targetDir) {
|
|
586
|
-
const skillsDir =
|
|
587
|
-
if (!
|
|
588
|
-
const skillFiles =
|
|
598
|
+
const skillsDir = join5(targetDir, "docs", "skills");
|
|
599
|
+
if (!existsSync4(skillsDir)) return [];
|
|
600
|
+
const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
589
601
|
return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
|
|
590
602
|
}
|
|
591
603
|
function loadOverrides(worktreeDir) {
|
|
592
|
-
const overridesDir =
|
|
593
|
-
if (!
|
|
604
|
+
const overridesDir = join5(worktreeDir, ".harness-overrides");
|
|
605
|
+
if (!existsSync4(overridesDir)) return void 0;
|
|
594
606
|
const added = loadHarness(overridesDir, {
|
|
595
|
-
skillsDir:
|
|
596
|
-
commandsDir:
|
|
607
|
+
skillsDir: join5(overridesDir, "skills"),
|
|
608
|
+
commandsDir: join5(overridesDir, "commands")
|
|
597
609
|
});
|
|
598
|
-
const disablePath =
|
|
610
|
+
const disablePath = join5(overridesDir, "disable.yaml");
|
|
599
611
|
let disable = [];
|
|
600
|
-
if (
|
|
612
|
+
if (existsSync4(disablePath)) {
|
|
601
613
|
try {
|
|
602
614
|
const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
|
|
603
615
|
if (parsed.success && parsed.data.disable) {
|
|
@@ -609,6 +621,214 @@ function loadOverrides(worktreeDir) {
|
|
|
609
621
|
return { add: added, disable };
|
|
610
622
|
}
|
|
611
623
|
|
|
624
|
+
// src/parser/journey.ts
|
|
625
|
+
import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
|
|
626
|
+
import { basename as basename2, join as join6 } from "path";
|
|
627
|
+
import matter3 from "gray-matter";
|
|
628
|
+
var JOURNEYS_DIR = "docs/journeys";
|
|
629
|
+
var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
|
|
630
|
+
var NODE_FIELDS = [
|
|
631
|
+
"status",
|
|
632
|
+
"spec",
|
|
633
|
+
"anchors",
|
|
634
|
+
"acceptance",
|
|
635
|
+
"requires",
|
|
636
|
+
"creates"
|
|
637
|
+
];
|
|
638
|
+
var LEAF_FIELDS = [
|
|
639
|
+
"anchors",
|
|
640
|
+
"acceptance",
|
|
641
|
+
"requires",
|
|
642
|
+
"creates"
|
|
643
|
+
];
|
|
644
|
+
var MASKED_LINE = "\0";
|
|
645
|
+
var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
|
|
646
|
+
var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
|
|
647
|
+
var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
|
|
648
|
+
var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
|
|
649
|
+
function maskFencedCode(lines) {
|
|
650
|
+
let fence;
|
|
651
|
+
return lines.map((line) => {
|
|
652
|
+
const m = FENCE_RE.exec(line);
|
|
653
|
+
if (fence !== void 0) {
|
|
654
|
+
if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
|
|
655
|
+
return MASKED_LINE;
|
|
656
|
+
}
|
|
657
|
+
if (m?.[1]) {
|
|
658
|
+
fence = m[1];
|
|
659
|
+
return MASKED_LINE;
|
|
660
|
+
}
|
|
661
|
+
return line;
|
|
662
|
+
});
|
|
663
|
+
}
|
|
664
|
+
function parseHeading(line) {
|
|
665
|
+
const m = HEADING_RE.exec(line);
|
|
666
|
+
if (!m?.[1] || !m[2]) return void 0;
|
|
667
|
+
return { depth: m[1].length, title: m[2] };
|
|
668
|
+
}
|
|
669
|
+
function splitList(value) {
|
|
670
|
+
return value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
671
|
+
}
|
|
672
|
+
function bodyStart(lines) {
|
|
673
|
+
if (lines[0]?.trim() !== "---") return 0;
|
|
674
|
+
for (let i = 1; i < lines.length; i++) {
|
|
675
|
+
const l = lines[i]?.trim();
|
|
676
|
+
if (l === "---" || l === "...") return i + 1;
|
|
677
|
+
}
|
|
678
|
+
return lines.length;
|
|
679
|
+
}
|
|
680
|
+
function parseFrontmatter2(text, errors) {
|
|
681
|
+
let data;
|
|
682
|
+
try {
|
|
683
|
+
data = matter3(text).data;
|
|
684
|
+
} catch (error) {
|
|
685
|
+
const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
|
|
686
|
+
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
687
|
+
return void 0;
|
|
688
|
+
}
|
|
689
|
+
const result = Schemas.Journey.safeParse(data);
|
|
690
|
+
if (result.success) return result.data;
|
|
691
|
+
for (const issue of result.error.issues) {
|
|
692
|
+
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
693
|
+
errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
|
|
694
|
+
}
|
|
695
|
+
return void 0;
|
|
696
|
+
}
|
|
697
|
+
function newNode(title, level, line) {
|
|
698
|
+
return {
|
|
699
|
+
title,
|
|
700
|
+
level,
|
|
701
|
+
line,
|
|
702
|
+
isLeaf: true,
|
|
703
|
+
fieldLines: {},
|
|
704
|
+
anchors: [],
|
|
705
|
+
acceptance: [],
|
|
706
|
+
requires: [],
|
|
707
|
+
creates: [],
|
|
708
|
+
unknownFields: []
|
|
709
|
+
};
|
|
710
|
+
}
|
|
711
|
+
function parseFields(node, lines, from, to, errors) {
|
|
712
|
+
let lastKey;
|
|
713
|
+
for (let i = from; i < to; i++) {
|
|
714
|
+
const line = lines[i] ?? "";
|
|
715
|
+
if (line.trim() === "") continue;
|
|
716
|
+
const lineNo = i + 1;
|
|
717
|
+
const field = FIELD_RE.exec(line.trimEnd());
|
|
718
|
+
if (field?.[1] !== void 0) {
|
|
719
|
+
const key = field[1];
|
|
720
|
+
const value = (field[2] ?? "").trim();
|
|
721
|
+
lastKey = key;
|
|
722
|
+
if (!NODE_FIELDS.includes(key)) {
|
|
723
|
+
node.unknownFields.push({ key, line: lineNo });
|
|
724
|
+
continue;
|
|
725
|
+
}
|
|
726
|
+
const known = key;
|
|
727
|
+
node.fieldLines[known] = lineNo;
|
|
728
|
+
if (known === "status") {
|
|
729
|
+
if (JOURNEY_STATUSES.includes(value)) {
|
|
730
|
+
node.status = value;
|
|
731
|
+
} else {
|
|
732
|
+
errors.push({
|
|
733
|
+
line: lineNo,
|
|
734
|
+
message: `invalid status \`${value}\` (expected ${JOURNEY_STATUSES.join(" | ")})`
|
|
735
|
+
});
|
|
736
|
+
}
|
|
737
|
+
} else if (known === "spec") {
|
|
738
|
+
node.spec = value;
|
|
739
|
+
} else if (known === "acceptance") {
|
|
740
|
+
if (value) node.acceptance.push(value);
|
|
741
|
+
} else {
|
|
742
|
+
node[known] = splitList(value);
|
|
743
|
+
}
|
|
744
|
+
continue;
|
|
745
|
+
}
|
|
746
|
+
const item = LIST_ITEM_RE.exec(line);
|
|
747
|
+
if (lastKey === "acceptance" && item) {
|
|
748
|
+
const text = (item[1] ?? "").trim();
|
|
749
|
+
if (text) node.acceptance.push(text);
|
|
750
|
+
continue;
|
|
751
|
+
}
|
|
752
|
+
return;
|
|
753
|
+
}
|
|
754
|
+
}
|
|
755
|
+
function parseJourney(relPath, text) {
|
|
756
|
+
const errors = [];
|
|
757
|
+
const meta = parseFrontmatter2(text, errors);
|
|
758
|
+
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
759
|
+
const start = bodyStart(lines);
|
|
760
|
+
const headings = [];
|
|
761
|
+
for (let i = start; i < lines.length; i++) {
|
|
762
|
+
const h = parseHeading(lines[i] ?? "");
|
|
763
|
+
if (h) headings.push({ index: i, ...h });
|
|
764
|
+
}
|
|
765
|
+
const h1 = headings.find((h) => h.depth === 1);
|
|
766
|
+
let story;
|
|
767
|
+
if (h1) {
|
|
768
|
+
const paragraph = [];
|
|
769
|
+
for (let i = h1.index + 1; i < lines.length; i++) {
|
|
770
|
+
const line = lines[i] ?? "";
|
|
771
|
+
if (line.trim() === "") {
|
|
772
|
+
if (paragraph.length) break;
|
|
773
|
+
continue;
|
|
774
|
+
}
|
|
775
|
+
if (line === MASKED_LINE || parseHeading(line)) break;
|
|
776
|
+
paragraph.push(line.trim());
|
|
777
|
+
}
|
|
778
|
+
if (paragraph.length) story = paragraph.join(" ");
|
|
779
|
+
}
|
|
780
|
+
const nodes = [];
|
|
781
|
+
const stack = [];
|
|
782
|
+
for (const [k, h] of headings.entries()) {
|
|
783
|
+
if (h.depth < 2) continue;
|
|
784
|
+
const node = newNode(h.title, h.depth - 1, h.index + 1);
|
|
785
|
+
while (stack.length) {
|
|
786
|
+
const top = nodes[stack[stack.length - 1]];
|
|
787
|
+
if (top && top.level < node.level) break;
|
|
788
|
+
stack.pop();
|
|
789
|
+
}
|
|
790
|
+
const parentIndex = stack[stack.length - 1];
|
|
791
|
+
if (parentIndex !== void 0) {
|
|
792
|
+
node.parent = parentIndex;
|
|
793
|
+
const parent = nodes[parentIndex];
|
|
794
|
+
if (parent) parent.isLeaf = false;
|
|
795
|
+
}
|
|
796
|
+
const next = headings[k + 1];
|
|
797
|
+
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
798
|
+
const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
|
|
799
|
+
node.effectiveStatus = node.status ?? inherited;
|
|
800
|
+
stack.push(nodes.length);
|
|
801
|
+
nodes.push(node);
|
|
802
|
+
}
|
|
803
|
+
const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
|
|
804
|
+
return { ...meta ? { meta } : {}, title, ...story ? { story } : {}, nodes, errors };
|
|
805
|
+
}
|
|
806
|
+
function listJourneyFiles(targetDir) {
|
|
807
|
+
const dir = join6(targetDir, JOURNEYS_DIR);
|
|
808
|
+
if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
|
|
809
|
+
return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
|
|
810
|
+
}
|
|
811
|
+
function readJourneys(targetDir) {
|
|
812
|
+
return listJourneyFiles(targetDir).map((file) => {
|
|
813
|
+
const path = `${JOURNEYS_DIR}/${file}`;
|
|
814
|
+
const text = readFileSync5(join6(targetDir, path), "utf8");
|
|
815
|
+
return { path, file, ...parseJourney(path, text) };
|
|
816
|
+
});
|
|
817
|
+
}
|
|
818
|
+
function loadJourneys(targetDir) {
|
|
819
|
+
const journeys = readJourneys(targetDir);
|
|
820
|
+
const problems = journeys.flatMap(
|
|
821
|
+
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
822
|
+
);
|
|
823
|
+
if (problems.length) {
|
|
824
|
+
throw new Error(
|
|
825
|
+
`invalid journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
|
|
826
|
+
${problems.join("\n")}`
|
|
827
|
+
);
|
|
828
|
+
}
|
|
829
|
+
return journeys;
|
|
830
|
+
}
|
|
831
|
+
|
|
612
832
|
// src/renderers/common.ts
|
|
613
833
|
import { stringify as yamlStringify } from "yaml";
|
|
614
834
|
function checkSkillCapabilities(skill, engine) {
|
|
@@ -666,12 +886,15 @@ function frontmatterDataForCmd(cmd) {
|
|
|
666
886
|
return data;
|
|
667
887
|
}
|
|
668
888
|
function buildUmbrellaBody(extras) {
|
|
669
|
-
const
|
|
670
|
-
|
|
671
|
-
|
|
889
|
+
const triggersBySkill = /* @__PURE__ */ new Map();
|
|
890
|
+
for (const c of extras.availableCommands) {
|
|
891
|
+
const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
|
|
892
|
+
triggers.push(c.meta.trigger);
|
|
893
|
+
triggersBySkill.set(c.meta.invokes_skill, triggers);
|
|
894
|
+
}
|
|
672
895
|
const skillLines = extras.availableSkills.map((s) => {
|
|
673
|
-
const
|
|
674
|
-
const label =
|
|
896
|
+
const triggers = triggersBySkill.get(s.meta.id) ?? [];
|
|
897
|
+
const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
|
|
675
898
|
return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
|
|
676
899
|
});
|
|
677
900
|
const sections = [
|
|
@@ -683,19 +906,25 @@ function buildUmbrellaBody(extras) {
|
|
|
683
906
|
"",
|
|
684
907
|
"- `README.md` \u2014 pitch, quick start, scripts. Entry point.",
|
|
685
908
|
"- `docs/spec/<subsystem>.md` \u2014 *what* and *why* (tech-agnostic).",
|
|
686
|
-
"- `docs/handbook/<feature>.md` \u2014
|
|
909
|
+
"- `docs/handbook/<feature>.md` \u2014 what the code does not say: entry points, traps, settings outside the repo, manual procedures.",
|
|
687
910
|
"- `docs/decisions/<slug>.md` \u2014 ADRs: structural choices and rejected alternatives.",
|
|
688
|
-
"- `docs/tests/integration-tests.md` & `e2e-tests.md` \u2014
|
|
911
|
+
"- `docs/tests/integration-tests.md` & `e2e-tests.md` \u2014 test scope, stack, conventions, known gaps.",
|
|
689
912
|
"- `docs/workflow/coding-workflow.md` \u2014 CI, branches, PR, release. How this team works: follow it.",
|
|
690
913
|
...extras.hasProjectSkills ? ["- `docs/skills/*.skill.md` \u2014 the project's domain skills."] : [],
|
|
691
914
|
...extras.hasQualityDoc ? [
|
|
692
915
|
"- `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."
|
|
693
916
|
] : [],
|
|
917
|
+
...extras.hasJourneys ? [
|
|
918
|
+
"- `docs/journeys/<journey>.md` \u2014 user intentions and journeys, anchored to the code. `docs/journeys/README.md` is the generated index."
|
|
919
|
+
] : [],
|
|
694
920
|
"",
|
|
695
921
|
"## Doc-first",
|
|
696
922
|
"",
|
|
697
923
|
"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.",
|
|
698
924
|
"",
|
|
925
|
+
...extras.hasJourneys ? [
|
|
926
|
+
"- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
|
|
927
|
+
] : [],
|
|
699
928
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
700
929
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
701
930
|
"- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
|
|
@@ -824,6 +1053,23 @@ function getRenderer(engine) {
|
|
|
824
1053
|
return RENDERERS[engine];
|
|
825
1054
|
}
|
|
826
1055
|
|
|
1056
|
+
// src/renderers/journeys-index.ts
|
|
1057
|
+
var INTRO = "User intentions and journeys of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/journeys/*.md`: edit the journeys, not this file, then run `npx @vaubaan/harness update .`.";
|
|
1058
|
+
function buildJourneysIndex(journeys) {
|
|
1059
|
+
const lines = ["# Journeys", "", INTRO, ""];
|
|
1060
|
+
const sorted = [...journeys].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
1061
|
+
for (const journey of sorted) {
|
|
1062
|
+
const status = journey.meta?.status ?? "proposed";
|
|
1063
|
+
const actors = journey.meta?.actors.join(", ") ?? "";
|
|
1064
|
+
lines.push(`- [${journey.title}](./${journey.file}) \u2014 ${status} \xB7 ${actors}`);
|
|
1065
|
+
for (const node of journey.nodes) {
|
|
1066
|
+
lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
|
|
1067
|
+
}
|
|
1068
|
+
}
|
|
1069
|
+
return `${lines.join("\n")}
|
|
1070
|
+
`;
|
|
1071
|
+
}
|
|
1072
|
+
|
|
827
1073
|
// src/render.ts
|
|
828
1074
|
var RenderError = class extends Error {
|
|
829
1075
|
constructor(message) {
|
|
@@ -893,12 +1139,16 @@ function render(input) {
|
|
|
893
1139
|
availableSkills: Array.from(exposedSkills.values()),
|
|
894
1140
|
availableCommands: Array.from(exposedCmds.values()),
|
|
895
1141
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
896
|
-
hasQualityDoc: input.hasQualityDoc === true
|
|
1142
|
+
hasQualityDoc: input.hasQualityDoc === true,
|
|
1143
|
+
hasJourneys: (input.journeys?.length ?? 0) > 0
|
|
897
1144
|
});
|
|
898
1145
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
899
1146
|
if (engines.includes("claude-code")) {
|
|
900
1147
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
901
1148
|
}
|
|
1149
|
+
if (input.journeys && input.journeys.length > 0) {
|
|
1150
|
+
files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
|
|
1151
|
+
}
|
|
902
1152
|
return { files, warnings };
|
|
903
1153
|
}
|
|
904
1154
|
|
|
@@ -930,7 +1180,8 @@ function planInit(args) {
|
|
|
930
1180
|
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
931
1181
|
const projectSkills = loadProjectSkills(args.targetDir);
|
|
932
1182
|
const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
|
|
933
|
-
const
|
|
1183
|
+
const journeys = loadJourneys(args.targetDir);
|
|
1184
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, journeys });
|
|
934
1185
|
return { engines, output };
|
|
935
1186
|
}
|
|
936
1187
|
|
|
@@ -977,7 +1228,7 @@ var generatedFresh = {
|
|
|
977
1228
|
const full = join8(repoRoot, file.path);
|
|
978
1229
|
if (!existsSync7(full)) {
|
|
979
1230
|
issues.push(issue(file.path, `generated file is missing; ${FIX}`));
|
|
980
|
-
} else if (
|
|
1231
|
+
} else if (readFileSync6(full, "utf8") !== file.content) {
|
|
981
1232
|
issues.push(
|
|
982
1233
|
issue(
|
|
983
1234
|
file.path,
|
|
@@ -1008,7 +1259,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
|
1008
1259
|
".codex/",
|
|
1009
1260
|
".agents/",
|
|
1010
1261
|
".opencode/",
|
|
1011
|
-
".harness-manifest.json"
|
|
1262
|
+
".harness-manifest.json",
|
|
1263
|
+
"docs/journeys/README.md"
|
|
1012
1264
|
];
|
|
1013
1265
|
function gitignoreEntries(text) {
|
|
1014
1266
|
const entries = /* @__PURE__ */ new Set();
|
|
@@ -1067,9 +1319,211 @@ var gitignoreHarness = {
|
|
|
1067
1319
|
}
|
|
1068
1320
|
};
|
|
1069
1321
|
|
|
1322
|
+
// src/linters/journey-anchors.ts
|
|
1323
|
+
var journeyAnchors = {
|
|
1324
|
+
id: "lint:journey-anchors",
|
|
1325
|
+
pillars: ["journeys"],
|
|
1326
|
+
defaultSeverity: "error",
|
|
1327
|
+
suggestedSkills: ["/journey"],
|
|
1328
|
+
run(repoRoot) {
|
|
1329
|
+
const issues = [];
|
|
1330
|
+
for (const journey of readJourneys(repoRoot)) {
|
|
1331
|
+
for (const node of journey.nodes) {
|
|
1332
|
+
if (node.effectiveStatus === "deprecated") continue;
|
|
1333
|
+
for (const anchor of node.anchors) {
|
|
1334
|
+
if (trackedPathExists(repoRoot, anchor)) continue;
|
|
1335
|
+
issues.push({
|
|
1336
|
+
linter: this.id,
|
|
1337
|
+
severity: "error",
|
|
1338
|
+
file: journey.path,
|
|
1339
|
+
line: node.line,
|
|
1340
|
+
message: `"${node.title}": anchor matches no file: ${anchor}`
|
|
1341
|
+
});
|
|
1342
|
+
}
|
|
1343
|
+
}
|
|
1344
|
+
}
|
|
1345
|
+
return issues;
|
|
1346
|
+
}
|
|
1347
|
+
};
|
|
1348
|
+
|
|
1349
|
+
// src/linters/journey-graph.ts
|
|
1350
|
+
var journeyGraph = {
|
|
1351
|
+
id: "lint:journey-graph",
|
|
1352
|
+
pillars: ["journeys"],
|
|
1353
|
+
defaultSeverity: "warning",
|
|
1354
|
+
suggestedSkills: ["/journey"],
|
|
1355
|
+
run(repoRoot) {
|
|
1356
|
+
const journeys = readJourneys(repoRoot);
|
|
1357
|
+
const leaves = journeys.flatMap(
|
|
1358
|
+
(journey) => journey.nodes.filter((node) => node.isLeaf).map((node) => ({ journey, node }))
|
|
1359
|
+
);
|
|
1360
|
+
const created = new Set(leaves.flatMap(({ node }) => node.creates));
|
|
1361
|
+
const issues = [];
|
|
1362
|
+
for (const { journey, node } of leaves) {
|
|
1363
|
+
for (const entity of node.requires) {
|
|
1364
|
+
if (created.has(entity)) continue;
|
|
1365
|
+
issues.push({
|
|
1366
|
+
linter: this.id,
|
|
1367
|
+
severity: "warning",
|
|
1368
|
+
file: journey.path,
|
|
1369
|
+
line: node.line,
|
|
1370
|
+
message: `"${node.title}": entity \`${entity}\` is required here but no leaf creates it`
|
|
1371
|
+
});
|
|
1372
|
+
}
|
|
1373
|
+
}
|
|
1374
|
+
return issues;
|
|
1375
|
+
}
|
|
1376
|
+
};
|
|
1377
|
+
|
|
1378
|
+
// src/linters/journey-util.ts
|
|
1379
|
+
import { posix } from "path";
|
|
1380
|
+
function journeySpecs(meta) {
|
|
1381
|
+
if (!meta) return [];
|
|
1382
|
+
return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
|
|
1383
|
+
}
|
|
1384
|
+
function resolveSpecPath(journeyPath, spec) {
|
|
1385
|
+
const withoutFragment = spec.split("#")[0] ?? "";
|
|
1386
|
+
return posix.normalize(posix.join(posix.dirname(journeyPath), withoutFragment));
|
|
1387
|
+
}
|
|
1388
|
+
|
|
1389
|
+
// src/linters/journey-schema.ts
|
|
1390
|
+
var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
|
|
1391
|
+
var journeySchema = {
|
|
1392
|
+
id: "lint:journey-schema",
|
|
1393
|
+
pillars: ["journeys"],
|
|
1394
|
+
defaultSeverity: "error",
|
|
1395
|
+
suggestedSkills: ["/journey"],
|
|
1396
|
+
run(repoRoot) {
|
|
1397
|
+
const issues = [];
|
|
1398
|
+
for (const journey of readJourneys(repoRoot)) {
|
|
1399
|
+
const report = (message, line) => {
|
|
1400
|
+
issues.push({
|
|
1401
|
+
linter: this.id,
|
|
1402
|
+
severity: "error",
|
|
1403
|
+
file: journey.path,
|
|
1404
|
+
...line !== void 0 ? { line } : {},
|
|
1405
|
+
message
|
|
1406
|
+
});
|
|
1407
|
+
};
|
|
1408
|
+
for (const error of journey.errors) report(error.message, error.line);
|
|
1409
|
+
for (const spec of journeySpecs(journey.meta)) {
|
|
1410
|
+
if (!fileExists(repoRoot, resolveSpecPath(journey.path, spec))) {
|
|
1411
|
+
report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
|
|
1412
|
+
}
|
|
1413
|
+
}
|
|
1414
|
+
for (const node of journey.nodes) {
|
|
1415
|
+
const at = (message) => report(`"${node.title}": ${message}`, node.line);
|
|
1416
|
+
for (const { key, line } of node.unknownFields) {
|
|
1417
|
+
report(
|
|
1418
|
+
DERIVABLE_FIELDS.has(key) ? `"${node.title}": \`${key}:\` is derivable, never declared` : `"${node.title}": unknown field \`${key}:\``,
|
|
1419
|
+
line
|
|
1420
|
+
);
|
|
1421
|
+
}
|
|
1422
|
+
if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(journey.path, node.spec))) {
|
|
1423
|
+
report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
|
|
1424
|
+
}
|
|
1425
|
+
if (!node.isLeaf) {
|
|
1426
|
+
for (const field of LEAF_FIELDS) {
|
|
1427
|
+
const line = node.fieldLines[field];
|
|
1428
|
+
if (line !== void 0) {
|
|
1429
|
+
report(
|
|
1430
|
+
`"${node.title}": \`${field}:\` is a leaf field, this node has children`,
|
|
1431
|
+
line
|
|
1432
|
+
);
|
|
1433
|
+
}
|
|
1434
|
+
}
|
|
1435
|
+
continue;
|
|
1436
|
+
}
|
|
1437
|
+
if (Object.keys(node.fieldLines).length === 0) {
|
|
1438
|
+
at("a leaf carries at least one field");
|
|
1439
|
+
continue;
|
|
1440
|
+
}
|
|
1441
|
+
if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
|
|
1442
|
+
at("an `implemented` leaf needs `anchors:`");
|
|
1443
|
+
}
|
|
1444
|
+
if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
|
|
1445
|
+
at("a `proposed` leaf needs `acceptance:` with at least one `- ` item");
|
|
1446
|
+
}
|
|
1447
|
+
}
|
|
1448
|
+
}
|
|
1449
|
+
return issues;
|
|
1450
|
+
}
|
|
1451
|
+
};
|
|
1452
|
+
|
|
1453
|
+
// src/linters/journey-vocabulary.ts
|
|
1454
|
+
var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
|
|
1455
|
+
var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
|
|
1456
|
+
function entitySlug(term) {
|
|
1457
|
+
return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
1458
|
+
}
|
|
1459
|
+
function vocabularyOf(specText) {
|
|
1460
|
+
const lines = maskFencedCode(specText.split(/\r?\n/));
|
|
1461
|
+
let depth;
|
|
1462
|
+
let terms;
|
|
1463
|
+
for (const line of lines) {
|
|
1464
|
+
const heading = parseHeading(line);
|
|
1465
|
+
if (depth !== void 0) {
|
|
1466
|
+
if (heading && heading.depth <= depth) break;
|
|
1467
|
+
const term = TERM.exec(line)?.[1];
|
|
1468
|
+
if (term) terms?.add(entitySlug(term));
|
|
1469
|
+
continue;
|
|
1470
|
+
}
|
|
1471
|
+
if (heading && VOCABULARY_HEADING.test(line)) {
|
|
1472
|
+
depth = heading.depth;
|
|
1473
|
+
terms = /* @__PURE__ */ new Set();
|
|
1474
|
+
}
|
|
1475
|
+
}
|
|
1476
|
+
return terms;
|
|
1477
|
+
}
|
|
1478
|
+
var journeyVocabulary = {
|
|
1479
|
+
id: "lint:journey-vocabulary",
|
|
1480
|
+
pillars: ["journeys"],
|
|
1481
|
+
defaultSeverity: "error",
|
|
1482
|
+
suggestedSkills: ["/spec"],
|
|
1483
|
+
run(repoRoot) {
|
|
1484
|
+
const issues = [];
|
|
1485
|
+
for (const journey of readJourneys(repoRoot)) {
|
|
1486
|
+
const used = journey.nodes.flatMap(
|
|
1487
|
+
(node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
|
|
1488
|
+
);
|
|
1489
|
+
if (used.length === 0) continue;
|
|
1490
|
+
const specs = journeySpecs(journey.meta).map((spec) => resolveSpecPath(journey.path, spec)).filter((path) => fileExists(repoRoot, path));
|
|
1491
|
+
if (specs.length === 0) continue;
|
|
1492
|
+
const entities = /* @__PURE__ */ new Set();
|
|
1493
|
+
let hasVocabulary = false;
|
|
1494
|
+
for (const spec of specs) {
|
|
1495
|
+
const terms = vocabularyOf(readText(repoRoot, spec));
|
|
1496
|
+
if (!terms) continue;
|
|
1497
|
+
hasVocabulary = true;
|
|
1498
|
+
for (const term of terms) entities.add(term);
|
|
1499
|
+
}
|
|
1500
|
+
if (!hasVocabulary) {
|
|
1501
|
+
issues.push({
|
|
1502
|
+
linter: this.id,
|
|
1503
|
+
severity: "warning",
|
|
1504
|
+
file: journey.path,
|
|
1505
|
+
message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
|
|
1506
|
+
});
|
|
1507
|
+
continue;
|
|
1508
|
+
}
|
|
1509
|
+
for (const { entity, node } of used) {
|
|
1510
|
+
if (entities.has(entity)) continue;
|
|
1511
|
+
issues.push({
|
|
1512
|
+
linter: this.id,
|
|
1513
|
+
severity: "error",
|
|
1514
|
+
file: journey.path,
|
|
1515
|
+
line: node.line,
|
|
1516
|
+
message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
|
|
1517
|
+
});
|
|
1518
|
+
}
|
|
1519
|
+
}
|
|
1520
|
+
return issues;
|
|
1521
|
+
}
|
|
1522
|
+
};
|
|
1523
|
+
|
|
1070
1524
|
// src/linters/orphan-decisions.ts
|
|
1071
|
-
import { basename as
|
|
1072
|
-
import
|
|
1525
|
+
import { basename as basename3 } from "path";
|
|
1526
|
+
import fg4 from "fast-glob";
|
|
1073
1527
|
var orphanDecisions = {
|
|
1074
1528
|
id: "lint:orphan-decisions",
|
|
1075
1529
|
pillars: ["decisions"],
|
|
@@ -1080,7 +1534,7 @@ var orphanDecisions = {
|
|
|
1080
1534
|
const issues = [];
|
|
1081
1535
|
const adrs = listMarkdown(repoRoot, "docs/decisions");
|
|
1082
1536
|
if (adrs.length === 0) return issues;
|
|
1083
|
-
const otherDocs =
|
|
1537
|
+
const otherDocs = fg4.sync("**/*.md", {
|
|
1084
1538
|
cwd: repoRoot,
|
|
1085
1539
|
absolute: false,
|
|
1086
1540
|
ignore: [
|
|
@@ -1097,7 +1551,7 @@ var orphanDecisions = {
|
|
|
1097
1551
|
});
|
|
1098
1552
|
const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
|
|
1099
1553
|
for (const adr of adrs) {
|
|
1100
|
-
const filename =
|
|
1554
|
+
const filename = basename3(adr);
|
|
1101
1555
|
const stem = filename.replace(/\.md$/, "");
|
|
1102
1556
|
const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
|
|
1103
1557
|
if (!referenced) {
|
|
@@ -1273,33 +1727,42 @@ var specTechAgnostic = {
|
|
|
1273
1727
|
};
|
|
1274
1728
|
|
|
1275
1729
|
// src/linters/tracks-drift.ts
|
|
1276
|
-
import
|
|
1730
|
+
import fg5 from "fast-glob";
|
|
1277
1731
|
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
1732
|
+
var JOURNEYS_DIR2 = "docs/journeys";
|
|
1278
1733
|
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
1279
1734
|
function expandGlob(repoRoot, pattern) {
|
|
1280
1735
|
if (pattern.includes("*")) {
|
|
1281
|
-
return
|
|
1736
|
+
return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
|
|
1282
1737
|
}
|
|
1283
1738
|
return [pattern];
|
|
1284
1739
|
}
|
|
1740
|
+
function trackedPaths(dir, file, text, data) {
|
|
1741
|
+
if (dir === JOURNEYS_DIR2) {
|
|
1742
|
+
const anchors = parseJourney(file, text).nodes.flatMap((node) => node.anchors);
|
|
1743
|
+
return anchors.length > 0 ? [...new Set(anchors)] : void 0;
|
|
1744
|
+
}
|
|
1745
|
+
return Array.isArray(data.tracks) ? data.tracks : void 0;
|
|
1746
|
+
}
|
|
1285
1747
|
var tracksDrift = {
|
|
1286
1748
|
id: "lint:tracks-drift",
|
|
1287
|
-
pillars: ["handbook", "tests", "workflow"],
|
|
1749
|
+
pillars: ["handbook", "tests", "workflow", "journeys"],
|
|
1288
1750
|
defaultSeverity: "warning",
|
|
1289
1751
|
suggestedSkills: ["/drift", "/handbook"],
|
|
1290
1752
|
run(repoRoot) {
|
|
1291
1753
|
const issues = [];
|
|
1292
|
-
for (const dir of TRACKED_DIRS2) {
|
|
1754
|
+
for (const dir of [...TRACKED_DIRS2, JOURNEYS_DIR2]) {
|
|
1293
1755
|
const files = listMarkdown(repoRoot, dir);
|
|
1294
1756
|
for (const f of files) {
|
|
1295
1757
|
const text = readText(repoRoot, f);
|
|
1296
1758
|
const { data } = parseFrontmatter(text);
|
|
1297
|
-
|
|
1759
|
+
const tracks = trackedPaths(dir, f, text, data);
|
|
1760
|
+
if (!tracks) continue;
|
|
1298
1761
|
const docCommit = gitLastCommitForPath(repoRoot, f);
|
|
1299
1762
|
if (!docCommit) continue;
|
|
1300
1763
|
const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
|
|
1301
1764
|
let driftCount = 0;
|
|
1302
|
-
for (const tracked of
|
|
1765
|
+
for (const tracked of tracks) {
|
|
1303
1766
|
if (typeof tracked !== "string") continue;
|
|
1304
1767
|
const targets = expandGlob(repoRoot, tracked);
|
|
1305
1768
|
for (const t of targets.length > 0 ? targets : [tracked]) {
|
|
@@ -1336,6 +1799,10 @@ var ALL_LINTERS = [
|
|
|
1336
1799
|
orphanDecisions,
|
|
1337
1800
|
gitignoreHarness,
|
|
1338
1801
|
qualitySchema,
|
|
1802
|
+
journeySchema,
|
|
1803
|
+
journeyAnchors,
|
|
1804
|
+
journeyVocabulary,
|
|
1805
|
+
journeyGraph,
|
|
1339
1806
|
generatedFresh
|
|
1340
1807
|
];
|
|
1341
1808
|
function runLinters(repoRoot, opts = {}) {
|
|
@@ -1391,7 +1858,7 @@ function formatReportText(report) {
|
|
|
1391
1858
|
}
|
|
1392
1859
|
|
|
1393
1860
|
// src/cli/check.ts
|
|
1394
|
-
import { existsSync as existsSync8, readFileSync as
|
|
1861
|
+
import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
|
|
1395
1862
|
import { join as join9 } from "path";
|
|
1396
1863
|
var REQUIRED_DIRS2 = [
|
|
1397
1864
|
"docs/spec",
|
|
@@ -1414,7 +1881,7 @@ function checkCommand(repoRoot) {
|
|
|
1414
1881
|
if (!existsSync8(gitignorePath)) {
|
|
1415
1882
|
issues.push(".gitignore missing at repo root");
|
|
1416
1883
|
} else {
|
|
1417
|
-
const text =
|
|
1884
|
+
const text = readFileSync7(gitignorePath, "utf8");
|
|
1418
1885
|
for (const entry of missingGitignoreEntries(text)) {
|
|
1419
1886
|
issues.push(`.gitignore missing entry: ${entry}`);
|
|
1420
1887
|
}
|
|
@@ -1430,7 +1897,7 @@ import { existsSync as existsSync12, mkdirSync as mkdirSync2, rmSync, writeFileS
|
|
|
1430
1897
|
import { dirname as dirname7, join as join14, resolve as resolve8 } from "path";
|
|
1431
1898
|
|
|
1432
1899
|
// src/cli/uninstall.ts
|
|
1433
|
-
import { existsSync as existsSync9, readFileSync as
|
|
1900
|
+
import { existsSync as existsSync9, readFileSync as readFileSync8, readdirSync as readdirSync2, rmdirSync, unlinkSync } from "fs";
|
|
1434
1901
|
import { dirname as dirname4, join as join10, relative as relative2, resolve as resolve5 } from "path";
|
|
1435
1902
|
function uninstallCommand(args) {
|
|
1436
1903
|
const root = resolve5(args.targetDir);
|
|
@@ -1447,7 +1914,7 @@ function uninstallCommand(args) {
|
|
|
1447
1914
|
const modified = files.filter((file) => {
|
|
1448
1915
|
const hash = manifest.fileHashes?.[file];
|
|
1449
1916
|
const full = join10(root, file);
|
|
1450
|
-
return hash !== void 0 && existsSync9(full) && hashContent(
|
|
1917
|
+
return hash !== void 0 && existsSync9(full) && hashContent(readFileSync8(full)) !== hash;
|
|
1451
1918
|
});
|
|
1452
1919
|
const ownedFiles = files.filter((file) => !modified.includes(file));
|
|
1453
1920
|
const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
|
|
@@ -1489,7 +1956,7 @@ function pruneEmptyDirs(root, leaves) {
|
|
|
1489
1956
|
const sorted = [...candidates].sort((a, b) => b.length - a.length);
|
|
1490
1957
|
for (const dir of sorted) {
|
|
1491
1958
|
if (!existsSync9(dir)) continue;
|
|
1492
|
-
if (
|
|
1959
|
+
if (readdirSync2(dir).length > 0) continue;
|
|
1493
1960
|
rmdirSync(dir);
|
|
1494
1961
|
pruned.push(relative2(root, dir));
|
|
1495
1962
|
}
|
|
@@ -1505,22 +1972,22 @@ import {
|
|
|
1505
1972
|
lstatSync as lstatSync2,
|
|
1506
1973
|
mkdirSync,
|
|
1507
1974
|
openSync,
|
|
1508
|
-
readFileSync as
|
|
1509
|
-
readdirSync as
|
|
1975
|
+
readFileSync as readFileSync9,
|
|
1976
|
+
readdirSync as readdirSync3,
|
|
1510
1977
|
realpathSync as realpathSync2,
|
|
1511
1978
|
rmdirSync as rmdirSync2,
|
|
1512
1979
|
unlinkSync as unlinkSync2,
|
|
1513
1980
|
writeFileSync as writeFileSync2
|
|
1514
1981
|
} from "fs";
|
|
1515
1982
|
import { homedir } from "os";
|
|
1516
|
-
import { basename as
|
|
1983
|
+
import { basename as basename4, dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative3, resolve as resolve6, sep } from "path";
|
|
1517
1984
|
var MANIFEST_PATH = ".harness-manifest.json";
|
|
1518
1985
|
var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
|
|
1519
1986
|
function canonicalRoot(root) {
|
|
1520
1987
|
let ancestor = resolve6(root);
|
|
1521
1988
|
const missing = [];
|
|
1522
1989
|
while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
|
|
1523
|
-
missing.unshift(
|
|
1990
|
+
missing.unshift(basename4(ancestor));
|
|
1524
1991
|
ancestor = dirname5(ancestor);
|
|
1525
1992
|
}
|
|
1526
1993
|
return join11(realpathSync2(ancestor), ...missing);
|
|
@@ -1580,7 +2047,7 @@ function saveSnapshot(root, paths, backup) {
|
|
|
1580
2047
|
entries.push({ path, exists: false });
|
|
1581
2048
|
continue;
|
|
1582
2049
|
}
|
|
1583
|
-
const content =
|
|
2050
|
+
const content = readFileSync9(full);
|
|
1584
2051
|
writeBackupFile(join11(backup, "files", path), content);
|
|
1585
2052
|
entries.push({
|
|
1586
2053
|
path,
|
|
@@ -1611,8 +2078,8 @@ function rollback(root, backup, entries, touched, createdDirectories) {
|
|
|
1611
2078
|
if (current) unlinkSync2(full);
|
|
1612
2079
|
continue;
|
|
1613
2080
|
}
|
|
1614
|
-
const original =
|
|
1615
|
-
if (!current || !
|
|
2081
|
+
const original = readFileSync9(join11(backup, "files", path));
|
|
2082
|
+
if (!current || !readFileSync9(full).equals(original)) {
|
|
1616
2083
|
if (current) unlinkSync2(full);
|
|
1617
2084
|
writeFileSync2(full, original, { mode: 384 });
|
|
1618
2085
|
}
|
|
@@ -1623,7 +2090,7 @@ function rollback(root, backup, entries, touched, createdDirectories) {
|
|
|
1623
2090
|
}
|
|
1624
2091
|
for (const directory of [...createdDirectories].reverse()) {
|
|
1625
2092
|
try {
|
|
1626
|
-
if (
|
|
2093
|
+
if (readdirSync3(directory).length === 0) rmdirSync2(directory);
|
|
1627
2094
|
} catch (error) {
|
|
1628
2095
|
errors.push(`${directory}: ${errorMessage(error)}`);
|
|
1629
2096
|
}
|
|
@@ -1678,12 +2145,12 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
1678
2145
|
}
|
|
1679
2146
|
|
|
1680
2147
|
// src/cli/update.ts
|
|
1681
|
-
import { existsSync as existsSync11, readFileSync as
|
|
2148
|
+
import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
|
|
1682
2149
|
import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
|
|
1683
2150
|
import { isDeepStrictEqual } from "util";
|
|
1684
2151
|
|
|
1685
2152
|
// src/cli/update-manifest.ts
|
|
1686
|
-
import { existsSync as existsSync10, readFileSync as
|
|
2153
|
+
import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
|
|
1687
2154
|
import { join as join12 } from "path";
|
|
1688
2155
|
import { z as z4 } from "zod";
|
|
1689
2156
|
var EngineSchema = z4.enum(ENGINES);
|
|
@@ -1699,7 +2166,7 @@ function readUpdateInstallation(root) {
|
|
|
1699
2166
|
if (!existsSync10(join12(root, MANIFEST_FILENAME))) {
|
|
1700
2167
|
throw new Error("no harness manifest found; use init for a new installation");
|
|
1701
2168
|
}
|
|
1702
|
-
const raw = JSON.parse(
|
|
2169
|
+
const raw = JSON.parse(readFileSync10(join12(root, MANIFEST_FILENAME), "utf8"));
|
|
1703
2170
|
const sourceVersion = String(raw?.version);
|
|
1704
2171
|
let manifest;
|
|
1705
2172
|
if (["1", "2", "3"].includes(sourceVersion)) {
|
|
@@ -1724,7 +2191,7 @@ function readUpdateInstallation(root) {
|
|
|
1724
2191
|
var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
|
|
1725
2192
|
var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
|
|
1726
2193
|
function currentContent(root, path) {
|
|
1727
|
-
return existsSync11(join13(root, path)) ?
|
|
2194
|
+
return existsSync11(join13(root, path)) ? readFileSync11(join13(root, path), "utf8") : void 0;
|
|
1728
2195
|
}
|
|
1729
2196
|
function checkArtifactConflicts(root, previous, writes, removals) {
|
|
1730
2197
|
const desired = new Map(writes.map((file) => [file.path, file.content]));
|
|
@@ -1786,7 +2253,7 @@ function planInstallation(args, settings) {
|
|
|
1786
2253
|
const disablePath = join13(overridesDir, ".harness-overrides", "disable.yaml");
|
|
1787
2254
|
if (existsSync11(disablePath)) {
|
|
1788
2255
|
try {
|
|
1789
|
-
DisableYamlSchema.parse(parseYAML(
|
|
2256
|
+
DisableYamlSchema.parse(parseYAML(readFileSync11(disablePath, "utf8")));
|
|
1790
2257
|
} catch {
|
|
1791
2258
|
throw new Error(`invalid override selection: ${disablePath}`);
|
|
1792
2259
|
}
|
|
@@ -2007,7 +2474,7 @@ program.command("check").description("Verify repo layout: doc pillars present an
|
|
|
2007
2474
|
});
|
|
2008
2475
|
program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
|
|
2009
2476
|
"--pillar <pillar>",
|
|
2010
|
-
"filter by pillar (spec, decisions, handbook, tests, workflow, quality)"
|
|
2477
|
+
"filter by pillar (spec, decisions, handbook, tests, workflow, quality, journeys)"
|
|
2011
2478
|
).option("--only <ids>", "comma-separated linter ids to run (e.g. lint:cross-links)").option("--format <fmt>", "text | json", "text").option("--cwd <dir>", "repo root", ".").action((opts) => {
|
|
2012
2479
|
const repoRoot = resolve9(opts.cwd ?? ".");
|
|
2013
2480
|
const only = parseList(opts.only);
|