clud-bug 0.6.34 → 0.7.0-rc.11

package/dist/core/inline-threads.js

@@ -0,0 +1,369 @@
+// Wave 5a — D.2.X inline review threads (npm workflow parity, OSS port).
+//
+// This module holds the pure helpers + GraphQL operation strings that BOTH
+// the npm workflow path and the hosted clud-bug-app use to attach a
+// per-finding inline review thread to the PR (replacing the legacy
+// "one big summary comment listing every finding" UX).
+//
+// The split between npm and app:
+//   - npm path (this package's CLI verb `post-inline-threads`) is stateless:
+//     it shells out to `gh api` for the REST createReview + `gh api graphql`
+//     for the GraphQL thread-id lookup, then EXITS. No persistent record —
+//     Wave 5b's auto-resolve re-queries GitHub on the next push and re-derives
+//     finding IDs from the comment-body markers we embed here.
+//   - app path keeps its Redis-backed persistence for performance (cross-
+//     push thread correlation without re-querying GraphQL every time). The
+//     pure helpers below are designed so a future Wave 5c swap can have the
+//     App import from this module + drop its local duplicates.
+//
+// Designed to share `findingId` semantics with clud-bug-app's
+// `lib/inline-threads.ts:findingId` (SHA-256 of the canonical 5-tuple,
+// truncated to 16 hex chars) so threads posted by one consumer stay
+// matchable by the other after the App migrates.
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Stable finding id — SHA-256 of the canonical 5-tuple, truncated to 16 hex.
+// ---------------------------------------------------------------------------
+/**
+ * Hashes the canonical `${file}:${line}:${severity}:${skill}:${summary[:100]}`
+ * tuple to 16 hex characters. Stable across consumers — the App computes
+ * the same hash for the same finding, so threads posted by one consumer
+ * stay matchable by the other.
+ *
+ * Summary is truncated to 100 chars BEFORE hashing so small wording tweaks
+ * on subsequent review passes don't generate a fresh id and orphan the
+ * prior thread.
+ *
+ * Distinct from `findingIdentity` in `./diff-findings` (which returns the
+ * plain unhashed string — used by the Resolved/Still-open block matcher).
+ * Both helpers coexist on purpose: the unhashed string is human-readable
+ * for in-prose matching; the hash is short + collision-safe for embedding
+ * in `<!-- finding-id: ... -->` comment-body markers.
+ */
+export function findingId(finding) {
+    const file = finding.file ?? '<no-file>';
+    const line = finding.line ?? 0;
+    const summary = finding.summary.slice(0, 100);
+    const payload = `${file}:${line}:${finding.severity}:${finding.skill}:${summary}`;
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+// ---------------------------------------------------------------------------
+// Diff anchor detection
+// ---------------------------------------------------------------------------
+/**
+ * Returns the set of 1-indexed HEAD-side line numbers a unified-diff patch
+ * touches (added + context lines). GitHub only accepts inline review
+ * comments on lines that appear in the diff, so this gates whether a
+ * finding's `line` can become a thread.
+ *
+ * "Touched" = appears on the RIGHT side of the unified diff: added (`+`)
+ * lines OR unchanged context (` `) lines inside any hunk. Removed (`-`)
+ * lines are LEFT-side only and can't anchor inline comments.
+ *
+ * If `patch` is undefined (binary file, GitHub truncation) returns an empty
+ * set — the caller falls back to the summary comment for those findings.
+ */
+export function parseHeadLines(patch) {
+    const lines = new Set();
+    if (!patch)
+        return lines;
+    // Hunk header: @@ -oldStart,oldLines +newStart,newLines @@
+    // newLines defaults to 1 when omitted.
+    const hunkHeaderRe = /^@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,(\d+))?\s+@@/;
+    let newLine = 0;
+    let inHunk = false;
+    for (const rawLine of patch.split('\n')) {
+        const m = rawLine.match(hunkHeaderRe);
+        if (m) {
+            newLine = Number.parseInt(m[1], 10);
+            inHunk = true;
+            continue;
+        }
+        if (!inHunk)
+            continue;
+        if (rawLine.startsWith('+') && !rawLine.startsWith('+++')) {
+            lines.add(newLine);
+            newLine++;
+        }
+        else if (rawLine.startsWith('-') && !rawLine.startsWith('---')) {
+            // LEFT-side only — does not advance the newLine counter.
+        }
+        else if (rawLine.startsWith('\\')) {
+            // "" — doesn't advance.
+        }
+        else {
+            // Context line — counts as a HEAD-side line.
+            lines.add(newLine);
+            newLine++;
+        }
+    }
+    return lines;
+}
+/**
+ * Returns true when the finding's `(file, line)` can be anchored as an
+ * inline comment on the current diff. `diffFiles` is the per-file diff
+ * (as returned by `gh api repos/.../pulls/.../files`).
+ */
+export function findingAnchorable(finding, diffFiles) {
+    if (!finding.file || !finding.line)
+        return false;
+    const file = diffFiles.find((f) => f.filename === finding.file);
+    if (!file)
+        return false;
+    return parseHeadLines(file.patch).has(finding.line);
+}
+// ---------------------------------------------------------------------------
+// Context extraction for the verifier (consumed in Wave 5b)
+// ---------------------------------------------------------------------------
+/**
+ * Builds the `{codeBefore, codeAfter, diffAtAnchor?}` triple Wave 5b's
+ * auto-resolve verifier consumes for a single finding, pulled out of the
+ * unified-diff hunk that touches the finding's line.
+ *
+ * Works entirely from the in-hand patch — no fresh API calls. The patch
+ * already encodes BEFORE (lines with `-` or context) and AFTER (lines with
+ * `+` or context) for every hunk the PR touches.
+ *
+ * Returns empty strings for `codeBefore`/`codeAfter` when the finding's
+ * file isn't in the diff at all. The verifier sees "unchanged" and
+ * typically returns NOT_ADDRESSED / UNCERTAIN, which is the correct
+ * behavior — an unchanged file isn't a fix.
+ */
+export function extractAnchorContext(finding, diffFiles) {
+    if (!finding.file || !finding.line) {
+        return { codeBefore: '', codeAfter: '' };
+    }
+    const file = diffFiles.find((f) => f.filename === finding.file);
+    if (!file || !file.patch) {
+        return { codeBefore: '', codeAfter: '' };
+    }
+    // Locate the hunk whose new-side range contains finding.line.
+    const hunkHeaderRe = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/;
+    const patchLines = file.patch.split('\n');
+    let currentHunkStart = -1;
+    for (let i = 0; i < patchLines.length; i++) {
+        const m = patchLines[i].match(hunkHeaderRe);
+        if (!m)
+            continue;
+        const newStart = Number.parseInt(m[3], 10);
+        const newLen = m[4] !== undefined ? Number.parseInt(m[4], 10) : 1;
+        if (finding.line >= newStart &&
+            finding.line < newStart + Math.max(newLen, 1)) {
+            currentHunkStart = i;
+            break;
+        }
+    }
+    if (currentHunkStart < 0) {
+        return { codeBefore: '', codeAfter: '' };
+    }
+    const before = [];
+    const after = [];
+    const hunkBody = [patchLines[currentHunkStart]];
+    for (let i = currentHunkStart + 1; i < patchLines.length; i++) {
+        const line = patchLines[i];
+        if (line.match(hunkHeaderRe))
+            break;
+        hunkBody.push(line);
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            after.push(line.slice(1));
+        }
+        else if (line.startsWith('-') && !line.startsWith('---')) {
+            before.push(line.slice(1));
+        }
+        else if (line.startsWith('\\')) {
+            // No-newline marker — skip.
+        }
+        else if (line.length > 0) {
+            // Context line — appears on both sides.
+            const stripped = line.startsWith(' ') ? line.slice(1) : line;
+            before.push(stripped);
+            after.push(stripped);
+        }
+    }
+    return {
+        codeBefore: before.join('\n'),
+        codeAfter: after.join('\n'),
+        diffAtAnchor: hunkBody.join('\n'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Comment body rendering
+// ---------------------------------------------------------------------------
+/**
+ * Body for a single inline-thread comment. Includes a hidden HTML marker
+ * carrying `findingId` so Wave 5b's auto-resolve can recover the canonical
+ * id from the thread's first comment body without persisting state.
+ */
+export function renderThreadBody(finding) {
+    const id = findingId(finding);
+    const severityBadge = finding.severity === 'critical' ? '🔴' : '🟡';
+    const header = `${severityBadge} \`${finding.skill}\``;
+    const body = finding.summary.trim();
+    const reasoning = finding.reasoning ? `\n\n${finding.reasoning.trim()}` : '';
+    return `<!-- finding-id: ${id} -->\n${header}\n\n${body}${reasoning}`;
+}
+/**
+ * Extracts the hashed `findingId` from a thread comment body that was
+ * rendered by `renderThreadBody`. Returns null when the marker is absent
+ * (a manual reply, or a comment posted by a different tool).
+ *
+ * Used by Wave 5b's auto-resolve to re-derive finding ids from existing
+ * GitHub threads on a stateless re-run.
+ */
+export function extractFindingIdFromBody(body) {
+    // Anchor to start-of-string so a user reply that quotes the marker can't be
+    // misattributed as bot-authored. `renderThreadBody` always places the marker
+    // on line 1 — anything else is suspect input.
+    const m = body.match(/^<!--\s*finding-id:\s*([a-f0-9]{16})\s*-->/);
+    return m ? m[1] : null;
+}
+/**
+ * Wave 5b — invert `renderThreadBody` to recover the original finding
+ * tuple from a bot-authored thread comment. The fix-push auto-resolve
+ * CLI verb uses this to reconstruct `PriorFinding` from the GraphQL
+ * `reviewThreads` response without persistent state.
+ *
+ * Returns null when the body doesn't match the canonical shape
+ * `<!-- finding-id: XX -->\n🔴|🟡 \`skill\`\n\nsummary[\n\nreasoning]`.
+ * Same start-anchored posture as `extractFindingIdFromBody` for anti-
+ * injection: a user reply that quotes the marker mid-body won't be
+ * misattributed as bot-authored.
+ */
+export function parseThreadBody(body) {
+    // Marker (line 1), header (line 2: badge + backticked skill), blank,
+    // summary, optional blank + reasoning. The header line shape:
+    //   `🔴 \`critical-issues-only\``  or  `🟡 \`magic-numbers\``
+    const re = /^<!--\s*finding-id:\s*([a-f0-9]{16})\s*-->\n(🔴|🟡)\s+`([^`]+)`\n\n([\s\S]+?)(?:\n\n([\s\S]+))?$/;
+    const m = body.match(re);
+    if (!m)
+        return null;
+    const [, findingId, badge, skill, summary, reasoning] = m;
+    const severity = badge === '🔴' ? 'critical' : 'minor';
+    const out = {
+        findingId: findingId,
+        severity,
+        skill: skill,
+        summary: summary.trim(),
+    };
+    if (reasoning && reasoning.trim())
+        out.reasoning = reasoning.trim();
+    return out;
+}
+/**
+ * Partitions a flat findings list into the `comments[]` body for
+ * `POST /repos/:owner/:repo/pulls/:n/reviews` + the findings the caller
+ * should surface elsewhere (summary comment for `skipped`; never for
+ * `preexisting`).
+ *
+ * Pure function — no I/O. The CLI verb uses this to compute the API body;
+ * the App can use it after Wave 5c migration to share the same partitioning.
+ */
+export function planInlineThreads(findings, diffFiles) {
+    const comments = [];
+    const skipped = [];
+    const preexisting = [];
+    for (const f of findings) {
+        if (f.severity === 'preexisting') {
+            preexisting.push(f);
+            continue;
+        }
+        if (!findingAnchorable(f, diffFiles)) {
+            skipped.push(f);
+            continue;
+        }
+        comments.push({
+            path: f.file,
+            line: f.line,
+            side: 'RIGHT',
+            body: renderThreadBody(f),
+        });
+    }
+    return { comments, skipped, preexisting };
+}
+// ---------------------------------------------------------------------------
+// GraphQL operations — pinned to module scope so callers (and tests) can
+// reference the same query strings as the App.
+// ---------------------------------------------------------------------------
+// Wave 5b update — `author { login }` added so the resolve-threads CLI
+// verb can filter to bot-authored threads. Without this, the bot-filter
+// reads `comments[0].author?.login` as undefined and accepts everything,
+// which would feed user-authored threads (that happen to start with the
+// marker) into the verifier. Additive change — Wave 5a consumers
+// (post-inline-threads) didn't read `author` so they're unaffected.
+export const REVIEW_THREADS_QUERY = `
+  query ReviewThreads($owner: String!, $repo: String!, $pr: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $pr) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            comments(first: 100) {
+              nodes {
+                databaseId
+                path
+                line
+                originalLine
+                body
+                author {
+                  login
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+// Includes `body` (unlike the App's lighter state query, which omits it) so
+// Wave 5b's auto-resolve can re-derive the `findingId` from the
+// `<!-- finding-id: ... -->` marker on each thread's first comment WITHOUT
+// persisting state between fix-pushes. The npm workflow is stateless; the
+// body field is the substitute for Redis-backed thread-id correlation.
+export const REVIEW_THREADS_STATE_QUERY = `
+  query ReviewThreadStates($owner: String!, $repo: String!, $pr: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $pr) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            comments(first: 1) {
+              nodes {
+                databaseId
+                body
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+export const RESOLVE_THREAD_MUTATION = `
+  mutation ResolveThread($threadId: ID!) {
+    resolveReviewThread(input: { threadId: $threadId }) {
+      thread {
+        isResolved
+      }
+    }
+  }
+`;
+// Wave 5b — post a reply on a review thread (used to attach the
+// auto-resolve marker explaining the verifier's verdict) BEFORE
+// calling `RESOLVE_THREAD_MUTATION`. The reply is visible in the PR
+// timeline so reviewers can audit why the bot auto-resolved.
+export const ADD_REPLY_MUTATION = `
+  mutation AddThreadReply($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(
+      input: { pullRequestReviewThreadId: $threadId, body: $body }
+    ) {
+      comment {
+        id
+        body
+      }
+    }
+  }
+`;
+//# sourceMappingURL=inline-threads.js.map

package/dist/core/inline-threads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-threads.js","sourceRoot":"","sources":["../../src/core/inline-threads.ts"],"names":[],"mappings":"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"}

package/dist/core/prompt-builder.d.ts

@@ -0,0 +1,164 @@
+import type { Finding } from './review-schema-zod.js';
+/** Max bytes of patch per file to include in the prompt. Beyond this we
+ * truncate with a `... (N bytes omitted)` marker so the model knows the
+ * file kept going.
+ */
+export declare const MAX_PATCH_BYTES_PER_FILE: number;
+/** Default skill-body byte cap when the caller doesn't supply one.
+ * Matches SPEC §1.10 ceiling + the App's `MAX_SKILL_BYTES` env default
+ * (see clud-bug-app/lib/env.ts).
+ */
+export declare const DEFAULT_MAX_SKILL_BYTES = 8192;
+/**
+ * Status taxonomy mirrors `PullRequestFile["status"]` from `@octokit/rest`.
+ * We accept the wider GitHub union so callers can pass octokit's raw status
+ * verbatim.
+ */
+export type ChangedFileStatus = 'added' | 'modified' | 'removed' | 'renamed' | 'copied' | 'changed' | 'unchanged';
+export interface ChangedFile {
+    /** Repo-relative POSIX path. */
+    path: string;
+    /** GitHub's per-file status. */
+    status: ChangedFileStatus;
+    /** Lines added. */
+    additions: number;
+    /** Lines deleted. */
+    deletions: number;
+    /**
+     * Unified-diff patch for this file. May be empty for binary files or
+     * very large diffs (GitHub omits the patch above ~3000 lines). The
+     * App orchestrator treats absent patch as "skip this file from review".
+     */
+    patch: string | undefined;
+}
+export interface PullRequestDiff {
+    files: ChangedFile[];
+    /** PR HEAD SHA (40-char). Pinned to `<!-- review-sha: ... -->`. */
+    headSha: string;
+    /** PR BASE SHA (40-char). Used as the ref for skills-loader. */
+    baseSha: string;
+    /** PR base branch name (e.g. `main`). Used for human-readable logs. */
+    baseRef: string;
+    /** PR head branch name. Used for the writeback commit. */
+    headRef: string;
+    /** Sum of `additions + deletions` across `files`. */
+    totalChanges: number;
+    /** Total bytes of `patch` content combined. Drives the 100KB skip rule. */
+    totalPatchBytes: number;
+}
+/** Minimal applies_to rule type — matches `SkillFrontmatter.applies_to`. */
+export interface PromptAppliesToRule {
+    paths?: string[];
+    extensions?: string[];
+}
+/** Minimal frontmatter shape the prompt builder needs from each skill. */
+export interface PromptSkillFrontmatter {
+    name: string;
+    description: string;
+    applies_to?: PromptAppliesToRule;
+}
+/** Minimal LoadedSkill shape — slug + parsed frontmatter + body. */
+export interface PromptLoadedSkill {
+    slug: string;
+    frontmatter: PromptSkillFrontmatter;
+    body: string;
+}
+export interface BuildReviewPromptInput {
+    repo: {
+        owner: string;
+        name: string;
+    };
+    pr: {
+        number: number;
+        title?: string;
+        baseRef: string;
+        headRef: string;
+    };
+    diff: PullRequestDiff;
+    skills: PromptLoadedSkill[];
+    /**
+     * Per-skill body byte cap. Defaults to `DEFAULT_MAX_SKILL_BYTES` (8192)
+     * matching SPEC §1.10 + the App's `MAX_SKILL_BYTES` env. Callers running
+     * the App provide it from `getEnv().MAX_SKILL_BYTES`; callers outside
+     * the App may omit it.
+     */
+    maxSkillBytes?: number;
+}
+export interface BuiltPrompt {
+    system: string;
+    prompt: string;
+    /** Slugs actually included (used for skills_referenced fallback). */
+    includedSkillSlugs: string[];
+    /** Files skipped because their patch was empty (binary, too large). */
+    skippedFiles: string[];
+}
+/**
+ * Builds the system + user prompt pair for the review call.
+ */
+export declare function buildReviewPrompt(input: BuildReviewPromptInput): BuiltPrompt;
+/**
+ * Returns true when the diff includes at least one file matching the
+ * applies_to clause. Absent applies_to → matches everything.
+ */
+export declare function skillMatchesDiff(appliesTo: PromptAppliesToRule | undefined, changedPaths: string[]): boolean;
+/**
+ * Very small glob matcher supporting `**` (any path segment) and `*`
+ * (any chars within a segment). Sufficient for the SPEC §1.10 examples
+ * (`src/**`, `*.ts`). Not a drop-in replacement for `minimatch`; if we
+ * need negation / brace expansion later, swap to minimatch — but adding
+ * a dependency for two characters of syntax isn't worth it yet.
+ *
+ * Exported because the App's skill-routing code reuses it for an
+ * orchestrator-side pre-filter that runs before prompt construction.
+ */
+export declare function globMatch(pattern: string, path: string): boolean;
+/**
+ * Truncates a patch to `MAX_PATCH_BYTES_PER_FILE`, appending a marker so
+ * the model knows it didn't see the whole file.
+ *
+ * Cut via UTF-8 byte buffer (see sliceUtf8Bytes) so multi-byte content
+ * — emoji in commit-author lines, CJK identifiers — doesn't blow past
+ * the byte cap. clud-bug-review #158 flagged the original code-unit
+ * slice as a contract violation when content went non-ASCII.
+ */
+export declare function truncatePatch(patch: string): string;
+/**
+ * Slice a string to at most `maxBytes` UTF-8 bytes, trimming any trailing
+ * partial codepoint (so the output is always a valid UTF-8 string).
+ *
+ * Why we need this: `String.prototype.slice(0, N)` keeps N UTF-16 code
+ * units, not N bytes. A skill body of CJK characters at maxSkillBytes=8192
+ * would actually carry 3*8192 ≈ 24KiB of UTF-8 bytes — silently busting
+ * the cap the call site exists to enforce. Buffer-based slicing is
+ * authoritative; we then decode back as UTF-8 with `fatal: false` so a
+ * trailing partial codepoint becomes a single replacement character that
+ * we strip below.
+ *
+ * For pure-ASCII content (the dominant case for skill files + diffs), this
+ * is bit-equivalent to String.slice. The fix only kicks in on multibyte.
+ */
+export declare function sliceUtf8Bytes(input: string, maxBytes: number): string;
+export interface BuildCrossCheckPromptInput extends BuildReviewPromptInput {
+    /** Pass 1's findings — the cross-check pass annotates these. */
+    pass1Findings: Finding[];
+}
+/**
+ * Builds a cross-check prompt: Pass 2 sees Pass 1's findings as a numbered
+ * list + the same skills + the same diff.
+ *
+ * The prompt asks Pass 2 to:
+ *   - emit a verdict per Pass-1 finding (referenced by 0-indexed number)
+ *   - emit an independent findings list (issues Pass 1 missed)
+ *
+ * The aggregator turns the verdicts into per-finding attribution lines.
+ */
+export declare function buildCrossCheckPrompt(input: BuildCrossCheckPromptInput): BuiltPrompt;
+/**
+ * Builds a consensus prompt: Pass N runs fully independent of Pass 1. The
+ * orchestrator diffs their outputs and keeps the intersection.
+ *
+ * This is essentially `buildReviewPrompt` with a tweaked system prompt
+ * — the user message is identical so the model can't tell which pass it is.
+ */
+export declare function buildConsensusPrompt(input: BuildReviewPromptInput): BuiltPrompt;
+//# sourceMappingURL=prompt-builder.d.ts.map

package/dist/core/prompt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../../src/core/prompt-builder.ts"],"names":[],"mappings":"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"}