@miroshnik/elves 2026.1026.0 → 2026.1026.2

package/dist/github/scripts/github.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import {
   locale_default
-} from "../../spec/scripts/harness-bysg15km.js";
+} from "../../spec/scripts/harness-xqp7tdyr.js";
 
 // skills/github/scripts/github.ts
 import { spawnSync } from "node:child_process";

package/dist/spec/scripts/architecture.js

@@ -2,10 +2,10 @@ import {
   invariant2,
   codeOnly2,
   envNamesInCode2
-} from "./harness-4hzx0w5b.js";
+} from "./harness-q8q5bvat.js";
 import {
   locale_default
-} from "./harness-bysg15km.js";
+} from "./harness-xqp7tdyr.js";
 
 // skills/spec/scripts/architecture.ts
 import { readdirSync, readFileSync } from "node:fs";

package/dist/spec/scripts/eslint-config.js

@@ -2,7 +2,7 @@
 import { readdirSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-var FRAGMENT = new Set(["eslint.ts", "eslint.mts", "eslint.mjs", "eslint.js"]);
+var FRAGMENT = /^(?:[^.]+\.)?eslint\.(?:ts|mts|mjs|js)$/;
 var SKIP = new Set(["node_modules", ".git"]);
 var SKIP_REL = new Set(["tests/lib"]);
 function eslintFragments(root, dirs = ["tests"]) {
@@ -19,7 +19,7 @@ function eslintFragments(root, dirs = ["tests"]) {
       if (e.isDirectory()) {
         if (!SKIP.has(e.name) && !SKIP_REL.has(path.relative(root, full).split(path.sep).join("/")))
           walk(full);
-      } else if (FRAGMENT.has(e.name))
+      } else if (FRAGMENT.test(e.name))
         out.push(full);
     }
   };

package/dist/spec/scripts/{harness-4hzx0w5b.js → harness-q8q5bvat.js}

