@vintasoftware/pr-review-canvas 0.1.0

package/src/contract/api.ts

@@ -0,0 +1,190 @@
+import type { z } from 'zod'
+import type { CanvasManifest } from './canvas-manifest.js'
+import type { CommentsPayload, IssueComment, ReviewComment } from './comments.js'
+import type { SharedCanvasInfoSchema } from './discovery.js'
+import type { FileEntry, Pr, ReviewArtifact } from './review-artifact.js'
+import type { PrState } from './state.js'
+
+export const ERROR_CODES = [
+  'BAD_REQUEST',
+  'NOT_FOUND',
+  'FORBIDDEN_HOST',
+  'CROSS_ORIGIN',
+  'NOT_A_REPO',
+  'NO_ORIGIN',
+  'GIT_ERROR',
+  'GH_MISSING',
+  'GH_UNAUTHENTICATED',
+  'GITHUB_API_ERROR',
+  'PR_NOT_FOUND',
+  'CANVAS_NOT_FOUND',
+  'CANVAS_INVALID',
+  'CANVAS_REPO_MISMATCH',
+  'CANVAS_TOO_LARGE',
+  'CANVAS_STALE',
+  'MODEL_INVALID',
+  'SKILL_DIR_EXISTS',
+  'COMMENT_FORBIDDEN',
+  'COMMENT_LINE_NOT_IN_DIFF',
+  'SIGNOFF_INCOMPLETE',
+  'CHAT_BUSY',
+  'NOT_IMPLEMENTED',
+  'INTERNAL',
+] as const
+export type ErrorCode = (typeof ERROR_CODES)[number]
+
+export interface ErrorEnvelope {
+  /** `issues` names what a rejected file got wrong, one line each, never its content. */
+  error: { code: ErrorCode; message: string; hint?: string; issues?: string[] }
+}
+
+export type BundleStatus = 'missing' | 'ready' | 'stale' | 'error'
+
+export interface Capabilities {
+  canComment: boolean | 'unknown'
+  tokenKind: string
+  login: string | null
+  reason?: string
+  hint?: string
+}
+
+export interface CanvasInfo {
+  headSha: string
+  source: 'local' | 'import' | 'fixture'
+  manifest: CanvasManifest | null
+  importedAt?: string
+}
+
+/** How a canvas for another commit relates to the PR head: behind it, or off a discarded branch. */
+export type CanvasRelation = 'ancestor' | 'unrelated'
+
+export interface StaleInfo {
+  canvasHeadSha: string
+  currentHeadSha: string
+  relation: CanvasRelation
+  commitsBehind?: number
+}
+
+/** The answer of `POST /import`, of `pr-review import`, and of an imported shared canvas. */
+export interface ImportResult {
+  status: 'ready' | 'stale' | 'exists'
+  headSha: string
+  currentHeadSha: string
+  relation?: CanvasRelation
+  commitsBehind?: number
+  /** True when the diffs of this canvas can be rebuilt from the local clone. */
+  derivable: boolean
+  warnings: string[]
+}
+
+/** The answer of `POST /shared-canvas/fetch`. */
+export interface SharedCanvasFetchResponse {
+  imported: boolean
+  status: 'ready' | 'stale' | 'missing'
+  sharedCanvas: SharedCanvasInfo | null
+  warnings: string[]
+}
+
+/** A canvas zip found on the pull request. Shaped by the schema the discovery cache stores. */
+export type SharedCanvasInfo = z.infer<typeof SharedCanvasInfoSchema>
+
+export interface PrBundle {
+  status: BundleStatus
+  pr: Pr
+  files: FileEntry[]
+  derivable: boolean
+  artifact?: ReviewArtifact
+  canvas?: CanvasInfo
+  stale?: StaleInfo
+  sharedCanvas?: SharedCanvasInfo
+  skillCommand: string
+  comments: CommentsPayload
+  state: PrState
+  capabilities: Capabilities
+  /** From the project config plus the acpx check; the client hides the pane when either says no. */
+  chat: ChatStatus
+  /** More than 400 files or 50 000 changed lines: the page says the canvas was capped. */
+  largePr: boolean
+  error?: ErrorEnvelope['error']
+  warnings: string[]
+}
+
+/** Every answer of a state route, so the page can replace its copy of the state in one step. */
+export interface StateResponse {
+  prNumber: number
+  state: PrState
+}
+
+export type PostCommentResponse = (
+  | { kind: 'review'; comment: ReviewComment }
+  | { kind: 'issue'; comment: IssueComment }
+) & { state: PrState }
+
+/** The review GitHub created, as the page shows it: a link and its state. */
+export interface ReviewSummary {
+  id: number
+  state: string
+  url: string
+  submittedAt: string | null
+}
+
+/** What the sign-off dialog shows before anything is posted. */
+export interface ReviewBodyResponse {
+  headSha: string
+  body: string
+  /** The titles of the layers that still need a look; approve is refused while this is not empty. */
+  unreviewed: string[]
+}
+
+export interface PostReviewResponse {
+  review: ReviewSummary
+}
+
+export interface PatchesResponse {
+  headSha: string
+  patches: Record<string, string>
+}
+
+export interface ContextResponse {
+  path: string
+  side: 'new' | 'old'
+  from: number
+  to: number
+  lines: string[]
+}
+
+export interface HealthCheck {
+  ok: boolean
+  detail?: string
+}
+
+export interface HealthResponse {
+  ok: boolean
+  version: string
+  checks: {
+    git: HealthCheck
+    origin: HealthCheck
+    gh: HealthCheck
+    ghAuth: HealthCheck
+    /** Chat only; absent when the project config turns chat off. */
+    acpx?: HealthCheck
+    agentInstalled?: HealthCheck
+    agentAuth?: HealthCheck
+  }
+  repo: { owner: string; name: string } | null
+  dataDir: string
+  chat: ChatStatus
+}
+
+/** What the page needs to decide whether to draw the AI Chat pane, and what to say when it cannot. */
+export interface ChatStatus {
+  enabled: boolean
+  /** False when acpx is not on PATH: the pane is hidden and a banner says why. */
+  acpx: boolean
+  agent?: string
+  model?: string | null
+}
+
+export interface HomeData {
+  recentPrs: Array<{ number: number; title: string; updatedAt: string }>
+}

