@vintasoftware/pr-review-canvas 0.1.0

package/src/github/pr.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod'
+import type { Pr, Repo } from '../contract/review-artifact.js'
+import type { Git } from '../git/git.js'
+import { GitHubApiError, type GitHubClient } from './gh.js'
+
+/** The subset of GitHub's pull request object the tool reads. */
+const GhPullSchema = z.object({
+  number: z.number().int(),
+  title: z.string(),
+  body: z.string().nullable(),
+  html_url: z.string(),
+  state: z.string(),
+  draft: z.boolean().optional(),
+  merged: z.boolean().optional(),
+  merge_commit_sha: z.string().nullable().optional(),
+  updated_at: z.string(),
+  additions: z.number().int(),
+  deletions: z.number().int(),
+  changed_files: z.number().int(),
+  user: z.object({ login: z.string() }).nullable(),
+  base: z.object({ ref: z.string() }),
+  head: z.object({ ref: z.string(), sha: z.string() }),
+})
+
+export class PrNotFoundError extends Error {
+  readonly number: number
+
+  constructor(number: number) {
+    super(`pull request #${number} not found`)
+    this.name = 'PrNotFoundError'
+    this.number = number
+  }
+}
+
+export interface PrMeta {
+  number: number
+  title: string
+  body: string
+  author: string
+  url: string
+  state: string
+  draft: boolean
+  updatedAt: string
+  baseRef: string
+  headRef: string
+  headSha: string
+  /** The commit that merged the PR into its base, once merged. */
+  mergeCommitSha: string | null
+  additions: number
+  deletions: number
+  changedFiles: number
+}
+
+export function mapPull(raw: unknown): PrMeta {
+  const p = GhPullSchema.parse(raw)
+  return {
+    number: p.number,
+    title: p.title,
+    body: p.body ?? '',
+    author: p.user?.login ?? 'ghost',
+    url: p.html_url,
+    state: p.merged === true ? 'merged' : p.state,
+    draft: p.draft === true,
+    updatedAt: p.updated_at,
+    baseRef: p.base.ref,
+    headRef: p.head.ref,
+    headSha: p.head.sha,
+    mergeCommitSha: p.merged === true ? (p.merge_commit_sha ?? null) : null,
+    additions: p.additions,
+    deletions: p.deletions,
+    changedFiles: p.changed_files,
+  }
+}
+
+export async function fetchPrMeta(gh: GitHubClient, repo: Repo, number: number): Promise<PrMeta> {
+  try {
+    return mapPull(await gh.api(`repos/${repo.owner}/${repo.name}/pulls/${number}`))
+  } catch (err) {
+    if (err instanceof GitHubApiError && err.notFound) {
+      throw new PrNotFoundError(number)
+    }
+    throw err
+  }
+}
+
+export function prHeadRef(number: number): string {
+  return `refs/pr/${number}/head`
+}
+
+export function prBaseRef(number: number): string {
+  return `refs/pr/${number}/base`
+}
+
+/**
+ * Fetches the PR head and base into local refs and resolves the two commits the diff needs.
+ * The refs are the same ones the prior-art skill used, so an existing clone keeps working.
+ *
+ * A merged PR is diffed against the base as it was at merge time: the merge commit's first
+ * parent (a merge commit, a squash, or the last rebased commit all sit on the base branch, so
+ * it is local once the base was fetched). Today's base tip would contain the PR and give an
+ * empty diff.
+ */
+export async function fetchPrRefs(git: Git, meta: PrMeta): Promise<{ headSha: string; mergeBaseSha: string }> {
+  await git.fetch('origin', [
+    `+pull/${meta.number}/head:${prHeadRef(meta.number)}`,
+    `+refs/heads/${meta.baseRef}:${prBaseRef(meta.number)}`,
+  ])
+  const headSha = await git.revParse(prHeadRef(meta.number))
+  const base = meta.mergeCommitSha === null ? prBaseRef(meta.number) : `${meta.mergeCommitSha}^1`
+  const mergeBaseSha = await git.mergeBase(base, headSha)
+  return { headSha, mergeBaseSha }
+}
+
+export function toPr(meta: PrMeta, repo: Repo, shas: { headSha: string; mergeBaseSha: string }): Pr {
+  return {
+    number: meta.number,
+    title: meta.title,
+    body: meta.body,
+    author: meta.author,
+    url: meta.url,
+    state: meta.state,
+    draft: meta.draft,
+    updatedAt: meta.updatedAt,
+    baseRef: meta.baseRef,
+    headRef: meta.headRef,
+    headSha: shas.headSha,
+    mergeBaseSha: shas.mergeBaseSha,
+    additions: meta.additions,
+    deletions: meta.deletions,
+    changedFiles: meta.changedFiles,
+    repo,
+  }
+}

