@nathapp/nax 0.80.1 → 0.81.0-canary.2

package/flows/nax-finish/pr-template-merge.ts

@@ -1,253 +0,0 @@
-/**
- * Merge nax's generated PR/MR body into the repository's own PR template.
- *
- * ## Why this exists
- *
- * `gh pr create --body` / `glab mr create --description` suppress the repo's
- * template, so a generated body has to account for it. The first attempt
- * appended the template verbatim after the generated content, which shipped a
- * *blank form* below a filled one: placeholder comments, a dangling `Closes #`,
- * duplicated headings, and an unchecked "`bun test` passes" box sitting under a
- * Verification section that already said the gates were green (nax#1504).
- *
- * A PR template is an input form, not decoration. So the template is treated as
- * **shape** and nax's content as **fill**:
- *
- * - a template heading nax can fill  → keep the heading, replace its body
- * - a template heading nax cannot    → drop it (`merge`) or empty it (`strict`)
- * - nax content with no home         → append under nax's own heading
- *
- * The governing invariant is **never emit a field that was not filled**. That
- * is the same rule `buildFinishBody` already followed for its own sections
- * (nax#1477 forbids a bare heading with nothing under it); this module extends
- * it to template-derived text. `strict` mode is the one deliberate exception,
- * for repos whose CI asserts a set of headings exists.
- *
- * ## Why deterministic
- *
- * Placement is decided by a heading-alias table, not by a model. The facts in
- * the body — gate results, story counts, diffstat, review rounds — stay a pure
- * string join, which is what keeps a finish body greppable in PR history. A
- * repo whose headings the table does not know loses nothing: its sections are
- * dropped and nax's own headings are used instead, and `sectionMap` pins the
- * mapping explicitly when a team wants its headings honoured.
- *
- * Lives under `flows/` (and is imported from `src/` via `@flows/*`, not
- * re-implemented) because `flows/` is the more constrained runtime — acpx runs
- * it in its own Node process where `Bun` and the `@/*` alias do not exist. Code
- * that satisfies that constraint runs in both places; the reverse is not true.
- */
-
-/** One nax-authored section of the body. */
-export interface BodySection {
-  /**
-   * Stable id matched against the alias table. Independent of `heading` so
-   * renaming nax's own heading does not silently break template matching.
-   */
-  key: string;
-  /**
-   * nax's H2 text, used when the section is appended rather than merged.
-   * Empty means headingless (the run footer) — such a section is rendered as
-   * bare text and is never matched to a template heading, so a stray alias
-   * cannot bury the footer under someone's `## Notes`.
-   */
-  heading: string;
-  /** Markdown body without its heading line. Callers omit empty sections. */
-  body: string;
-}
-
-/**
- * - `merge`  — template headings nax cannot fill are dropped. Default.
- * - `strict` — they are kept, empty, for repos with heading-checking CI.
- * - `ignore` — the template is not consulted at all.
- */
-export type TemplateMode = "merge" | "strict" | "ignore";
-
-export interface MergeOptions {
-  mode?: TemplateMode;
-  /**
-   * Normalised template heading → `BodySection.key`, layered over
-   * `DEFAULT_SECTION_ALIASES`. An empty value suppresses a default alias,
-   * which is how a repo says "do not put anything under this heading".
-   */
-  sectionMap?: Record<string, string>;
-}
-
-/**
- * Normalised heading → section key.
- *
- * Deliberately partial. `why`, `notes`, `screenshots` and friends are absent
- * because nax has nothing truthful to put under them — an alias that mapped
- * them to some loosely-related section would reintroduce exactly the
- * unfilled-field problem this module exists to remove.
- */
-export const DEFAULT_SECTION_ALIASES: Record<string, string> = {
-  // → narrative
-  what: "narrative",
-  "what changed": "narrative",
-  "whats changed": "narrative",
-  summary: "narrative",
-  description: "narrative",
-  overview: "narrative",
-  changes: "narrative",
-  "what does this do": "narrative",
-  "what does this mr do and why": "narrative",
-  "what does this pr do": "narrative",
-  // → stories
-  how: "stories",
-  implementation: "stories",
-  "implementation details": "stories",
-  "changes made": "stories",
-  approach: "stories",
-  design: "stories",
-  // → verification
-  testing: "verification",
-  tests: "verification",
-  "test plan": "verification",
-  verification: "verification",
-  qa: "verification",
-  validation: "verification",
-  "how to test": "verification",
-  "how has this been tested": "verification",
-  "how to set up and validate locally": "verification",
-};
-
-const HEADING_RE = /^##[ \t]+(.+?)[ \t]*$/;
-const FRONTMATTER_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
-const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
-/** `Closes #`, `Fixes # (issue)` — an issue reference with no issue. */
-const DANGLING_ISSUE_RE = /^[ \t]*(?:closes?|fixe?s?|resolves?)[ \t]*:?[ \t]*#[ \t]*(?:\([^)]*\))?[ \t]*$/i;
-/** An unticked task-list item — an unfilled field wherever it appears. */
-const UNCHECKED_BOX_RE = /^[ \t]*[-*+][ \t]+\[[ \t]\]/;
-
-interface TemplateSection {
-  heading: string;
-  body: string;
-}
-
-interface ParsedTemplate {
-  frontmatter: string;
-  preamble: string;
-  sections: TemplateSection[];
-}
-
-/** Lowercase, drop punctuation, collapse whitespace — so `## Testing:` matches `testing`. */
-function normalizeHeading(heading: string): string {
-  return heading
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]/g, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-/**
- * Strip placeholders from template-derived prose.
- *
- * Only ever applied to the preamble — the one template region that survives
- * into the body. Text under a matched heading is replaced wholesale and text
- * under an unmatched one is discarded, so a checklist or a stale `Closes #`
- * *inside a section* never reaches this function, which is why there is no
- * checkbox-versus-gate reconciliation anywhere in this module.
- *
- * The preamble is the exception, because a template may open with a
- * contributor checklist before its first heading. An unticked box there is an
- * unfilled field like any other, so it is dropped while the prose around it is
- * kept.
- */
-function cleanTemplateText(text: string): string {
-  return text
-    .replace(HTML_COMMENT_RE, "")
-    .split("\n")
-    .filter((line) => !DANGLING_ISSUE_RE.test(line) && !UNCHECKED_BOX_RE.test(line))
-    .map((line) => line.trimEnd())
-    .join("\n")
-    .trim();
-}
-
-function parseTemplate(rawText: string): ParsedTemplate {
-  // Normalised up front so a CRLF template (anything authored on Windows, or
-  // fetched through a forge web editor) cannot leak a stray carriage return
-  // into a heading this module re-emits.
-  const text = rawText.replace(/\r\n/g, "\n");
-  const frontmatterMatch = FRONTMATTER_RE.exec(text);
-  const frontmatter = frontmatterMatch ? frontmatterMatch[0].trimEnd() : "";
-  const rest = frontmatterMatch ? text.slice(frontmatterMatch[0].length) : text;
-
-  const preambleLines: string[] = [];
-  const sections: TemplateSection[] = [];
-  let current: { heading: string; lines: string[] } | null = null;
-
-  for (const line of rest.split("\n")) {
-    const heading = HEADING_RE.exec(line);
-    if (heading) {
-      if (current) sections.push({ heading: current.heading, body: current.lines.join("\n") });
-      current = { heading: heading[1], lines: [] };
-      continue;
-    }
-    if (current) current.lines.push(line);
-    else preambleLines.push(line);
-  }
-  if (current) sections.push({ heading: current.heading, body: current.lines.join("\n") });
-
-  return { frontmatter, preamble: preambleLines.join("\n"), sections };
-}
-
-function renderSection(heading: string, body: string): string {
-  if (heading.length === 0) return body;
-  return body.length === 0 ? `## ${heading}` : `## ${heading}\n\n${body}`;
-}
-
-/** Nax-only body: every section under its own heading, in the order given. */
-function renderSections(sections: BodySection[]): string {
-  return sections
-    .filter((s) => s.body.trim().length > 0)
-    .map((s) => renderSection(s.heading, s.body.trim()))
-    .join("\n\n")
-    .trim();
-}
-
-export function mergeTemplate(
-  template: string | null | undefined,
-  sections: BodySection[],
-  opts: MergeOptions = {},
-): string {
-  const mode = opts.mode ?? "merge";
-  if (mode === "ignore" || !template || template.trim().length === 0) return renderSections(sections);
-
-  const parsed = parseTemplate(template);
-  // No H2 anywhere: the template is prose, or nests everything under H1/H3.
-  // There is no shape to merge into, and appending it unparsed is the defect
-  // this module removes — so fall back to the body nax would have written.
-  if (parsed.sections.length === 0) return renderSections(sections);
-
-  // Override keys go through the same normalisation as the template headings
-  // they are matched against, so a repo pins a heading by pasting it —
-  // `"What does this MR do and why?"` — not by hand-normalising it first.
-  const aliases = { ...DEFAULT_SECTION_ALIASES };
-  for (const [heading, key] of Object.entries(opts.sectionMap ?? {})) aliases[normalizeHeading(heading)] = key;
-  const fillable = sections.filter((s) => s.heading.length > 0 && s.body.trim().length > 0);
-  const consumed = new Set<string>();
-  const parts: string[] = [];
-
-  if (parsed.frontmatter.length > 0) parts.push(parsed.frontmatter);
-  const preamble = cleanTemplateText(parsed.preamble);
-  if (preamble.length > 0) parts.push(preamble);
-
-  for (const templateSection of parsed.sections) {
-    const key = aliases[normalizeHeading(templateSection.heading)];
-    const match = key ? fillable.find((s) => s.key === key && !consumed.has(s.key)) : undefined;
-    if (match) {
-      consumed.add(match.key);
-      parts.push(renderSection(templateSection.heading, match.body.trim()));
-    } else if (mode === "strict") {
-      parts.push(renderSection(templateSection.heading, ""));
-    }
-  }
-
-  for (const section of sections) {
-    if (consumed.has(section.key) || section.body.trim().length === 0) continue;
-    parts.push(renderSection(section.heading, section.body.trim()));
-  }
-
-  return parts.join("\n\n").trim();
-}