package/src/contract/canvas-manifest.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+import { GeneratorSchema, RepoSchema } from './review-artifact.js'
+
+export const CanvasManifestSchema = z.object({
+  formatVersion: z.literal(1),
+  tool: z.object({ name: z.string(), version: z.string() }),
+  repo: RepoSchema,
+  prNumber: z.number().int().positive().optional(),
+  headSha: z.string().regex(/^[0-9a-f]{40}$/),
+  mergeBaseSha: z.string().regex(/^[0-9a-f]{40}$/),
+  baseRef: z.string(),
+  headRef: z.string(),
+  generatedAt: z.string(),
+  generator: GeneratorSchema,
+})
+export type CanvasManifest = z.infer<typeof CanvasManifestSchema>
+
+export const CanvasIndexSchema = z.object({
+  canvases: z.record(
+    z.string(),
+    z.object({
+      prNumber: z.number().int().positive().optional(),
+      generatedAt: z.string(),
+      source: z.enum(['local', 'import']),
+      importedAt: z.string().optional(),
+    })
+  ),
+})
+export type CanvasIndex = z.infer<typeof CanvasIndexSchema>

package/src/contract/chat.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod'
+import { SideSchema } from './review-artifact.js'
+
+// The context helpers live in static/js/chat-context.js so the browser can load them without a
+// bundler; the server imports the same code here.
+export type { ChatContext } from '../../static/js/chat-context.js'
+export {
+  chatContextAttrs,
+  chatContextFromElement,
+  chatContextLabel,
+  sameChatContext,
+  WHOLE_PR,
+} from '../../static/js/chat-context.js'
+
+export const ChatContextSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('pr') }),
+  z.object({ kind: z.literal('layer'), layerId: z.string().min(1).max(200) }),
+  z.object({ kind: z.literal('file'), path: z.string().min(1).max(1024) }),
+  z.object({
+    kind: z.literal('lines'),
+    path: z.string().min(1).max(1024),
+    side: SideSchema,
+    start: z.number().int().positive(),
+    end: z.number().int().positive(),
+  }),
+  z.object({ kind: z.literal('point'), fingerprint: z.string().min(1).max(200) }),
+])
+
+/** A message longer than this is a paste, not a question. */
+export const CHAT_MESSAGE_MAX = 8000
+
+export const ChatSendSchema = z.object({
+  message: z.string().min(1).max(CHAT_MESSAGE_MAX),
+  context: ChatContextSchema,
+  /** The thread to answer in; the active one when absent. */
+  thread: z.string().min(1).max(200).optional(),
+})
+export type ChatSendInput = z.infer<typeof ChatSendSchema>
+
+export const ChatThreadInputSchema = z.object({ agent: z.string().min(1).max(40).optional() })
+
+/** One saved turn of a thread, as `chat/<name>.jsonl` stores it. */
+export const ChatTurnSchema = z.object({
+  role: z.enum(['user', 'assistant']),
+  text: z.string(),
+  at: z.string(),
+  context: ChatContextSchema.optional(),
+  /** Why the turn ended, on an assistant turn that did not finish. */
+  incomplete: z.string().optional(),
+})
+export type ChatTurn = z.infer<typeof ChatTurnSchema>
+
+export interface ChatThreadsResponse {
+  threads: Array<{ name: string; agent: string; title: string; createdAt: string }>
+  activeThread: string | null
+  /** The agent the next thread would use, from the settings plus any flag override. */
+  agent: string
+}
+
+export interface ChatHistoryResponse {
+  name: string
+  turns: ChatTurn[]
+}
+
+/** The SSE frames the chat route writes, named the same on both sides. */
+export const CHAT_EVENTS = ['turn', 'chunk', 'thought', 'tool', 'done', 'error', 'cancelled'] as const
+export type ChatEventName = (typeof CHAT_EVENTS)[number]
+
+export type ChatEvent =
+  | { event: 'turn'; thread: string; agent: string; seeded: boolean }
+  | { event: 'chunk'; text: string }
+  | { event: 'thought'; text: string }
+  | { event: 'tool'; id: string; title: string; status: string }
+  | { event: 'done'; stopReason: string }
+  | { event: 'error'; code: string; message: string; hint?: string }
+  | { event: 'cancelled' }