package/src/github/review-body.ts

@@ -0,0 +1,72 @@
+// The same reviewed rules the page uses, so the body and the header never disagree.
+import { layerProgress } from '../../static/js/progress.js'
+import type { CommentsPayload } from '../contract/comments.js'
+import type { Layer, ReviewArtifact } from '../contract/review-artifact.js'
+import type { PrState } from '../contract/state.js'
+
+export const REVIEW_BODY_FOOTER = 'Reviewed with the pr-review canvas (localhost).'
+
+/**
+ * Model text on one line of a list. Markdown characters are escaped so a title cannot open a
+ * heading, a link, or a code span in the review GitHub publishes.
+ */
+export function inlineText(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/([\\`*_[\]<>#|])/g, '\\$1')
+}
+
+/**
+ * The state as it applies to one commit. Marks made on another commit, and marks whose commit
+ * is unknown, describe other code, so they count for nothing here.
+ */
+export function stateForHead(state: PrState, headSha: string): PrState {
+  return state.reviewedHeadSha === headSha ? state : { ...state, reviewed: {} }
+}
+
+/** The layers a human still has to look at. Empty means approve is allowed. */
+export function unreviewedLayers(artifact: ReviewArtifact, state: PrState): Layer[] {
+  return artifact.layers.filter(l => l.kind !== 'other' && layerProgress(l, state) !== 'done')
+}
+
+function section(title: string, items: string[]): string {
+  return items.length === 0 ? '' : `\n\n**${title}**\n${items.map(i => `- ${i}`).join('\n')}`
+}
+
+export interface ReviewBodyInput {
+  artifact: ReviewArtifact
+  state: PrState
+  comments: CommentsPayload
+  headSha: string
+}
+
+/**
+ * The body of the review the canvas posts: what was read, what was set aside, and what was said
+ * on the diff. The user sees it in the dialog and may edit it before it is sent.
+ */
+export function buildReviewBody(input: ReviewBodyInput): string {
+  const { artifact, state, comments, headSha } = input
+  const layers = artifact.layers.filter(l => l.kind !== 'other')
+  const reviewed = layers.filter(l => layerProgress(l, state) === 'done')
+  const dismissed = artifact.points.filter(p => state.dismissed[p.fingerprint] !== undefined)
+  const urls = new Map<number, string>()
+  for (const c of [...comments.reviewComments, ...comments.issueComments]) {
+    urls.set(c.id, c.url)
+  }
+  const posted = state.posted.map(p => urls.get(p.commentId) ?? `comment ${p.commentId}`)
+  const head = `Reviewed ${reviewed.length} of ${layers.length} ${layers.length === 1 ? 'layer' : 'layers'} on \`${headSha.slice(0, 7)}\`.`
+  return (
+    head +
+    section(
+      'Layers reviewed',
+      reviewed.map(l => inlineText(l.title))
+    ) +
+    section(
+      'Attention points dismissed',
+      dismissed.map(p => inlineText(p.title))
+    ) +
+    section('Comments posted from the canvas', posted) +
+    `\n\n${REVIEW_BODY_FOOTER}\n`
+  )
+}

package/src/github/threads.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod'
+import type { Repo } from '../contract/review-artifact.js'
+import type { GitHubClient } from './gh.js'
+
+const ThreadsPageSchema = z.object({
+  repository: z.object({
+    pullRequest: z.object({
+      reviewThreads: z.object({
+        pageInfo: z.object({ hasNextPage: z.boolean(), endCursor: z.string().nullable() }),
+        nodes: z.array(
+          z.object({
+            isResolved: z.boolean(),
+            comments: z.object({ nodes: z.array(z.object({ databaseId: z.number().int().nullable() })) }),
+          })
+        ),
+      }),
+    }),
+  }),
+})
+
+export const THREADS_QUERY = `query($owner: String!, $name: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100, after: $after) {
+        pageInfo { hasNextPage endCursor }
+        nodes { isResolved comments(first: 100) { nodes { databaseId } } }
+      }
+    }
+  }
+}`
+
+/**
+ * The ids of every review comment that sits in a resolved thread. REST has no resolved flag,
+ * so this one GraphQL query is joined to the REST comments by id.
+ */
+export async function fetchResolvedCommentIds(gh: GitHubClient, repo: Repo, number: number): Promise<Set<number>> {
+  const resolved = new Set<number>()
+  let after: string | null = null
+  for (;;) {
+    const vars: Record<string, string | number> = {
+      owner: repo.owner,
+      name: repo.name,
+      number,
+      ...(after === null ? {} : { after }),
+    }
+    const page = ThreadsPageSchema.parse(await gh.graphql(THREADS_QUERY, vars))
+    const threads = page.repository.pullRequest.reviewThreads
+    for (const t of threads.nodes) {
+      if (!t.isResolved) {
+        continue
+      }
+      for (const c of t.comments.nodes) {
+        if (c.databaseId !== null) {
+          resolved.add(c.databaseId)
+        }
+      }
+    }
+    if (!threads.pageInfo.hasNextPage || threads.pageInfo.endCursor === null) {
+      return resolved
+    }
+    after = threads.pageInfo.endCursor
+  }
+}

package/src/paths.ts

@@ -0,0 +1,10 @@
+// Where this package's own files live. Its own module so that anything needing a path does not
+// have to import the server context, which pulls in every adapter.
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+export const PACKAGE_ROOT = path.resolve(here, '..')
+export const STATIC_DIR = path.join(PACKAGE_ROOT, 'static')
+export const PROMPTS_DIR = path.join(PACKAGE_ROOT, 'prompts')

package/src/project-config.ts

@@ -0,0 +1,219 @@
+import path from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { z } from 'zod'
+import type { TextCaps } from './contract/review-artifact.js'
+import { DEFAULT_TEST_PATTERNS } from './review/test-paths.js'
+import { readText } from './store/atomic-json.js'
+
+export const PROJECT_CONFIG_FILE = 'pr-review.config.yml'
+export const GenerationModeSchema = z.enum(['strict', 'surfacing'])
+export type GenerationMode = z.infer<typeof GenerationModeSchema>
+
+export const DefaultLayerSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string(),
+  paths: z.array(z.string()).optional(),
+})
+export type DefaultLayer = z.infer<typeof DefaultLayerSchema>
+
+export const HighRiskRuleSchema = z.object({ pattern: z.string().min(1), label: z.string().min(1) })
+export type HighRiskRule = z.infer<typeof HighRiskRuleSchema>
+
+const cap = () => z.number().int().positive().optional()
+
+/** One optional override per text cap. `satisfies` fails the build when TEXT_CAPS gains a key. */
+const capsShape = {
+  summary: cap(),
+  layerTitle: cap(),
+  rationale: cap(),
+  decisions: cap(),
+  checkByHand: cap(),
+  annotation: cap(),
+  pointTitle: cap(),
+  pointBody: cap(),
+  testBehavior: cap(),
+  diagram: cap(),
+} satisfies Record<keyof TextCaps, z.ZodOptional<z.ZodNumber>>
+
+export const PromptOverridesSchema = z.object({
+  'generation-format.md': z.string().min(1).optional(),
+  'generation-strict.md': z.string().min(1).optional(),
+  'generation-surfacing.md': z.string().min(1).optional(),
+  'quality-standards.md': z.string().min(1).optional(),
+  'layers-default.md': z.string().min(1).optional(),
+  'chat-seed.md': z.string().min(1).optional(),
+}).strict()
+export type PromptOverrides = z.infer<typeof PromptOverridesSchema>
+
+export const ProjectConfigSchema = z.object({
+  version: z.literal(1),
+  rulebook: z.string().min(1).optional(),
+  prompts: PromptOverridesSchema.optional(),
+  layers: z.array(DefaultLayerSchema),
+  highRisk: z.array(HighRiskRuleSchema),
+  generation: z.object({
+    mode: GenerationModeSchema.default('strict'),
+    maxRepairRounds: z.number().int().positive(),
+    inlineDiffMaxLines: z.number().int().positive(),
+    /** A change set with at most this many hunks is "small": one layer unless concerns differ. */
+    smallPrHunks: z.number().int().positive(),
+    caps: z.object(capsShape).optional(),
+  }),
+  /** Which paths count as tests, for the layering rules and the `isTest` flag on a file. */
+  tests: z.object({ patterns: z.array(z.string().min(1)) }),
+  chat: z.object({ enabled: z.boolean() }),
+})
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>
+
+/** The shape a user may write: everything optional, filled from the defaults. */
+const PartialProjectConfigSchema = z.object({
+  version: z.literal(1).optional(),
+  rulebook: z.string().min(1).optional(),
+  prompts: PromptOverridesSchema.optional(),
+  layers: z.array(DefaultLayerSchema).optional(),
+  highRisk: z.array(HighRiskRuleSchema).optional(),
+  generation: z
+    .object({
+      mode: GenerationModeSchema.optional(),
+      maxRepairRounds: z.number().int().positive().optional(),
+      inlineDiffMaxLines: z.number().int().positive().optional(),
+      smallPrHunks: z.number().int().positive().optional(),
+      caps: z.object(capsShape).optional(),
+    })
+    .optional(),
+  tests: z.object({ patterns: z.array(z.string().min(1)).optional() }).optional(),
+  chat: z.object({ enabled: z.boolean().optional() }).optional(),
+})
+
+/** The 8 architecture groups, in review order. A project file replaces the list. */
+export const DEFAULT_LAYERS: DefaultLayer[] = [
+  {
+    id: 'contracts',
+    title: 'Contracts and schemas',
+    description: 'Types, Zod schemas, FHIR profiles, and the shapes two packages must agree on.',
+  },
+  {
+    id: 'data-access',
+    title: 'Data access',
+    description: 'Server functions, FHIR client calls, repositories, migrations, and storage.',
+  },
+  {
+    id: 'mappers',
+    title: 'Mappers and DTOs',
+    description: 'Code that turns resources or rows into view models and back.',
+  },
+  {
+    id: 'hooks-state',
+    title: 'Hooks and state',
+    description: 'React hooks, query definitions, stores, and client-side state machines.',
+  },
+  { id: 'views', title: 'Views', description: 'Components, screens, styles, and copy.' },
+  {
+    id: 'routes-wiring',
+    title: 'Routes and wiring',
+    description: 'Route files, providers, app shells, dependency wiring, and entry points.',
+  },
+  {
+    id: 'policy-config',
+    title: 'Policy and config',
+    description: 'Access policies, environment variables, feature flags, CI, and deployment config.',
+  },
+  {
+    id: 'mechanical',
+    title: 'Mechanical changes',
+    description: 'Renames, lockfiles, generated files, formatting, and moved code.',
+  },
+]
+
+export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
+  version: 1,
+  layers: DEFAULT_LAYERS,
+  highRisk: [],
+  generation: { mode: 'strict', maxRepairRounds: 3, inlineDiffMaxLines: 1500, smallPrHunks: 10 },
+  tests: { patterns: [...DEFAULT_TEST_PATTERNS] },
+  chat: { enabled: true },
+}
+
+export interface LoadedProjectConfig {
+  config: ProjectConfig
+  warnings: string[]
+  /** Absolute path of the file that was read, or null when the defaults are in use. */
+  source: string | null
+}
+
+function formatIssues(err: z.ZodError): string {
+  return err.issues.map(i => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ')
+}
+
+/** Merges a parsed user file over the defaults. Exported for tests; `loadProjectConfig` reads the file. */
+export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warnings: string[] } {
+  const parsed = PartialProjectConfigSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      config: DEFAULT_PROJECT_CONFIG,
+      warnings: [`${PROJECT_CONFIG_FILE} is invalid, using defaults: ${formatIssues(parsed.error)}`],
+    }
+  }
+  const user = parsed.data
+  const generation: ProjectConfig['generation'] = {
+    mode: user.generation?.mode ?? DEFAULT_PROJECT_CONFIG.generation.mode,
+    maxRepairRounds: user.generation?.maxRepairRounds ?? DEFAULT_PROJECT_CONFIG.generation.maxRepairRounds,
+    inlineDiffMaxLines: user.generation?.inlineDiffMaxLines ?? DEFAULT_PROJECT_CONFIG.generation.inlineDiffMaxLines,
+    smallPrHunks: user.generation?.smallPrHunks ?? DEFAULT_PROJECT_CONFIG.generation.smallPrHunks,
+  }
+  if (user.generation?.caps !== undefined) {
+    generation.caps = user.generation.caps
+  }
+  const config: ProjectConfig = {
+    version: 1,
+    layers: user.layers ?? DEFAULT_LAYERS,
+    highRisk: user.highRisk ?? [],
+    generation,
+    tests: { patterns: user.tests?.patterns ?? [...DEFAULT_TEST_PATTERNS] },
+    chat: { enabled: user.chat?.enabled ?? true },
+  }
+  if (user.rulebook !== undefined) {
+    config.rulebook = user.rulebook
+  }
+  if (user.prompts !== undefined) {
+    config.prompts = user.prompts
+  }
+  const warnings: string[] = []
+  if (config.layers.length === 0) {
+    warnings.push(`${PROJECT_CONFIG_FILE}: "layers" is empty, the model gets no default taxonomy`)
+  }
+  if (config.tests.patterns.length === 0) {
+    warnings.push(`${PROJECT_CONFIG_FILE}: "tests.patterns" is empty, so no file counts as a test`)
+  }
+  const ids = new Set<string>()
+  for (const layer of config.layers) {
+    if (ids.has(layer.id)) {
+      warnings.push(`${PROJECT_CONFIG_FILE}: duplicate layer id "${layer.id}"`)
+    }
+    ids.add(layer.id)
+  }
+  return { config, warnings }
+}
+
+export async function loadProjectConfig(repoRoot: string): Promise<LoadedProjectConfig> {
+  const file = path.join(repoRoot, PROJECT_CONFIG_FILE)
+  const text = await readText(file)
+  if (text === null) {
+    return { config: DEFAULT_PROJECT_CONFIG, warnings: [], source: null }
+  }
+  let raw: unknown
+  try {
+    raw = parseYaml(text)
+  } catch (err) {
+    return {
+      config: DEFAULT_PROJECT_CONFIG,
+      warnings: [
+        `${PROJECT_CONFIG_FILE} is not valid YAML, using defaults: ${err instanceof Error ? err.message : String(err)}`,
+      ],
+      source: file,
+    }
+  }
+  const merged = mergeProjectConfig(raw ?? {})
+  return { ...merged, source: file }
+}

package/src/prompt-files.ts

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { PROMPTS_DIR } from './paths.js'
+import type { PromptOverrides } from './project-config.js'
+
+export interface ProjectPrompts {
+  repoRoot: string
+  overrides?: PromptOverrides | undefined
+}
+
+/** Explicit overrides must be readable; only omitted entries use bundled templates. */
+export async function loadPromptFile(
+  name: keyof PromptOverrides,
+  dir = PROMPTS_DIR,
+  project?: ProjectPrompts
+): Promise<string> {
+  const override = project?.overrides?.[name]
+  const file = project !== undefined && override !== undefined
+    ? path.resolve(project.repoRoot, override)
+    : path.join(dir, name)
+  try {
+    return await readFile(file, 'utf8')
+  } catch (cause) {
+    throw new Error(`Cannot read prompt ${name} from ${file}`, { cause })
+  }
+}