@turri-dev/cli 0.2.1 → 0.2.2

package/dist/regenerate/chunk-plan.d.ts

@@ -160,10 +160,21 @@ export interface PlaceAnswer {
     /** What of the person's wishes it did not follow, and why. */
     notes?: string;
 }
-/** A group to title: the number the agent answers with, and its functional specs' text. */
+/**
+ * A group to title: the number the agent answers with, and its functional specs' text - or, for a pulse that makes the
+ * whole of an edit, `changes`: what the edit does to the ***plain the code is built from.
+ */
 export interface TitleGroup {
     number: number;
     specs: string[];
+    changes?: TitleChange[];
+}
+/** A change a pulse makes, as the title agent is shown it: what it is, how it changes, its text now - and before, changed. */
+export interface TitleChange {
+    kind: "changed" | "taken out" | "added";
+    what: string;
+    text: string;
+    before?: string;
 }
 export interface TitleAnswer {
     titles: Array<{
@@ -175,7 +186,8 @@ export interface TitleAnswer {
  * The judgements, each asked again with what was wrong with its answer - the last answer given, whether it holds
  * or not: the plan checks it again. Injectable, so the plan is testable without a model. `title` titles the groups no
  * agent titled - the conformance tests', and a grouping that fell back - for what each pulse does, rather than its
- * first functional spec's first line; without it, they keep that.
+ * first functional spec's first line; without it, they keep that. It titles a pulse that makes the whole of an edit
+ * too, shown the edit's changes; without it, that pulse is titled by `editTitle`.
  */
 export interface ChunkAgents {
     group(specs: NewSpec[], check: (answer: GroupAnswer) => string[], steering?: Steering[], maxSpecs?: number, built?: BuiltChange[]): Promise<GroupAnswer | undefined>;
@@ -188,10 +200,15 @@ export interface ChunkAgents {
  * is built as the new ones are. One taken out builds nothing, and does not.
  */
 export declare function groupProblems(specs: NewSpec[], answer: GroupAnswer, maxSpecs?: number, built?: BuiltChange[]): string[];
-/** What is wrong with a titling: every group titled once, by its number, none empty, none too long. */
+/** What is wrong with a titling: every group titled once, by its number, none empty, none too long, none naming the act. */
 export declare function titleProblems(groups: TitleGroup[], answer: TitleAnswer): string[];
 /** What is wrong with a placement: every new req once, each where there is such a job. */
 export declare function placeProblems(input: PlaceInput, answer: PlaceAnswer): string[];
+/**
+ * The title of a pulse that makes the whole of an edit, when no agent gave one: the first line of the first functional
+ * spec it changes - else of its first change - and how many more it makes. Never the bare word.
+ */
+export declare function editTitle(changes: SpecChange[]): string;
 export declare function planChunks(input: PlanInput, agents?: ChunkAgents, notes?: string[]): Promise<DraftJob[]>;
 export declare function groupPrompt(specs: NewSpec[], steering?: Steering[], maxSpecs?: number, built?: BuiltChange[]): string;
 export declare function placePrompt(input: PlaceInput): string;

package/dist/regenerate/chunk-plan.js

@@ -79,6 +79,20 @@ export const TITLE_CHARS = 70;
 function fitsTitle(title) {
     return title.trim().split(/\s+/).length <= TITLE_WORDS && title.trim().length <= TITLE_CHARS;
 }
+/** Whether a title names the act of regenerating - "regenerate", "Regenerate the scenery" - rather than the change. */
+function namesTheAct(title) {
+    return /^regenerat(e|es|ed|ing)\b/i.test(title.trim());
+}
+/** What is wrong with one title, or nothing: empty, too long, or naming the act rather than the change. */
+function titleProblem(title, empty) {
+    if (title.trim() === "")
+        return empty;
+    if (!fitsTitle(title))
+        return `"${title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`;
+    if (namesTheAct(title))
+        return `"${title}" names the act of regenerating: say what the pulse changes in the software.`;
+    return undefined;
+}
 /**
  * A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. Text
  * cut already is cut again without stacking a second: several first lines joined, each cut, end on one ellipsis.
@@ -101,7 +115,10 @@ const RETRIES = 2;
  * its scenarios, each under its scenario-id, where the tree has them: the conformance track's.
  */
 function textOf(change) {
-    const line = change.after ?? change.before ?? "";
+    return textOfLine(change.after ?? change.before ?? "");
+}
+/** An item's text from its line in a tree: its markdown, and its scenarios, if any. */
+function textOfLine(line) {
     try {
         const item = JSON.parse(line);
         const scenarios = [...(item[CONFORMANCE_TESTS] ?? []), ...(item[ACCEPTANCE_TESTS] ?? [])].map((scenario) => `# ${scenario.id ?? ""}\n${scenario.text ?? ""}`);
@@ -181,14 +198,13 @@ function newSpecProblems(specs, answer, maxSpecs, built) {
             if (!nextTo(group.specs[i - 1], group.specs[i]))
                 problems.push(`"${group.title}" groups ${group.specs.join(", ")}: only functional specs next to each other in the same module go together.`);
         }
-        if (group.title.trim() === "")
-            problems.push("Every group needs a title.");
-        else if (!fitsTitle(group.title))
-            problems.push(`"${group.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
+        const wrong = titleProblem(group.title, "Every group needs a title.");
+        if (wrong !== undefined)
+            problems.push(wrong);
     });
     return problems;
 }
-/** What is wrong with a titling: every group titled once, by its number, none empty, none too long. */
+/** What is wrong with a titling: every group titled once, by its number, none empty, none too long, none naming the act. */
 export function titleProblems(groups, answer) {
     const problems = [];
     const numbers = groups.map((group) => group.number);
@@ -197,10 +213,9 @@ export function titleProblems(groups, answer) {
         if (!numbers.includes(entry.group))
             problems.push(`There is no group ${entry.group}.`);
         seen.set(entry.group, (seen.get(entry.group) ?? 0) + 1);
-        if (entry.title.trim() === "")
-            problems.push(`Group ${entry.group} needs a title.`);
-        else if (!fitsTitle(entry.title))
-            problems.push(`"${entry.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
+        const wrong = titleProblem(entry.title, `Group ${entry.group} needs a title.`);
+        if (wrong !== undefined)
+            problems.push(wrong);
     }
     for (const number of numbers) {
         const times = seen.get(number) ?? 0;
@@ -323,7 +338,34 @@ function draftOf(chunks, net) {
 }
 /** A spec's first line, as a group's title when no agent gave one. */
 function titleOf(change) {
-    return shortTitle(textOf(change).split("\n")[0].replace(/^-\s*/, ""));
+    return shortTitle(firstLineOf(change));
+}
+function firstLineOf(change) {
+    return textOf(change).split("\n")[0].replace(/^-\s*/, "");
+}
+const isFunctionalSpec = (change) => change.section === FUNCTIONAL_REQUIREMENTS || change.section === REQUIRED_FUNCTIONAL_SPECS;
+/**
+ * The title of a pulse that makes the whole of an edit, when no agent gave one: the first line of the first functional
+ * spec it changes - else of its first change - and how many more it makes. Never the bare word.
+ */
+export function editTitle(changes) {
+    const [first, ...rest] = [...changes.filter(isFunctionalSpec), ...changes.filter((change) => !isFunctionalSpec(change))];
+    if (first === undefined)
+        return "No change";
+    const line = first.kind === "remove" ? `Takes out: ${firstLineOf(first)}` : firstLineOf(first);
+    if (rest.length === 0)
+        return shortTitle(line);
+    const more = `, and ${rest.length} more`;
+    return `${shortTitle(line, TITLE_CHARS - more.length, TITLE_WORDS - 3).replace(/[.,;:]+$/, "")}${more}`;
+}
+/** A change as the title agent is shown it: what it is, how it changes, its text now - and before, for a change. */
+function titleChangeOf(change) {
+    return {
+        kind: change.kind === "change" ? "changed" : change.kind === "remove" ? "taken out" : "added",
+        what: WHAT[change.section] ?? change.section,
+        text: textOf(change),
+        ...(change.kind === "change" && change.before !== undefined ? { before: textOfLine(change.before) } : {}),
+    };
 }
 /**
  * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
@@ -472,10 +514,29 @@ async function cut(input, agents, notes) {
     const builtShown = builtChanges.map((change, index) => builtChangeOf(change, index + 1, input.moduleName));
     /** Where each change to what is built goes: with the group holding a new functional spec - by that spec's number - or first. */
     const builtTo = new Map();
-    // Named as the person asks for it: "shorty.plain regenerate".
-    const whole = [{ title: "regenerate", reason: "the whole of the work, in one job", changes: net.map((change) => change.id) }];
+    /**
+     * The whole of the work in one job - an edit that only changes what is built, or one no plan of holds together -
+     * titled by what the edit does: by the title agent, shown every change, else by what it changes first.
+     */
+    const wholeJob = async () => {
+        const whole = { title: "", reason: "the whole of the work, in one job", changes: net.map((change) => change.id) };
+        if (checkDraft(input, [whole]).length > 0)
+            return [];
+        const fallback = editTitle(net);
+        if (agents?.title === undefined)
+            return [{ ...whole, title: fallback }];
+        reportStage("planning the queue: a title for the pulse");
+        const toTitle = [{ number: 1, specs: [], changes: net.map(titleChangeOf) }];
+        const answer = (await agents.title(toTitle, (given) => titleProblems(toTitle, given), input.track === "conformance" ? "conformance" : "code").catch((error) => plannerFailed("title", error))) ?? undefined;
+        const problems = answer === undefined ? [] : titleProblems(toTitle, answer);
+        if (answer !== undefined && problems.length === 0)
+            return [{ ...whole, title: answer.titles[0].title.trim() }];
+        record({ kind: "planner.fellBack", step: "title", why: answer === undefined ? "no title was given" : firstLine(problems.join(" "), 300) });
+        say(answer === undefined ? `the title was not given - the pulse titled by what it changes first: "${fallback}"` : `the title did not hold (${problems.join(" ")}) - the pulse titled by what it changes first: "${fallback}"`);
+        return [{ ...whole, title: fallback }];
+    };
     if (specs.length === 0)
-        return checkDraft(input, whole).length === 0 ? whole : [];
+        return wholeJob();
     // 1. Which functional specs go together.
     reportStage(`planning the queue: which of the ${specs.length} functional spec${specs.length === 1 ? "" : "s"} to build go together`);
     const numbered = specs.map((change, index) => {
@@ -661,7 +722,7 @@ async function cut(input, agents, notes) {
     const simple = draftOf(chunks, net);
     if (checkDraft(input, simple).length === 0)
         return simple;
-    return checkDraft(input, whole).length === 0 ? whole : [];
+    return wholeJob();
 }
 // ---------------------------------------------------------------------------------------------
 // The agents.
@@ -752,8 +813,25 @@ export function titlePrompt(groups, track) {
             ? "Give each group a title that says what its pulse tests - the behaviour, not the spec's wording."
             : "Give each group a title that says what its pulse builds - the feature, not the spec's wording.",
         `At most ${TITLE_WORDS} words and ${TITLE_CHARS} characters: it heads the pulse where the person watches the work, and a longer one is cut short there.`,
+        ...(groups.some((group) => group.changes !== undefined)
+            ? [
+                "",
+                "A group of changes is one edit to software already built: its pulse makes the whole of it. Title it by what the",
+                "edit does to the software, briefly - \"Expired links answer 410 and the stats page goes\", \"Greeter greets by",
+                "name\". A definition or an implementation req changed is titled by what it changes in what is built - \"Links are",
+                "kept for 30 days\" - never by the section it is in.",
+            ]
+            : []),
+        "Name the change, never the act: \"regenerate\", \"Regenerate the scenery\" and \"Changes\" are not titles.",
         "",
-        ...groups.map((group) => [`<group number="${group.number}">`, ...group.specs.map((spec) => `<functional spec>\n${spec.trim()}\n</functional spec>`), "</group>"].join("\n")),
+        ...groups.map((group) => [
+            `<group number="${group.number}">`,
+            ...group.specs.map((spec) => `<functional spec>\n${spec.trim()}\n</functional spec>`),
+            ...(group.changes ?? []).map((change) => change.before !== undefined
+                ? `<change kind="${change.kind}" what="${change.what}">\n<before>\n${change.before.trim()}\n</before>\n<now>\n${change.text.trim()}\n</now>\n</change>`
+                : `<change kind="${change.kind}" what="${change.what}">\n${change.text.trim()}\n</change>`),
+            "</group>",
+        ].join("\n")),
         "",
         "Call submit_titles once, with a title for every group, by its number.",
     ].join("\n");

package/docs/regenerating.md

@@ -184,7 +184,7 @@ A job that regenerates the whole of a new module's \*\*\*plain is too big to bui
 2. **The definitions each group uses**, in code: the concepts its functional specs name, and the concepts those definitions name in turn. A definition goes with the first group that uses it; later groups have it built. One nothing uses goes with the last.
 3. **Where each new implementation req goes.** An agent places each with the group it is about - or with the first, when it is about everything (the language, the framework).
 
-Each pulse's title says what it does - at most 10 words and 70 characters, as it heads the pulse where the person watches the work. The grouping agent titles its groups; groups no agent made - the conformance tests', and a grouping that fell back - are titled by a third agent, told what each pulse does: what it builds, or, for the conformance tests, what they test. Without it, or when it fails, a pulse is titled by its functional specs' first lines, cut short.
+Each pulse's title says what it does - at most 10 words and 70 characters, as it heads the pulse where the person watches the work. The grouping agent titles its groups; groups no agent made - the conformance tests', and a grouping that fell back - are titled by a third agent, told what each pulse does: what it builds, or, for the conformance tests, what they test. Without it, or when it fails, a pulse is titled by its functional specs' first lines, cut short. A pulse that makes the whole of an edit in one go - an edit that only changes what is built (a functional spec reworded, a definition or an implementation req changed, none new and none marked to regenerate again), or one no plan of holds together - is titled by the same agent, shown every change, before and after: by what the edit does (`Expired links answer 410 and the stats page goes`), and an edit to definitions or implementation reqs alone by what it changes in what is built (`Links are kept for 30 days`), never by its section. Without it, or when it fails, it is titled by the first line of the first functional spec it changes - else of its first change - and how many more (`Follow-link answers 410 for expired links, and 2 more`). A title names the change, never the act: one that starts with "regenerate" does not hold. Pulses already in the ledger keep the titles they were recorded with.
 
 Changes to what is built - an item edited or taken out, a functional spec built worded differently - go where the same agent places each: with the group of new functional specs it is about, by default - so one edit that adds a functional spec, changes another and takes out a third is one pulse - or first, in a pulse of its own, when it reshapes what the new work is built on (a concept many functional specs use redefined, one others rely on taken out, a large rewrite) or has nothing to do with it. A functional spec changed counts toward its group's `max-specs-per-pulse`; one taken out does not. Every answer is checked: every new functional spec once, in order, next to each other, at most `max-specs-per-pulse`; every change to what is built placed once; every req placed once; every group titled once, within the limit. One that does not hold goes back to its agent, twice at most, and then the plan is a functional spec a job with every req in the first. A group whose functional specs and the definitions they bring pass `max-lines-per-pulse` (120 unset) is split into as few pulses as fit - its functional specs kept together in runs, in order, as long as each run stays within it, `Comments (1 of 2)`, `Comments (2 of 2)` - not a functional spec a job; its reqs do not count, as a split leaves them with its first job whatever happens. The planner runs on the chat's model in a conversation, and on the harness model under `turri regenerate`. No agent reviews its plan: the harness checks it - every change in exactly one job, \*\*\*plain holding together after each, the last ending on \*\*\*plain as it is.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "type": "module",
   "repository": {