@vintasoftware/pr-review-canvas 0.1.0

package/src/contract/review-artifact.ts

@@ -0,0 +1,324 @@
+import { z } from 'zod'
+
+/** Character caps applied to model output. Numbers, so the prompt can print them. */
+export const TEXT_CAPS = {
+  summary: 1200,
+  layerTitle: 60,
+  rationale: 300,
+  decisions: 600,
+  checkByHand: 400,
+  annotation: 240,
+  pointTitle: 90,
+  pointBody: 600,
+  testBehavior: 120,
+  /** Mermaid source. Measured raw, since it is code and not text a reader reads. */
+  diagram: 1500,
+} as const
+export type TextCaps = { -readonly [K in keyof typeof TEXT_CAPS]: number }
+
+export const LIMITS = { maxPoints: 12, maxDiagramsPerLayer: 1, maxDiagramLinks: 12 } as const
+export type Limits = { -readonly [K in keyof typeof LIMITS]: number }
+
+export const TEXT_CAP_KEYS = [
+  'summary',
+  'layerTitle',
+  'rationale',
+  'decisions',
+  'checkByHand',
+  'annotation',
+  'pointTitle',
+  'pointBody',
+  'testBehavior',
+  'diagram',
+] as const satisfies ReadonlyArray<keyof TextCaps>
+
+function mapCaps(fn: (key: keyof TextCaps) => number): TextCaps {
+  return {
+    summary: fn('summary'),
+    layerTitle: fn('layerTitle'),
+    rationale: fn('rationale'),
+    decisions: fn('decisions'),
+    checkByHand: fn('checkByHand'),
+    annotation: fn('annotation'),
+    pointTitle: fn('pointTitle'),
+    pointBody: fn('pointBody'),
+    testBehavior: fn('testBehavior'),
+    diagram: fn('diagram'),
+  }
+}
+
+/** The project config may raise or lower a cap; the result is what the validator and the prompt use. */
+export function effectiveCaps(overrides: { [K in keyof TextCaps]?: number | undefined } | undefined): TextCaps {
+  return mapCaps(key => overrides?.[key] ?? TEXT_CAPS[key])
+}
+
+/**
+ * The raw-text ceiling behind a cap: four times the cap. The cap itself is measured on the visible
+ * text (review/text-length.ts) by the validator; the schema only refuses pathological input.
+ */
+export const HARD_CAP_FACTOR = 4
+export function hardCaps(caps: TextCaps): TextCaps {
+  return mapCaps(key => caps[key] * HARD_CAP_FACTOR)
+}
+
+/**
+ * Ceilings on a stored or imported artifact: four times the default caps and point limit. A project
+ * may raise its caps, but a zip from elsewhere must not hand the browser unbounded text.
+ */
+export const ARTIFACT_HARD_CAPS: TextCaps = hardCaps(TEXT_CAPS)
+export const ARTIFACT_MAX_POINTS = LIMITS.maxPoints * HARD_CAP_FACTOR
+
+export const FILE_STATUSES = ['added', 'modified', 'deleted', 'renamed', 'binary'] as const
+export const POINT_KINDS = ['decision', 'risk', 'drift', 'tests', 'debt', 'question'] as const
+export const POINT_LEVELS = ['decide', 'check', 'fyi'] as const
+export const TEST_STATUSES = ['covered', 'missing', 'not-needed'] as const
+export const HARNESSES = ['claude-code', 'codex', 'other'] as const
+
+export const SideSchema = z.enum(['new', 'old'])
+export type Side = z.infer<typeof SideSchema>
+
+export const HunkSchema = z.object({
+  id: z.string().min(1),
+  header: z.string(),
+  oldStart: z.number().int().nonnegative(),
+  oldLines: z.number().int().nonnegative(),
+  newStart: z.number().int().nonnegative(),
+  newLines: z.number().int().nonnegative(),
+})
+export type Hunk = z.infer<typeof HunkSchema>
+
+export const FileEntrySchema = z.object({
+  path: z.string().min(1),
+  oldPath: z.string().min(1).optional(),
+  key: z.string().min(1),
+  status: z.enum(FILE_STATUSES),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  lang: z.string().optional(),
+  hunks: z.array(HunkSchema),
+})
+export type FileEntry = z.infer<typeof FileEntrySchema>
+
+export const RepoSchema = z.object({ owner: z.string().min(1), name: z.string().min(1) })
+export type Repo = z.infer<typeof RepoSchema>
+
+export const PrSchema = z.object({
+  number: z.number().int().positive().nullable(),
+  title: z.string(),
+  body: z.string(),
+  author: z.string(),
+  url: z.string(),
+  state: z.string(),
+  draft: z.boolean(),
+  /**
+   * When the pull request was last edited; the body's attachment links are ranked by it. Absent
+   * in a canvas written before this field existed, so an older zip still imports.
+   */
+  updatedAt: z.string().optional(),
+  baseRef: z.string(),
+  headRef: z.string(),
+  headSha: z.string().regex(/^[0-9a-f]{40}$/),
+  mergeBaseSha: z.string().regex(/^[0-9a-f]{40}$/),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  changedFiles: z.number().int().nonnegative(),
+  repo: RepoSchema,
+})
+export type Pr = z.infer<typeof PrSchema>
+
+export const RiskTagSchema = z.object({
+  label: z.string().min(1),
+  source: z.enum(['config', 'model']),
+  reason: z.string().optional(),
+})
+export type RiskTag = z.infer<typeof RiskTagSchema>
+
+/** A link in one of the four canvas forms. Parsed and resolved by contract/links. */
+export const LinkSchema = z.string().regex(/^#(layer|file|hunk|line):.+/)
+
+/**
+ * One diagram of a layer. `links` maps a node id of the mermaid source to a canvas link, so a
+ * reader can click a node and land on the code it stands for. The validator checks that every key
+ * names a node of the source and that every value resolves.
+ */
+export function diagramSchema(caps: Caps) {
+  return z.object({
+    mermaid: z.string().min(1).max(caps.diagram),
+    links: z.record(z.string(), LinkSchema),
+  })
+}
+export const DiagramSchema = diagramSchema(ARTIFACT_HARD_CAPS)
+export type Diagram = z.infer<typeof DiagramSchema>
+
+/**
+ * The model output is checked against the caps in force; the artifact is the published result of
+ * a validated output, so it reads back under the generous hard ceilings instead.
+ */
+type Caps = TextCaps
+
+function text(caps: Caps, key: keyof TextCaps): z.ZodString {
+  return textOrEmpty(caps, key).min(1)
+}
+
+function textOrEmpty(caps: Caps, key: keyof TextCaps): z.ZodString {
+  const visibleCap = caps[key] / HARD_CAP_FACTOR
+  const diagrams = key === 'summary' || key === 'rationale'
+    ? ' Mermaid fences count toward the separate diagram cap, not this prose cap.'
+    : ''
+  return z.string().max(caps[key]).meta({
+    description: `At most ${visibleCap} visible characters. Link targets, backticks, and code-fence lines do not count. maxLength is only the raw Markdown ceiling.${diagrams}`,
+    'x-visibleMaxLength': visibleCap,
+  })
+}
+
+export function testEntrySchema(caps: Caps) {
+  return z.object({
+    behavior: text(caps, 'testBehavior'),
+    status: z.enum(TEST_STATUSES),
+    testPath: z.string().min(1).optional(),
+    note: z.string().optional(),
+  })
+}
+export const TestEntrySchema = testEntrySchema(ARTIFACT_HARD_CAPS)
+export type TestEntry = z.infer<typeof TestEntrySchema>
+
+export function annotationSchema(caps: Caps) {
+  return z.object({
+    side: SideSchema,
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    text: text(caps, 'annotation'),
+  })
+}
+export const AnnotationSchema = annotationSchema(ARTIFACT_HARD_CAPS)
+export type Annotation = z.infer<typeof AnnotationSchema>
+
+function codeFoldSchema(caps: Caps) {
+  return z.object({
+    title: z.string().max(caps.pointTitle).regex(/\S/, 'A fold title must contain visible text'),
+    side: SideSchema,
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+  })
+}
+export const CodeFoldSchema = codeFoldSchema(ARTIFACT_HARD_CAPS)
+export type CodeFold = z.infer<typeof CodeFoldSchema>
+
+function layerFileBase(caps: Caps, foldTitleCap = caps.pointTitle) {
+  return {
+    path: z.string().min(1),
+    hunks: z.array(z.string().min(1)).min(1),
+    note: textOrEmpty(caps, 'annotation').optional(),
+    annotations: z.array(annotationSchema(caps)),
+    collapsed: z.boolean().optional(),
+    folds: z.array(codeFoldSchema({ ...caps, pointTitle: foldTitleCap })).optional(),
+  }
+}
+
+export const LayerFileSchema = z.object({ ...layerFileBase(ARTIFACT_HARD_CAPS), isTest: z.boolean() })
+export type LayerFile = z.infer<typeof LayerFileSchema>
+
+export const LayerKeySchema = z
+  .string()
+  .min(1)
+  .max(40)
+  .regex(/^[a-z0-9][a-z0-9-]*$/)
+
+function layerBase(caps: Caps) {
+  return {
+    key: LayerKeySchema,
+    title: text(caps, 'layerTitle'),
+    rationale: textOrEmpty(caps, 'rationale'),
+    /** Markdown: decisions and trade-offs a human should agree with. */
+    decisions: text(caps, 'decisions').optional(),
+    /** Markdown: what tests cannot verify (UI feel, migrations on real data, ...). */
+    checkByHand: text(caps, 'checkByHand').optional(),
+    kind: z.enum(['layer', 'other']),
+    defaultLayerId: z.string().optional(),
+    diagram: diagramSchema(caps).optional(),
+    tests: z.array(testEntrySchema(caps)),
+  }
+}
+
+export const LayerSchema = z.object({
+  ...layerBase(ARTIFACT_HARD_CAPS),
+  id: z.string().min(1),
+  risk: z.array(RiskTagSchema),
+  files: z.array(LayerFileSchema).min(1),
+})
+export type Layer = z.infer<typeof LayerSchema>
+
+function pointBase(caps: Caps) {
+  return {
+    kind: z.enum(POINT_KINDS),
+    level: z.enum(POINT_LEVELS),
+    title: text(caps, 'pointTitle'),
+    path: z.string().min(1),
+    line: z.number().int().positive(),
+    endLine: z.number().int().positive().optional(),
+    side: SideSchema.optional(),
+    body: text(caps, 'pointBody'),
+  }
+}
+
+export const PointSchema = z.object({
+  ...pointBase(ARTIFACT_HARD_CAPS),
+  id: z.string().min(1),
+  fingerprint: z.string().min(1),
+  origin: z.enum(['model', 'tests']),
+  /** The layer that owns the point's hunk; publish fills it from the file's layer. */
+  layerId: z.string().optional(),
+})
+export type Point = z.infer<typeof PointSchema>
+
+export const GeneratorSchema = z.object({
+  agent: z.string().min(1),
+  model: z.string().optional(),
+  harness: z.enum(HARNESSES),
+  attempts: z.number().int().positive(),
+})
+export type Generator = z.infer<typeof GeneratorSchema>
+
+export const ReviewArtifactSchema = z.object({
+  version: z.literal(1),
+  pr: PrSchema,
+  files: z.array(FileEntrySchema),
+  /** Markdown, PR-wide "what changes": behavior before and after, no required sections. */
+  summary: textOrEmpty(ARTIFACT_HARD_CAPS, 'summary'),
+  risk: z.array(RiskTagSchema),
+  layers: z.array(LayerSchema).min(1),
+  points: z.array(PointSchema).max(ARTIFACT_MAX_POINTS),
+  generatedAt: z.string(),
+  generator: GeneratorSchema,
+  source: z.enum(['local', 'import']),
+  importedAt: z.string().optional(),
+})
+export type ReviewArtifact = z.infer<typeof ReviewArtifactSchema>
+
+/**
+ * What the agent writes to model.json. The schema bounds raw text at the hard limit (4x the cap);
+ * the validator measures the visible text against the cap itself. Ids, fingerprints, layerId,
+ * isTest, and config risk are added by publish. A layer may list no files here so the validator
+ * can name the problem (`LAYER_EMPTY`) instead of a schema failure; the point count is checked by
+ * the validator too, together with the points that missing tests add.
+ */
+export function modelOutputSchema(textCaps: TextCaps) {
+  const caps = hardCaps(textCaps)
+  return z.object({
+    summary: textOrEmpty(caps, 'summary'),
+    layers: z
+      .array(
+        z.object({
+          ...layerBase(caps),
+          risk: z.array(z.object({ label: z.string().min(1), reason: z.string().min(1) })).optional(),
+          files: z.array(z.object(layerFileBase(caps, textCaps.pointTitle))),
+        })
+      )
+      .min(1),
+    points: z.array(z.object(pointBase(caps))),
+  })
+}
+export const ModelOutputSchema = modelOutputSchema(TEXT_CAPS)
+export type ModelOutput = z.infer<typeof ModelOutputSchema>
+export type ModelLayer = ModelOutput['layers'][number]
+export type ModelPoint = ModelOutput['points'][number]

package/src/contract/settings.ts

@@ -0,0 +1,144 @@
+import { z } from 'zod'
+import { DEFAULT_SKIN, isSkin, SKINS, type Skin } from '../../static/js/skin.js'
+import { DEFAULT_THEME, isTheme, THEMES, type Theme } from '../../static/js/theme.js'
+
+export type { Skin } from '../../static/js/skin.js'
+// The skin and theme names live with the browser modules that apply them, because the page needs
+// them before any server type could reach it.
+export { DEFAULT_SKIN, SKINS } from '../../static/js/skin.js'
+export type { Theme } from '../../static/js/theme.js'
+export { DEFAULT_THEME, THEMES } from '../../static/js/theme.js'
+
+/** The agents the chat knows how to reach through acpx. */
+export const CHAT_AGENTS = ['claude', 'codex'] as const
+export type ChatAgent = (typeof CHAT_AGENTS)[number]
+
+export function isChatAgent(value: string): value is ChatAgent {
+  return (CHAT_AGENTS as readonly string[]).includes(value)
+}
+
+export const CHAT_TIMEOUT_MIN_SEC = 30
+export const CHAT_TIMEOUT_MAX_SEC = 3600
+
+export const SettingsSchema = z.object({
+  version: z.literal(1),
+  skin: z.enum(SKINS),
+  theme: z.enum(THEMES),
+  agent: z.enum(CHAT_AGENTS),
+  model: z.string().min(1).nullable(),
+  chatTimeoutSec: z.number().int().min(CHAT_TIMEOUT_MIN_SEC).max(CHAT_TIMEOUT_MAX_SEC),
+  maxTurns: z.number().int().positive().max(100).nullable(),
+})
+export type Settings = z.infer<typeof SettingsSchema>
+
+export const DEFAULT_SETTINGS: Settings = {
+  version: 1,
+  skin: DEFAULT_SKIN,
+  theme: DEFAULT_THEME,
+  agent: 'claude',
+  model: null,
+  chatTimeoutSec: 600,
+  maxTurns: null,
+}
+
+/** What `PUT /api/settings` accepts: every field optional, the rest stays as it was. */
+export const SettingsInputSchema = z.object({
+  skin: z.enum(SKINS).optional(),
+  theme: z.enum(THEMES).optional(),
+  agent: z.enum(CHAT_AGENTS).optional(),
+  model: z.string().max(200).nullable().optional(),
+  chatTimeoutSec: z.number().int().min(CHAT_TIMEOUT_MIN_SEC).max(CHAT_TIMEOUT_MAX_SEC).optional(),
+  maxTurns: z.number().int().positive().max(100).nullable().optional(),
+})
+export type SettingsInput = z.infer<typeof SettingsInputSchema>
+
+/** How the page is painted: the skin, and light or dark. Both live in the settings file. */
+export interface Appearance {
+  skin: Skin
+  theme: Theme
+}
+
+/** The `?skin` and `?theme` of one request, either of which may be absent. */
+export interface AppearanceQuery {
+  skin?: string | undefined
+  theme?: string | undefined
+}
+
+/** The appearance for one request: `?skin=` and `?theme=` win over the saved ones, for that load. */
+export function appearanceForRequest(saved: Appearance, query: AppearanceQuery): Appearance {
+  return {
+    skin: isSkin(query.skin) ? query.skin : saved.skin,
+    theme: isTheme(query.theme) ? query.theme : saved.theme,
+  }
+}
+
+/**
+ * What `PUT /api/appearance` accepts. It is its own route, apart from the chat settings, because a
+ * repository with chat turned off still has a page to paint. A body that names neither is refused
+ * rather than saved as a no-op.
+ */
+export const AppearanceInputSchema = z
+  .object({ skin: z.enum(SKINS).optional(), theme: z.enum(THEMES).optional() })
+  .refine(input => input.skin !== undefined || input.theme !== undefined, {
+    message: 'name a skin, a theme, or both',
+  })
+export type AppearanceInput = z.infer<typeof AppearanceInputSchema>
+
+/** How the page is painted right now, as the server has it saved. */
+export type AppearanceResponse = Appearance
+
+/** A `serve --agent/--model` flag wins over the file, and the dialog says so. */
+export interface SettingsOverrides {
+  agent?: ChatAgent
+  model?: string
+}
+
+export interface SettingsResponse {
+  settings: Settings
+  /** The flags that win over the file for this run. */
+  overrides: SettingsOverrides
+  /** Absolute path of `.pr-review/settings.yml`, shown in the dialog. */
+  file: string
+  /** The committed project config, read-only in the UI. */
+  project: {
+    file: string | null
+    chatEnabled: boolean
+    rulebook: string | null
+    maxRepairRounds: number
+    inlineDiffMaxLines: number
+    smallPrHunks: number
+    layers: number
+    highRisk: number
+  }
+}
+
+/** Whether an agent can run right now, and why not when it cannot. */
+export interface AgentAvailability {
+  id: ChatAgent
+  /** True when the binary is on PATH and its auth check passed. */
+  available: boolean
+  installed: boolean
+  authenticated: boolean
+  reason?: string
+}
+
+export interface AgentsResponse {
+  /** False when `acpx` itself is missing: the whole pane is unusable then. */
+  acpx: { installed: boolean; version: string | null }
+  agents: AgentAvailability[]
+}
+
+/** The answer of `POST /api/settings/agents/:id/probe`: one real one-shot round trip. */
+export interface AgentProbeResult {
+  id: ChatAgent
+  ok: boolean
+  /** How long the round trip took, in milliseconds. */
+  ms: number
+  /** The agent's reply, cut to one short line; empty when it failed. */
+  reply: string
+  code?: string
+  message?: string
+  /** When this result was produced; results are reused for ten minutes. */
+  at: string
+  cached: boolean
+}

package/src/contract/state.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod'
+
+export const ChatThreadSchema = z.object({
+  name: z.string(),
+  agent: z.string(),
+  rev: z.number().int(),
+  title: z.string(),
+  createdAt: z.string(),
+  seededHeadSha: z.string(),
+})
+
+export type ChatThread = z.infer<typeof ChatThreadSchema>
+
+export const PrStateSchema = z.object({
+  version: z.literal(1),
+  /**
+   * Counts the writes to this file. The page uses it to tell a newer answer from an older one
+   * when two of its requests overlap. Absent in state files of older tool versions.
+   */
+  rev: z.number().int().nonnegative().optional(),
+  reviewed: z.record(z.string(), z.literal(true)),
+  /**
+   * The commit the reviewed marks describe. A canvas for another commit describes other code,
+   * so the marks start again when the head moves. Absent in state files of older tool versions.
+   */
+  reviewedHeadSha: z.string().optional(),
+  hiddenThreads: z.record(z.string(), z.object({ at: z.string() })),
+  posted: z.array(z.object({ commentId: z.number().int(), pointFingerprint: z.string().optional(), at: z.string() })),
+  dismissed: z.record(z.string(), z.object({ at: z.string(), reason: z.string().optional() })),
+  chat: z.object({ threads: z.array(ChatThreadSchema), activeThread: z.string().optional() }),
+  updatedAt: z.string(),
+})
+export type PrState = z.infer<typeof PrStateSchema>
+
+export function emptyState(updatedAt: string): PrState {
+  return {
+    version: 1,
+    rev: 0,
+    reviewed: {},
+    hiddenThreads: {},
+    posted: [],
+    dismissed: {},
+    chat: { threads: [] },
+    updatedAt,
+  }
+}

package/src/contract/validation.ts

@@ -0,0 +1,43 @@
+/** The problems `pr-review validate` and `publish` report, one line each. */
+export const VALIDATION_CODES = [
+  'SCHEMA',
+  'TEXT_TOO_LONG',
+  'HUNK_UNASSIGNED',
+  'HUNK_DUPLICATE',
+  'HUNK_UNKNOWN',
+  'PATH_UNKNOWN',
+  'LAYER_EMPTY',
+  'LAYER_KEY_DUPLICATE',
+  'OTHER_DUPLICATE',
+  'OTHER_NOT_LAST',
+  'TEST_NOT_LAST',
+  'TEST_IN_OTHER',
+  'RISK_IN_OTHER',
+  'ANNOTATION_OUTSIDE_HUNK',
+  'FOLD_INVALID',
+  'POINT_OUTSIDE_DIFF',
+  'TOO_MANY_POINTS',
+  'TEST_PATH_UNKNOWN',
+  'LINK_UNRESOLVED',
+  'DIAGRAM_NODE_UNKNOWN',
+  'DIAGRAM_LIMIT',
+] as const
+export type ValidationCode = (typeof VALIDATION_CODES)[number]
+
+export interface ValidationError {
+  code: ValidationCode
+  /** One line that stands on its own, without the code. */
+  message: string
+  /** Where in the output the problem sits, for tools: `summary`, `layer:<key>`, `point:<n>`. */
+  where?: string
+}
+
+export interface ValidationReport {
+  ok: boolean
+  errors: ValidationError[]
+}
+
+/** The line a human reads: the code, then the message. */
+export function formatValidationError(error: ValidationError): string {
+  return `${error.code} ${error.message}`
+}