@miroshnik/elves 2026.1105.1 → 2026.1106.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.
@@ -122,6 +122,9 @@ var Q = {
122
122
  repository(owner: $owner, name: $name) {
123
123
  issues(states: OPEN, first: 100, after: $after) { pageInfo { hasNextPage endCursor } nodes { id number } }
124
124
  }
125
+ }`,
126
+ IssueItems: `query IssueItems($ids: [ID!]!) {
127
+ nodes(ids: $ids) { ... on Issue { id projectItems(first: 20) { nodes { id isArchived project { id } } } } }
125
128
  }`,
126
129
  OwnerProjects: `query OwnerProjects($login: String!, $query: String!) {
127
130
  repositoryOwner(login: $login) { ... on ProjectV2Owner { projectsV2(first: 20, query: $query) { nodes { ${REF} } } } }
@@ -486,7 +489,24 @@ function loadState(io, slug) {
486
489
  const repo = loadRepo(io, slug);
487
490
  const openIssues = pages((after) => graphql(io, Q.RepoIssues, { owner, name, after }).repository.issues);
488
491
  const main = mainProject(repo);
489
- return { repo, project: main ? loadProject(io, main.id) : null, openIssues, labels: loadLabels(io, slug), decisions: loadDecisions(io, slug), merge: loadMerge(io, slug) };
492
+ const project = main ? loadProject(io, main.id) : null;
493
+ if (project)
494
+ markUnlisted(io, project, openIssues);
495
+ return { repo, project, openIssues, labels: loadLabels(io, slug), decisions: loadDecisions(io, slug), merge: loadMerge(io, slug) };
496
+ }
497
+ var NODES_PAGE = 100;
498
+ function markUnlisted(io, project, issues) {
499
+ const listed = new Set(project.items.map((it) => it.issue?.id));
500
+ const missing = issues.filter((i) => !listed.has(i.id));
501
+ for (let k = 0;k < missing.length; k += NODES_PAGE) {
502
+ const batch = missing.slice(k, k + NODES_PAGE);
503
+ for (const n of graphql(io, Q.IssueItems, { ids: batch.map((i) => i.id) })?.nodes ?? []) {
504
+ const item = (n?.projectItems?.nodes ?? []).find((it) => it?.project?.id === project.id && !it.isArchived);
505
+ const issue = batch.find((i) => i.id === n?.id);
506
+ if (item && issue)
507
+ issue.unlisted = item.id;
508
+ }
509
+ }
490
510
  }
491
511
  var statusChecks = (rule) => rule?.type === "REQUIRED_STATUS_CHECKS" ? { strict: !!rule.parameters?.strictRequiredStatusChecksPolicy, contexts: (rule.parameters?.requiredStatusChecks ?? []).map((c) => c.context) } : null;
492
512
  var WORST = ["fail", "cancel", "pending", "skipping", "pass"];
@@ -900,9 +920,13 @@ function analyze(s) {
900
920
  closedAdd(`closed without being done, but in the project: ${nums(dropped.map((it) => it.issue))}`, api(`remove from the project ${nums(dropped.map((it) => it.issue))}`, ...dropped.map((it) => ({ op: "DeleteItem", input: { projectId: p.id, itemId: it.id } }))));
901
921
  const open = add("open", `Open tasks of the repository — in the project, with ${STATUS}`);
902
922
  const inProject = new Set(issues.map((it) => it.issue.id));
903
- const missing = s.openIssues.filter((i) => !inProject.has(i.id));
923
+ const outside = s.openIssues.filter((i) => !inProject.has(i.id));
924
+ const unlisted = outside.filter((i) => i.unlisted);
925
+ const missing = outside.filter((i) => !i.unlisted);
904
926
  if (missing.length)
905
927
  open(`not in the project: ${nums(missing)}`, api(`add to the project ${nums(missing)}`, ...missing.map((i) => ({ op: "AddItem", input: { projectId: p.id, contentId: i.id } }))));
928
+ if (unlisted.length)
929
+ open.note(`GitHub doesn't return the item in the project's list: ${unlisted.map((i) => `#${i.number} (${i.unlisted})`).join(", ")} — the issue's projectItems has it`);
906
930
  const noStatus = issues.filter((it) => it.issue.state === "OPEN" && !it.status);
907
931
  if (noStatus.length)
908
932
  open(`without ${STATUS}: ${nums(noStatus.map((it) => it.issue))}`, ...statusReady ? [api(`${STATUS} ${q(N.status.backlog)}: ${nums(noStatus.map((it) => it.issue))}`, ...noStatus.map((it) => setStatus(it, N.status.backlog)))] : []);
@@ -2073,13 +2097,14 @@ function parseEdits(args) {
2073
2097
  var CHECKLIST_RE = /^(\s*[-*+]\s+)\[ \](\s)/;
2074
2098
  var LIST_ITEM_RE = /^(?:[-*+]|\d+\.)\s/;
2075
2099
  var headingLevel = (line) => /^(#{1,6})\s/.exec(line)?.[1]?.length ?? 0;
2076
- function itemMarker(prev) {
2100
+ var QUESTIONS_SECTION_RE = new RegExp(`^(?:${locale_default.every((n) => n.sections.questions).map(locale_default.escapeRe).join("|")})\\s*$`);
2101
+ function itemMarker(prev, none) {
2077
2102
  const numbered = /^(\d+)\.\s/.exec(prev ?? "");
2078
2103
  if (numbered)
2079
2104
  return `${Number(numbered[1]) + 1}. `;
2080
2105
  const bullet = /^([-*+]\s+)(\[[ xX]\]\s)?/.exec(prev ?? "");
2081
2106
  if (!bullet)
2082
- return "- ";
2107
+ return none;
2083
2108
  return bullet[2] ? `${bullet[1]}[ ] ` : bullet[1];
2084
2109
  }
2085
2110
  function applyEdits(number, body, edits) {
@@ -2118,7 +2143,7 @@ function applyEdits(number, body, edits) {
2118
2143
  last--;
2119
2144
  const item = e.item.trim().replace(/\s*\r?\n\s*/g, " ");
2120
2145
  const prev = lines.slice(from + 1, last + 1).filter((l) => LIST_ITEM_RE.test(l)).at(-1);
2121
- const line = `${LIST_ITEM_RE.test(item) ? "" : itemMarker(prev)}${item}`;
2146
+ const line = `${LIST_ITEM_RE.test(item) ? "" : itemMarker(prev, QUESTIONS_SECTION_RE.test(heading) ? "1. " : "- ")}${item}`;
2122
2147
  lines.splice(last + 1, 0, ...last === from ? ["", line] : [line]);
2123
2148
  done.push(`added to ${q(heading)}`);
2124
2149
  } else {
@@ -3114,9 +3139,8 @@ var MEANING_CHECKS = [0, 2, 4];
3114
3139
  var ANSWER_MARK_RE = /(?:^\s*(?:\d+\.\s+)?|[?.!—–][»"'*_)`]*\s+)[*_(]*✅/;
3115
3140
  var THEMATIC_BREAK_RE = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/;
3116
3141
  function questionItems(body) {
3117
- const section = new RegExp(`^(?:${locale_default.every((n) => n.sections.questions).map(locale_default.escapeRe).join("|")})\\s*$`);
3118
3142
  const lines = body.split(/\r?\n/);
3119
- const from = lines.findIndex((l) => section.test(l));
3143
+ const from = lines.findIndex((l) => QUESTIONS_SECTION_RE.test(l));
3120
3144
  if (from < 0)
3121
3145
  return [];
3122
3146
  const items = [];
@@ -4705,10 +4729,10 @@ Examples:
4705
4729
 
4706
4730
  An edit of the description in one call, not gh issue view --json body, a file and gh issue edit --body-file: --replace —
4707
4731
  the text must occur exactly once; --add — an item at the end of the section «## …» (without a list marker — the one of
4708
- the section's last item: «- [ ]», the next number, its bullet); --check — «- [ ]» → «- [x]» of the one unchecked item
4709
- with the text. Several edits — in order, each sees the previous one's result, written together; any not found or
4710
- ambiguous — refused (code 2), the description untouched. Questions are answered by task answer. A cloud session — over
4711
- the repository's REST.
4732
+ the section's last item: «- [ ]», the next number, its bullet; the questions section's first — «1.»); --check —
4733
+ «- [ ]» → «- [x]» of the one unchecked item with the text. Several edits — in order, each sees the previous one's result,
4734
+ written together; any not found or ambiguous — refused (code 2), the description untouched. Questions are answered by
4735
+ task answer. A cloud session — over the repository's REST.
4712
4736
 
4713
4737
  Examples:
4714
4738
  github task edit 42 --replace "PDF only" "PDF and CSV"
@@ -2,7 +2,7 @@ import {
2
2
  invariant2,
3
3
  codeOnly2,
4
4
  envNamesInCode2
5
- } from "./harness-dms3b7ke.js";
5
+ } from "./harness-yh1g3dhm.js";
6
6
  import {
7
7
  locale_default
8
8
  } from "./harness-1rfkbdbn.js";
@@ -23,7 +23,7 @@ import {
23
23
  envNamesInCode2,
24
24
  dotenvNames2,
25
25
  envVars2
26
- } from "./harness-dms3b7ke.js";
26
+ } from "./harness-yh1g3dhm.js";
27
27
  export {
28
28
  ENV_SERVICE2 as ENV_SERVICE,
29
29
  codeFiles2 as codeFiles,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miroshnik/elves",
3
- "version": "2026.1105.1",
3
+ "version": "2026.1106.0",
4
4
  "type": "module",
5
5
  "description": "Elves — a development flow with AI agents: shared rules and skills for any agent; install — bunx @miroshnik/elves install -g; the installer and skill scripts — TypeScript under Bun, tests — bun test in tests/",
6
6
  "repository": {
@@ -72,5 +72,5 @@
72
72
  "eslint-plugin-boundaries": "^7.2.0",
73
73
  "knip": "^6.41.0"
74
74
  },
75
- "gitHead": "339b95668410844065b1be68aedac49b040f2d6e"
75
+ "gitHead": "d649573363ee2ff2ff7a1a04eb5ee94ca8d20fd8"
76
76
  }
@@ -372,7 +372,12 @@ outside git — ❌, `update` puts it into its commit.
372
372
  Others aren't checked.
373
373
  7. Closed tasks — in Done; those closed without being done (not planned,
374
374
  duplicate) — outside the project.
375
- 8. The repository's open tasks — in the project, each has a `Status`.
375
+ 8. The repository's open tasks — in the project, each has a `Status`. A
376
+ task the project's item list doesn't return is rechecked by its own
377
+ `projectItems`: a live (not archived) item of this project — GitHub
378
+ hasn't reindexed the project yet, and `AddItem` would answer with that
379
+ same item — is an `○` line with the item's id, item ✅, `task start`
380
+ goes on.
376
381
  9. Decision labels — by the spec tree of the default branch (via the API): the
377
382
  label name is the topic name (folder
378
383
  `tests/capabilities|standards|architecture/<topic>` or a model module), kind
@@ -622,11 +627,12 @@ text must occur exactly once; `--add "## <section>" "<item>"` — at the end of
622
627
  the section (it ends at a heading of its level or higher, or `---`: the cloud
623
628
  proxy's signature isn't in it); an item without a list marker gets the one of
624
629
  the section's last top-level item — `- [ ]` after a checklist, the next
625
- number after a numbered list, its bullet, otherwise `- `; `--check "<text>"`
626
- — `- [ ]` → `- [x]` of the one unchecked item containing the text. Several
627
- edits — in order, each sees the previous one's result, one write. Refused
628
- before any change (code 2), none of the call's edits written: a text not
629
- found or found twice, no such section or two of them, no or two unchecked
630
+ number after a numbered list, its bullet, otherwise `- `, in the questions
631
+ section `1.` (`task answer` finds a question by its number); `--check
632
+ "<text>"` — `- [ ]` → `- [x]` of the one unchecked item containing the text.
633
+ Several edits — in order, each sees the previous one's result, one write.
634
+ Refused before any change (code 2), none of the call's edits written: a text
635
+ not found or found twice, no such section or two of them, no or two unchecked
630
636
  items, an edit missing a value. Questions — `task answer`. A cloud session —
631
637
  over the repository's REST.
632
638
 
@@ -333,7 +333,11 @@ export interface Merge {
333
333
  export interface State {
334
334
  repo: { id: string; name: string; nameWithOwner: string; owner: Owner; linked: ProjectRef[] };
335
335
  project: Project | null;
336
- openIssues: { id: string; number: number }[];
336
+ /**
337
+ * `unlisted` — the id of the project's item that the project's item list doesn't return, though the issue's own
338
+ * `projectItems` has it (`markUnlisted`).
339
+ */
340
+ openIssues: { id: string; number: number; unlisted?: string }[];
337
341
  labels: Label[];
338
342
  decisions: Decisions;
339
343
  /** An empty repository (no default branch) — null. */
@@ -413,6 +417,10 @@ export const Q = {
413
417
  repository(owner: $owner, name: $name) {
414
418
  issues(states: OPEN, first: 100, after: $after) { pageInfo { hasNextPage endCursor } nodes { id number } }
415
419
  }
420
+ }`,
421
+ /** The project items of issues by their ids — as the issue sees them (`markUnlisted`), at most `NODES_PAGE` ids. */
422
+ IssueItems: `query IssueItems($ids: [ID!]!) {
423
+ nodes(ids: $ids) { ... on Issue { id projectItems(first: 20) { nodes { id isArchived project { id } } } } }
416
424
  }`,
417
425
  OwnerProjects: `query OwnerProjects($login: String!, $query: String!) {
418
426
  repositoryOwner(login: $login) { ... on ProjectV2Owner { projectsV2(first: 20, query: $query) { nodes { ${REF} } } } }
@@ -834,9 +842,33 @@ const mainProject = (repo: State["repo"]) => repo.linked.find((p) => p.title ===
834
842
  export function loadState(io: Io, slug: string): State {
835
843
  const [owner, name] = slug.split("/") as [string, string];
836
844
  const repo = loadRepo(io, slug);
837
- const openIssues = pages<{ id: string; number: number }>((after) => graphql(io, Q.RepoIssues, { owner, name, after }).repository.issues);
845
+ const openIssues = pages<State["openIssues"][number]>((after) => graphql(io, Q.RepoIssues, { owner, name, after }).repository.issues);
838
846
  const main = mainProject(repo);
839
- return { repo, project: main ? loadProject(io, main.id) : null, openIssues, labels: loadLabels(io, slug), decisions: loadDecisions(io, slug), merge: loadMerge(io, slug) };
847
+ const project = main ? loadProject(io, main.id) : null;
848
+ if (project) markUnlisted(io, project, openIssues);
849
+ return { repo, project, openIssues, labels: loadLabels(io, slug), decisions: loadDecisions(io, slug), merge: loadMerge(io, slug) };
850
+ }
851
+
852
+ /** How many ids one `nodes(ids:)` query takes — GitHub's limit. */
853
+ const NODES_PAGE = 100;
854
+
855
+ /**
856
+ * GitHub sometimes leaves an item out of `ProjectV2.items` that the issue has (#791): `issue.projectItems` returns it,
857
+ * `AddItem` answers with that same item, and the list doesn't change until GitHub reindexes the project. An open issue
858
+ * missing from the list is asked by its own `projectItems`: a live (not archived) item of this project marks it
859
+ * `unlisted` — the task is in the project, it isn't added again.
860
+ */
861
+ function markUnlisted(io: Io, project: Project, issues: State["openIssues"]): void {
862
+ const listed = new Set(project.items.map((it) => it.issue?.id));
863
+ const missing = issues.filter((i) => !listed.has(i.id));
864
+ for (let k = 0; k < missing.length; k += NODES_PAGE) {
865
+ const batch = missing.slice(k, k + NODES_PAGE);
866
+ for (const n of graphql(io, Q.IssueItems, { ids: batch.map((i) => i.id) })?.nodes ?? []) {
867
+ const item = (n?.projectItems?.nodes ?? []).find((it: Any) => it?.project?.id === project.id && !it.isArchived);
868
+ const issue = batch.find((i) => i.id === n?.id);
869
+ if (item && issue) issue.unlisted = item.id;
870
+ }
871
+ }
840
872
  }
841
873
 
842
874
  const statusChecks = (rule: Any): { strict: boolean; contexts: string[] } | null =>
@@ -1319,8 +1351,13 @@ export function analyze(s: State): Check[] {
1319
1351
 
1320
1352
  const open = add("open", `Open tasks of the repository — in the project, with ${STATUS}`);
1321
1353
  const inProject = new Set(issues.map((it) => it.issue!.id));
1322
- const missing = s.openIssues.filter((i) => !inProject.has(i.id));
1354
+ // the item the issue has but the project's list doesn't return — the task is in the project: AddItem would answer
1355
+ // with the same item and change nothing (#791)
1356
+ const outside = s.openIssues.filter((i) => !inProject.has(i.id));
1357
+ const unlisted = outside.filter((i) => i.unlisted);
1358
+ const missing = outside.filter((i) => !i.unlisted);
1323
1359
  if (missing.length) open(`not in the project: ${nums(missing)}`, api(`add to the project ${nums(missing)}`, ...missing.map((i) => ({ op: "AddItem", input: { projectId: p.id, contentId: i.id } }))));
1360
+ if (unlisted.length) open.note(`GitHub doesn't return the item in the project's list: ${unlisted.map((i) => `#${i.number} (${i.unlisted})`).join(", ")} — the issue's projectItems has it`);
1324
1361
  const noStatus = issues.filter((it) => it.issue!.state === "OPEN" && !it.status);
1325
1362
  if (noStatus.length) open(`without ${STATUS}: ${nums(noStatus.map((it) => it.issue!))}`, ...(statusReady ? [api(`${STATUS} ${q(N.status.backlog)}: ${nums(noStatus.map((it) => it.issue!))}`, ...noStatus.map((it) => setStatus(it, N.status.backlog)))] : []));
1326
1363
 
@@ -2844,13 +2881,18 @@ const CHECKLIST_RE = /^(\s*[-*+]\s+)\[ \](\s)/;
2844
2881
  const LIST_ITEM_RE = /^(?:[-*+]|\d+\.)\s/;
2845
2882
  /** A Markdown heading's level (`## …` — 2), not a heading — 0. */
2846
2883
  const headingLevel = (line: string) => /^(#{1,6})\s/.exec(line)?.[1]?.length ?? 0;
2884
+ /** The questions section's heading in any language of the dictionary: `questionItems` reads it, `task edit --add` numbers its first item. */
2885
+ const QUESTIONS_SECTION_RE = new RegExp(`^(?:${locale.every((n) => n.sections.questions).map(locale.escapeRe).join("|")})\\s*$`);
2847
2886
 
2848
- /** The marker of an item added after `prev`, the section's last item: `- [ ]` after a checklist item, the next number, its bullet; none — `- `. */
2849
- function itemMarker(prev: string | undefined): string {
2887
+ /**
2888
+ * The marker of an item added after `prev`, the section's last item: `- [ ]` after a checklist item, the next number,
2889
+ * its bullet; none — `none`.
2890
+ */
2891
+ function itemMarker(prev: string | undefined, none: string): string {
2850
2892
  const numbered = /^(\d+)\.\s/.exec(prev ?? "");
2851
2893
  if (numbered) return `${Number(numbered[1]) + 1}. `;
2852
2894
  const bullet = /^([-*+]\s+)(\[[ xX]\]\s)?/.exec(prev ?? "");
2853
- if (!bullet) return "- ";
2895
+ if (!bullet) return none;
2854
2896
  return bullet[2] ? `${bullet[1]}[ ] ` : bullet[1]!;
2855
2897
  }
2856
2898
 
@@ -2858,7 +2900,8 @@ function itemMarker(prev: string | undefined): string {
2858
2900
  * The edits applied in order to the description, each to the result of the previous one; an edit that is ambiguous or
2859
2901
  * finds nothing — an error, so none is written. `--add` — after the section's last non-blank line (the section ends at
2860
2902
  * a heading of its level or higher, or a thematic break: the cloud proxy's signature isn't the section's); an item
2861
- * without a list marker gets the one of the section's last item: `- [ ]`, the next number, or `-`.
2903
+ * without a list marker gets the one of the section's last item: `- [ ]`, the next number, or `-`; the first one of the
2904
+ * questions section — `1.`: `task answer <N> <k>` finds a question by its number (#795).
2862
2905
  */
2863
2906
  export function applyEdits(number: number, body: string, edits: Edit[]): { body: string; done: string[] } {
2864
2907
  const eol = body.includes("\r\n") ? "\r\n" : "\n";
@@ -2888,7 +2931,7 @@ export function applyEdits(number: number, body: string, edits: Edit[]): { body:
2888
2931
  const item = e.item.trim().replace(/\s*\r?\n\s*/g, " ");
2889
2932
  // the section's last top-level item: a nested one under it isn't the list's
2890
2933
  const prev = lines.slice(from + 1, last + 1).filter((l) => LIST_ITEM_RE.test(l)).at(-1);
2891
- const line = `${LIST_ITEM_RE.test(item) ? "" : itemMarker(prev)}${item}`;
2934
+ const line = `${LIST_ITEM_RE.test(item) ? "" : itemMarker(prev, QUESTIONS_SECTION_RE.test(heading) ? "1. " : "- ")}${item}`;
2892
2935
  // a heading right before the item — a blank line between them, as the section's own items have
2893
2936
  lines.splice(last + 1, 0, ...(last === from ? ["", line] : [line]));
2894
2937
  done.push(`added to ${q(heading)}`);
@@ -4304,9 +4347,8 @@ const THEMATIC_BREAK_RE = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/;
4304
4347
  * into the item.
4305
4348
  */
4306
4349
  export function questionItems(body: string): { k: number; text: string; lines: string[]; answered: boolean; first: number; last: number }[] {
4307
- const section = new RegExp(`^(?:${locale.every((n) => n.sections.questions).map(locale.escapeRe).join("|")})\\s*$`);
4308
4350
  const lines = body.split(/\r?\n/);
4309
- const from = lines.findIndex((l) => section.test(l));
4351
+ const from = lines.findIndex((l) => QUESTIONS_SECTION_RE.test(l));
4310
4352
  if (from < 0) return [];
4311
4353
  const items: { first: number; last: number }[] = [];
4312
4354
  for (let i = from + 1; i < lines.length && !/^##\s/.test(lines[i]!) && !THEMATIC_BREAK_RE.test(lines[i]!); i++) {
@@ -6394,10 +6436,10 @@ Examples:
6394
6436
 
6395
6437
  An edit of the description in one call, not gh issue view --json body, a file and gh issue edit --body-file: --replace —
6396
6438
  the text must occur exactly once; --add — an item at the end of the section «## …» (without a list marker — the one of
6397
- the section's last item: «- [ ]», the next number, its bullet); --check — «- [ ]» → «- [x]» of the one unchecked item
6398
- with the text. Several edits — in order, each sees the previous one's result, written together; any not found or
6399
- ambiguous — refused (code 2), the description untouched. Questions are answered by task answer. A cloud session — over
6400
- the repository's REST.
6439
+ the section's last item: «- [ ]», the next number, its bullet; the questions section's first — «1.»); --check —
6440
+ «- [ ]» → «- [x]» of the one unchecked item with the text. Several edits — in order, each sees the previous one's result,
6441
+ written together; any not found or ambiguous — refused (code 2), the description untouched. Questions are answered by
6442
+ task answer. A cloud session — over the repository's REST.
6401
6443
 
6402
6444
  Examples:
6403
6445
  github task edit 42 --replace "PDF only" "PDF and CSV"
@@ -226,7 +226,9 @@ no decision claims is dead and is deleted.
226
226
  creation the labels of its topics (the "Task tracking" section in `AGENTS.md`)
227
227
  and the scenarios section: future `it` names (or "describe › it") as a list,
228
228
  optionally with the decision folder in front, as `spec-diff` prints a test
229
- (`` `billing` · a draft is deleted `` — only a test of that folder matches):
229
+ (`` `billing` · a draft is deleted `` — only a test of that folder matches;
230
+ in a topic with sections — the section, `` `permissions` · … `` or
231
+ `` `routes#permissions` · … ``, while the topic matches any of its sections):
230
232
  from them the user sees the requirements before the code and can stop it.
231
233
  For a "registry + invariant" standard the harness generates the tests per
232
234
  element — the scenario is the name of the `describe` in which `invariant`
@@ -228,10 +228,12 @@ names the folders and asks for a full run's report, `--json` lists the tests
228
228
  in `unreported`. A file without such a call or test in the head — its tests
229
229
  are removed.
230
230
 
231
- A test's identity is the folder path + the `describe` chain + `it`: a move
232
- between files of one folder isn't a change, a move to another folder is
233
- removed and added (the requirement changed home). The output is a ready
234
- section for the PR body:
231
+ A test's identity is its place (the folder, in a topic's section —
232
+ `<folder>#<section>`), the `describe` chain and `it`: a move between files of
233
+ one section (`<section>.<part>.test.ts`, `<package>/<section>.test.ts`) isn't a
234
+ change; same-named tests of two sections are two requirements, a move to
235
+ another section or folder is removed and added (the requirement changed home).
236
+ The output is a ready section for the PR body:
235
237
 
236
238
  ```markdown
237
239
  ## Spec (tests)
@@ -838,16 +840,19 @@ the project's CI" below.
838
840
 
839
841
  ## Identity and renames
840
842
 
841
- - A test key is the folder path + the `describe` chain + the name. The file
842
- isn't part of the key: the rule treats the folder as the spec's unit, and
843
- moving tests between files of one capability doesn't change requirements.
843
+ - A test key is its place, the `describe` chain and the name; the place is
844
+ the folder, in a topic's section — `<folder>#<section>`. A topic's section
845
+ is a decision of its own (#685), so it's part of the key (#794): same-named
846
+ tests of two sections are two requirements. The file isn't: moving tests
847
+ between files of one section doesn't change requirements.
844
848
  - A rename is searched for in two steps: (1) the same file and `describe`, a
845
849
  similar name, similarity ≥ 0.6 by Ratcliff/Obershelp (like
846
850
  `difflib.SequenceMatcher.ratio`), greedily by descending similarity; (2) the
847
- same folder and the same name, a different `describe` — the `describe` was
848
- renamed or the test was moved to another section, including from another
849
- file. The threshold is deliberately high: hiding a removed requirement as a
850
- rename is worse than showing a rename as a deletion and an addition. Step 2
851
+ same place and the same name, a different `describe` — the `describe` was
852
+ renamed or the test was moved under another one, including from another
853
+ file of the section. The threshold is deliberately high: hiding a removed
854
+ requirement as a rename is worse than showing a rename as a deletion and an
855
+ addition. Step 2
851
856
  isn't limited to one file since #63: the requirement text is the same, and
852
857
  regrouping into the main file's capability sections (unit and e2e of one
853
858
  capability under one `describe`, files renamed to `<name>.test.ts`) would
@@ -1,10 +1,11 @@
1
1
  #!/usr/bin/env bun
2
2
  /**
3
- * spec-diff — the spec diff: test names (folder path + describe + it) between the base branch and HEAD, by static
4
- * parsing of the files at the two revisions (git cat-file, no runs and no checkouts). Prints a markdown section for the
5
- * PR body: removed (first), changed (renamed in the same file), added, moved into the tree (a test vanished from a file
6
- * outside tests/ and appeared in the tree under the same name — a summary by folders); plus test files changed outside
7
- * the tests/ tree and the number of the PR's new names that aren't statements in the project language.
3
+ * spec-diff — the spec diff: test names (the place — a topic and its section — + describe + it) between the base
4
+ * branch and HEAD, by static parsing of the files at the two revisions (git cat-file, no runs and no checkouts). Prints
5
+ * a markdown section for the PR body: removed (first), changed (renamed in the same file), added, moved into the tree
6
+ * (a test vanished from a file outside tests/ and appeared in the tree under the same name — a summary by folders);
7
+ * plus test files changed outside the tests/ tree and the number of the PR's new names that aren't statements in the
8
+ * project language.
8
9
  *
9
10
  * bun spec-diff.ts [--base origin/main] [--head HEAD | --worktree] [--root DIR] [--no-merge-base] [--json]
10
11
  * [--scenarios issue.md | -]
@@ -337,13 +338,14 @@ export function diff(
337
338
  const changed = pair(removed, added, (r, a) => unique(r) && bodyKey(r) === bodyKey(a), () => 1, 1);
338
339
  // 2) the same file and describe, a similar name — the test is renamed
339
340
  changed.push(...pair(removed, added, (r, a) => r.path === a.path && sameDescribes(r, a), (r, a) => ratio(r.name, a.name), RENAME_RATIO));
340
- // 3) the same folder and name, a different describe — the describe is renamed or the test moved to another section,
341
- // including from another file of the folder: the requirement text is the same, the section changed
341
+ // 3) the same place and name, a different describe — the describe is renamed or the test moved under another
342
+ // describe, including from another file of the topic's section: the requirement text is the same, the describe
343
+ // changed. Another section of the topic is another decision (#794): the move is removed and added
342
344
  changed.push(
343
345
  ...pair(
344
346
  removed,
345
347
  added,
346
- (r, a) => L.folderOf(r) === L.folderOf(a) && r.name === a.name,
348
+ (r, a) => placeOf(r) === placeOf(a) && r.name === a.name,
347
349
  (r, a) => ratio(r.describes.join(" › "), a.describes.join(" › ")),
348
350
  0,
349
351
  ),
@@ -365,19 +367,10 @@ export function unmovedFiles(outFiles: string[], moved: Moved[], count: Map<stri
365
367
  const outMark = (t: Test) => (L.classify(t.path)[0] === "out" ? ` ⚠️ ${N.spec.diff.outsideMark}` : "");
366
368
 
367
369
  /**
368
- * A test's place in the lists — its folder and, in a topic's section (#685), the section after `#`, as in the spec-doc
369
- * anchor: `tests/standards/routes#permissions`; the topic's own statements (a file named after the folder) — the
370
- * folder. The lists go by place.
370
+ * A test's place in the lists (`L.placeOf`) — its folder and, in a topic's section (#685), the section after `#`:
371
+ * `tests/standards/routes#permissions`. The lists go by place, and a harness check's place is by its file the same way.
371
372
  */
372
- export const placeOf = (t: Test): string => placeAt(t.path);
373
-
374
- /** A harness check's place by its file — as in the test lists: a topic's section `<folder>#<section>` or the folder. */
375
- function placeAt(file: string): string {
376
- const folder = L.decisionFolder(file);
377
- if (folder === null) return path.posix.dirname(file);
378
- const section = L.sectionOf(file);
379
- return section === null ? folder : `${folder}#${section}`;
380
- }
373
+ export const placeOf = (t: Test): string => L.placeOf(t.path);
381
374
 
382
375
  /** The lists by place — topic and section; within a place — the order of the difference. */
383
376
  const byPlace = <T>(list: T[], test: (x: T) => Test): T[] =>
@@ -802,6 +795,9 @@ export function render(
802
795
  return lines.join("\n").trimEnd() + "\n";
803
796
  }
804
797
 
798
+ /** A test in `--json` — the same in the lists and the scenarios: the file tells apart the sections of one folder. */
799
+ const testJson = (t: Test) => ({ file: t.path, folder: L.folderOf(t), describes: t.describes, name: t.name });
800
+
805
801
  /** `unreported` — base tests only a run names, of files a partial report didn't run: not compared (`unreportedTests`). */
806
802
  function asJson(
807
803
  baseLabel: string,
@@ -813,18 +809,17 @@ function asJson(
813
809
  notStatements: number,
814
810
  unreported: Test[],
815
811
  ): string {
816
- const d = (t: Test) => ({ file: t.path, folder: L.folderOf(t), describes: t.describes, name: t.name });
817
812
  return (
818
813
  JSON.stringify(
819
814
  {
820
815
  base: baseLabel,
821
- removed: removed.map(d),
822
- changed: changed.map(([o, n]) => ({ old: d(o), new: d(n) })),
823
- added: added.map(d),
824
- moved: moved.map((m) => ({ from: m.from, ...d(m.test) })),
816
+ removed: removed.map(testJson),
817
+ changed: changed.map(([o, n]) => ({ old: testJson(o), new: testJson(n) })),
818
+ added: added.map(testJson),
819
+ moved: moved.map((m) => ({ from: m.from, ...testJson(m.test) })),
825
820
  out_of_tree_files: outFiles,
826
821
  not_statements: notStatements,
827
- unreported: unreported.map(d),
822
+ unreported: unreported.map(testJson),
828
823
  },
829
824
  null,
830
825
  2,
@@ -871,11 +866,17 @@ export function scenarioFolder(scenario: string): { folder: string | null; name:
871
866
  }
872
867
 
873
868
  /**
874
- * The prefix names the folder as spec-diff prints it (`tests/capabilities/billing`, with `#section` in a topic with
875
- * sections) or by its tail (`billing`, `capabilities/billing`).
869
+ * The prefix names the place as spec-diff prints it (`tests/capabilities/billing`, `tests/capabilities/routes#permissions`
870
+ * in a topic with sections) or by its tail (`billing`, `capabilities/billing`, `routes#permissions`). In a topic with
871
+ * sections (#685) the decision is a section, and the prefix is its name alone (`permissions`) — only that section's
872
+ * tests; the topic in front — any of its sections, as the decision folder before sections (#790).
876
873
  */
877
874
  const inFolder = (folder: string | null, places: string[]): boolean =>
878
- folder === null || places.some((p) => p === folder || p.endsWith(`/${folder}`));
875
+ folder === null ||
876
+ places.some((p) => {
877
+ const [topic, section] = p.split("#");
878
+ return section === folder || [p, topic!].some((q) => q === folder || q.endsWith(`/${folder}`));
879
+ });
879
880
 
880
881
  /** A scenario and what it became: new tests, a harness check's describe, or nothing. */
881
882
  export interface Found {
@@ -888,7 +889,7 @@ export interface Found {
888
889
  * Scenario ↔ new tests: each one whose it name or "describe › it" chain matches it (case-insensitive, without outer
889
890
  * quotes and a trailing mark) — one scenario is checked both on the server and in the UI; no test — the describe of a
890
891
  * new harness check, its name or chain. A scenario with the decision folder in front (`scenarioFolder`) is matched only
891
- * within that folder; without it — in any. Tests that check generated (`generated` — only from the report) are tests of
892
+ * within that folder or topic's section (`inFolder`); without it — in any. Tests that check generated (`generated` — only from the report) are tests of
892
893
  * its scenario, not beyond the scenarios.
893
894
  */
894
895
  export function matchScenarios(
@@ -1104,7 +1105,7 @@ export async function main(argv: string[]): Promise<number> {
1104
1105
  const changedOut = outOfTreeFiles(base, v.head, top, prefix, v.worktree);
1105
1106
  const { pool, count, gone } = outOfTreePool(base, v.head, top, root, prefix, changedOut, v.worktree);
1106
1107
  ({ removed, changed, added, moved } = diff(baseTests, headTests, pool));
1107
- checks = freshChecks(baseScan.checks, headScan.checks, [placeAt, placeAt]);
1108
+ checks = freshChecks(baseScan.checks, headScan.checks, [L.placeOf, L.placeOf]);
1108
1109
  notStatements = newNotStatements([...added, ...changed.map(([, n]) => n)], baseTests, LANG);
1109
1110
  outFiles = unmovedFiles(changedOut, moved, count, gone);
1110
1111
  // lint disables — only in changed code files: a removed or added exception is always in the PR diff
@@ -1116,8 +1117,8 @@ export async function main(argv: string[]): Promise<number> {
1116
1117
  const untracked = v.worktree ? gitText(["ls-files", "--others", "--exclude-standard", "-z", "--", "."], top).split("\0") : [];
1117
1118
  const changedAll = [...changedPaths, ...untracked].filter((f) => f.startsWith(prefix) && CODE.test(f) && !FLOW_COPY.test(f.slice(prefix.length)));
1118
1119
  decisionData = {
1119
- base: await decisionsAt(base, top, prefix, changedAll, baseScan.checks, placeAt),
1120
- head: await decisionsAt(v.worktree ? null : v.head, top, prefix, changedAll, headScan.checks, placeAt),
1120
+ base: await decisionsAt(base, top, prefix, changedAll, baseScan.checks, L.placeOf),
1121
+ head: await decisionsAt(v.worktree ? null : v.head, top, prefix, changedAll, headScan.checks, L.placeOf),
1121
1122
  };
1122
1123
  decisions = decisionLines(decisionData.base, decisionData.head, limit);
1123
1124
  } catch (e) {
@@ -1163,16 +1164,15 @@ export async function main(argv: string[]): Promise<number> {
1163
1164
  if (v.scenarios !== undefined) {
1164
1165
  if (v.json) {
1165
1166
  const j = JSON.parse(text);
1166
- const d = (t: Test) => ({ folder: L.folderOf(t), describes: t.describes, name: t.name });
1167
1167
  j.scenarios =
1168
1168
  scenarios === null
1169
1169
  ? null
1170
1170
  : match.found.map(({ scenario, tests, harness: h }) => ({
1171
1171
  scenario,
1172
- tests: tests.map(d),
1172
+ tests: tests.map(testJson),
1173
1173
  harness: h ? { folder: h.folder, describes: h.describes, checks: h.checks } : null,
1174
1174
  }));
1175
- j.extra_tests = match.extra.map(d);
1175
+ j.extra_tests = match.extra.map(testJson);
1176
1176
  text = JSON.stringify(j, null, 2) + "\n";
1177
1177
  } else {
1178
1178
  const listed = !summarized(removed, changed, added, limit);
@@ -56,9 +56,14 @@ export function folderOf(t: Test): string {
56
56
  return posix.dirname(t.path);
57
57
  }
58
58
 
59
- /** Requirement identity: folder path + describe + it (the file inside the folder doesn't matter). */
59
+ /**
60
+ * Requirement identity: the test's place (`placeOf` — the topic and its section) + describe + it. A topic's section is
61
+ * a decision of its own (#685): same-named tests of two sections are two requirements, a move between sections is
62
+ * removed and added; the file inside a section (`<section>.<part>.test.ts`, `<package>/<section>.test.ts`) doesn't
63
+ * matter (#794).
64
+ */
60
65
  export function keyOf(t: Test): string {
61
- return JSON.stringify([folderOf(t), t.describes, t.name]);
66
+ return JSON.stringify([placeOf(t.path), t.describes, t.name]);
62
67
  }
63
68
 
64
69
  export function titleOf(t: Test): string {
@@ -123,6 +128,19 @@ export function sectionOf(file: string): string | null {
123
128
  return section === folder.split("/")[2] ? null : section;
124
129
  }
125
130
 
131
+ /**
132
+ * A test file's place in the spec — its decision folder and, in a topic's section (#685), the section after `#`, as
133
+ * the spec-doc anchor: `tests/standards/routes#permissions`; the topic's own statements (a file named after the
134
+ * folder) — the folder; outside the decision tree — the file's folder. spec-diff's lists and the requirement identity
135
+ * (`keyOf`) go by place.
136
+ */
137
+ export function placeOf(file: string): string {
138
+ const folder = decisionFolder(file);
139
+ if (folder === null) return posix.dirname(file);
140
+ const section = sectionOf(file);
141
+ return section === null ? folder : `${folder}#${section}`;
142
+ }
143
+
126
144
  /** Decision folder exceptions — the `exceptions/` directory, a file per harness registry element (`exceptionsIn`). */
127
145
  export const EXCEPTIONS_DIR = "exceptions";
128
146