package/src/contract/comments.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod'
+import { SideSchema } from './review-artifact.js'
+
+export const ReviewCommentSchema = z.object({
+  id: z.number().int(),
+  author: z.string(),
+  avatarUrl: z.string().optional(),
+  body: z.string(),
+  path: z.string(),
+  line: z.number().int().nullable(),
+  originalLine: z.number().int().nullable(),
+  side: SideSchema,
+  startLine: z.number().int().optional(),
+  outdated: z.boolean(),
+  commitId: z.string(),
+  inReplyToId: z.number().int().optional(),
+  createdAt: z.string(),
+  /** When the comment was last edited, which is its creation time until someone edits it. */
+  updatedAt: z.string(),
+  url: z.string(),
+  resolved: z.boolean(),
+})
+export type ReviewComment = z.infer<typeof ReviewCommentSchema>
+
+export const IssueCommentSchema = z.object({
+  id: z.number().int(),
+  author: z.string(),
+  avatarUrl: z.string().optional(),
+  body: z.string(),
+  createdAt: z.string(),
+  /** When the comment was last edited, which is its creation time until someone edits it. */
+  updatedAt: z.string(),
+  url: z.string(),
+})
+export type IssueComment = z.infer<typeof IssueCommentSchema>
+
+export const ReviewSummarySchema = IssueCommentSchema.extend({ state: z.string() })
+
+export const CommentsPayloadSchema = z.object({
+  fetchedAt: z.string(),
+  headSha: z.string(),
+  reviewComments: z.array(ReviewCommentSchema),
+  issueComments: z.array(IssueCommentSchema),
+  reviews: z.array(ReviewSummarySchema).optional(),
+})
+export type CommentsPayload = z.infer<typeof CommentsPayloadSchema>
+
+/** GitHub rejects a comment body over 65 536 characters, so the tool rejects it first. */
+export const COMMENT_BODY_MAX = 65536
+
+const BodySchema = z.string().min(1).max(COMMENT_BODY_MAX)
+const HeadShaSchema = z
+  .string()
+  .regex(/^[0-9a-f]{40}$/)
+  .optional()
+
+/** What the page sends to `POST /api/prs/:n/comments`. */
+export const PostCommentInputSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('inline'),
+    path: z.string().min(1),
+    line: z.number().int().positive(),
+    side: SideSchema,
+    startLine: z.number().int().positive().optional(),
+    body: BodySchema,
+    /** Set when the comment comes from an attention point, so the sign-off body can name it. */
+    pointFingerprint: z.string().min(1).optional(),
+    /** The commit the page was showing. The server refuses the post when the head moved on. */
+    headSha: HeadShaSchema,
+  }),
+  z.object({
+    kind: z.literal('reply'),
+    inReplyToId: z.number().int().positive(),
+    body: BodySchema,
+    headSha: HeadShaSchema,
+  }),
+  z.object({ kind: z.literal('issue'), body: BodySchema, headSha: HeadShaSchema }),
+])
+export type PostCommentInput = z.infer<typeof PostCommentInputSchema>
+
+/** The posted comment: a review comment for inline and reply, an issue comment for PR-level. */
+export type PostCommentResult = { kind: 'review'; comment: ReviewComment } | { kind: 'issue'; comment: IssueComment }
+
+// The proposed-comment block a chat answer can carry. The parser lives in
+// static/js/proposed-comment.js so the browser loads the same code without a bundler.
+export type { ChatSegment, CommentTargets, ProposedComment } from '../../static/js/proposed-comment.js'
+export {
+  PROPOSED_BODY_MAX,
+  parseProposedComment,
+  splitChatAnswer,
+  targetsFromFiles,
+} from '../../static/js/proposed-comment.js'
+
+export function emptyComments(headSha: string, fetchedAt: string): CommentsPayload {
+  return { fetchedAt, headSha, reviewComments: [], issueComments: [] }
+}

