@vaubaan/harness 2.2.0 → 2.3.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 +533 -69
- package/dist/cli/index.js +153 -121
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/intent.cmd.md +33 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +90 -58
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +90 -58
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +124 -117
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +65 -32
- package/dist/parser/index.js +42 -38
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-BzrBb_l4.d.ts → render-CTx7VNOK.d.ts} +3 -3
- package/dist/render.d.ts +1 -1
- package/dist/render.js +37 -32
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +21 -20
- package/dist/skills/drift-detector.skill.md +17 -17
- package/dist/skills/handbook-writer.skill.md +3 -3
- package/dist/skills/intent-writer.skill.md +174 -0
- package/dist/templates/e2e-tests.md.tmpl +1 -1
- package/dist/templates/integration-tests.md.tmpl +1 -1
- package/dist/templates/{journey.md.tmpl → intent.md.tmpl} +8 -7
- package/package.json +3 -7
- package/dist/commands/journey.cmd.md +0 -22
- package/dist/commands/story.cmd.md +0 -24
- package/dist/skills/journey-writer.skill.md +0 -159
package/dist/cli/index.js
CHANGED
|
@@ -364,9 +364,15 @@ var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
|
364
364
|
"AGENTS.md",
|
|
365
365
|
"CLAUDE.md",
|
|
366
366
|
".harness-manifest.json",
|
|
367
|
-
// Index of the optional
|
|
367
|
+
// Index of the optional intents pillar, rendered while an intent file exists.
|
|
368
|
+
"docs/intents/README.md",
|
|
369
|
+
// Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
|
|
368
370
|
"docs/journeys/README.md"
|
|
369
371
|
]);
|
|
372
|
+
var MOVED_PATHS = /* @__PURE__ */ new Map([
|
|
373
|
+
// 2.3: the journeys pillar became the intents pillar.
|
|
374
|
+
["docs/journeys/README.md", "docs/intents/README.md"]
|
|
375
|
+
]);
|
|
370
376
|
var RELEASED_PATHS = [
|
|
371
377
|
".mcp.json",
|
|
372
378
|
".codex/config.toml",
|
|
@@ -439,7 +445,7 @@ import { join as join4 } from "path";
|
|
|
439
445
|
import { z } from "zod";
|
|
440
446
|
|
|
441
447
|
// src/version.ts
|
|
442
|
-
var VERSION = "2.
|
|
448
|
+
var VERSION = "2.3.0";
|
|
443
449
|
|
|
444
450
|
// src/cli/manifest.ts
|
|
445
451
|
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
@@ -511,12 +517,16 @@ var CmdArgEnumSchema = z2.object({
|
|
|
511
517
|
name: z2.string().min(1),
|
|
512
518
|
type: z2.literal("enum"),
|
|
513
519
|
values: z2.array(z2.string()).min(1),
|
|
514
|
-
default: z2.string().optional()
|
|
520
|
+
default: z2.string().optional(),
|
|
521
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
522
|
+
required: z2.boolean().optional()
|
|
515
523
|
}).strict();
|
|
516
524
|
var CmdArgStringSchema = z2.object({
|
|
517
525
|
name: z2.string().min(1),
|
|
518
526
|
type: z2.literal("string"),
|
|
519
|
-
default: z2.string().optional()
|
|
527
|
+
default: z2.string().optional(),
|
|
528
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
529
|
+
required: z2.boolean().optional()
|
|
520
530
|
}).strict();
|
|
521
531
|
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
522
532
|
var CmdFrontmatterSchema = z2.object({
|
|
@@ -526,10 +536,10 @@ var CmdFrontmatterSchema = z2.object({
|
|
|
526
536
|
args: z2.array(CmdArgSchema).optional(),
|
|
527
537
|
description: z2.string().min(1)
|
|
528
538
|
}).strict();
|
|
529
|
-
var
|
|
530
|
-
var
|
|
539
|
+
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
540
|
+
var IntentFrontmatterSchema = z2.object({
|
|
531
541
|
title: z2.string().min(1),
|
|
532
|
-
status: z2.enum(
|
|
542
|
+
status: z2.enum(INTENT_STATUSES),
|
|
533
543
|
actors: z2.array(z2.string().min(1)).min(1),
|
|
534
544
|
spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
|
|
535
545
|
last_reviewed: z2.union([z2.date(), z2.string().min(1)])
|
|
@@ -537,7 +547,7 @@ var JourneyFrontmatterSchema = z2.object({
|
|
|
537
547
|
var Schemas = {
|
|
538
548
|
Skill: SkillFrontmatterSchema,
|
|
539
549
|
Cmd: CmdFrontmatterSchema,
|
|
540
|
-
|
|
550
|
+
Intent: IntentFrontmatterSchema
|
|
541
551
|
};
|
|
542
552
|
var ParseError = class extends Error {
|
|
543
553
|
constructor(file, issues) {
|
|
@@ -621,12 +631,12 @@ function loadOverrides(worktreeDir) {
|
|
|
621
631
|
return { add: added, disable };
|
|
622
632
|
}
|
|
623
633
|
|
|
624
|
-
// src/parser/
|
|
634
|
+
// src/parser/intent.ts
|
|
625
635
|
import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
|
|
626
636
|
import { basename as basename2, join as join6 } from "path";
|
|
627
637
|
import matter3 from "gray-matter";
|
|
628
|
-
var
|
|
629
|
-
var
|
|
638
|
+
var INTENTS_DIR = "docs/intents";
|
|
639
|
+
var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
|
|
630
640
|
var NODE_FIELDS = [
|
|
631
641
|
"status",
|
|
632
642
|
"spec",
|
|
@@ -635,7 +645,7 @@ var NODE_FIELDS = [
|
|
|
635
645
|
"requires",
|
|
636
646
|
"creates"
|
|
637
647
|
];
|
|
638
|
-
var
|
|
648
|
+
var TERMINAL_FIELDS = [
|
|
639
649
|
"anchors",
|
|
640
650
|
"acceptance",
|
|
641
651
|
"requires",
|
|
@@ -686,7 +696,7 @@ function parseFrontmatter2(text, errors) {
|
|
|
686
696
|
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
687
697
|
return void 0;
|
|
688
698
|
}
|
|
689
|
-
const result = Schemas.
|
|
699
|
+
const result = Schemas.Intent.safeParse(data);
|
|
690
700
|
if (result.success) return result.data;
|
|
691
701
|
for (const issue of result.error.issues) {
|
|
692
702
|
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
@@ -699,7 +709,7 @@ function newNode(title, level, line) {
|
|
|
699
709
|
title,
|
|
700
710
|
level,
|
|
701
711
|
line,
|
|
702
|
-
|
|
712
|
+
isTerminal: true,
|
|
703
713
|
fieldLines: {},
|
|
704
714
|
anchors: [],
|
|
705
715
|
acceptance: [],
|
|
@@ -726,12 +736,12 @@ function parseFields(node, lines, from, to, errors) {
|
|
|
726
736
|
const known = key;
|
|
727
737
|
node.fieldLines[known] = lineNo;
|
|
728
738
|
if (known === "status") {
|
|
729
|
-
if (
|
|
739
|
+
if (INTENT_STATUSES.includes(value)) {
|
|
730
740
|
node.status = value;
|
|
731
741
|
} else {
|
|
732
742
|
errors.push({
|
|
733
743
|
line: lineNo,
|
|
734
|
-
message: `invalid status \`${value}\` (expected ${
|
|
744
|
+
message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
|
|
735
745
|
});
|
|
736
746
|
}
|
|
737
747
|
} else if (known === "spec") {
|
|
@@ -752,7 +762,7 @@ function parseFields(node, lines, from, to, errors) {
|
|
|
752
762
|
return;
|
|
753
763
|
}
|
|
754
764
|
}
|
|
755
|
-
function
|
|
765
|
+
function parseIntentFile(relPath, text) {
|
|
756
766
|
const errors = [];
|
|
757
767
|
const meta = parseFrontmatter2(text, errors);
|
|
758
768
|
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
@@ -763,7 +773,7 @@ function parseJourney(relPath, text) {
|
|
|
763
773
|
if (h) headings.push({ index: i, ...h });
|
|
764
774
|
}
|
|
765
775
|
const h1 = headings.find((h) => h.depth === 1);
|
|
766
|
-
let
|
|
776
|
+
let statement;
|
|
767
777
|
if (h1) {
|
|
768
778
|
const paragraph = [];
|
|
769
779
|
for (let i = h1.index + 1; i < lines.length; i++) {
|
|
@@ -775,7 +785,7 @@ function parseJourney(relPath, text) {
|
|
|
775
785
|
if (line === MASKED_LINE || parseHeading(line)) break;
|
|
776
786
|
paragraph.push(line.trim());
|
|
777
787
|
}
|
|
778
|
-
if (paragraph.length)
|
|
788
|
+
if (paragraph.length) statement = paragraph.join(" ");
|
|
779
789
|
}
|
|
780
790
|
const nodes = [];
|
|
781
791
|
const stack = [];
|
|
@@ -791,7 +801,7 @@ function parseJourney(relPath, text) {
|
|
|
791
801
|
if (parentIndex !== void 0) {
|
|
792
802
|
node.parent = parentIndex;
|
|
793
803
|
const parent = nodes[parentIndex];
|
|
794
|
-
if (parent) parent.
|
|
804
|
+
if (parent) parent.isTerminal = false;
|
|
795
805
|
}
|
|
796
806
|
const next = headings[k + 1];
|
|
797
807
|
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
@@ -801,32 +811,32 @@ function parseJourney(relPath, text) {
|
|
|
801
811
|
nodes.push(node);
|
|
802
812
|
}
|
|
803
813
|
const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
|
|
804
|
-
return { ...meta ? { meta } : {}, title, ...
|
|
814
|
+
return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
|
|
805
815
|
}
|
|
806
|
-
function
|
|
807
|
-
const dir = join6(targetDir,
|
|
816
|
+
function listIntentFiles(targetDir) {
|
|
817
|
+
const dir = join6(targetDir, INTENTS_DIR);
|
|
808
818
|
if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
|
|
809
819
|
return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
|
|
810
820
|
}
|
|
811
|
-
function
|
|
812
|
-
return
|
|
813
|
-
const path = `${
|
|
821
|
+
function readIntentFiles(targetDir) {
|
|
822
|
+
return listIntentFiles(targetDir).map((file) => {
|
|
823
|
+
const path = `${INTENTS_DIR}/${file}`;
|
|
814
824
|
const text = readFileSync5(join6(targetDir, path), "utf8");
|
|
815
|
-
return { path, file, ...
|
|
825
|
+
return { path, file, ...parseIntentFile(path, text) };
|
|
816
826
|
});
|
|
817
827
|
}
|
|
818
|
-
function
|
|
819
|
-
const
|
|
820
|
-
const problems =
|
|
828
|
+
function loadIntentFiles(targetDir) {
|
|
829
|
+
const intentFiles = readIntentFiles(targetDir);
|
|
830
|
+
const problems = intentFiles.flatMap(
|
|
821
831
|
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
822
832
|
);
|
|
823
833
|
if (problems.length) {
|
|
824
834
|
throw new Error(
|
|
825
|
-
`invalid
|
|
835
|
+
`invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
|
|
826
836
|
${problems.join("\n")}`
|
|
827
837
|
);
|
|
828
838
|
}
|
|
829
|
-
return
|
|
839
|
+
return intentFiles;
|
|
830
840
|
}
|
|
831
841
|
|
|
832
842
|
// src/renderers/common.ts
|
|
@@ -876,12 +886,13 @@ function frontmatterDataForCmd(cmd) {
|
|
|
876
886
|
description: cmd.meta.description
|
|
877
887
|
};
|
|
878
888
|
if (cmd.meta.args && cmd.meta.args.length > 0) {
|
|
879
|
-
data.args = cmd.meta.args.map((a) => {
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
}
|
|
883
|
-
|
|
884
|
-
|
|
889
|
+
data.args = cmd.meta.args.map((a) => ({
|
|
890
|
+
name: a.name,
|
|
891
|
+
type: a.type,
|
|
892
|
+
...a.type === "enum" ? { values: a.values } : {},
|
|
893
|
+
...a.default !== void 0 ? { default: a.default } : {},
|
|
894
|
+
...a.required === false ? { required: false } : {}
|
|
895
|
+
}));
|
|
885
896
|
}
|
|
886
897
|
return data;
|
|
887
898
|
}
|
|
@@ -914,16 +925,16 @@ function buildUmbrellaBody(extras) {
|
|
|
914
925
|
...extras.hasQualityDoc ? [
|
|
915
926
|
"- `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."
|
|
916
927
|
] : [],
|
|
917
|
-
...extras.
|
|
918
|
-
"- `docs/
|
|
928
|
+
...extras.hasIntents ? [
|
|
929
|
+
"- `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."
|
|
919
930
|
] : [],
|
|
920
931
|
"",
|
|
921
932
|
"## Doc-first",
|
|
922
933
|
"",
|
|
923
934
|
"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.",
|
|
924
935
|
"",
|
|
925
|
-
...extras.
|
|
926
|
-
"- Visible change of behavior \u2192 a `proposed`
|
|
936
|
+
...extras.hasIntents ? [
|
|
937
|
+
"- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
|
|
927
938
|
] : [],
|
|
928
939
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
929
940
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
@@ -1053,16 +1064,16 @@ function getRenderer(engine) {
|
|
|
1053
1064
|
return RENDERERS[engine];
|
|
1054
1065
|
}
|
|
1055
1066
|
|
|
1056
|
-
// src/renderers/
|
|
1057
|
-
var INTRO = "User
|
|
1058
|
-
function
|
|
1059
|
-
const lines = ["#
|
|
1060
|
-
const sorted = [...
|
|
1061
|
-
for (const
|
|
1062
|
-
const status =
|
|
1063
|
-
const actors =
|
|
1064
|
-
lines.push(`- [${
|
|
1065
|
-
for (const node of
|
|
1067
|
+
// src/renderers/intents-index.ts
|
|
1068
|
+
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 .`.";
|
|
1069
|
+
function buildIntentsIndex(intentFiles) {
|
|
1070
|
+
const lines = ["# Intents", "", INTRO, ""];
|
|
1071
|
+
const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
1072
|
+
for (const intentFile of sorted) {
|
|
1073
|
+
const status = intentFile.meta?.status ?? "proposed";
|
|
1074
|
+
const actors = intentFile.meta?.actors.join(", ") ?? "";
|
|
1075
|
+
lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
|
|
1076
|
+
for (const node of intentFile.nodes) {
|
|
1066
1077
|
lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
|
|
1067
1078
|
}
|
|
1068
1079
|
}
|
|
@@ -1140,14 +1151,14 @@ function render(input) {
|
|
|
1140
1151
|
availableCommands: Array.from(exposedCmds.values()),
|
|
1141
1152
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
1142
1153
|
hasQualityDoc: input.hasQualityDoc === true,
|
|
1143
|
-
|
|
1154
|
+
hasIntents: (input.intentFiles?.length ?? 0) > 0
|
|
1144
1155
|
});
|
|
1145
1156
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
1146
1157
|
if (engines.includes("claude-code")) {
|
|
1147
1158
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
1148
1159
|
}
|
|
1149
|
-
if (input.
|
|
1150
|
-
files.push({ path:
|
|
1160
|
+
if (input.intentFiles && input.intentFiles.length > 0) {
|
|
1161
|
+
files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
|
|
1151
1162
|
}
|
|
1152
1163
|
return { files, warnings };
|
|
1153
1164
|
}
|
|
@@ -1180,8 +1191,8 @@ function planInit(args) {
|
|
|
1180
1191
|
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
1181
1192
|
const projectSkills = loadProjectSkills(args.targetDir);
|
|
1182
1193
|
const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
|
|
1183
|
-
const
|
|
1184
|
-
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc,
|
|
1194
|
+
const intentFiles = loadIntentFiles(args.targetDir);
|
|
1195
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
|
|
1185
1196
|
return { engines, output };
|
|
1186
1197
|
}
|
|
1187
1198
|
|
|
@@ -1260,7 +1271,7 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
|
1260
1271
|
".agents/",
|
|
1261
1272
|
".opencode/",
|
|
1262
1273
|
".harness-manifest.json",
|
|
1263
|
-
"docs/
|
|
1274
|
+
"docs/intents/README.md"
|
|
1264
1275
|
];
|
|
1265
1276
|
function gitignoreEntries(text) {
|
|
1266
1277
|
const entries = /* @__PURE__ */ new Set();
|
|
@@ -1319,23 +1330,23 @@ var gitignoreHarness = {
|
|
|
1319
1330
|
}
|
|
1320
1331
|
};
|
|
1321
1332
|
|
|
1322
|
-
// src/linters/
|
|
1323
|
-
var
|
|
1324
|
-
id: "lint:
|
|
1325
|
-
pillars: ["
|
|
1333
|
+
// src/linters/intent-anchors.ts
|
|
1334
|
+
var intentAnchors = {
|
|
1335
|
+
id: "lint:intent-anchors",
|
|
1336
|
+
pillars: ["intents"],
|
|
1326
1337
|
defaultSeverity: "error",
|
|
1327
|
-
suggestedSkills: ["/
|
|
1338
|
+
suggestedSkills: ["/intent"],
|
|
1328
1339
|
run(repoRoot) {
|
|
1329
1340
|
const issues = [];
|
|
1330
|
-
for (const
|
|
1331
|
-
for (const node of
|
|
1341
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1342
|
+
for (const node of intentFile.nodes) {
|
|
1332
1343
|
if (node.effectiveStatus === "deprecated") continue;
|
|
1333
1344
|
for (const anchor of node.anchors) {
|
|
1334
1345
|
if (trackedPathExists(repoRoot, anchor)) continue;
|
|
1335
1346
|
issues.push({
|
|
1336
1347
|
linter: this.id,
|
|
1337
1348
|
severity: "error",
|
|
1338
|
-
file:
|
|
1349
|
+
file: intentFile.path,
|
|
1339
1350
|
line: node.line,
|
|
1340
1351
|
message: `"${node.title}": anchor matches no file: ${anchor}`
|
|
1341
1352
|
});
|
|
@@ -1346,28 +1357,28 @@ var journeyAnchors = {
|
|
|
1346
1357
|
}
|
|
1347
1358
|
};
|
|
1348
1359
|
|
|
1349
|
-
// src/linters/
|
|
1350
|
-
var
|
|
1351
|
-
id: "lint:
|
|
1352
|
-
pillars: ["
|
|
1360
|
+
// src/linters/intent-graph.ts
|
|
1361
|
+
var intentGraph = {
|
|
1362
|
+
id: "lint:intent-graph",
|
|
1363
|
+
pillars: ["intents"],
|
|
1353
1364
|
defaultSeverity: "warning",
|
|
1354
|
-
suggestedSkills: ["/
|
|
1365
|
+
suggestedSkills: ["/intent"],
|
|
1355
1366
|
run(repoRoot) {
|
|
1356
|
-
const
|
|
1357
|
-
const
|
|
1358
|
-
(
|
|
1367
|
+
const intentFiles = readIntentFiles(repoRoot);
|
|
1368
|
+
const terminals = intentFiles.flatMap(
|
|
1369
|
+
(intentFile) => intentFile.nodes.filter((node) => node.isTerminal).map((node) => ({ intentFile, node }))
|
|
1359
1370
|
);
|
|
1360
|
-
const created = new Set(
|
|
1371
|
+
const created = new Set(terminals.flatMap(({ node }) => node.creates));
|
|
1361
1372
|
const issues = [];
|
|
1362
|
-
for (const {
|
|
1373
|
+
for (const { intentFile, node } of terminals) {
|
|
1363
1374
|
for (const entity of node.requires) {
|
|
1364
1375
|
if (created.has(entity)) continue;
|
|
1365
1376
|
issues.push({
|
|
1366
1377
|
linter: this.id,
|
|
1367
1378
|
severity: "warning",
|
|
1368
|
-
file:
|
|
1379
|
+
file: intentFile.path,
|
|
1369
1380
|
line: node.line,
|
|
1370
|
-
message: `"${node.title}": entity \`${entity}\` is required here but no
|
|
1381
|
+
message: `"${node.title}": entity \`${entity}\` is required here but no terminal intent creates it`
|
|
1371
1382
|
});
|
|
1372
1383
|
}
|
|
1373
1384
|
}
|
|
@@ -1375,43 +1386,43 @@ var journeyGraph = {
|
|
|
1375
1386
|
}
|
|
1376
1387
|
};
|
|
1377
1388
|
|
|
1378
|
-
// src/linters/
|
|
1389
|
+
// src/linters/intent-util.ts
|
|
1379
1390
|
import { posix } from "path";
|
|
1380
|
-
function
|
|
1391
|
+
function intentFileSpecs(meta) {
|
|
1381
1392
|
if (!meta) return [];
|
|
1382
1393
|
return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
|
|
1383
1394
|
}
|
|
1384
|
-
function resolveSpecPath(
|
|
1395
|
+
function resolveSpecPath(filePath, spec) {
|
|
1385
1396
|
const withoutFragment = spec.split("#")[0] ?? "";
|
|
1386
|
-
return posix.normalize(posix.join(posix.dirname(
|
|
1397
|
+
return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
|
|
1387
1398
|
}
|
|
1388
1399
|
|
|
1389
|
-
// src/linters/
|
|
1400
|
+
// src/linters/intent-schema.ts
|
|
1390
1401
|
var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
|
|
1391
|
-
var
|
|
1392
|
-
id: "lint:
|
|
1393
|
-
pillars: ["
|
|
1402
|
+
var intentSchema = {
|
|
1403
|
+
id: "lint:intent-schema",
|
|
1404
|
+
pillars: ["intents"],
|
|
1394
1405
|
defaultSeverity: "error",
|
|
1395
|
-
suggestedSkills: ["/
|
|
1406
|
+
suggestedSkills: ["/intent"],
|
|
1396
1407
|
run(repoRoot) {
|
|
1397
1408
|
const issues = [];
|
|
1398
|
-
for (const
|
|
1409
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1399
1410
|
const report = (message, line) => {
|
|
1400
1411
|
issues.push({
|
|
1401
1412
|
linter: this.id,
|
|
1402
1413
|
severity: "error",
|
|
1403
|
-
file:
|
|
1414
|
+
file: intentFile.path,
|
|
1404
1415
|
...line !== void 0 ? { line } : {},
|
|
1405
1416
|
message
|
|
1406
1417
|
});
|
|
1407
1418
|
};
|
|
1408
|
-
for (const error of
|
|
1409
|
-
for (const spec of
|
|
1410
|
-
if (!fileExists(repoRoot, resolveSpecPath(
|
|
1419
|
+
for (const error of intentFile.errors) report(error.message, error.line);
|
|
1420
|
+
for (const spec of intentFileSpecs(intentFile.meta)) {
|
|
1421
|
+
if (!fileExists(repoRoot, resolveSpecPath(intentFile.path, spec))) {
|
|
1411
1422
|
report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
|
|
1412
1423
|
}
|
|
1413
1424
|
}
|
|
1414
|
-
for (const node of
|
|
1425
|
+
for (const node of intentFile.nodes) {
|
|
1415
1426
|
const at = (message) => report(`"${node.title}": ${message}`, node.line);
|
|
1416
1427
|
for (const { key, line } of node.unknownFields) {
|
|
1417
1428
|
report(
|
|
@@ -1419,15 +1430,15 @@ var journeySchema = {
|
|
|
1419
1430
|
line
|
|
1420
1431
|
);
|
|
1421
1432
|
}
|
|
1422
|
-
if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(
|
|
1433
|
+
if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(intentFile.path, node.spec))) {
|
|
1423
1434
|
report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
|
|
1424
1435
|
}
|
|
1425
|
-
if (!node.
|
|
1426
|
-
for (const field of
|
|
1436
|
+
if (!node.isTerminal) {
|
|
1437
|
+
for (const field of TERMINAL_FIELDS) {
|
|
1427
1438
|
const line = node.fieldLines[field];
|
|
1428
1439
|
if (line !== void 0) {
|
|
1429
1440
|
report(
|
|
1430
|
-
`"${node.title}": \`${field}:\` is a
|
|
1441
|
+
`"${node.title}": \`${field}:\` is a field of a terminal intent, this node has sub-intents`,
|
|
1431
1442
|
line
|
|
1432
1443
|
);
|
|
1433
1444
|
}
|
|
@@ -1435,14 +1446,14 @@ var journeySchema = {
|
|
|
1435
1446
|
continue;
|
|
1436
1447
|
}
|
|
1437
1448
|
if (Object.keys(node.fieldLines).length === 0) {
|
|
1438
|
-
at("a
|
|
1449
|
+
at("a terminal intent carries at least one field");
|
|
1439
1450
|
continue;
|
|
1440
1451
|
}
|
|
1441
1452
|
if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
|
|
1442
|
-
at("an `implemented`
|
|
1453
|
+
at("an `implemented` intent needs `anchors:`");
|
|
1443
1454
|
}
|
|
1444
1455
|
if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
|
|
1445
|
-
at("a `proposed`
|
|
1456
|
+
at("a `proposed` intent needs `acceptance:` with at least one `- ` item");
|
|
1446
1457
|
}
|
|
1447
1458
|
}
|
|
1448
1459
|
}
|
|
@@ -1450,7 +1461,7 @@ var journeySchema = {
|
|
|
1450
1461
|
}
|
|
1451
1462
|
};
|
|
1452
1463
|
|
|
1453
|
-
// src/linters/
|
|
1464
|
+
// src/linters/intent-vocabulary.ts
|
|
1454
1465
|
var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
|
|
1455
1466
|
var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
|
|
1456
1467
|
function entitySlug(term) {
|
|
@@ -1475,19 +1486,19 @@ function vocabularyOf(specText) {
|
|
|
1475
1486
|
}
|
|
1476
1487
|
return terms;
|
|
1477
1488
|
}
|
|
1478
|
-
var
|
|
1479
|
-
id: "lint:
|
|
1480
|
-
pillars: ["
|
|
1489
|
+
var intentVocabulary = {
|
|
1490
|
+
id: "lint:intent-vocabulary",
|
|
1491
|
+
pillars: ["intents"],
|
|
1481
1492
|
defaultSeverity: "error",
|
|
1482
1493
|
suggestedSkills: ["/spec"],
|
|
1483
1494
|
run(repoRoot) {
|
|
1484
1495
|
const issues = [];
|
|
1485
|
-
for (const
|
|
1486
|
-
const used =
|
|
1496
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1497
|
+
const used = intentFile.nodes.flatMap(
|
|
1487
1498
|
(node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
|
|
1488
1499
|
);
|
|
1489
1500
|
if (used.length === 0) continue;
|
|
1490
|
-
const specs =
|
|
1501
|
+
const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
|
|
1491
1502
|
if (specs.length === 0) continue;
|
|
1492
1503
|
const entities = /* @__PURE__ */ new Set();
|
|
1493
1504
|
let hasVocabulary = false;
|
|
@@ -1501,7 +1512,7 @@ var journeyVocabulary = {
|
|
|
1501
1512
|
issues.push({
|
|
1502
1513
|
linter: this.id,
|
|
1503
1514
|
severity: "warning",
|
|
1504
|
-
file:
|
|
1515
|
+
file: intentFile.path,
|
|
1505
1516
|
message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
|
|
1506
1517
|
});
|
|
1507
1518
|
continue;
|
|
@@ -1511,7 +1522,7 @@ var journeyVocabulary = {
|
|
|
1511
1522
|
issues.push({
|
|
1512
1523
|
linter: this.id,
|
|
1513
1524
|
severity: "error",
|
|
1514
|
-
file:
|
|
1525
|
+
file: intentFile.path,
|
|
1515
1526
|
line: node.line,
|
|
1516
1527
|
message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
|
|
1517
1528
|
});
|
|
@@ -1729,7 +1740,7 @@ var specTechAgnostic = {
|
|
|
1729
1740
|
// src/linters/tracks-drift.ts
|
|
1730
1741
|
import fg5 from "fast-glob";
|
|
1731
1742
|
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
1732
|
-
var
|
|
1743
|
+
var INTENTS_DIR2 = "docs/intents";
|
|
1733
1744
|
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
1734
1745
|
function expandGlob(repoRoot, pattern) {
|
|
1735
1746
|
if (pattern.includes("*")) {
|
|
@@ -1738,20 +1749,20 @@ function expandGlob(repoRoot, pattern) {
|
|
|
1738
1749
|
return [pattern];
|
|
1739
1750
|
}
|
|
1740
1751
|
function trackedPaths(dir, file, text, data) {
|
|
1741
|
-
if (dir ===
|
|
1742
|
-
const anchors =
|
|
1752
|
+
if (dir === INTENTS_DIR2) {
|
|
1753
|
+
const anchors = parseIntentFile(file, text).nodes.flatMap((node) => node.anchors);
|
|
1743
1754
|
return anchors.length > 0 ? [...new Set(anchors)] : void 0;
|
|
1744
1755
|
}
|
|
1745
1756
|
return Array.isArray(data.tracks) ? data.tracks : void 0;
|
|
1746
1757
|
}
|
|
1747
1758
|
var tracksDrift = {
|
|
1748
1759
|
id: "lint:tracks-drift",
|
|
1749
|
-
pillars: ["handbook", "tests", "workflow", "
|
|
1760
|
+
pillars: ["handbook", "tests", "workflow", "intents"],
|
|
1750
1761
|
defaultSeverity: "warning",
|
|
1751
1762
|
suggestedSkills: ["/drift", "/handbook"],
|
|
1752
1763
|
run(repoRoot) {
|
|
1753
1764
|
const issues = [];
|
|
1754
|
-
for (const dir of [...TRACKED_DIRS2,
|
|
1765
|
+
for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
|
|
1755
1766
|
const files = listMarkdown(repoRoot, dir);
|
|
1756
1767
|
for (const f of files) {
|
|
1757
1768
|
const text = readText(repoRoot, f);
|
|
@@ -1799,10 +1810,10 @@ var ALL_LINTERS = [
|
|
|
1799
1810
|
orphanDecisions,
|
|
1800
1811
|
gitignoreHarness,
|
|
1801
1812
|
qualitySchema,
|
|
1802
|
-
|
|
1803
|
-
|
|
1804
|
-
|
|
1805
|
-
|
|
1813
|
+
intentSchema,
|
|
1814
|
+
intentAnchors,
|
|
1815
|
+
intentVocabulary,
|
|
1816
|
+
intentGraph,
|
|
1806
1817
|
generatedFresh
|
|
1807
1818
|
];
|
|
1808
1819
|
function runLinters(repoRoot, opts = {}) {
|
|
@@ -2145,7 +2156,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
2145
2156
|
}
|
|
2146
2157
|
|
|
2147
2158
|
// src/cli/update.ts
|
|
2148
|
-
import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
|
|
2159
|
+
import { existsSync as existsSync11, readFileSync as readFileSync11, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
|
|
2149
2160
|
import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
|
|
2150
2161
|
import { isDeepStrictEqual } from "util";
|
|
2151
2162
|
|
|
@@ -2221,6 +2232,27 @@ function releaseLegacyPaths(previous, warnings) {
|
|
|
2221
2232
|
if (released.length === 0) return previous;
|
|
2222
2233
|
return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
|
|
2223
2234
|
}
|
|
2235
|
+
function carryMovedPaths(root, previous, warnings) {
|
|
2236
|
+
let files = previous.files;
|
|
2237
|
+
let fileHashes = previous.fileHashes;
|
|
2238
|
+
for (const [from, to] of MOVED_PATHS) {
|
|
2239
|
+
if (!files.includes(from) || existsSync11(join13(root, from))) continue;
|
|
2240
|
+
files = [...new Set(files.map((path) => path === from ? to : path))];
|
|
2241
|
+
const hash = fileHashes?.[from];
|
|
2242
|
+
if (fileHashes && hash !== void 0) {
|
|
2243
|
+
const { [from]: _moved, ...rest } = fileHashes;
|
|
2244
|
+
fileHashes = { ...rest, [to]: hash };
|
|
2245
|
+
}
|
|
2246
|
+
}
|
|
2247
|
+
const oldDir = join13(root, "docs/journeys");
|
|
2248
|
+
if (existsSync11(oldDir) && statSync4(oldDir).isDirectory() && readdirSync4(oldDir).length > 0) {
|
|
2249
|
+
warnings.push(
|
|
2250
|
+
"docs/journeys/ is now docs/intents/: run `git mv docs/journeys docs/intents`, then `npx @vaubaan/harness update .` again"
|
|
2251
|
+
);
|
|
2252
|
+
}
|
|
2253
|
+
if (files === previous.files) return previous;
|
|
2254
|
+
return { ...previous, files, ...fileHashes ? { fileHashes } : {} };
|
|
2255
|
+
}
|
|
2224
2256
|
function legacyHookWarnings(root) {
|
|
2225
2257
|
const warnings = [];
|
|
2226
2258
|
for (const path of LEGACY_HOOK_FILES) {
|
|
@@ -2237,7 +2269,7 @@ function planInstallation(args, settings) {
|
|
|
2237
2269
|
const root = resolve7(args.targetDir);
|
|
2238
2270
|
const { engines } = settings;
|
|
2239
2271
|
const warnings = [];
|
|
2240
|
-
const previous = releaseLegacyPaths(settings.previous, warnings);
|
|
2272
|
+
const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
|
|
2241
2273
|
const preserved = [
|
|
2242
2274
|
.../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
|
|
2243
2275
|
].sort();
|
|
@@ -2474,7 +2506,7 @@ program.command("check").description("Verify repo layout: doc pillars present an
|
|
|
2474
2506
|
});
|
|
2475
2507
|
program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
|
|
2476
2508
|
"--pillar <pillar>",
|
|
2477
|
-
"filter by pillar (spec, decisions, handbook, tests, workflow, quality,
|
|
2509
|
+
"filter by pillar (spec, decisions, handbook, tests, workflow, quality, intents)"
|
|
2478
2510
|
).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) => {
|
|
2479
2511
|
const repoRoot = resolve9(opts.cwd ?? ".");
|
|
2480
2512
|
const only = parseList(opts.only);
|