@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/linters/index.js
CHANGED
|
@@ -357,7 +357,9 @@ var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
|
357
357
|
"AGENTS.md",
|
|
358
358
|
"CLAUDE.md",
|
|
359
359
|
".harness-manifest.json",
|
|
360
|
-
// Index of the optional
|
|
360
|
+
// Index of the optional intents pillar, rendered while an intent file exists.
|
|
361
|
+
"docs/intents/README.md",
|
|
362
|
+
// Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
|
|
361
363
|
"docs/journeys/README.md"
|
|
362
364
|
]);
|
|
363
365
|
var RELEASED_PATHS = [
|
|
@@ -496,12 +498,16 @@ var CmdArgEnumSchema = z2.object({
|
|
|
496
498
|
name: z2.string().min(1),
|
|
497
499
|
type: z2.literal("enum"),
|
|
498
500
|
values: z2.array(z2.string()).min(1),
|
|
499
|
-
default: z2.string().optional()
|
|
501
|
+
default: z2.string().optional(),
|
|
502
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
503
|
+
required: z2.boolean().optional()
|
|
500
504
|
}).strict();
|
|
501
505
|
var CmdArgStringSchema = z2.object({
|
|
502
506
|
name: z2.string().min(1),
|
|
503
507
|
type: z2.literal("string"),
|
|
504
|
-
default: z2.string().optional()
|
|
508
|
+
default: z2.string().optional(),
|
|
509
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
510
|
+
required: z2.boolean().optional()
|
|
505
511
|
}).strict();
|
|
506
512
|
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
507
513
|
var CmdFrontmatterSchema = z2.object({
|
|
@@ -511,10 +517,10 @@ var CmdFrontmatterSchema = z2.object({
|
|
|
511
517
|
args: z2.array(CmdArgSchema).optional(),
|
|
512
518
|
description: z2.string().min(1)
|
|
513
519
|
}).strict();
|
|
514
|
-
var
|
|
515
|
-
var
|
|
520
|
+
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
521
|
+
var IntentFrontmatterSchema = z2.object({
|
|
516
522
|
title: z2.string().min(1),
|
|
517
|
-
status: z2.enum(
|
|
523
|
+
status: z2.enum(INTENT_STATUSES),
|
|
518
524
|
actors: z2.array(z2.string().min(1)).min(1),
|
|
519
525
|
spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
|
|
520
526
|
last_reviewed: z2.union([z2.date(), z2.string().min(1)])
|
|
@@ -522,7 +528,7 @@ var JourneyFrontmatterSchema = z2.object({
|
|
|
522
528
|
var Schemas = {
|
|
523
529
|
Skill: SkillFrontmatterSchema,
|
|
524
530
|
Cmd: CmdFrontmatterSchema,
|
|
525
|
-
|
|
531
|
+
Intent: IntentFrontmatterSchema
|
|
526
532
|
};
|
|
527
533
|
var ParseError = class extends Error {
|
|
528
534
|
constructor(file, issues) {
|
|
@@ -606,12 +612,12 @@ function loadOverrides(worktreeDir) {
|
|
|
606
612
|
return { add: added, disable };
|
|
607
613
|
}
|
|
608
614
|
|
|
609
|
-
// src/parser/
|
|
615
|
+
// src/parser/intent.ts
|
|
610
616
|
import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
|
|
611
617
|
import { basename as basename2, join as join6 } from "path";
|
|
612
618
|
import matter3 from "gray-matter";
|
|
613
|
-
var
|
|
614
|
-
var
|
|
619
|
+
var INTENTS_DIR = "docs/intents";
|
|
620
|
+
var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
|
|
615
621
|
var NODE_FIELDS = [
|
|
616
622
|
"status",
|
|
617
623
|
"spec",
|
|
@@ -620,7 +626,7 @@ var NODE_FIELDS = [
|
|
|
620
626
|
"requires",
|
|
621
627
|
"creates"
|
|
622
628
|
];
|
|
623
|
-
var
|
|
629
|
+
var TERMINAL_FIELDS = [
|
|
624
630
|
"anchors",
|
|
625
631
|
"acceptance",
|
|
626
632
|
"requires",
|
|
@@ -671,7 +677,7 @@ function parseFrontmatter2(text, errors) {
|
|
|
671
677
|
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
672
678
|
return void 0;
|
|
673
679
|
}
|
|
674
|
-
const result = Schemas.
|
|
680
|
+
const result = Schemas.Intent.safeParse(data);
|
|
675
681
|
if (result.success) return result.data;
|
|
676
682
|
for (const issue of result.error.issues) {
|
|
677
683
|
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
@@ -684,7 +690,7 @@ function newNode(title, level, line) {
|
|
|
684
690
|
title,
|
|
685
691
|
level,
|
|
686
692
|
line,
|
|
687
|
-
|
|
693
|
+
isTerminal: true,
|
|
688
694
|
fieldLines: {},
|
|
689
695
|
anchors: [],
|
|
690
696
|
acceptance: [],
|
|
@@ -711,12 +717,12 @@ function parseFields(node, lines, from, to, errors) {
|
|
|
711
717
|
const known = key;
|
|
712
718
|
node.fieldLines[known] = lineNo;
|
|
713
719
|
if (known === "status") {
|
|
714
|
-
if (
|
|
720
|
+
if (INTENT_STATUSES.includes(value)) {
|
|
715
721
|
node.status = value;
|
|
716
722
|
} else {
|
|
717
723
|
errors.push({
|
|
718
724
|
line: lineNo,
|
|
719
|
-
message: `invalid status \`${value}\` (expected ${
|
|
725
|
+
message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
|
|
720
726
|
});
|
|
721
727
|
}
|
|
722
728
|
} else if (known === "spec") {
|
|
@@ -737,7 +743,7 @@ function parseFields(node, lines, from, to, errors) {
|
|
|
737
743
|
return;
|
|
738
744
|
}
|
|
739
745
|
}
|
|
740
|
-
function
|
|
746
|
+
function parseIntentFile(relPath, text) {
|
|
741
747
|
const errors = [];
|
|
742
748
|
const meta = parseFrontmatter2(text, errors);
|
|
743
749
|
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
@@ -748,7 +754,7 @@ function parseJourney(relPath, text) {
|
|
|
748
754
|
if (h) headings.push({ index: i, ...h });
|
|
749
755
|
}
|
|
750
756
|
const h1 = headings.find((h) => h.depth === 1);
|
|
751
|
-
let
|
|
757
|
+
let statement;
|
|
752
758
|
if (h1) {
|
|
753
759
|
const paragraph = [];
|
|
754
760
|
for (let i = h1.index + 1; i < lines.length; i++) {
|
|
@@ -760,7 +766,7 @@ function parseJourney(relPath, text) {
|
|
|
760
766
|
if (line === MASKED_LINE || parseHeading(line)) break;
|
|
761
767
|
paragraph.push(line.trim());
|
|
762
768
|
}
|
|
763
|
-
if (paragraph.length)
|
|
769
|
+
if (paragraph.length) statement = paragraph.join(" ");
|
|
764
770
|
}
|
|
765
771
|
const nodes = [];
|
|
766
772
|
const stack = [];
|
|
@@ -776,7 +782,7 @@ function parseJourney(relPath, text) {
|
|
|
776
782
|
if (parentIndex !== void 0) {
|
|
777
783
|
node.parent = parentIndex;
|
|
778
784
|
const parent = nodes[parentIndex];
|
|
779
|
-
if (parent) parent.
|
|
785
|
+
if (parent) parent.isTerminal = false;
|
|
780
786
|
}
|
|
781
787
|
const next = headings[k + 1];
|
|
782
788
|
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
@@ -786,32 +792,32 @@ function parseJourney(relPath, text) {
|
|
|
786
792
|
nodes.push(node);
|
|
787
793
|
}
|
|
788
794
|
const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
|
|
789
|
-
return { ...meta ? { meta } : {}, title, ...
|
|
795
|
+
return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
|
|
790
796
|
}
|
|
791
|
-
function
|
|
792
|
-
const dir = join6(targetDir,
|
|
797
|
+
function listIntentFiles(targetDir) {
|
|
798
|
+
const dir = join6(targetDir, INTENTS_DIR);
|
|
793
799
|
if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
|
|
794
800
|
return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
|
|
795
801
|
}
|
|
796
|
-
function
|
|
797
|
-
return
|
|
798
|
-
const path = `${
|
|
802
|
+
function readIntentFiles(targetDir) {
|
|
803
|
+
return listIntentFiles(targetDir).map((file) => {
|
|
804
|
+
const path = `${INTENTS_DIR}/${file}`;
|
|
799
805
|
const text = readFileSync5(join6(targetDir, path), "utf8");
|
|
800
|
-
return { path, file, ...
|
|
806
|
+
return { path, file, ...parseIntentFile(path, text) };
|
|
801
807
|
});
|
|
802
808
|
}
|
|
803
|
-
function
|
|
804
|
-
const
|
|
805
|
-
const problems =
|
|
809
|
+
function loadIntentFiles(targetDir) {
|
|
810
|
+
const intentFiles = readIntentFiles(targetDir);
|
|
811
|
+
const problems = intentFiles.flatMap(
|
|
806
812
|
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
807
813
|
);
|
|
808
814
|
if (problems.length) {
|
|
809
815
|
throw new Error(
|
|
810
|
-
`invalid
|
|
816
|
+
`invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
|
|
811
817
|
${problems.join("\n")}`
|
|
812
818
|
);
|
|
813
819
|
}
|
|
814
|
-
return
|
|
820
|
+
return intentFiles;
|
|
815
821
|
}
|
|
816
822
|
|
|
817
823
|
// src/renderers/common.ts
|
|
@@ -861,12 +867,13 @@ function frontmatterDataForCmd(cmd) {
|
|
|
861
867
|
description: cmd.meta.description
|
|
862
868
|
};
|
|
863
869
|
if (cmd.meta.args && cmd.meta.args.length > 0) {
|
|
864
|
-
data.args = cmd.meta.args.map((a) => {
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
}
|
|
868
|
-
|
|
869
|
-
|
|
870
|
+
data.args = cmd.meta.args.map((a) => ({
|
|
871
|
+
name: a.name,
|
|
872
|
+
type: a.type,
|
|
873
|
+
...a.type === "enum" ? { values: a.values } : {},
|
|
874
|
+
...a.default !== void 0 ? { default: a.default } : {},
|
|
875
|
+
...a.required === false ? { required: false } : {}
|
|
876
|
+
}));
|
|
870
877
|
}
|
|
871
878
|
return data;
|
|
872
879
|
}
|
|
@@ -899,16 +906,16 @@ function buildUmbrellaBody(extras) {
|
|
|
899
906
|
...extras.hasQualityDoc ? [
|
|
900
907
|
"- `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."
|
|
901
908
|
] : [],
|
|
902
|
-
...extras.
|
|
903
|
-
"- `docs/
|
|
909
|
+
...extras.hasIntents ? [
|
|
910
|
+
"- `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."
|
|
904
911
|
] : [],
|
|
905
912
|
"",
|
|
906
913
|
"## Doc-first",
|
|
907
914
|
"",
|
|
908
915
|
"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.",
|
|
909
916
|
"",
|
|
910
|
-
...extras.
|
|
911
|
-
"- Visible change of behavior \u2192 a `proposed`
|
|
917
|
+
...extras.hasIntents ? [
|
|
918
|
+
"- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
|
|
912
919
|
] : [],
|
|
913
920
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
914
921
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
@@ -1038,16 +1045,16 @@ function getRenderer(engine) {
|
|
|
1038
1045
|
return RENDERERS[engine];
|
|
1039
1046
|
}
|
|
1040
1047
|
|
|
1041
|
-
// src/renderers/
|
|
1042
|
-
var INTRO = "User
|
|
1043
|
-
function
|
|
1044
|
-
const lines = ["#
|
|
1045
|
-
const sorted = [...
|
|
1046
|
-
for (const
|
|
1047
|
-
const status =
|
|
1048
|
-
const actors =
|
|
1049
|
-
lines.push(`- [${
|
|
1050
|
-
for (const node of
|
|
1048
|
+
// src/renderers/intents-index.ts
|
|
1049
|
+
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 .`.";
|
|
1050
|
+
function buildIntentsIndex(intentFiles) {
|
|
1051
|
+
const lines = ["# Intents", "", INTRO, ""];
|
|
1052
|
+
const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
1053
|
+
for (const intentFile of sorted) {
|
|
1054
|
+
const status = intentFile.meta?.status ?? "proposed";
|
|
1055
|
+
const actors = intentFile.meta?.actors.join(", ") ?? "";
|
|
1056
|
+
lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
|
|
1057
|
+
for (const node of intentFile.nodes) {
|
|
1051
1058
|
lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
|
|
1052
1059
|
}
|
|
1053
1060
|
}
|
|
@@ -1125,14 +1132,14 @@ function render(input) {
|
|
|
1125
1132
|
availableCommands: Array.from(exposedCmds.values()),
|
|
1126
1133
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
1127
1134
|
hasQualityDoc: input.hasQualityDoc === true,
|
|
1128
|
-
|
|
1135
|
+
hasIntents: (input.intentFiles?.length ?? 0) > 0
|
|
1129
1136
|
});
|
|
1130
1137
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
1131
1138
|
if (engines.includes("claude-code")) {
|
|
1132
1139
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
1133
1140
|
}
|
|
1134
|
-
if (input.
|
|
1135
|
-
files.push({ path:
|
|
1141
|
+
if (input.intentFiles && input.intentFiles.length > 0) {
|
|
1142
|
+
files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
|
|
1136
1143
|
}
|
|
1137
1144
|
return { files, warnings };
|
|
1138
1145
|
}
|
|
@@ -1165,8 +1172,8 @@ function planInit(args) {
|
|
|
1165
1172
|
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
1166
1173
|
const projectSkills = loadProjectSkills(args.targetDir);
|
|
1167
1174
|
const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
|
|
1168
|
-
const
|
|
1169
|
-
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc,
|
|
1175
|
+
const intentFiles = loadIntentFiles(args.targetDir);
|
|
1176
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
|
|
1170
1177
|
return { engines, output };
|
|
1171
1178
|
}
|
|
1172
1179
|
|
|
@@ -1245,7 +1252,7 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
|
1245
1252
|
".agents/",
|
|
1246
1253
|
".opencode/",
|
|
1247
1254
|
".harness-manifest.json",
|
|
1248
|
-
"docs/
|
|
1255
|
+
"docs/intents/README.md"
|
|
1249
1256
|
];
|
|
1250
1257
|
function gitignoreEntries(text) {
|
|
1251
1258
|
const entries = /* @__PURE__ */ new Set();
|
|
@@ -1304,23 +1311,23 @@ var gitignoreHarness = {
|
|
|
1304
1311
|
}
|
|
1305
1312
|
};
|
|
1306
1313
|
|
|
1307
|
-
// src/linters/
|
|
1308
|
-
var
|
|
1309
|
-
id: "lint:
|
|
1310
|
-
pillars: ["
|
|
1314
|
+
// src/linters/intent-anchors.ts
|
|
1315
|
+
var intentAnchors = {
|
|
1316
|
+
id: "lint:intent-anchors",
|
|
1317
|
+
pillars: ["intents"],
|
|
1311
1318
|
defaultSeverity: "error",
|
|
1312
|
-
suggestedSkills: ["/
|
|
1319
|
+
suggestedSkills: ["/intent"],
|
|
1313
1320
|
run(repoRoot) {
|
|
1314
1321
|
const issues = [];
|
|
1315
|
-
for (const
|
|
1316
|
-
for (const node of
|
|
1322
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1323
|
+
for (const node of intentFile.nodes) {
|
|
1317
1324
|
if (node.effectiveStatus === "deprecated") continue;
|
|
1318
1325
|
for (const anchor of node.anchors) {
|
|
1319
1326
|
if (trackedPathExists(repoRoot, anchor)) continue;
|
|
1320
1327
|
issues.push({
|
|
1321
1328
|
linter: this.id,
|
|
1322
1329
|
severity: "error",
|
|
1323
|
-
file:
|
|
1330
|
+
file: intentFile.path,
|
|
1324
1331
|
line: node.line,
|
|
1325
1332
|
message: `"${node.title}": anchor matches no file: ${anchor}`
|
|
1326
1333
|
});
|
|
@@ -1331,28 +1338,28 @@ var journeyAnchors = {
|
|
|
1331
1338
|
}
|
|
1332
1339
|
};
|
|
1333
1340
|
|
|
1334
|
-
// src/linters/
|
|
1335
|
-
var
|
|
1336
|
-
id: "lint:
|
|
1337
|
-
pillars: ["
|
|
1341
|
+
// src/linters/intent-graph.ts
|
|
1342
|
+
var intentGraph = {
|
|
1343
|
+
id: "lint:intent-graph",
|
|
1344
|
+
pillars: ["intents"],
|
|
1338
1345
|
defaultSeverity: "warning",
|
|
1339
|
-
suggestedSkills: ["/
|
|
1346
|
+
suggestedSkills: ["/intent"],
|
|
1340
1347
|
run(repoRoot) {
|
|
1341
|
-
const
|
|
1342
|
-
const
|
|
1343
|
-
(
|
|
1348
|
+
const intentFiles = readIntentFiles(repoRoot);
|
|
1349
|
+
const terminals = intentFiles.flatMap(
|
|
1350
|
+
(intentFile) => intentFile.nodes.filter((node) => node.isTerminal).map((node) => ({ intentFile, node }))
|
|
1344
1351
|
);
|
|
1345
|
-
const created = new Set(
|
|
1352
|
+
const created = new Set(terminals.flatMap(({ node }) => node.creates));
|
|
1346
1353
|
const issues = [];
|
|
1347
|
-
for (const {
|
|
1354
|
+
for (const { intentFile, node } of terminals) {
|
|
1348
1355
|
for (const entity of node.requires) {
|
|
1349
1356
|
if (created.has(entity)) continue;
|
|
1350
1357
|
issues.push({
|
|
1351
1358
|
linter: this.id,
|
|
1352
1359
|
severity: "warning",
|
|
1353
|
-
file:
|
|
1360
|
+
file: intentFile.path,
|
|
1354
1361
|
line: node.line,
|
|
1355
|
-
message: `"${node.title}": entity \`${entity}\` is required here but no
|
|
1362
|
+
message: `"${node.title}": entity \`${entity}\` is required here but no terminal intent creates it`
|
|
1356
1363
|
});
|
|
1357
1364
|
}
|
|
1358
1365
|
}
|
|
@@ -1360,43 +1367,43 @@ var journeyGraph = {
|
|
|
1360
1367
|
}
|
|
1361
1368
|
};
|
|
1362
1369
|
|
|
1363
|
-
// src/linters/
|
|
1370
|
+
// src/linters/intent-util.ts
|
|
1364
1371
|
import { posix } from "path";
|
|
1365
|
-
function
|
|
1372
|
+
function intentFileSpecs(meta) {
|
|
1366
1373
|
if (!meta) return [];
|
|
1367
1374
|
return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
|
|
1368
1375
|
}
|
|
1369
|
-
function resolveSpecPath(
|
|
1376
|
+
function resolveSpecPath(filePath, spec) {
|
|
1370
1377
|
const withoutFragment = spec.split("#")[0] ?? "";
|
|
1371
|
-
return posix.normalize(posix.join(posix.dirname(
|
|
1378
|
+
return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
|
|
1372
1379
|
}
|
|
1373
1380
|
|
|
1374
|
-
// src/linters/
|
|
1381
|
+
// src/linters/intent-schema.ts
|
|
1375
1382
|
var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
|
|
1376
|
-
var
|
|
1377
|
-
id: "lint:
|
|
1378
|
-
pillars: ["
|
|
1383
|
+
var intentSchema = {
|
|
1384
|
+
id: "lint:intent-schema",
|
|
1385
|
+
pillars: ["intents"],
|
|
1379
1386
|
defaultSeverity: "error",
|
|
1380
|
-
suggestedSkills: ["/
|
|
1387
|
+
suggestedSkills: ["/intent"],
|
|
1381
1388
|
run(repoRoot) {
|
|
1382
1389
|
const issues = [];
|
|
1383
|
-
for (const
|
|
1390
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1384
1391
|
const report = (message, line) => {
|
|
1385
1392
|
issues.push({
|
|
1386
1393
|
linter: this.id,
|
|
1387
1394
|
severity: "error",
|
|
1388
|
-
file:
|
|
1395
|
+
file: intentFile.path,
|
|
1389
1396
|
...line !== void 0 ? { line } : {},
|
|
1390
1397
|
message
|
|
1391
1398
|
});
|
|
1392
1399
|
};
|
|
1393
|
-
for (const error of
|
|
1394
|
-
for (const spec of
|
|
1395
|
-
if (!fileExists(repoRoot, resolveSpecPath(
|
|
1400
|
+
for (const error of intentFile.errors) report(error.message, error.line);
|
|
1401
|
+
for (const spec of intentFileSpecs(intentFile.meta)) {
|
|
1402
|
+
if (!fileExists(repoRoot, resolveSpecPath(intentFile.path, spec))) {
|
|
1396
1403
|
report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
|
|
1397
1404
|
}
|
|
1398
1405
|
}
|
|
1399
|
-
for (const node of
|
|
1406
|
+
for (const node of intentFile.nodes) {
|
|
1400
1407
|
const at = (message) => report(`"${node.title}": ${message}`, node.line);
|
|
1401
1408
|
for (const { key, line } of node.unknownFields) {
|
|
1402
1409
|
report(
|
|
@@ -1404,15 +1411,15 @@ var journeySchema = {
|
|
|
1404
1411
|
line
|
|
1405
1412
|
);
|
|
1406
1413
|
}
|
|
1407
|
-
if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(
|
|
1414
|
+
if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(intentFile.path, node.spec))) {
|
|
1408
1415
|
report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
|
|
1409
1416
|
}
|
|
1410
|
-
if (!node.
|
|
1411
|
-
for (const field of
|
|
1417
|
+
if (!node.isTerminal) {
|
|
1418
|
+
for (const field of TERMINAL_FIELDS) {
|
|
1412
1419
|
const line = node.fieldLines[field];
|
|
1413
1420
|
if (line !== void 0) {
|
|
1414
1421
|
report(
|
|
1415
|
-
`"${node.title}": \`${field}:\` is a
|
|
1422
|
+
`"${node.title}": \`${field}:\` is a field of a terminal intent, this node has sub-intents`,
|
|
1416
1423
|
line
|
|
1417
1424
|
);
|
|
1418
1425
|
}
|
|
@@ -1420,14 +1427,14 @@ var journeySchema = {
|
|
|
1420
1427
|
continue;
|
|
1421
1428
|
}
|
|
1422
1429
|
if (Object.keys(node.fieldLines).length === 0) {
|
|
1423
|
-
at("a
|
|
1430
|
+
at("a terminal intent carries at least one field");
|
|
1424
1431
|
continue;
|
|
1425
1432
|
}
|
|
1426
1433
|
if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
|
|
1427
|
-
at("an `implemented`
|
|
1434
|
+
at("an `implemented` intent needs `anchors:`");
|
|
1428
1435
|
}
|
|
1429
1436
|
if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
|
|
1430
|
-
at("a `proposed`
|
|
1437
|
+
at("a `proposed` intent needs `acceptance:` with at least one `- ` item");
|
|
1431
1438
|
}
|
|
1432
1439
|
}
|
|
1433
1440
|
}
|
|
@@ -1435,7 +1442,7 @@ var journeySchema = {
|
|
|
1435
1442
|
}
|
|
1436
1443
|
};
|
|
1437
1444
|
|
|
1438
|
-
// src/linters/
|
|
1445
|
+
// src/linters/intent-vocabulary.ts
|
|
1439
1446
|
var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
|
|
1440
1447
|
var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
|
|
1441
1448
|
function entitySlug(term) {
|
|
@@ -1460,19 +1467,19 @@ function vocabularyOf(specText) {
|
|
|
1460
1467
|
}
|
|
1461
1468
|
return terms;
|
|
1462
1469
|
}
|
|
1463
|
-
var
|
|
1464
|
-
id: "lint:
|
|
1465
|
-
pillars: ["
|
|
1470
|
+
var intentVocabulary = {
|
|
1471
|
+
id: "lint:intent-vocabulary",
|
|
1472
|
+
pillars: ["intents"],
|
|
1466
1473
|
defaultSeverity: "error",
|
|
1467
1474
|
suggestedSkills: ["/spec"],
|
|
1468
1475
|
run(repoRoot) {
|
|
1469
1476
|
const issues = [];
|
|
1470
|
-
for (const
|
|
1471
|
-
const used =
|
|
1477
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1478
|
+
const used = intentFile.nodes.flatMap(
|
|
1472
1479
|
(node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
|
|
1473
1480
|
);
|
|
1474
1481
|
if (used.length === 0) continue;
|
|
1475
|
-
const specs =
|
|
1482
|
+
const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
|
|
1476
1483
|
if (specs.length === 0) continue;
|
|
1477
1484
|
const entities = /* @__PURE__ */ new Set();
|
|
1478
1485
|
let hasVocabulary = false;
|
|
@@ -1486,7 +1493,7 @@ var journeyVocabulary = {
|
|
|
1486
1493
|
issues.push({
|
|
1487
1494
|
linter: this.id,
|
|
1488
1495
|
severity: "warning",
|
|
1489
|
-
file:
|
|
1496
|
+
file: intentFile.path,
|
|
1490
1497
|
message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
|
|
1491
1498
|
});
|
|
1492
1499
|
continue;
|
|
@@ -1496,7 +1503,7 @@ var journeyVocabulary = {
|
|
|
1496
1503
|
issues.push({
|
|
1497
1504
|
linter: this.id,
|
|
1498
1505
|
severity: "error",
|
|
1499
|
-
file:
|
|
1506
|
+
file: intentFile.path,
|
|
1500
1507
|
line: node.line,
|
|
1501
1508
|
message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
|
|
1502
1509
|
});
|
|
@@ -1714,7 +1721,7 @@ var specTechAgnostic = {
|
|
|
1714
1721
|
// src/linters/tracks-drift.ts
|
|
1715
1722
|
import fg5 from "fast-glob";
|
|
1716
1723
|
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
1717
|
-
var
|
|
1724
|
+
var INTENTS_DIR2 = "docs/intents";
|
|
1718
1725
|
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
1719
1726
|
function expandGlob(repoRoot, pattern) {
|
|
1720
1727
|
if (pattern.includes("*")) {
|
|
@@ -1723,20 +1730,20 @@ function expandGlob(repoRoot, pattern) {
|
|
|
1723
1730
|
return [pattern];
|
|
1724
1731
|
}
|
|
1725
1732
|
function trackedPaths(dir, file, text, data) {
|
|
1726
|
-
if (dir ===
|
|
1727
|
-
const anchors =
|
|
1733
|
+
if (dir === INTENTS_DIR2) {
|
|
1734
|
+
const anchors = parseIntentFile(file, text).nodes.flatMap((node) => node.anchors);
|
|
1728
1735
|
return anchors.length > 0 ? [...new Set(anchors)] : void 0;
|
|
1729
1736
|
}
|
|
1730
1737
|
return Array.isArray(data.tracks) ? data.tracks : void 0;
|
|
1731
1738
|
}
|
|
1732
1739
|
var tracksDrift = {
|
|
1733
1740
|
id: "lint:tracks-drift",
|
|
1734
|
-
pillars: ["handbook", "tests", "workflow", "
|
|
1741
|
+
pillars: ["handbook", "tests", "workflow", "intents"],
|
|
1735
1742
|
defaultSeverity: "warning",
|
|
1736
1743
|
suggestedSkills: ["/drift", "/handbook"],
|
|
1737
1744
|
run(repoRoot) {
|
|
1738
1745
|
const issues = [];
|
|
1739
|
-
for (const dir of [...TRACKED_DIRS2,
|
|
1746
|
+
for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
|
|
1740
1747
|
const files = listMarkdown(repoRoot, dir);
|
|
1741
1748
|
for (const f of files) {
|
|
1742
1749
|
const text = readText(repoRoot, f);
|
|
@@ -1784,10 +1791,10 @@ var ALL_LINTERS = [
|
|
|
1784
1791
|
orphanDecisions,
|
|
1785
1792
|
gitignoreHarness,
|
|
1786
1793
|
qualitySchema,
|
|
1787
|
-
|
|
1788
|
-
|
|
1789
|
-
|
|
1790
|
-
|
|
1794
|
+
intentSchema,
|
|
1795
|
+
intentAnchors,
|
|
1796
|
+
intentVocabulary,
|
|
1797
|
+
intentGraph,
|
|
1791
1798
|
generatedFresh
|
|
1792
1799
|
];
|
|
1793
1800
|
function runLinters(repoRoot, opts = {}) {
|