package/src/contract/discovery.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod'
+
+export const SharedCanvasInfoSchema = z.object({
+  url: z.string(),
+  name: z.string(),
+  matchesHead: z.boolean(),
+  downloadable: z.boolean(),
+  reason: z.enum(['auth-required', 'not-zip', 'too-large', 'network', 'name-mismatch']).optional(),
+})
+
+/**
+ * The result of one attachment scan, kept next to the PR. `fingerprint` covers the PR body and
+ * its comments: the scan runs again when one of them changes, or when the user asks for it.
+ */
+export const DiscoveryCacheSchema = z.object({
+  fingerprint: z.string(),
+  checkedAt: z.string(),
+  sharedCanvas: SharedCanvasInfoSchema.nullable(),
+})
+export type DiscoveryCache = z.infer<typeof DiscoveryCacheSchema>

package/src/contract/generation-context.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod'
+import { DefaultLayerSchema, GenerationModeSchema, HighRiskRuleSchema } from '../project-config.js'
+import { DEFAULT_TEST_PATTERNS } from '../review/test-paths.js'
+import { FileEntrySchema, LIMITS, PrSchema, RepoSchema, type TextCaps } from './review-artifact.js'
+
+/** What `prepare` was asked to describe: a pull request, or two refs before a PR exists. */
+export const PrepareTargetSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('pr'), number: z.number().int().positive() }),
+  z.object({ kind: z.literal('refs'), base: z.string().min(1), head: z.string().min(1) }),
+])
+export type PrepareTarget = z.infer<typeof PrepareTargetSchema>
+
+const capsShape = {
+  summary: z.number().int().positive(),
+  layerTitle: z.number().int().positive(),
+  rationale: z.number().int().positive(),
+  decisions: z.number().int().positive(),
+  checkByHand: z.number().int().positive(),
+  annotation: z.number().int().positive(),
+  pointTitle: z.number().int().positive(),
+  pointBody: z.number().int().positive(),
+  testBehavior: z.number().int().positive(),
+  diagram: z.number().int().positive(),
+} satisfies Record<keyof TextCaps, z.ZodNumber>
+
+/**
+ * `context.json`: everything the agent and `publish` need about one prepared canvas. Written by
+ * `prepare` next to `prompt.md`; `publish` validates `model.json` against the hunk index and the
+ * caps recorded here, so a config change between the two commands does not change the rules.
+ */
+export const GenerationContextSchema = z.object({
+  version: z.literal(1),
+  target: PrepareTargetSchema,
+  repo: RepoSchema,
+  pr: PrSchema,
+  headSha: z.string().regex(/^[0-9a-f]{40}$/),
+  mergeBaseSha: z.string().regex(/^[0-9a-f]{40}$/),
+  canvasDir: z.string().min(1),
+  /** Absolute paths: the PR head files, the merge-base files, and one labeled patch per file. */
+  paths: z.object({ head: z.string(), base: z.string(), patches: z.string(), model: z.string() }),
+  /** The manifest: every changed file with its hunk ids and headers. */
+  files: z.array(FileEntrySchema),
+  defaultLayers: z.array(DefaultLayerSchema),
+  rulebook: z.object({ path: z.string().nullable(), text: z.string().nullable() }),
+  highRisk: z.array(HighRiskRuleSchema),
+  caps: z.object(capsShape),
+  limits: z.object({
+    maxPoints: z.number().int().positive(),
+    maxDiagramsPerLayer: z.number().int().positive(),
+    maxDiagramLinks: z.number().int().positive().default(LIMITS.maxDiagramLinks),
+  }),
+  generation: z.object({
+    mode: GenerationModeSchema.default('strict'),
+    maxRepairRounds: z.number().int().positive(),
+    inlineDiffMaxLines: z.number().int().positive(),
+    smallPrHunks: z.number().int().positive(),
+  }),
+  /** The globs that make a file a test here. Defaulted, so a context written before this
+   * field existed still reads. */
+  tests: z.object({ patterns: z.array(z.string().min(1)) }).default(() => ({ patterns: [...DEFAULT_TEST_PATTERNS] })),
+  /** At most `generation.smallPrHunks` hunks: one layer unless concerns differ, fewer annotations. */
+  smallPr: z.boolean(),
+  /** More than 400 files or 50 000 changed lines: the prompt inlines nothing and tightens the caps. */
+  largePr: z.boolean(),
+  preparedAt: z.string(),
+})
+export type GenerationContext = z.infer<typeof GenerationContextSchema>
+
+export const LARGE_PR = { files: 400, lines: 50_000 } as const
+
+/**
+ * A change set big enough that the prompt stops inlining diffs, the model keeps to 6 annotations
+ * per file, and the page says so in its header.
+ */
+export function isLargePr(counts: { files: number; additions: number; deletions: number }): boolean {
+  return counts.files > LARGE_PR.files || counts.additions + counts.deletions > LARGE_PR.lines
+}

