specrails-desktop 2.20.1 → 2.22.0

package/server/dist/pr-body.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTestFilePath = isTestFilePath;
+exports.collectBranchChanges = collectBranchChanges;
+exports.parseShortstat = parseShortstat;
+exports.parseNameStatus = parseNameStatus;
+exports.buildCanonicalPrBody = buildCanonicalPrBody;
+exports.extractSpecNarrative = extractSpecNarrative;
+const explore_contract_refine_1 = require("./explore-contract-refine");
+const pr_naming_1 = require("./pr-naming");
+const TEST_FILE_RE = /(\.test\.[jt]sx?|\.spec\.[jt]sx?)$/;
+const PROBLEM_MAX = 600;
+const SOLUTION_MAX = 900;
+const OVERFLOW_MAX = 3000;
+const MAX_TEST_FILES_LISTED = 20;
+function isTestFilePath(p) {
+    return TEST_FILE_RE.test(p) || p.includes('__tests__/');
+}
+/**
+ * Per-branch diffstat + touched test files via `git diff` against the base
+ * (three-dot: what the branch adds over the merge-base). Failures are recorded
+ * per branch (`failed: true`) — never thrown.
+ */
+async function collectBranchChanges(git, repoDir, baseBranch, branches) {
+    const out = new Map();
+    for (const branch of [...new Set(branches)]) {
+        const entry = { branch, filesChanged: 0, insertions: 0, deletions: 0, testFiles: [], failed: false };
+        try {
+            const stat = await git.run(['diff', '--shortstat', `${baseBranch}...${branch}`], repoDir);
+            const names = await git.run(['diff', '--name-status', `${baseBranch}...${branch}`], repoDir);
+            if (stat.code !== 0 || names.code !== 0) {
+                entry.failed = true;
+            }
+            else {
+                const parsed = parseShortstat(stat.stdout);
+                entry.filesChanged = parsed.filesChanged;
+                entry.insertions = parsed.insertions;
+                entry.deletions = parsed.deletions;
+                entry.testFiles = parseNameStatus(names.stdout).filter(isTestFilePath);
+            }
+        }
+        catch {
+            entry.failed = true;
+        }
+        out.set(branch, entry);
+    }
+    return out;
+}
+/** Parse `N files changed, X insertions(+), Y deletions(-)` (any part may be absent). */
+function parseShortstat(stdout) {
+    const files = /(\d+) files? changed/.exec(stdout);
+    const ins = /(\d+) insertions?\(\+\)/.exec(stdout);
+    const del = /(\d+) deletions?\(-\)/.exec(stdout);
+    return {
+        filesChanged: files ? parseInt(files[1], 10) : 0,
+        insertions: ins ? parseInt(ins[1], 10) : 0,
+        deletions: del ? parseInt(del[1], 10) : 0,
+    };
+}
+/** Parse `git diff --name-status` output into touched paths (rename → new path). */
+function parseNameStatus(stdout) {
+    const paths = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const parts = trimmed.split('\t');
+        if (parts.length < 2)
+            continue;
+        paths.push(parts[parts.length - 1]);
+    }
+    return paths;
+}
+function buildCanonicalPrBody(input) {
+    const parts = [summaryParagraph(input)];
+    for (const t of input.tickets) {
+        parts.push(ticketSection(t, input.changes ?? null));
+    }
+    const changesSection = buildChangesSection(input.changes ?? null);
+    if (changesSection)
+        parts.push(changesSection);
+    return parts.join('\n\n');
+}
+function summaryParagraph(input) {
+    const n = input.tickets.length;
+    const refs = input.tickets.map((t) => displayRef(t)).join(', ');
+    const noun = n === 1 ? 'ticket' : 'tickets';
+    return (`This pull request delivers ${n} ${noun} (${refs}) implemented by the ` +
+        `**${input.loopName}** run against \`${input.baseBranch}\`. Each ticket below ` +
+        `describes the problem it addresses, the approach taken, and the test files ` +
+        `touched by its diff.`);
+}
+/** Body-facing ref: Jira key verbatim when linked, `#<id>` for local tickets. */
+function displayRef(t) {
+    return t.jiraKey?.trim() ? (0, pr_naming_1.ticketRef)(t) : `#${t.ticketId}`;
+}
+function ticketSection(t, changes) {
+    const title = cleanInline(t.title);
+    const heading = title ? `## ${displayRef(t)} — ${title}` : `## ${displayRef(t)}`;
+    const chunks = [heading];
+    const narrative = extractSpecNarrative(t.description);
+    if (narrative.problem) {
+        chunks.push('**Problem**', clampText(narrative.problem, PROBLEM_MAX));
+    }
+    if (narrative.solution) {
+        chunks.push('**Solution**', clampText(narrative.solution, SOLUTION_MAX));
+        if (narrative.overflow) {
+            chunks.push(`<details>\n<summary>Full spec digest</summary>\n\n${clampText(narrative.overflow, OVERFLOW_MAX)}\n\n</details>`);
+        }
+    }
+    chunks.push('**Tests**', testsLine(t, changes));
+    return chunks.join('\n\n');
+}
+function testsLine(t, changes) {
+    const entry = t.branch ? changes?.get(t.branch) : undefined;
+    if (!entry || entry.failed) {
+        return '_Diff unavailable — test changes could not be derived._';
+    }
+    if (entry.testFiles.length === 0) {
+        return 'No test files changed in this diff.';
+    }
+    const listed = entry.testFiles.slice(0, MAX_TEST_FILES_LISTED);
+    const lines = listed.map((f) => `- \`${f}\``);
+    const more = entry.testFiles.length - listed.length;
+    if (more > 0)
+        lines.push(`- … and ${more} more`);
+    return lines.join('\n');
+}
+function buildChangesSection(changes) {
+    if (!changes)
+        return null;
+    const ok = [...changes.values()].filter((c) => !c.failed);
+    if (ok.length === 0)
+        return null;
+    const lines = ok.map((c) => {
+        const stat = c.filesChanged > 0
+            ? `${c.filesChanged} file${c.filesChanged === 1 ? '' : 's'} changed, +${c.insertions} −${c.deletions}`
+            : 'no file changes detected';
+        return `- \`${c.branch}\` — ${stat}`;
+    });
+    return ['## Changes', lines.join('\n')].join('\n\n');
+}
+const PROBLEM_HEADING_RE = /\b(problem|context|background|motivation|why)\b/i;
+const SOLUTION_HEADING_RE = /\b(solution|approach|design|implementation|proposal|how|what)\b/i;
+/**
+ * Split a spec description into Problem/Solution digests:
+ *  - a heading matching problem/context/background wins the Problem slot,
+ *    else the leading narrative before the first heading;
+ *  - headings matching solution/approach/design/implementation feed the
+ *    Solution slot, else everything that is not the Problem;
+ *  - the Contract Layer appendix (app machinery) is stripped first.
+ * Tolerates missing/empty descriptions (both slots null → headings omitted).
+ */
+function extractSpecNarrative(description) {
+    if (typeof description !== 'string' || !description.trim()) {
+        return { problem: null, solution: null, overflow: null };
+    }
+    const { user } = (0, explore_contract_refine_1.splitDescriptionAtContractLayer)(description);
+    const text = user.replace(/\r\n/g, '\n').trim();
+    if (!text)
+        return { problem: null, solution: null, overflow: null };
+    const sections = splitSections(text);
+    const preamble = sections.find((s) => s.title === null)?.content?.trim() ?? '';
+    const headed = sections.filter((s) => s.title !== null);
+    let problem = null;
+    const problemSection = headed.find((s) => PROBLEM_HEADING_RE.test(s.title));
+    if (problemSection?.content.trim()) {
+        problem = problemSection.content.trim();
+    }
+    else if (preamble) {
+        problem = preamble;
+    }
+    const solutionParts = [];
+    const solutionSections = headed.filter((s) => s !== problemSection && SOLUTION_HEADING_RE.test(s.title));
+    if (solutionSections.length > 0) {
+        for (const s of solutionSections) {
+            if (s.content.trim())
+                solutionParts.push(`**${s.title.trim()}** — ${s.content.trim()}`);
+        }
+    }
+    else {
+        // No explicit solution headings: use the remaining content (everything
+        // after what we used as the problem).
+        const rest = headed.filter((s) => s !== problemSection && s.content.trim());
+        if (rest.length > 0) {
+            for (const s of rest)
+                solutionParts.push(`**${s.title.trim()}** — ${s.content.trim()}`);
+        }
+        else if (!problemSection && preamble && problem === preamble) {
+            // Heading-less description: first paragraph = problem, remainder = solution.
+            const paras = preamble.split(/\n{2,}/);
+            if (paras.length > 1) {
+                problem = paras[0].trim();
+                solutionParts.push(paras.slice(1).join('\n\n').trim());
+            }
+        }
+    }
+    const solutionFull = solutionParts.join('\n\n').trim() || null;
+    if (!solutionFull)
+        return { problem, solution: null, overflow: null };
+    if (solutionFull.length <= SOLUTION_MAX)
+        return { problem, solution: solutionFull, overflow: null };
+    return {
+        problem,
+        solution: clampText(solutionFull, SOLUTION_MAX),
+        overflow: solutionFull,
+    };
+}
+/** Split markdown into sections at `#`-headings and standalone `**Bold**` label lines. */
+function splitSections(text) {
+    const lines = text.split('\n');
+    const sections = [];
+    let current = { title: null, content: '' };
+    for (const line of lines) {
+        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line) ?? /^\*\*([^*]+)\*\*:?\s*$/.exec(line);
+        if (heading) {
+            sections.push(current);
+            current = { title: heading[1], content: '' };
+        }
+        else {
+            current.content += (current.content ? '\n' : '') + line;
+        }
+    }
+    sections.push(current);
+    return sections;
+}
+function cleanInline(raw) {
+    if (typeof raw !== 'string')
+        return '';
+    // eslint-disable-next-line no-control-regex
+    return raw.replace(/[\x00-\x1F\x7F]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function clampText(s, max) {
+    const trimmed = s.trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    const cut = trimmed.slice(0, max);
+    const lastSpace = cut.lastIndexOf(' ');
+    return `${cut.slice(0, lastSpace > max / 2 ? lastSpace : max).trimEnd()} …`;
+}

package/server/dist/pr-naming.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyChangeType = classifyChangeType;
+exports.batchChangeType = batchChangeType;
+exports.ticketRef = ticketRef;
+exports.kebabTitle = kebabTitle;
+exports.ticketBranchName = ticketBranchName;
+exports.batchBranchNameFor = batchBranchNameFor;
+exports.resolveCollisionFreeName = resolveCollisionFreeName;
+exports.titleChangeSummary = titleChangeSummary;
+exports.buildPrTitle = buildPrTitle;
+/**
+ * Conventional naming for the safe-pr-review-flow's user-facing git surface:
+ * branch names and PR titles. Pure string logic (no git/db IO) so the whole
+ * matrix is unit-testable; callers thread ticket data (title/labels/jira key)
+ * in and run the collision predicate against their own branch listing.
+ *
+ * Branch conventions:
+ *   per-unit  →  `<type>/<ref>-<kebab-title>`   e.g. feat/SKILLS-101-add-dark-mode
+ *   batch     →  `<type>/<primary-ref>-batch-<n>-tickets`
+ *
+ * PR title conventions:
+ *   single    →  `[<ref>]<type> - <change>`      e.g. [SKILLS-101]feat - darkmode added
+ *   batch     →  `[<ref> +<n-1>]<type> - <loop-level summary>`
+ *
+ * `<ref>` is the ticket's Jira key when Jira-linked (JIRA ALWAYS PREVAILS —
+ * resolved by the caller from the authoritative `jira_links` row first, the
+ * ticket's `jira_key` field second), else the local ticket number.
+ *
+ * `<type>` heuristic (labels checked before the title; first match wins):
+ *   bug | bugfix | fix | hotfix            → fix
+ *   chore | refactor | cleanup | clean-up  → chore
+ *   docs | doc | documentation            → docs
+ *   anything else                          → feat
+ */
+const integration_branch_1 = require("./integration-branch");
+const TYPE_PATTERNS = [
+    { type: 'fix', re: /(^|[^a-z0-9])(bug|bugfix|fix|fixes|fixed|hotfix)([^a-z0-9]|$)/i },
+    { type: 'chore', re: /(^|[^a-z0-9])(chore|refactor|refactoring|cleanup|clean-up|maintenance)([^a-z0-9]|$)/i },
+    { type: 'docs', re: /(^|[^a-z0-9])(docs|doc|documentation)([^a-z0-9]|$)/i },
+];
+/** The documented `<type>` heuristic: labels take precedence over the title. */
+function classifyChangeType(t) {
+    const labels = (t.labels ?? []).filter((l) => typeof l === 'string');
+    for (const { type, re } of TYPE_PATTERNS) {
+        if (labels.some((l) => re.test(l)))
+            return type;
+    }
+    const title = typeof t.title === 'string' ? t.title : '';
+    for (const { type, re } of TYPE_PATTERNS) {
+        if (re.test(title))
+            return type;
+    }
+    return 'feat';
+}
+/** Batch type: `feat` unless EVERY ticket maps to the same other type. */
+function batchChangeType(tickets) {
+    if (tickets.length === 0)
+        return 'feat';
+    const types = new Set(tickets.map(classifyChangeType));
+    if (types.size === 1) {
+        const only = [...types][0];
+        return only;
+    }
+    return 'feat';
+}
+/** Display ref: the Jira key when linked (Jira always prevails), else the local id. */
+function ticketRef(t) {
+    const key = t.jiraKey?.trim();
+    return key ? key : String(t.ticketId);
+}
+/**
+ * Branch-safe form of the ref. Jira keys (`PROJ-123`) are already ref-safe;
+ * anything unusual is folded to the safe subset, and an unusable key falls
+ * back to the local ticket number.
+ */
+function refSlug(t) {
+    const key = t.jiraKey?.trim();
+    if (key) {
+        const safe = key
+            .replace(/[^A-Za-z0-9._-]+/g, '-')
+            .replace(/\.{2,}/g, '.')
+            .replace(/^[-.]+|[-.]+$/g, '');
+        if (safe && !/\.lock$/i.test(safe))
+            return safe;
+    }
+    return String(t.ticketId);
+}
+/**
+ * ASCII-folded kebab of a ticket title: NFKD fold + strip diacritics, lowercase,
+ * everything outside [a-z0-9] collapsed to single dashes, ~40 char cap, never a
+ * leading/trailing dash. Emoji/symbol-only titles fold to '' (caller omits).
+ */
+function kebabTitle(raw, maxLen = 40) {
+    if (typeof raw !== 'string' || !raw)
+        return '';
+    const folded = raw
+        .replace(/\u00df/g, 'ss') // no NFKD decomposition \u2014 fold explicitly
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '');
+    let kebab = folded
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (kebab.length > maxLen) {
+        kebab = kebab.slice(0, maxLen);
+        // Prefer cutting at a word boundary when one exists in the tail.
+        const lastDash = kebab.lastIndexOf('-');
+        if (lastDash > maxLen / 2)
+            kebab = kebab.slice(0, lastDash);
+        kebab = kebab.replace(/-+$/g, '');
+    }
+    return kebab;
+}
+/**
+ * Conventional per-unit branch name: `<type>/<ref>-<kebab-title>` (the kebab is
+ * omitted when the title folds to nothing). Guaranteed to pass
+ * `isValidBranchName` — a pathological input degrades to `<type>/<ticketId>`.
+ */
+function ticketBranchName(t) {
+    const type = classifyChangeType(t);
+    const ref = refSlug(t);
+    const kebab = kebabTitle(t.title);
+    const name = kebab ? `${type}/${ref}-${kebab}` : `${type}/${ref}`;
+    return (0, integration_branch_1.isValidBranchName)(name) ? name : `${type}/${t.ticketId}`;
+}
+/**
+ * Conventional batch branch name (N>1 assembled delivery):
+ * `<type>/<primary-ref>-batch-<n>-tickets`.
+ */
+function batchBranchNameFor(tickets) {
+    const type = batchChangeType(tickets);
+    const primary = tickets[0];
+    const ref = primary ? refSlug(primary) : '0';
+    const name = `${type}/${ref}-batch-${tickets.length}-tickets`;
+    return (0, integration_branch_1.isValidBranchName)(name) ? name : `${type}/batch-${tickets.length}-tickets`;
+}
+/**
+ * Bounded collision resolution: the preferred name, else `-2`, `-3`, … up to
+ * `maxAttempts`. Reserved names (the integration branch) are NEVER returned.
+ * `null` when exhausted — the caller picks its own fallback.
+ */
+function resolveCollisionFreeName(preferred, opts) {
+    const reserved = new Set(opts.reserved ?? []);
+    const max = Math.max(1, opts.maxAttempts ?? 20);
+    for (let i = 1; i <= max; i++) {
+        const name = i === 1 ? preferred : `${preferred}-${i}`;
+        if (reserved.has(name))
+            continue;
+        if (!opts.taken(name))
+            return name;
+    }
+    return null;
+}
+const TITLE_CHANGE_MAX = 72;
+const TITLE_MAX = 100;
+/**
+ * One short sentence derived from the ticket title: control chars stripped,
+ * whitespace collapsed, trailing periods dropped, first letter lowercased
+ * unless the leading word reads as an acronym / proper CamelCase identifier.
+ */
+function titleChangeSummary(raw) {
+    if (typeof raw !== 'string')
+        return '';
+    // eslint-disable-next-line no-control-regex
+    let s = raw.replace(/[\x00-\x1F\x7F]/g, ' ').replace(/\s+/g, ' ').trim();
+    s = s.replace(/[.\s]+$/g, '');
+    if (!s)
+        return '';
+    s = decapitalizeFirst(s);
+    if (s.length > TITLE_CHANGE_MAX)
+        s = `${s.slice(0, TITLE_CHANGE_MAX - 1).trimEnd()}…`;
+    return s;
+}
+function decapitalizeFirst(s) {
+    const m = /^[A-Za-z][A-Za-z0-9']*/.exec(s);
+    if (!m)
+        return s;
+    const word = m[0];
+    // All-caps acronym (MCP, OTEL) or CamelCase identifier (JobDetailPage) → keep.
+    if (word.length > 1 && /[A-Z]/.test(word.slice(1)))
+        return s;
+    return s[0].toLowerCase() + s.slice(1);
+}
+/**
+ * Conventional PR title.
+ *   1 ticket  → `[<ref>]<type> - <change>`
+ *   N tickets → `[<primary-ref> +<n-1>]<type> - <loop-level summary>`
+ * The per-ticket `<type>` uses the SAME heuristic as the branch name, so the
+ * two stay consistent for a given ticket.
+ */
+function buildPrTitle(tickets, opts = {}) {
+    if (tickets.length === 0) {
+        // Defensive — deliveries always carry ≥1 succeeded ticket.
+        return truncateTitle(titleChangeSummary(opts.loopName) || 'specrails delivery');
+    }
+    if (tickets.length === 1) {
+        const t = tickets[0];
+        const change = titleChangeSummary(t.title) || `implement ${ticketRef(t)}`;
+        return truncateTitle(`[${ticketRef(t)}]${classifyChangeType(t)} - ${change}`);
+    }
+    const primary = tickets[0];
+    const type = batchChangeType(tickets);
+    const loop = titleChangeSummary(opts.loopName);
+    const summary = loop ? `${loop} batch of ${tickets.length} tickets` : `batch of ${tickets.length} tickets`;
+    return truncateTitle(`[${ticketRef(primary)} +${tickets.length - 1}]${type} - ${summary}`);
+}
+function truncateTitle(s) {
+    return s.length > TITLE_MAX ? `${s.slice(0, TITLE_MAX - 1).trimEnd()}…` : s;
+}

package/server/dist/pr-publisher.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultExec = void 0;
+exports.parsePrUrl = parsePrUrl;
+exports.publishDraftPr = publishDraftPr;
+/**
+ * App-owned "deliver a mutating loop's result as a DRAFT PR" primitive.
+ *
+ * This is the single sanctioned path for a loop's work to leave the machine:
+ * push the (already-committed) ticket/integration branch and open a **draft**
+ * pull request against the designated integration branch. specrails never
+ * merges and never opens a non-draft PR — the human owns the merge.
+ *
+ * Degradation ladder (a loop must NEVER fail because a PR could not be opened):
+ *   pr-created  → branch pushed AND `gh pr create --draft` succeeded.
+ *   pushed      → branch pushed but the PR could not be created (no `gh`, not
+ *                 authenticated, insufficient remote perms). The user can open
+ *                 the PR by hand from the pushed branch.
+ *   local-only  → the branch could not be pushed (no remote / no network /
+ *                 auth). The work is still safe as a local branch.
+ *
+ * Pure over an injectable `Exec` so it is unit-tested without git/gh or a network.
+ */
+const child_process_1 = require("child_process");
+const git_guardrails_1 = require("./git-guardrails");
+exports.defaultExec = {
+    run(cmd, args, cwd) {
+        return new Promise((resolve) => {
+            (0, child_process_1.execFile)(cmd, args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+                const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
+                resolve({ code, stdout: stdout?.toString() ?? '', stderr: stderr?.toString() ?? '' });
+            });
+        });
+    },
+};
+/** Extract the first PR URL gh prints (e.g. https://github.com/o/r/pull/12). */
+function parsePrUrl(stdout) {
+    const m = stdout.match(/https?:\/\/\S+\/pull\/\d+/);
+    return m ? m[0] : undefined;
+}
+async function publishDraftPr(exec, input) {
+    const remote = input.remote ?? 'origin';
+    const { repoDir, branch, baseBranch } = input;
+    // 1. Push the branch (set upstream). Failure → local-only, never throw.
+    //    Guardrail: never force-push, never push the integration branch itself.
+    const pushArgs = ['push', '-u', remote, branch];
+    (0, git_guardrails_1.assertGitAllowed)('git', pushArgs, { protectedBranch: baseBranch });
+    const push = await exec.run('git', pushArgs, repoDir);
+    if (push.code !== 0) {
+        return { state: 'local-only', branch, reason: reasonFrom(push) };
+    }
+    // 2. Open a DRAFT PR. Failure (no gh / not authed / perms) → pushed, never throw.
+    const pr = await exec.run('gh', ['pr', 'create', '--draft', '--base', baseBranch, '--head', branch, '--title', input.title, '--body', input.body], repoDir);
+    if (pr.code !== 0) {
+        return { state: 'pushed', branch, reason: reasonFrom(pr) };
+    }
+    const prUrl = parsePrUrl(pr.stdout);
+    if (!prUrl) {
+        // gh exited 0 but we couldn't find a URL — treat as pushed (the PR likely
+        // exists) rather than claiming a URL we don't have.
+        return { state: 'pushed', branch, reason: 'pr-created-no-url' };
+    }
+    return { state: 'pr-created', branch, prUrl };
+}
+function reasonFrom(r) {
+    const msg = (r.stderr.trim() || r.stdout.trim()).split('\n')[0];
+    return msg || `exit ${r.code}`;
+}