package/flows/nax-finish/pr-template.ts

@@ -1,56 +0,0 @@
-/**
- * Repository PR/MR template discovery, ported from
- * `src/plugins/builtin/auto-pr/template.ts`.
- *
- * Ported rather than imported: `flows/` is loaded by acpx in its own Node
- * process, where nax's `src/` and its `@/*` alias do not exist. This matches
- * the convention already in this directory — `errors.ts`, `exec.ts`, `types.ts`
- * and the PR body builder are all flow-local re-implementations.
- *
- * The duplication is stable: these candidate paths are an external convention
- * set by GitHub and GitLab, not internal logic that drifts with the codebase.
- *
- * Why preserve-not-fill: passing `--body` / `--description` to `gh` / `glab`
- * suppresses the repo's default template, so it must be read and re-embedded.
- */
-import { join } from "node:path";
-import type { Forge } from "./steps/forge";
-
-/**
- * Candidate template paths for GitHub, in priority order.
- * Multi-template directories (`PULL_REQUEST_TEMPLATE/`) are intentionally
- * skipped because they are ambiguous unattended.
- */
-const GITHUB_TEMPLATE_PATHS: readonly string[] = [
-  ".github/PULL_REQUEST_TEMPLATE.md",
-  ".github/pull_request_template.md",
-  "PULL_REQUEST_TEMPLATE.md",
-  "docs/PULL_REQUEST_TEMPLATE.md",
-] as const;
-
-/** Preferred single-template location for GitLab. */
-const GITLAB_DEFAULT_TEMPLATE_PATH = ".gitlab/merge_request_templates/Default.md";
-
-/** Only `readText` is consulted, so any caller with a file reader can supply it. */
-export interface TemplateDeps {
-  readText: (path: string) => Promise<string | null>;
-}
-
-async function firstExisting(workdir: string, deps: TemplateDeps, paths: readonly string[]): Promise<string | null> {
-  for (const relPath of paths) {
-    const content = await deps.readText(join(workdir, relPath));
-    if (content !== null) return content;
-  }
-  return null;
-}
-
-/**
- * Locate the PR/MR template for the current repository.
- *
- * @returns Template text verbatim, or `null` when none resolves — which is the
- *          common case and never an error.
- */
-export async function findPrTemplate(workdir: string, forge: Forge, deps: TemplateDeps): Promise<string | null> {
-  if (forge === "github") return firstExisting(workdir, deps, GITHUB_TEMPLATE_PATHS);
-  return firstExisting(workdir, deps, [GITLAB_DEFAULT_TEMPLATE_PATH]);
-}