package/src/contract/keys.ts

@@ -0,0 +1,14 @@
+// One implementation for both sides: the browser loads static/js/keys.js as a module, and
+// the server imports the same file through this re-export.
+export {
+  buildLineId,
+  fileAnchorId,
+  hunkAnchorId,
+  hunkId,
+  layerAnchorId,
+  parseHunkId,
+  parseLineId,
+  pointAnchorId,
+  sanitizeKey,
+  uniqueKey,
+} from '../../static/js/keys.js'

package/src/contract/links.ts

@@ -0,0 +1,5 @@
+// The link parser lives in static/js/links.js so the browser can load it without a bundler;
+// the server imports the same code here.
+
+export type { LinkTargets, ParsedLink } from '../../static/js/links.js'
+export { extractLinks, linkLabel, linkTargetId, parseLink, resolveLink } from '../../static/js/links.js'

package/src/contract/mermaid-fences.ts

@@ -0,0 +1,4 @@
+// One implementation for both sides: the browser loads static/js/mermaid-fences.js as a module,
+// and the validator imports the same file through this re-export.
+export type { MermaidSegment } from '../../static/js/mermaid-fences.js'
+export { diagramKind, mermaidBlocks, splitMermaid, withoutMermaid } from '../../static/js/mermaid-fences.js'