@vintasoftware/pr-review-canvas 0.1.0

package/src/review/diagram-nodes.ts

@@ -0,0 +1,227 @@
+// The node ids a mermaid source names. The validator uses them to tell a diagram link keyed on a
+// real node from one keyed on a name the drawing does not have.
+//
+// Coverage: the four types the prompt recommends (flowchart, sequence, state, ER) are read
+// statement by statement; every other type, and any source these readers find no name in, falls
+// back to every word of the text. Each reader keeps names it is unsure about, since a name it
+// misses would be reported as a mistake the model did not make.
+
+import { diagramKind } from '../contract/mermaid-fences.js'
+
+/** A bare word: an identifier, or a number a flowchart may use as a node id. */
+const WORD_RE = /[A-Za-z_][\w.-]*|\d[\w.-]*/g
+
+/** Words that open a statement instead of naming a node. */
+const FLOW_KEYWORDS = new Set([
+  'flowchart',
+  'flowchart-elk',
+  'graph',
+  'subgraph',
+  'end',
+  'direction',
+  'accTitle',
+  'accDescr',
+  'LR',
+  'RL',
+  'TB',
+  'BT',
+  'TD',
+])
+
+/** Statements that name styles, classes, or callbacks rather than nodes. */
+const FLOW_SKIP = /^(class|classDef|click|style|linkStyle|href|callback)\b/
+
+const STATE_KEYWORDS = new Set([
+  'stateDiagram',
+  'stateDiagram-v2',
+  'state',
+  'as',
+  'direction',
+  'note',
+  'end',
+  'left',
+  'right',
+  'of',
+  'classDef',
+  'class',
+  'accTitle',
+  'accDescr',
+  'LR',
+  'RL',
+  'TB',
+  'BT',
+  'TD',
+])
+
+const ER_KEYWORDS = new Set(['erDiagram', 'accTitle', 'accDescr', 'direction', 'LR', 'RL', 'TB', 'BT', 'TD'])
+
+/** The text before the first `sep`, or all of it when there is none. */
+function before(text: string, sep: string): string {
+  const at = text.indexOf(sep)
+  return at === -1 ? text : text.slice(0, at)
+}
+
+/** The words of a text, with no attempt at grammar. */
+function words(text: string): string[] {
+  return text.match(WORD_RE) ?? []
+}
+
+/** The lines of the source without its comments and without empty lines. */
+function lines(source: string): string[] {
+  return source
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line !== '' && !line.startsWith('%%'))
+}
+
+/** Drops quoted text and the label brackets around it, innermost first. */
+function stripLabels(line: string): string {
+  let out = line.replace(/"[^"]*"/g, ' ').replace(/\|[^|]*\|/g, ' ')
+  for (let i = 0; i < 6; i++) {
+    const next = out.replace(/\[[^[\]]*\]|\([^()]*\)|\{[^{}]*\}/g, ' ')
+    if (next === out) {
+      break
+    }
+    out = next
+  }
+  return out
+}
+
+/**
+ * Replaces the arrows and edge markers of a flowchart with spaces, the way mermaid's own lexer
+ * reads them: two or more of `-=.`, then one head, either `>` or the `x`/`o` of a crossing or
+ * circle arrow. A head is part of the arrow even with the next name glued to it (`A---oB` names
+ * `B`), while `A-->oven` keeps its `oven`, since that arrow already has its head. A leading
+ * `x`/`o` is the tail of a crossing or circle arrow only when the same letter closes it. An
+ * invisible link (`~~~`) takes no head, so `A~~~orange` keeps its `orange`.
+ */
+function stripFlowArrows(line: string): string {
+  return line.replace(/(?<![\w-])([ox])(?=[-=.]{2,}\1(?![-=.]))|<?[-=.]{2,}(?:>|[xo])?|~{2,}|&/g, ' ')
+}
+
+function flowchartIds(source: string): string[] {
+  const out: string[] = []
+  for (const line of lines(source)) {
+    if (FLOW_SKIP.test(line)) {
+      continue
+    }
+    for (const word of words(stripFlowArrows(stripLabels(line)))) {
+      if (!FLOW_KEYWORDS.has(word)) {
+        out.push(word)
+      }
+    }
+  }
+  return out
+}
+
+function sequenceIds(source: string): string[] {
+  const out: string[] = []
+  for (const line of lines(source)) {
+    const declared = /^(?:participant|actor|create\s+(?:participant|actor))\s+(.+)$/.exec(line)?.[1]
+    if (declared !== undefined) {
+      out.push(...words(declared.split(/\s+as\s+/)[0] ?? declared).slice(0, 1))
+      continue
+    }
+    // A message names its two sides; the text after the first colon is the message itself.
+    const head = before(line, ':')
+    if (!/-{1,2}[)>x-]/.test(head)) {
+      continue
+    }
+    for (const side of head.split(/(?:<<)?-{1,2}(?:>>|>|x|\))/)) {
+      out.push(...words(side))
+    }
+  }
+  return out
+}
+
+function stateIds(source: string): string[] {
+  const out: string[] = []
+  const take = (text: string): void => {
+    for (const word of words(text).slice(0, 1)) {
+      if (!STATE_KEYWORDS.has(word)) {
+        out.push(word)
+      }
+    }
+  }
+  for (const line of lines(source)) {
+    const bare = stripLabels(line).replace(/<<[^>]*>>/g, ' ')
+    if (bare.startsWith('state ')) {
+      const named = /\bas\s+([^\s{]+)/.exec(bare)?.[1]
+      take(named === undefined ? bare.slice('state '.length) : named)
+      continue
+    }
+    if (bare.includes('-->')) {
+      // `a --> b : label` carries the label on the right side.
+      for (const side of bare.split('-->')) {
+        take(before(side, ':'))
+      }
+      continue
+    }
+    // `id : description` names a state and describes it.
+    take(before(bare, ':'))
+  }
+  return out
+}
+
+/**
+ * The quoted names on the entity side of an ER line, which is where a name holds a space. The
+ * scan stops at the colon that opens the relationship label, so the label is not read as a name.
+ */
+function quotedEntities(line: string): string[] {
+  const out: string[] = []
+  let quote = -1
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]
+    if (ch === '"') {
+      if (quote === -1) {
+        quote = i + 1
+      } else {
+        out.push(line.slice(quote, i))
+        quote = -1
+      }
+    } else if (ch === ':' && quote === -1) {
+      break
+    }
+  }
+  return out
+}
+
+function erIds(source: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  for (const line of lines(source)) {
+    // A relationship marker (`||--o{`) carries a brace of its own, so it is removed before the
+    // braces that open and close an attribute block are counted.
+    const clean = stripLabels(line).replace(/[|}{o.-]{2,}/g, ' ')
+    if (depth <= 0) {
+      out.push(...quotedEntities(line))
+      for (const word of words(before(clean, ':'))) {
+        if (!ER_KEYWORDS.has(word)) {
+          out.push(word)
+        }
+      }
+    }
+    depth += (clean.match(/\{/g) ?? []).length - (clean.match(/\}/g) ?? []).length
+  }
+  return out
+}
+
+/**
+ * The node ids of a mermaid source. The first line decides how the source is read; a type this
+ * module does not know, or a source it reads nothing out of, falls back to every word in the text.
+ */
+export function diagramNodeIds(source: string): Set<string> {
+  const type = diagramKind(source)
+  let found: string[] = []
+  if (type === 'flowchart' || type === 'flowchart-elk' || type === 'graph') {
+    found = flowchartIds(source)
+  } else if (type === 'sequenceDiagram') {
+    found = sequenceIds(source)
+  } else if (type === 'stateDiagram') {
+    found = stateIds(source)
+  } else if (type === 'erDiagram') {
+    found = erIds(source)
+  }
+  return new Set(found.length > 0 ? found : words(source))
+}