@@ -1,6 +1,6 @@
 import {
   locale_default
-} from "./harness-bysg15km.js";
+} from "./harness-xqp7tdyr.js";
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
@@ -15282,7 +15282,8 @@ function elementMarks(it, spec, key, tag) {
   const folder = spec.fileOf && callerFolder();
   if (!folder)
     return out;
-  const decision = path2.posix.basename(folder.rel);
+  const topic = path2.posix.basename(folder.rel);
+  const section = path2.posix.basename(folder.file).split(".")[0];
   const byFile = new Map;
   for (const item of spec.items) {
     const f = spec.fileOf(item);
@@ -15291,6 +15292,7 @@ function elementMarks(it, spec, key, tag) {
   }
   const shared = [];
   const missing = [];
+  const unknown = [];
   for (const [file, keys] of byFile) {
     let text;
     try {
@@ -15303,7 +15305,18 @@ function elementMarks(it, spec, key, tag) {
     if (!text.includes("spec-"))
       continue;
     const shown = path2.isAbsolute(file) ? shownPath(file) : file;
-    const mine = marksIn2(shown, text).filter((m) => m.decision === decision);
+    const all = marksIn2(shown, text);
+    const known = all.some((m) => m.decision !== topic && m.decision !== section) ? decisionNames(folder.base) : null;
+    for (const m of all) {
+      if (!known || known.has(m.decision) || m.decision === topic || m.decision === section)
+        continue;
+      const at = `${m.file}:${m.line}`;
+      if (seen.has(`mark\x00${at}`))
+        continue;
+      seen.add(`mark\x00${at}`);
+      unknown.push(`${at}: spec-${m.kind}(${m.decision}) — no topic or section of tests/ is named «${m.decision}»: a topic's name takes the file out of all its sections, a section's — out of that section's invariants`);
+    }
+    const mine = all.filter((m) => m.decision === topic || m.decision === section);
     out.skipped.push(...mine.filter((m) => m.rule && m.rule !== spec.rule));
     const marks = mine.filter((m) => !m.rule || m.rule === spec.rule);
     if (!marks.length)
@@ -15328,11 +15341,34 @@ function elementMarks(it, spec, key, tag) {
   if (missing.length) {
     it(locale_default.fill(localeNames().spec.harness.elementFiles, { tag }), () => {
       throw new Error(missing.join(`
+`));
+    });
+  }
+  if (unknown.length) {
+    it(locale_default.fill(localeNames().spec.harness.markNames, { tag }), () => {
+      throw new Error(unknown.join(`
 `));
     });
   }
   return out;
 }
+var decisionNamesAt = new Map;
+function decisionNames(base) {
+  let names = decisionNamesAt.get(base);
+  if (names)
+    return names;
+  names = new Set;
+  for (const f of filesUnder("tests", base)) {
+    if (!/\.(?:test|spec|e2e)\.[cm]?[jt]sx?$/.test(f))
+      continue;
+    const parts = f.split("/");
+    if (parts.length > 3)
+      names.add(parts[2]);
+    names.add(path2.posix.basename(f).split(".")[0]);
+  }
+  decisionNamesAt.set(base, names);
+  return names;
+}
 function invariant2(it, spec) {
   legacyExceptions(it);
   const N = localeNames();

package/dist/spec/scripts/{harness-bysg15km.js → harness-xqp7tdyr.js}

@@ -399,6 +399,7 @@ var en_default = {
       violator: "violator does not pass{tag}: {name}",
       oneRecord: "one record per element{tag}",
       markOneElement: "a mark belongs in one element's file{tag}",
+      markNames: "a mark names a topic or its section{tag}",
       elementFiles: "element files from fileOf exist{tag}",
       outside: "outside scope{tag}: {item}",
       exception: "exception{tag}: {item} (#{issue})",
@@ -885,6 +886,7 @@ var ru_default = {
       violator: "нарушитель не проходит{tag}: {name}",
       oneRecord: "у элемента одна запись — отметка или exceptions/ и outside{tag}",
       markOneElement: "отметка — в файле одного элемента{tag}",
+      markNames: "отметка называет тему или её раздел{tag}",
       elementFiles: "файлы элементов из fileOf есть на диске{tag}",
       outside: "вне охвата{tag}: {item}",
       exception: "исключение{tag}: {item} (#{issue})",

package/dist/spec/scripts/harness.js

@@ -23,7 +23,7 @@ import {
   envNamesInCode2,
   dotenvNames2,
   envVars2
-} from "./harness-4hzx0w5b.js";
+} from "./harness-q8q5bvat.js";
 export {
   ENV_SERVICE2 as ENV_SERVICE,
   codeFiles2 as codeFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miroshnik/elves",
-  "version": "2026.1026.0",
+  "version": "2026.1026.2",
   "type": "module",
   "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/",
   "repository": {
@@ -72,5 +72,5 @@
     "eslint-plugin-boundaries": "^7.2.0",
     "knip": "^6.41.0"
   },
-  "gitHead": "c5e6bd32225415d44c4e961766e72a639142fd1e"
+  "gitHead": "d4afa46ebc54c4c981f5f22822bebbd9c21e4d95"
 }

package/skills/github/locales/en.json

@@ -395,6 +395,7 @@
       "violator": "violator does not pass{tag}: {name}",
       "oneRecord": "one record per element{tag}",
       "markOneElement": "a mark belongs in one element's file{tag}",
+      "markNames": "a mark names a topic or its section{tag}",
       "elementFiles": "element files from fileOf exist{tag}",
       "outside": "outside scope{tag}: {item}",
       "exception": "exception{tag}: {item} (#{issue})",

package/skills/github/locales/ru.json

@@ -395,6 +395,7 @@
       "violator": "нарушитель не проходит{tag}: {name}",
       "oneRecord": "у элемента одна запись — отметка или exceptions/ и outside{tag}",
       "markOneElement": "отметка — в файле одного элемента{tag}",
+      "markNames": "отметка называет тему или её раздел{tag}",
       "elementFiles": "файлы элементов из fileOf есть на диске{tag}",
       "outside": "вне охвата{tag}: {item}",
       "exception": "исключение{tag}: {item} (#{issue})",

package/skills/github/scripts/locale.ts

@@ -295,6 +295,7 @@ interface SpecNames {
     violator: string;
     oneRecord: string;
     markOneElement: string;
+    markNames: string;
     elementFiles: string;
     outside: string;
     exception: string;

package/skills/spec/SKILL.md

@@ -183,7 +183,7 @@ each one — `checks.md` next to this file:
 
 - a convention on every item of a registry from the code — `invariant`
   (`standards/<name>/`);
-- a lint rule — `examples`, `eslintLinter`, the folder's `eslint.ts` fragment
+- a lint rule — `examples`, `eslintLinter`, an `eslint.ts` or `<section>.eslint.ts` fragment
   collected by `collectEslint`;
 - out of scope and exceptions — `fileOf`, marks `spec-outside(<decision>)` /
   `spec-exception(<decision>) #N`, `exceptionsIn()`, `lintExceptions`;

package/skills/spec/canon.md

@@ -44,8 +44,8 @@ no decision claims is dead and is deleted.
   - a topic of one section has the same anatomy — `<topic>.md` and a section
     with a name of its own; a test file named after its folder
     (`<name>/<name>.test.ts`) is a decision not regrouped yet;
-  - the mechanism — in the same folder: an `eslint.ts` fragment, an ast-grep
-    `rule.yml`. The project's tool configs (`eslint.config.*`, `sgconfig.yml`)
+  - the mechanism — in the same folder: an ESLint fragment (the topic's
+    `eslint.ts`, a section's `<section>.eslint.ts`), an ast-grep `rule.yml`. The project's tool configs (`eslint.config.*`, `sgconfig.yml`)
     only collect them from the tree (the harness's `collectEslint`) — a rule
     has one home;
   - `exceptions/<section>/` — exceptions for elements without a file of their

package/skills/spec/checks.md

@@ -7,8 +7,8 @@ Which check for what:
 | What to check | With what | Where in `tests/` |
 |---|---|---|
 | A convention on every item of a registry from the code ("every mutation writes an audit record") | `invariant` | `standards/<name>/` |
-| A lint rule: «not allowed», «allowed», «outside scope» | `examples`, `eslintLinter` | `standards/<name>/` + an `eslint.ts` fragment |
-| An ESLint rule in a standard's folder | `collectEslint` in `eslint.config.*` | the tree's `eslint.ts` fragments |
+| A lint rule: «not allowed», «allowed», «outside scope» | `examples`, `eslintLinter` | `standards/<topic>/` + an ESLint fragment (`eslint.ts`, `<section>.eslint.ts`) |
+| An ESLint rule in a standard's folder | `collectEslint` in `eslint.config.*` | the tree's `eslint.ts` and `<section>.eslint.ts` fragments |
 | Out of scope and an item's exception with its own file | `fileOf` in `invariant`; a mark `spec-outside(<decision>)` / `spec-exception(<decision>) #N` in the file (`marksIn`), in JSON — the value of the `"//"` key | the item's file (a route, a script, a migration, a workspace package's `package.json`) |
 | Exceptions with a ratchet | `exceptionsIn()` → `exceptions` in `invariant`; a disable `-- #N reason` + `lintExceptions` | the decision folder's `exceptions/<item>.json`; migration — `spec-exceptions` |
 | Architecture model: module boundaries, directories, packages | `boundariesConfig`, `architecture` | `architecture/model.ts`, `architecture/<name>/` |
@@ -142,7 +142,8 @@ Biome will be added when a project needs them (the core doesn't depend on the
 linter, `Linter` is an interface with one required method, `lint`).
 
 **A rule lives in its standard's folder.** A flat config fragment is
-`eslint.ts` next to the test (`export default [{ files: ["src/domain/**"],
+the topic's `eslint.ts` or a section's `<section>.eslint.ts` — each standard
+of a topic keeps its own — next to the test (`export default [{ files: ["src/domain/**"],
 rules: {…} }]`, paths from the project root); the project's `eslint.config.*`
 only collects the tree's fragments — `lint` and the editor see the rule as
 usual:
@@ -168,7 +169,9 @@ export default restrict({ id: "no-alert", selectors: ["CallExpression[callee.nam
 
 A fragment is `eslint.ts`, `eslint.mts` (ESM even in a project without
 `"type": "module"`, without the `MODULE_TYPELESS_PACKAGE_JSON` warning),
-`eslint.mjs` or `eslint.js`; `tests/lib` holds helpers, not fragments.
+`eslint.mjs` or `eslint.js`, a section's — the same under its prefix
+(`<section>.eslint.mts`); a knip entry for the fragments —
+`tests/**/*eslint.{ts,mts}`; `tests/lib` holds helpers, not fragments.
 
 **Exceptions are explicit, have a task, and go away when no longer needed.**
 
@@ -220,10 +223,13 @@ A fragment is `eslint.ts`, `eslint.mts` (ESM even in a project without
   The element is deleted — the mark goes too; two PRs don't edit a shared file.
   A record in `outside` or `exceptions/` outlived the element: one PR deleted a
   route, another added it as outside scope — after both merges `main` is red
-  (measurement #211, three of five breakages). `audit` is the decision folder's
-  name: a file may be an element of registries in different folders, and the
-  mark names its own; `audit/cancel` is the folder invariant with that `rule`,
-  without it — all of the folder's invariants. A mark starts the comment text
+  (measurement #211, three of five breakages). `audit` is a topic or its section:
+  the topic folder's name takes the file out of all its sections, a section's
+  name (`<topic>/audit.test.ts`) — out of that section's invariants only; a
+  name no topic or section of `tests/` has — red «a mark names a topic or its
+  section» with the mark's location. A file may be an element of registries in
+  different folders, and the mark names its own; `audit/cancel` is the
+  invariant with that `rule`, without it — all of them. A mark starts the comment text
   (`//`, `/*`, a block's `*`, `#`, `--`, `<!--`): in JS/TS — only in comments,
   not in strings; the format in the middle of prose isn't a mark (`marksIn`).
   JSON has no comments — there the mark is the value of the top-level key `"//"`
@@ -460,7 +466,10 @@ claimed behavior").
   entry points. The report is `.spec-claims.xml` (JUnit) in the standard's
   folder `tests/standards/entry-points` (`--standard`): pass it to `spec-doc`
   together with the runners' reports — the reconciliation gets into the spec
-  with the standard's `entry-points.md` description.
+  with the standard's `entry-points.md` description. A section of a topic — the
+  registry `tests/standards/<topic>/<section>.entries.ts`: the report goes to
+  `<topic>/<section>.test.ts` by that path (explicit `--standard`, `--section`
+  win), the description — `<section>.md`.
 
 **Scenarios — `sequence` and `trace`.** How the parts of the system interact in
 a scenario is a sequence diagram from a capability test's trace, not a drawing.

package/skills/spec/migration.md

@@ -143,7 +143,7 @@ a flat decision as a topic of one section. One task, one PR, in this order:
    `<topic>/<name>.md` (the other `<name>.*` files alongside), another test
    file of the folder `<name>/<file>.test.ts` → `<topic>/<name>.<file>.test.ts`
    (by its own name it would be a section of its own), a helper file under the
-   section's prefix (`<name>.preload.ts`), `<name>/exceptions/*.json` → `<topic>/exceptions/<name>/`, a package
+   section's prefix (`<name>.preload.ts`, the ESLint fragment `<name>/eslint.ts` → `<topic>/<name>.eslint.ts`), `<name>/exceptions/*.json` → `<topic>/exceptions/<name>/`, a package
    subfolder `<name>/<package>/` → `<topic>/<package>/`. The moves go in a
    commit of their own, without content edits, so history follows the files
    and `pr labels` reads them as mechanical. Each topic gets `<topic>.md`: its
@@ -154,7 +154,14 @@ a flat decision as a topic of one section. One task, one PR, in this order:
    and added.
 3. **Cross-references.** Every path `tests/<root>/<name>/…` — in code, marks,
    tool configs, CI fragments, docs and the README — is rewritten to the new
-   one; a search for each former path finds nothing outside the history.
+   one; a search for each former path finds nothing outside the history. A
+   mark `spec-outside(<name>)` / `spec-exception(<name>) #N` in an element's
+   file stays as is: `<name>` is now the section's name, and the mark takes
+   the file out of that section's invariants only; `spec-outside(<topic>)` —
+   out of all the topic's sections. A mark whose name no topic or section has
+   is red «a mark names a topic or its section». The `spec-claims` registry
+   moves as `tests/standards/<topic>/<section>.entries.ts`: the report goes
+   under that section by the path itself, no `--standard`/`--section`.
 4. **Labels.** After the merge — `github project check`, then `project fix
    --confirm`: a label whose name is a section of exactly one topic of the
    same root is merged into the topic's label on every task, closed ones too,

package/skills/spec/scripts/eslint-config.ts

@@ -1,7 +1,8 @@
 /**
- * eslint-config — assembling ESLint rules from the spec tree: a standard's rule lives as an `eslint.ts` fragment
- * (default — a flat config object or array) in its folder, next to the examples and the reason, and the project's
- * `eslint.config.*` only collects the fragments — `lint` and the editor see the rule as usual:
+ * eslint-config — assembling ESLint rules from the spec tree: a standard's rule lives as a fragment (default — a flat
+ * config object or array) in its topic folder, next to the examples and the reason — the topic's `eslint.ts` or a
+ * section's `<section>.eslint.ts`, so each standard of a topic keeps its own —, and the project's `eslint.config.*`
+ * only collects the fragments — `lint` and the editor see the rule as usual:
  *
  *   import { collectEslint } from "@miroshnik/elves/spec/eslint-config";
  *   export default [...base, ...(await collectEslint(import.meta.dirname))];
@@ -20,12 +21,13 @@ import { readdirSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-const FRAGMENT = new Set(["eslint.ts", "eslint.mts", "eslint.mjs", "eslint.js"]);
+/** A topic's fragment `eslint.ts` or a section's `<section>.eslint.ts` (`.mts`, `.mjs`, `.js` too). */
+const FRAGMENT = /^(?:[^.]+\.)?eslint\.(?:ts|mts|mjs|js)$/;
 const SKIP = new Set(["node_modules", ".git"]);
 // test helpers, not the spec: `spec-doc` skips them too
 const SKIP_REL = new Set(["tests/lib"]);
 
-/** Paths of `eslint.ts` fragments in the directories (by default `tests/`), in order. */
+/** Paths of the topics' `eslint.ts` and the sections' `<section>.eslint.ts` fragments in the directories (by default `tests/`), in order. */
 export function eslintFragments(root: string, dirs: string[] = ["tests"]): string[] {
   const out: string[] = [];
   const walk = (dir: string): void => {
@@ -39,7 +41,7 @@ export function eslintFragments(root: string, dirs: string[] = ["tests"]): strin
       const full = path.join(dir, e.name);
       if (e.isDirectory()) {
         if (!SKIP.has(e.name) && !SKIP_REL.has(path.relative(root, full).split(path.sep).join("/"))) walk(full);
-      } else if (FRAGMENT.has(e.name)) out.push(full);
+      } else if (FRAGMENT.test(e.name)) out.push(full);
     }
   };
   for (const d of dirs) walk(path.join(root, d));
@@ -67,7 +69,7 @@ const SPEC_PLUGIN: { meta: { name: string }; rules: Record<string, object> } = {
 
 /**
  * A standard's ban by AST selectors (as in `no-restricted-syntax`) — as its own rule `spec/<id>` in the shared `spec`
- * plugin: bans of different standards on the same files all apply. A standard's `eslint.ts` fragment:
+ * plugin: bans of different standards on the same files all apply. A standard's fragment (`eslint.ts`, `<section>.eslint.ts`):
  *
  *   export default restrict({ id: "no-alert", selectors: ["CallExpression[callee.name='alert']"], message: "…", files: ["src/**"] });
  */

package/skills/spec/scripts/harness.ts

@@ -107,9 +107,11 @@ interface Outside {
 
 /**
  * A mark in the element's file — a comment, like `eslint-disable` for lint: `spec-outside(<decision>[/<rule>]): reason`
- * or `spec-exception(<decision>[/<rule>]) #N: reason`. The decision is the decision folder's name (`audit` —
- * `tests/standards/audit`): a file can be an element of registries of different folders, the mark names its own;
- * `rule` is the folder's invariant, without it — all of them.
+ * or `spec-exception(<decision>[/<rule>]) #N: reason`. The decision is a topic or one of its sections (#745): the topic
+ * folder's name (`pages` — `tests/standards/pages`) covers all its sections, a section's name (`routes` —
+ * `pages/routes.test.ts`) only the invariants of that section — the former decision's mark keeps working after the
+ * regrouping. A file can be an element of registries of different folders, the mark names its own; `rule` is the
+ * invariant's, without it — all of them.
  */
 export interface Mark {
   kind: "outside" | "exception";
@@ -447,7 +449,9 @@ function elementMarks<T>(it: It, spec: Invariant<T>, key: (item: T) => string, t
   const out = { outside: [] as Outside[], exceptions: [] as Exception[], skipped: [] as Mark[] };
   const folder = spec.fileOf && callerFolder();
   if (!folder) return out;
-  const decision = path.posix.basename(folder.rel);
+  // a topic's name — all its sections, a section's (the test file's name, as in exceptionsIn) — only its own
+  const topic = path.posix.basename(folder.rel);
+  const section = path.posix.basename(folder.file).split(".")[0]!;
   const byFile = new Map<string, string[]>();
   for (const item of spec.items) {
     const f = spec.fileOf!(item);
@@ -455,6 +459,7 @@ function elementMarks<T>(it: It, spec: Invariant<T>, key: (item: T) => string, t
   }
   const shared: string[] = [];
   const missing: string[] = [];
+  const unknown: string[] = [];
   for (const [file, keys] of byFile) {
     let text: string;
     try {
@@ -467,7 +472,17 @@ function elementMarks<T>(it: It, spec: Invariant<T>, key: (item: T) => string, t
     if (!text.includes("spec-")) continue;
     // an absolute path (built from a root) is shown from the repository root, like other hints
     const shown = path.isAbsolute(file) ? shownPath(file) : file;
-    const mine = marksIn(shown, text).filter((m) => m.decision === decision);
+    const all = marksIn(shown, text);
+    // a name no topic or section has — the mark is taken by nobody and the element silently turns red or stays out
+    const known = all.some((m) => m.decision !== topic && m.decision !== section) ? decisionNames(folder.base) : null;
+    for (const m of all) {
+      if (!known || known.has(m.decision) || m.decision === topic || m.decision === section) continue;
+      const at = `${m.file}:${m.line}`;
+      if (seen.has(`mark\0${at}`)) continue;
+      seen.add(`mark\0${at}`);
+      unknown.push(`${at}: spec-${m.kind}(${m.decision}) — no topic or section of tests/ is named «${m.decision}»: a topic's name takes the file out of all its sections, a section's — out of that section's invariants`);
+    }
+    const mine = all.filter((m) => m.decision === topic || m.decision === section);
     out.skipped.push(...mine.filter((m) => m.rule && m.rule !== spec.rule));
     const marks = mine.filter((m) => !m.rule || m.rule === spec.rule);
     if (!marks.length) continue;
@@ -490,9 +505,34 @@ function elementMarks<T>(it: It, spec: Invariant<T>, key: (item: T) => string, t
       throw new Error(missing.join("\n"));
     });
   }
+  if (unknown.length) {
+    it(locale.fill(localeNames().spec.harness.markNames, { tag }), () => {
+      throw new Error(unknown.join("\n"));
+    });
+  }
   return out;
 }
 
+const decisionNamesAt = new Map<string, Set<string>>();
+
+/**
+ * Names a mark may give in a project (`base` — the directory with `tests/`): topic folders `tests/<kind>/<name>` and
+ * sections — the first part of a test file's name inside them.
+ */
+function decisionNames(base: string): Set<string> {
+  let names = decisionNamesAt.get(base);
+  if (names) return names;
+  names = new Set<string>();
+  for (const f of filesUnder("tests", base)) {
+    if (!/\.(?:test|spec|e2e)\.[cm]?[jt]sx?$/.test(f)) continue;
+    const parts = f.split("/");
+    if (parts.length > 3) names.add(parts[2]!);
+    names.add(path.posix.basename(f).split(".")[0]!);
+  }
+  decisionNamesAt.set(base, names);
+  return names;
+}
+
 /**
  * Tests of a convention: "registry is not empty" (a typo in a path doesn't pass silently), "violator does not pass"
  * (the check can fail) and a test per element. No counters in the names: the registry grows — the spec diff shows only

package/skills/spec/scripts/spec-claims.ts

@@ -15,7 +15,8 @@
  * section — `exceptions/<section>/`), a file per exception (`{ item, issue, reason }`): an entry point without a test,
  * with a task, until a test appears; once it appears — "remove the exception". The report is JUnit in the standard's
  * folder (`spec-doc` puts it into the spec with the description from the standard's `<folder>.md`; with `--section` — a
- * section of the topic `--standard` (#685), the description from `<section>.md`). Codes: 0 — everything is claimed,
+ * section of the topic `--standard` (#685), the description from `<section>.md`; without both flags a registry
+ * `tests/standards/<topic>/<section>.entries.ts` names that topic and section, #751). Codes: 0 — everything is claimed,
  * 1 — there are unclaimed ones or exception errors, 2 — a call error.
  */
 
@@ -38,6 +39,7 @@ is claimed, 1 — there are unclaimed ones or exception errors, 2 — a call err
 
 Examples:
   spec-claims --entries tests/standards/entry-points/entries.ts
+  spec-claims --entries tests/standards/routes/entry-points.entries.ts   # report: tests/standards/routes/entry-points.test.ts
   spec-claims --entries entries.json --journal .spec-journal --report .spec-claims.xml`;
 const CAPABILITIES = "tests/capabilities/";
 
@@ -92,6 +94,23 @@ ${body}
 `;
 }
 
+const DEFAULT_STANDARD = "tests/standards/entry-points";
+/** A registry `tests/standards/<topic>/<section>.entries.<ext>` — its topic and section (#751). */
+const SECTION_ENTRIES = /(?:^|\/)(tests\/standards\/[^/]+)\/([^/]+)\.entries\.(?:[cm]?[jt]s|json)$/;
+
+/**
+ * Where the report goes: explicit `--standard`/`--section` win; without them a registry
+ * `tests/standards/<topic>/<section>.entries.ts` names its topic and section — after regrouping decisions into topics
+ * the project moves the registry, and a default path hidden in the script would leave the report under the old decision
+ * (#751); otherwise — `tests/standards/entry-points`.
+ */
+function reportPlace(entries: string, standard?: string, section?: string): { standard: string; section: string } {
+  const m = SECTION_ENTRIES.exec(entries.split(path.sep).join("/"));
+  const topic = (standard ?? m?.[1] ?? DEFAULT_STANDARD).replace(/\/+$/, "");
+  const name = section ?? (standard === undefined && m ? m[2]! : path.posix.basename(topic));
+  return { standard: topic, section: name };
+}
+
 export async function main(argv: string[]): Promise<number> {
   let opts;
   try {
@@ -101,7 +120,7 @@ export async function main(argv: string[]): Promise<number> {
         entries: { type: "string" },
         journal: { type: "string", default: ".spec-journal" },
         exceptions: { type: "string" },
-        standard: { type: "string", default: "tests/standards/entry-points" },
+        standard: { type: "string" },
         section: { type: "string" },
         report: { type: "string", default: ".spec-claims.xml" },
         help: { type: "boolean", short: "h", default: false },
@@ -184,9 +203,9 @@ export async function main(argv: string[]): Promise<number> {
     cases.push({ name: locale.fill(N.spec.harness.exception, { tag: "", item: e.item, issue: e.issue }), failure });
   }
 
-  const standard = v.standard.replace(/\/+$/, "");
+  const { standard, section } = reportPlace(v.entries, v.standard, v.section);
   // a section of a topic (#685) — its file `<section>.test.ts`: spec-doc shows it under the section with `<section>.md`
-  writeFileSync(v.report, junit(`${standard}/${v.section ?? path.posix.basename(standard)}.test.ts`, N.spec.claims.describe, cases));
+  writeFileSync(v.report, junit(`${standard}/${section}.test.ts`, N.spec.claims.describe, cases));
   const unclaimed = entries.filter((id) => !excepted.has(id) && !claimed(id));
   const failed = cases.filter((c) => c.failure);
   console.error(

package/skills/spec/scripts/spec-diff.ts

@@ -203,9 +203,20 @@ export function regroupMap(baseFiles: Iterable<string>, headFiles: Iterable<stri
     const k = path.posix.join(path.posix.dirname(folder), L.sectionOf(f, flatHead)!);
     places.set(k, (places.get(k) ?? new Set()).add(`${folder}#${L.sectionOf(f, flatHead)}`));
   }
+  const flatBase = L.unregroupedFolders(baseFiles);
+  // the topic kept the former decision's folder name (#743): its own section — the one topic section not named after
+  // another former decision of the root
+  const own = new Map<string, Set<string>>();
+  for (const f of head) {
+    const folder = L.decisionFolder(f);
+    if (folder === null || !flatBase.has(folder) || flatHead.has(folder) || !L.isTestFile(f)) continue;
+    const section = L.sectionOf(f, flatHead)!;
+    if (flatBase.has(path.posix.join(path.posix.dirname(folder), section))) continue;
+    own.set(folder, (own.get(folder) ?? new Set()).add(`${folder}#${section}`));
+  }
   const out = new Map<string, string>();
-  for (const folder of L.unregroupedFolders(baseFiles)) {
-    const to = places.get(folder);
+  for (const folder of flatBase) {
+    const to = own.get(folder) ?? places.get(folder);
     if (!flatHead.has(folder) && to?.size === 1) out.set(folder, [...to][0]!);
   }
   return out;
@@ -336,6 +347,7 @@ export function diff(
   baseTests: Test[],
   headTests: Test[],
   pool: Test[] = [],
+  files: { base: Iterable<string>; head: Iterable<string> } = { base: [], head: [] },
 ): { removed: Test[]; changed: [Test, Test][]; added: Test[]; moved: Moved[] } {
   const b = new Map<string, Test>();
   const h = new Map<string, Test>();
@@ -365,8 +377,10 @@ export function diff(
   // 0b) regrouping into topics (#685): a test of a decision not regrouped at the base, with the same describe and name
   // in a section of the same root named after that decision — the section keeps the former name — moved with its file,
   // not removed and added. An exact match again: a test renamed in the move is honestly "changed" or "added".
-  const flatBase = L.unregroupedFolders(baseTests.map((t) => t.path));
-  const flatHead = L.unregroupedFolders(headTests.map((t) => t.path));
+  // Not regrouped — by the revision's files, as in regroupMap (#746): a lint standard's folder-named file has only
+  // examples(it, …), no static tests
+  const flatBase = L.unregroupedFolders([...baseTests.map((t) => t.path), ...files.base]);
+  const flatHead = L.unregroupedFolders([...headTests.map((t) => t.path), ...files.head]);
   const regroupKey = (folder: string, t: Test) => JSON.stringify([path.posix.dirname(folder), path.posix.basename(folder), t.describes, t.name]);
   const former = new Map<string, Test[]>();
   for (const r of removed) {
@@ -383,6 +397,13 @@ export function diff(
     moved.push({ test: a, from: L.folderOf(r), regrouped: true });
     regrouped.add(a).add(r);
   }
+  // the topic kept the former decision's folder name (#743): its tests are in the same folder, so neither removed nor
+  // added, but now in a section of the topic — regrouped into it, not outside the lists
+  for (const [k, a] of h) {
+    const r = b.get(k);
+    const folder = L.decisionFolder(a.path);
+    if (r && folder && flatBase.has(folder) && !flatHead.has(folder)) moved.push({ test: a, from: L.folderOf(r), regrouped: true });
+  }
   added = added.filter((a) => !regrouped.has(a));
   removed.splice(0, removed.length, ...removed.filter((r) => !regrouped.has(r)));
   // 1) the same file and the same body, unique in the file among the removed and among the new — the test is renamed,
@@ -428,28 +449,41 @@ export function unmovedFiles(outFiles: string[], moved: Moved[], count: Map<stri
 }
 
 const outMark = (t: Test) => (L.classify(t.path)[0] === "out" ? ` ⚠️ ${N.spec.diff.outsideMark}` : "");
-// decision folders of not-yet-regrouped decisions (a test file named after the folder) among the base and HEAD tests:
-// render sets it — a test of such a folder is in its one section, the folder's own
-let UNREGROUPED = new Set<string>();
+/** The revision a test is from: a base test — removed, the old side of a change; the rest — HEAD. */
+type Rev = "base" | "head";
+// decision folders of not-yet-regrouped decisions (a test file named after the folder), each revision its own (#743):
+// a folder flat only at the base is a topic with sections for HEAD tests. `setFlat` sets it — a test of such a folder
+// is in its one section, the folder's own
+const FLAT: Record<Rev, Set<string>> = { base: new Set(), head: new Set() };
+
+/** The not-yet-regrouped folders of each revision by its test files: base and HEAD places are counted separately. */
+export function setFlat(files: { base: Iterable<string>; head: Iterable<string> }): void {
+  FLAT.base = L.unregroupedFolders(files.base);
+  FLAT.head = L.unregroupedFolders(files.head);
+}
 
 /**
  * A test's place in the lists — its folder and, in a topic with sections (#685), the section after `#`, as in the
- * spec-doc anchor: `tests/standards/routes#permissions`; the lists go by place.
+ * spec-doc anchor: `tests/standards/routes#permissions`; by the flat folders of the test's revision. The lists go by
+ * place.
  */
-export function placeOf(t: Test): string {
+export function placeOf(t: Test, rev: Rev = "head"): string {
+  const flat = FLAT[rev];
   const folder = L.decisionFolder(t.path);
-  const section = L.sectionOf(t.path, UNREGROUPED);
-  return folder === null || section === null || UNREGROUPED.has(folder) ? L.folderOf(t) : `${L.folderOf(t)}#${section}`;
+  const section = L.sectionOf(t.path, flat);
+  return folder === null || section === null || flat.has(folder) ? L.folderOf(t) : `${L.folderOf(t)}#${section}`;
 }
 
 /** The lists by place — topic and section; within a place — the order of the difference. */
-const byPlace = <T>(list: T[], test: (x: T) => Test): T[] =>
+const byPlace = <T>(list: T[], test: (x: T) => Test, rev: Rev = "head"): T[] =>
   list
-    .map((x, i) => ({ x, i, p: placeOf(test(x)) }))
+    .map((x, i) => ({ x, i, p: placeOf(test(x), rev) }))
     .sort((a, b) => (a.p < b.p ? -1 : a.p > b.p ? 1 : a.i - b.i))
     .map((e) => e.x);
 
-const entry = (t: Test) => `- \`${placeOf(t)}\` · ${L.titleOf(t)}${outMark(t)}`;
+const entryAt = (t: Test, rev: Rev) => `- \`${placeOf(t, rev)}\` · ${L.titleOf(t)}${outMark(t)}`;
+const entry = (t: Test) => entryAt(t, "head");
+const removedEntry = (t: Test) => entryAt(t, "base");
 
 function changedEntry([o, n]: [Test, Test]): string {
   const md = (parts: string[]) => parts.map(L.mdText).join(" › ");
@@ -634,6 +668,25 @@ function exceptionLine(folder: string, e: ExceptionEntry): string {
 }
 const CODE = /\.[cm]?[jt]sx?$/;
 
+/**
+ * `git diff --name-status -M -z`: every path the diff names — both sides of a rename, so the base reads the file at its
+ * former path — and the renames, former path → new.
+ */
+export function changedFiles(out: string): { paths: string[]; renames: Map<string, string> } {
+  const f = out.split("\0");
+  const paths: string[] = [];
+  const renames = new Map<string, string>();
+  for (let i = 0; i < f.length && f[i]; ) {
+    const st = f[i++]!;
+    if (st[0] === "R" || st[0] === "C") {
+      const [from, to] = [f[i++]!, f[i++]!];
+      paths.push(from, to);
+      if (st[0] === "R") renames.set(from, to);
+    } else paths.push(f[i++]!);
+  }
+  return { paths, renames };
+}
+
 /** Files at a revision (null — the working tree) by paths from the git root: path without the prefix → text. */
 function readFiles(rev: string | null, top: string, prefix: string, paths: string[]): Map<string, string> {
   if (rev !== null) return filesAtRev(rev, top, prefix, paths);
@@ -660,6 +713,7 @@ async function decisionsAt(
   checks: Check[],
   place: (file: string) => string,
   regrouped: ReadonlyMap<string, string> = new Map(),
+  movedCode: ReadonlyMap<string, string> = new Map(),
 ): Promise<Decisions> {
   const listed = rev !== null ? gitText(["ls-tree", "-r", "--name-only", "-z", rev, "--", prefix + L.TESTS], top).split("\0") : [];
   const excPaths =
@@ -687,7 +741,8 @@ async function decisionsAt(
     const rel = p.slice(prefix.length);
     const text = files.get(rel);
     if (!text || !text.includes("eslint-disable")) continue;
-    for (const d of disablesIn(rel, text)) exceptions.push(`\`${rel}\` · ${d.rules.join(", ") || N.spec.lint.allRules} — ${d.description || N.spec.lint.noReason}`);
+    const named = movedCode.get(rel) ?? rel;
+    for (const d of disablesIn(rel, text)) exceptions.push(`\`${named}\` · ${d.rules.join(", ") || N.spec.lint.allRules} — ${d.description || N.spec.lint.noReason}`);
   }
   return { model: modelFacts(model), exceptions: exceptions.sort(), checks: checkFacts(checks, place) };
 }
@@ -767,14 +822,14 @@ export const SUMMARY_LIMIT = 100;
 function summaryLines(removed: Test[], changed: [Test, Test][], added: Test[], limit: number, harness?: Set<Test>): string[] {
   type Row = { removed: number; changed: number; added: number; harness: number };
   const rows = new Map<string, Row>();
-  const row = (t: Test) => {
-    const f = placeOf(t);
+  const row = (t: Test, rev: Rev) => {
+    const f = placeOf(t, rev);
     if (!rows.has(f)) rows.set(f, { removed: 0, changed: 0, added: 0, harness: 0 });
     return rows.get(f)!;
   };
   const count = (ts: Test[], k: "removed" | "changed" | "added") => {
     for (const t of ts) {
-      const r = row(t);
+      const r = row(t, k === "removed" ? "base" : "head");
       r[k]++;
       if (harness?.has(t)) r.harness++;
     }
@@ -828,12 +883,24 @@ export function render(
   added: Test[],
   outFiles: string[],
   moved: Moved[] = [],
-  opts: { limit?: number; harness?: Set<Test>; extra?: Set<Test>; note?: string; notStatements?: number; files?: Iterable<string> } = {},
+  opts: {
+    limit?: number;
+    harness?: Set<Test>;
+    extra?: Set<Test>;
+    note?: string;
+    notStatements?: number;
+    files?: { base: Iterable<string>; head: Iterable<string> };
+  } = {},
 ): string {
-  // `files` — all test files of the base and HEAD: a folder-named file the PR didn't touch still makes the folder one
-  // section
-  UNREGROUPED = L.unregroupedFolders(opts.files ?? [...removed, ...changed.flat(), ...added].map((t) => t.path));
-  removed = byPlace(removed, (t) => t);
+  // `files` — the test files of the base and of HEAD: a folder-named file the PR didn't touch still makes the folder
+  // one section
+  setFlat(
+    opts.files ?? {
+      base: [...removed, ...changed.map(([o]) => o)].map((t) => t.path),
+      head: [...changed.map(([, n]) => n), ...added, ...moved.map((m) => m.test)].map((t) => t.path),
+    },
+  );
+  removed = byPlace(removed, (t) => t, "base");
   changed = byPlace(changed, ([, n]) => n);
   added = byPlace(added, (t) => t);
   const lines = [N.prSpecSection, "", locale.fill(N.spec.diff.base, { base: baseLabel }), ""];
@@ -847,7 +914,7 @@ export function render(
   if (summarized(removed, changed, added, limit)) {
     // a removed test is a removed requirement: named one by one in the PR body while there aren't more of them than
     // the threshold
-    if (removed.length && removed.length <= limit) lines.push(`**${N.spec.diff.removed} (${removed.length}):**`, "", ...removed.map(entry), "");
+    if (removed.length && removed.length <= limit) lines.push(`**${N.spec.diff.removed} (${removed.length}):**`, "", ...removed.map(removedEntry), "");
     lines.push(...summaryLines(removed, changed, added, limit, opts.harness));
     lines.push(...movedLines(moved));
     if (outFiles.length) lines.push(outsideFilesLine(outFiles), "");
@@ -856,7 +923,7 @@ export function render(
   }
   const mark = (t: Test) => (opts.extra?.has(t) ? ` — ${N.spec.diff.extraMark}` : "");
   const sections: [string, string[]][] = [
-    [N.spec.diff.removed, removed.map(entry)],
+    [N.spec.diff.removed, removed.map(removedEntry)],
     [N.spec.diff.changed, changed.map((p) => changedEntry(p) + mark(p[1]))],
     [N.spec.diff.added, added.map((t) => entry(t) + mark(t))],
   ];
@@ -1144,7 +1211,7 @@ export async function main(argv: string[]): Promise<number> {
   let checks: HarnessDescribe[];
   let sourced: Check[]; // harness calls in the head's sources: their describes aren't "report only"
   let notStatements: number;
-  let testFiles: string[]; // test files of the base and HEAD: which folders aren't regrouped yet
+  let testFiles: { base: string[]; head: string[] }; // test files of the base and HEAD: which folders aren't regrouped yet
   try {
     const { top, root, prefix } = findRoot(v.root);
     const base = v["no-merge-base"] ? v.base : gitText(["merge-base", v.base, v.worktree ? "HEAD" : v.head], top).trim();
@@ -1190,8 +1257,9 @@ export async function main(argv: string[]): Promise<number> {
     }
     const changedOut = outOfTreeFiles(base, v.head, top, prefix, v.worktree);
     const { pool, count, gone } = outOfTreePool(base, v.head, top, root, prefix, changedOut, v.worktree);
-    ({ removed, changed, added, moved } = diff(baseTests, headTests, pool));
-    testFiles = [...baseTests, ...headTests].map((t) => t.path);
+    testFiles = { base: [...baseTests.map((t) => t.path), ...baseFiles.keys()], head: [...headTests.map((t) => t.path), ...headFiles.keys()] };
+    ({ removed, changed, added, moved } = diff(baseTests, headTests, pool, testFiles));
+    setFlat(testFiles); // scenarios are matched by place before render
     // checks by place, as the tests: a decision regrouped into a topic keeps its checks
     const regrouped = regroupMap(baseFiles.keys(), headFiles.keys());
     // the files of a revision with tests or harness calls: a check's file has no static tests
@@ -1201,15 +1269,21 @@ export async function main(argv: string[]): Promise<number> {
     notStatements = newNotStatements([...added, ...changed.map(([, n]) => n)], baseTests, LANG);
     outFiles = unmovedFiles(changedOut, moved, count, gone);
     // lint disables — only in changed code files: a removed or added exception is always in the PR diff
-    const changedAll = (
+    const status = changedFiles(
       v.worktree
-        ? gitText(["diff", "--name-only", "-z", base, "--", "."], top) + gitText(["ls-files", "--others", "--exclude-standard", "-z", "--", "."], top)
-        : gitText(["diff", "--name-only", "-z", base, v.head, "--", "."], top)
-    )
-      .split("\0")
-      .filter((f) => f.startsWith(prefix) && CODE.test(f) && !FLOW_COPY.test(f.slice(prefix.length)));
+        ? gitText(["diff", "--name-status", "-M", "-z", base, "--", "."], top)
+        : gitText(["diff", "--name-status", "-M", "-z", base, v.head, "--", "."], top),
+    );
+    const untracked = v.worktree ? gitText(["ls-files", "--others", "--exclude-standard", "-z", "--", "."], top).split("\0") : [];
+    const changedAll = [...status.paths, ...untracked].filter((f) => f.startsWith(prefix) && CODE.test(f) && !FLOW_COPY.test(f.slice(prefix.length)));
+    // a file regrouped into a topic keeps its lint disables (#746): the base names them by the file's HEAD path
+    const movedCode = new Map<string, string>();
+    for (const [from, to] of status.renames) {
+      const folder = L.decisionFolder(from.slice(prefix.length));
+      if (folder && regrouped.has(folder) && from.startsWith(prefix) && to.startsWith(prefix)) movedCode.set(from.slice(prefix.length), to.slice(prefix.length));
+    }
     decisionData = {
-      base: await decisionsAt(base, top, prefix, changedAll, baseScan.checks, basePlace, regrouped),
+      base: await decisionsAt(base, top, prefix, changedAll, baseScan.checks, basePlace, regrouped, movedCode),
       head: await decisionsAt(v.worktree ? null : v.head, top, prefix, changedAll, headScan.checks, headPlace),
     };
     decisions = decisionLines(decisionData.base, decisionData.head, limit);