package/flows/nax-finish/pr-title.ts

@@ -1,140 +0,0 @@
-/**
- * The PR title — sentinel, sanitiser, and the fallback chain.
- *
- * `buildFinishTitle` used to return `feat: <feature>` unconditionally, so every
- * finish-opened PR was titled with its feature slug: `feat: schema-drift-gate`
- * describes the run, not the change. The narrative node has already read the
- * whole diff by the time the body is amended, so a real conventional-commit
- * subject costs one extra sentinel in a prompt that was being sent anyway.
- *
- * No deterministic source can replace it. The spec's H1 is the slug in prose
- * (`# SPEC: Schema drift gate`), the PRD carries no feature-level title, and
- * concatenating story titles reads worse than the slug it replaces — which is
- * why this is the one part of the PR metadata that is model-derived, and why
- * everything below assumes the model may return junk.
- *
- * Lives beside `narrative.ts` rather than in `src/prompts/builders/` for the
- * same reason that file gives: `flows/` runs in acpx's Node process and imports
- * nothing from `src/`.
- */
-
-/** Sentinel wrapping the title. See `narrative.ts` for why a delimiter is required at all. */
-export const TITLE_OPEN_TAG = "<title>";
-export const TITLE_CLOSE_TAG = "</title>";
-
-/**
- * Longest title rendered onto a PR.
- *
- * 72 is the conventional-commit subject norm, and GitHub truncates around this
- * width in list views.
- */
-export const TITLE_MAX_CHARS = 72;
-
-/**
- * Conventional-commit prefix, split into the type-with-scope and the subject.
- *
- * Types mirror the list in `.claude/rules/project-conventions.md`, plus
- * `revert`. Captured rather than merely tested so the two halves can be
- * rejoined with exactly one space — `feat:no space` and `feat:` both reach
- * here, and testing alone let the latter become `feat: feat:`.
- *
- * A title arriving without any prefix is prefixed rather than rejected: the
- * prose is usually right even when the model forgets the ceremony.
- */
-const CONVENTIONAL_PREFIX_RE =
-  /^((?:feat|fix|refactor|perf|docs|test|chore|ci|build|style|revert)(?:\([^)]*\))?!?):\s*([\s\S]*)$/i;
-
-const DEFAULT_TYPE = "feat";
-
-/** Wrapping quotes/backticks the model adds when it treats the title as a quoted string. */
-const WRAPPING_CHARS = new Set(['"', "'", "`", "*", "_"]);
-
-function stripWrapping(text: string): string {
-  let out = text;
-  // Loop: models nest these ("`fix: thing`" arrives quoted *and* fenced).
-  while (out.length >= 2) {
-    const first = out[0];
-    const last = out[out.length - 1];
-    if (first !== undefined && first === last && WRAPPING_CHARS.has(first)) {
-      out = out.slice(1, -1).trim();
-      continue;
-    }
-    break;
-  }
-  return out;
-}
-
-/**
- * Cut to `TITLE_MAX_CHARS` on a word boundary where one is available.
- *
- * A mid-word cut reads as corruption rather than brevity; falling back to a
- * hard slice only matters for a title with no spaces at all.
- */
-function clamp(text: string): string {
-  if (text.length <= TITLE_MAX_CHARS) return text;
-  const cut = text.slice(0, TITLE_MAX_CHARS);
-  const lastSpace = cut.lastIndexOf(" ");
-  // Guard against a long type prefix eating the whole budget: only honour a
-  // word boundary that leaves a meaningful subject behind.
-  const MIN_KEEP = 20;
-  return (lastSpace >= MIN_KEEP ? cut.slice(0, lastSpace) : cut).trimEnd();
-}
-
-/**
- * Normalise a model-supplied title, or `undefined` if nothing usable survives.
- *
- * Never throws — this feeds `parse` on an acp node, and the flow's PR is
- * already open by the time it runs.
- */
-export function sanitizeTitle(raw: string | undefined): string | undefined {
-  if (typeof raw !== "string") return undefined;
-
-  // First non-empty line: a title is single-line by definition, and a model
-  // that adds a rationale below it must not push that onto the PR.
-  const firstLine = raw.split(/\r?\n/).find((line) => line.trim().length > 0);
-  if (firstLine === undefined) return undefined;
-
-  // Collapse internal runs of whitespace before measuring, so the length cap
-  // reflects what a reader sees.
-  let title = stripWrapping(firstLine.trim()).replace(/\s+/g, " ");
-  // Markdown heading marks, for a model that answers the "write a title" ask
-  // with a heading.
-  title = title.replace(/^#+\s*/, "").trim();
-  title = stripWrapping(title);
-  // Trailing sentence punctuation — conventional-commit subjects carry none.
-  title = title.replace(/[.\s]+$/, "");
-  if (!title) return undefined;
-
-  const match = CONVENTIONAL_PREFIX_RE.exec(title);
-  const type = match?.[1] ?? DEFAULT_TYPE;
-  const subject = (match?.[2] ?? title).trim();
-  // A bare `feat:` carries no subject, and a type alone is not a title.
-  if (!subject) return undefined;
-
-  return clamp(`${type}: ${subject}`);
-}
-
-/**
- * Extract the title from the narrative node's reply.
- *
- * Last opening tag wins, mirroring `parseNarrative` — a model that narrates the
- * tag before emitting it must not beat the real one.
- */
-export function parseTitle(text: string): string | undefined {
-  if (typeof text !== "string") return undefined;
-  const open = text.lastIndexOf(TITLE_OPEN_TAG);
-  if (open === -1) return undefined;
-  const from = open + TITLE_OPEN_TAG.length;
-  const close = text.indexOf(TITLE_CLOSE_TAG, from);
-  return sanitizeTitle(close === -1 ? text.slice(from) : text.slice(from, close));
-}
-
-/**
- * The title to render, best source first.
- *
- * `feat: <feature>` remains the floor: it is what shipped before, it is what
- * the auto-PR plugin opens with, and it is always available.
- */
-export function resolveTitle(agentTitle: string | undefined, feature: string): string {
-  return sanitizeTitle(agentTitle) ?? `${DEFAULT_TYPE}: ${feature}`;
-}