package/src/review/doctor.ts

@@ -0,0 +1,139 @@
+// `pr-review doctor`: one pass over everything the tool needs before it can serve a review, as
+// one JSON line. It reports instead of throwing, so a broken setup still answers.
+import { randomBytes } from 'node:crypto'
+import { rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parseGithubRemote } from '../config.js'
+import type { Git } from '../git/git.js'
+import type { GitHubClient } from '../github/gh.js'
+import { ensureDataDir, resolveDataDir } from '../store/data-dir.js'
+import { CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, SKILL_NAME } from './install-skill.js'
+
+export const DOCTOR_CHECKS = ['git', 'origin', 'gh', 'ghAuth', 'dataDir', 'skill'] as const
+export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number]
+
+export interface DoctorCheck {
+  ok: boolean
+  detail: string
+  hint?: string
+}
+
+export interface DoctorReport {
+  ok: boolean
+  version: string
+  checks: Record<DoctorCheckName, DoctorCheck> & { acpx?: DoctorCheck }
+}
+
+export interface DoctorDeps {
+  git: Git
+  gh: GitHubClient
+  version: string
+  acpxVersion: () => Promise<string | null>
+  /** `--data-dir` or `PR_REVIEW_DATA_DIR`; without it the dir sits next to the git common dir. */
+  dataDirOverride?: string | undefined
+  /** Answers whether a file can be read; the skill check asks for the SKILL.md inside. */
+  exists: (file: string) => Promise<boolean>
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+/**
+ * Can the process write where canvases go? A probe file is written and removed. Its name is
+ * random and it is created with `wx`, so the probe writes over nothing.
+ */
+async function checkDataDir(dir: string): Promise<DoctorCheck> {
+  const probe = path.join(dir, `.doctor-probe-${randomBytes(8).toString('hex')}`)
+  try {
+    await ensureDataDir(dir)
+    await writeFile(probe, '', { encoding: 'utf8', flag: 'wx' })
+    await rm(probe, { force: true })
+    return { ok: true, detail: dir }
+  } catch (err) {
+    return { ok: false, detail: `${dir}: ${message(err)}`, hint: 'pass --data-dir <dir> to a writable place' }
+  }
+}
+
+/** The skill the generation flow needs, in either harness's directory. */
+async function checkSkill(repoRoot: string | null, exists: DoctorDeps['exists']): Promise<DoctorCheck> {
+  if (repoRoot === null) {
+    return { ok: false, detail: 'no repository, so no skill directory to look in', hint: 'run from a clone' }
+  }
+  const targets = [CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR].map(dir => path.join(repoRoot, dir, SKILL_NAME))
+  const found: string[] = []
+  for (const target of targets) {
+    // The file the harness reads, not the directory: an empty directory, a dangling link, and
+    // an unreadable file all install nothing.
+    if (await exists(path.join(target, 'SKILL.md'))) {
+      found.push(path.relative(repoRoot, target))
+    }
+  }
+  if (found.length === 0) {
+    return {
+      ok: false,
+      detail: `${SKILL_NAME} is in neither ${CLAUDE_SKILLS_DIR} nor ${CODEX_SKILLS_DIR}`,
+      hint: 'run `pr-review install-skill`',
+    }
+  }
+  return { ok: true, detail: found.join(', ') }
+}
+
+async function checkAcpx(deps: DoctorDeps): Promise<DoctorCheck> {
+  const hint = 'install with `npm install -g acpx` and check `acpx --version`'
+  try {
+    const version = (await deps.acpxVersion())?.trim()
+    return version
+      ? { ok: true, detail: version }
+      : { ok: false, detail: 'acpx is missing or could not report its version', hint }
+  } catch (err) {
+    return { ok: false, detail: message(err), hint }
+  }
+}
+
+/** Runs core checks and, with allChecks, checks acpx for AI Chat. */
+export async function runDoctorChecks(deps: DoctorDeps, options: { allChecks?: boolean } = {}): Promise<DoctorReport> {
+  let repoRoot: string | null = null
+  let git: DoctorCheck
+  try {
+    repoRoot = await deps.git.topLevel()
+    git = { ok: true, detail: repoRoot }
+  } catch (err) {
+    git = { ok: false, detail: message(err), hint: 'run from a clone or pass --repo <dir>' }
+  }
+
+  let origin: DoctorCheck
+  try {
+    const url = await deps.git.remoteUrl('origin')
+    const repo = url === null ? null : parseGithubRemote(url)
+    origin =
+      repo === null
+        ? { ok: false, detail: url ?? 'no origin remote', hint: 'add a github.com origin' }
+        : { ok: true, detail: `${repo.owner}/${repo.name}` }
+  } catch (err) {
+    origin = { ok: false, detail: message(err), hint: 'add a github.com origin' }
+  }
+
+  const status = await deps.gh.authStatus()
+  const gh: DoctorCheck = status.installed
+    ? { ok: true, detail: status.detail }
+    : { ok: false, detail: status.detail, hint: 'install it from https://cli.github.com' }
+  const ghAuth: DoctorCheck = status.authenticated
+    ? { ok: true, detail: status.detail }
+    : { ok: false, detail: status.detail, hint: 'run `gh auth login`' }
+
+  let dataDir: DoctorCheck
+  try {
+    const commonDir = await deps.git.commonDir()
+    dataDir = await checkDataDir(resolveDataDir({ override: deps.dataDirOverride, commonDir }))
+  } catch (err) {
+    dataDir = { ok: false, detail: message(err), hint: 'pass --data-dir <dir>' }
+  }
+
+  const skill = await checkSkill(repoRoot, deps.exists)
+  const checks: DoctorReport['checks'] = { git, origin, gh, ghAuth, dataDir, skill }
+  if (options.allChecks) {
+    checks.acpx = await checkAcpx(deps)
+  }
+  return { ok: Object.values(checks).every(check => check.ok), version: deps.version, checks }
+}

package/src/review/glob.ts

@@ -0,0 +1,33 @@
+/**
+ * The subset of glob syntax `pr-review.config.yml` patterns use: `**` crosses directories,
+ * `*` and `?` stay inside one path segment. Patterns match repo-relative paths.
+ */
+export function globToRegExp(pattern: string): RegExp {
+  let out = '^'
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i += 1
+        if (pattern[i + 1] === '/') {
+          // `**/` matches zero or more whole directories.
+          i += 1
+          out += '(?:.*/)?'
+        } else {
+          out += '.*'
+        }
+      } else {
+        out += '[^/]*'
+      }
+    } else if (ch === '?') {
+      out += '[^/]'
+    } else if (ch !== undefined) {
+      out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    }
+  }
+  return new RegExp(`${out}$`)
+}
+
+export function matchesGlob(pattern: string, filePath: string): boolean {
+  return globToRegExp(pattern).test(filePath)
+}

package/src/review/install-skill.ts

@@ -0,0 +1,107 @@
+// `pr-review install-skill`: link the bundled skill into the host repo's skill directories, so
+// Claude Code (`.claude/skills`) and Codex (`.agents/skills`) both see `/pr-review-canvas`.
+import { appendFile, cp, lstat, mkdir, readlink, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { PACKAGE_ROOT } from '../server/context.js'
+import { readText } from '../store/atomic-json.js'
+
+export const SKILL_NAME = 'pr-review-canvas'
+export const SKILL_SOURCE_DIR = path.join(PACKAGE_ROOT, 'skills', SKILL_NAME)
+export const CLAUDE_SKILLS_DIR = '.claude/skills'
+/** Codex reads repo skills from `.agents/skills` under the project root (codex-rs/ext/skills). */
+export const CODEX_SKILLS_DIR = '.agents/skills'
+
+export async function ignoreLocalSettings(repoRoot: string): Promise<void> {
+  const file = path.join(repoRoot, '.gitignore')
+  const text = (await readText(file)) ?? ''
+  const entry = '.pr-review/settings.yml'
+  if (text.split(/\r?\n/).some(line => line === entry || line === `/${entry}`)) {
+    return
+  }
+  const newline = text.includes('\r\n') ? '\r\n' : '\n'
+  const separator = text.length > 0 && !text.endsWith('\n') ? newline : ''
+  await appendFile(file, `${separator}${entry}${newline}`, 'utf8')
+}
+
+export interface InstallSkillOptions {
+  /** Absolute skills directories to install into; each gets `<dir>/pr-review-canvas`. */
+  targets: Array<{ kind: 'claude' | 'codex'; dir: string }>
+  source?: string
+  /** Windows copies; everything else links. */
+  platform?: NodeJS.Platform
+  /** Replace a real directory that already sits at the target. */
+  force?: boolean
+}
+
+/** A real directory (a customized copy of the skill) sits where the link would go. */
+export class SkillDirExistsError extends Error {
+  readonly path: string
+
+  constructor(target: string) {
+    super(`${target} is a directory, not a link to the bundled skill`)
+    this.name = 'SkillDirExistsError'
+    this.path = target
+  }
+}
+
+export type InstallStatus = 'linked' | 'copied' | 'exists' | 'replaced'
+
+export interface InstallSkillResult {
+  skill: string
+  targets: Array<{ kind: 'claude' | 'codex'; path: string; status: InstallStatus }>
+}
+
+/** What sits at the target now: nothing, a symlink (with its target), or something else. */
+async function inspect(target: string): Promise<{ kind: 'none' } | { kind: 'link'; to: string } | { kind: 'other' }> {
+  let stats: Awaited<ReturnType<typeof lstat>>
+  try {
+    stats = await lstat(target)
+  } catch {
+    return { kind: 'none' }
+  }
+  return stats.isSymbolicLink() ? { kind: 'link', to: await readlink(target) } : { kind: 'other' }
+}
+
+/** A copy carries a marker file, so a later run can tell it from a hand-made directory. */
+export const COPY_MARKER = '.pr-review-install'
+
+async function installOne(
+  source: string,
+  dir: string,
+  copy: boolean,
+  force: boolean
+): Promise<{ path: string; status: InstallStatus }> {
+  await mkdir(dir, { recursive: true })
+  const realDir = await realpath(dir)
+  const target = path.join(realDir, SKILL_NAME)
+  const current = await inspect(target)
+  if (current.kind === 'other' && !force && (await inspect(path.join(target, COPY_MARKER))).kind === 'none') {
+    throw new SkillDirExistsError(target)
+  }
+  if (copy) {
+    await rm(target, { recursive: true, force: true })
+    await cp(source, target, { recursive: true })
+    await writeFile(path.join(target, COPY_MARKER), `copied from ${source}\n`, 'utf8')
+    return { path: target, status: 'copied' }
+  }
+  const relative = path.relative(realDir, source)
+  if (current.kind === 'link' && current.to === relative) {
+    return { path: target, status: 'exists' }
+  }
+  if (current.kind !== 'none') {
+    await rm(target, { recursive: true, force: true })
+  }
+  await symlink(relative, target, 'dir')
+  return { path: target, status: current.kind === 'none' ? 'linked' : 'replaced' }
+}
+
+export async function installSkill(opts: InstallSkillOptions): Promise<InstallSkillResult> {
+  const source = await realpath(opts.source ?? SKILL_SOURCE_DIR)
+  const copy = (opts.platform ?? process.platform) === 'win32'
+  const targets: InstallSkillResult['targets'] = []
+  for (const t of opts.targets) {
+    const done = await installOne(source, t.dir, copy, opts.force === true)
+    targets.push({ kind: t.kind, ...done })
+  }
+  return { skill: SKILL_NAME, targets }
+}