@iceinvein/agent-skills 0.23.9 → 0.23.13

package/skills/magpie/scripts/impact-cmd.ts

@@ -0,0 +1,202 @@
+import { appendFile, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import {
+  buildImpactMap,
+  extractDiffNames,
+  type GrepHit,
+  type GrepPlan,
+  type ImpactMap,
+  parseGrepOutput,
+  planSearches,
+} from './impact.ts'
+import {
+  IMPACT_BRIEF_CAP_BYTES,
+  IMPACT_BRIEF_MAX_CHILDREN,
+  IMPACT_FULL_CAP_BYTES,
+  renderImpactMarkdown,
+} from './impact-render.ts'
+import { loadPathFilterConfig, matchesAny, type PathFilterConfig } from './path-filter.ts'
+import type { ShardEntry } from './shard.ts'
+import { type ReviewTarget, readTarget } from './target.ts'
+
+const IMPACT_FILE =
+  /^impact(?:\.brief)?\.md$|^impact\.json$|^impact\.shard-.*\.md$|^impact\..*\.tmp$/
+
+async function logLine(runDir: string, entry: Record<string, unknown>): Promise<void> {
+  await appendFile(join(runDir, 'log.jsonl'), `${JSON.stringify({ ...entry, ts: Date.now() })}\n`)
+}
+
+function isMissingFile(err: unknown): boolean {
+  return (err as NodeJS.ErrnoException)?.code === 'ENOENT'
+}
+
+async function readDiff(runDir: string): Promise<string> {
+  const path = join(runDir, 'diff.patch')
+  try {
+    return await readFile(path, 'utf8')
+  } catch (err) {
+    if (isMissingFile(err)) throw new Error(`${path} not found`)
+    throw err
+  }
+}
+
+// git grep exits 1 when nothing matches, which is an empty result, not a failure.
+async function runGrep(root: string, plan: GrepPlan): Promise<GrepHit[]> {
+  const proc = Bun.spawn(['git', ...plan.args], {
+    cwd: root,
+    stdin: new TextEncoder().encode(`${plan.patterns.join('\n')}\n`),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [out, err, exit] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  if (exit === 1) return []
+  if (exit !== 0) throw new Error(`git grep exited ${exit}: ${err.trim()}`)
+  return parseGrepOutput(out)
+}
+
+/** A run with no manifest was never sharded, which is the same as one shard. */
+async function readShards(runDir: string): Promise<ShardEntry[]> {
+  const path = join(runDir, 'shards', 'manifest.json')
+  let text: string
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (err) {
+    if (isMissingFile(err)) return []
+    throw err
+  }
+  const shards = (JSON.parse(text) as { shards?: unknown }).shards
+  if (!Array.isArray(shards)) throw new Error(`${path}: shards must be an array`)
+  for (const s of shards as Array<Partial<ShardEntry>>) {
+    if (typeof s?.id !== 'number' || !Array.isArray(s.files)) {
+      throw new Error(`${path}: each shard needs a numeric id and a files array`)
+    }
+  }
+  return shards as ShardEntry[]
+}
+
+// The same include/exclude decision filterDiff applies to the diff.
+function isFilteredOut(file: string, config: PathFilterConfig): boolean {
+  if (config.include.length > 0) return matchesAny(file, config.include) === null
+  return matchesAny(file, config.exclude) !== null
+}
+
+async function removeImpactFiles(runDir: string): Promise<void> {
+  for (const name of await readdir(runDir)) {
+    if (IMPACT_FILE.test(name)) await rm(join(runDir, name), { force: true })
+  }
+}
+
+// Written beside the target and renamed over it, so a run cut off mid-write leaves
+// either the whole file or none: a reader of a half-written file gets malformed JSON.
+async function writeAtomic(path: string, text: string): Promise<void> {
+  const temp = `${path}.tmp`
+  await writeFile(temp, text)
+  await rename(temp, path)
+}
+
+async function writeIfNonEmpty(path: string, text: string): Promise<void> {
+  if (text.length > 0) await writeAtomic(path, `${text}\n`)
+}
+
+async function writeRenders(runDir: string, map: ImpactMap, prefix: string, shard: number | null) {
+  await writeIfNonEmpty(
+    join(runDir, `${prefix}.md`),
+    renderImpactMarkdown(map, { shard, capBytes: IMPACT_FULL_CAP_BYTES }),
+  )
+  await writeIfNonEmpty(
+    join(runDir, `${prefix}.brief.md`),
+    renderImpactMarkdown(map, {
+      shard,
+      capBytes: IMPACT_BRIEF_CAP_BYTES,
+      maxChildren: IMPACT_BRIEF_MAX_CHILDREN,
+    }),
+  )
+}
+
+// setup reads .magpie.json from the user's checkout. A PR run's root is a worktree
+// at the PR head, so the checkout is the one owning the shared git dir.
+async function configDir(target: ReviewTarget): Promise<string> {
+  if (target.mode === 'local') return target.root
+  const args = ['rev-parse', '--path-format=absolute', '--git-common-dir']
+  const proc = Bun.spawn(['git', ...args], { cwd: target.root, stdout: 'pipe', stderr: 'pipe' })
+  const [out, err, exit] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  if (exit !== 0) throw new Error(`git ${args.join(' ')} exited ${exit}: ${err.trim()}`)
+  return dirname(out.trim())
+}
+
+async function buildMap(
+  runDir: string,
+  target: ReviewTarget,
+  shards: ShardEntry[],
+): Promise<ImpactMap> {
+  const root = target.root
+  const names = extractDiffNames(await readDiff(runDir))
+  const config = await loadPathFilterConfig(await configDir(target))
+  const hits: Record<GrepPlan['kind'], GrepHit[]> = {
+    references: [],
+    definitions: [],
+    writers: [],
+    routes: [],
+    docs: [],
+  }
+  for (const plan of planSearches(names)) hits[plan.kind].push(...(await runGrep(root, plan)))
+  const sharded = shards.length > 1
+  return buildImpactMap({
+    names,
+    hits,
+    shardOf: (file) => (sharded ? (shards.find((s) => s.files.includes(file))?.id ?? null) : null),
+    excluded: (file) => isFilteredOut(file, config),
+  })
+}
+
+export async function runImpact(runDir: string): Promise<number> {
+  const isDir = await stat(runDir)
+    .then((s) => s.isDirectory())
+    .catch(() => false)
+  if (!isDir) {
+    process.stderr.write(`impact: no such run directory: ${runDir}\n`)
+    return 2
+  }
+  let target: ReviewTarget
+  try {
+    target = await readTarget(runDir)
+  } catch (err) {
+    process.stderr.write(`impact: ${err instanceof Error ? err.message : String(err)}\n`)
+    return 2
+  }
+
+  try {
+    // Cleared before the search so a skipped re-run leaves no map from an older diff.
+    await removeImpactFiles(runDir)
+    const shards = await readShards(runDir)
+    const map = await buildMap(runDir, target, shards)
+    await writeAtomic(join(runDir, 'impact.json'), `${JSON.stringify(map, null, 2)}\n`)
+    await writeRenders(runDir, map, 'impact', null)
+    if (shards.length > 1) {
+      for (const s of shards) await writeRenders(runDir, map, `impact.shard-${s.id}`, s.id)
+    }
+    await logLine(runDir, {
+      stage: 'impact',
+      status: 'done',
+      symbols: map.symbols.length,
+      uses: map.uses.length,
+      stores: map.stores.length,
+      routes: map.routes.length,
+      docs: map.docs.length,
+    })
+    return 0
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    await logLine(runDir, { stage: 'impact', status: 'skipped', error: message })
+    process.stderr.write(`impact: skipped: ${message}\n`)
+    return 0
+  }
+}

package/skills/magpie/scripts/impact-render.ts

@@ -0,0 +1,158 @@
+import { COMMON_NAME_HITS, type ImpactLocation, type ImpactMap, type ImpactRef } from './impact.ts'
+
+export const IMPACT_FULL_CAP_BYTES = 8192
+export const IMPACT_BRIEF_CAP_BYTES = 2048
+export const IMPACT_BRIEF_MAX_CHILDREN = 3
+
+const SECTIONS = [
+  'Other writers of the same data',
+  'References to changed symbols',
+  'References to added symbols',
+  'Definitions this change relies on',
+  'Sibling routes',
+  'Docs naming what changed',
+] as const
+
+type Entry = {
+  section: number
+  anchor: ImpactLocation
+  shards: number[]
+  head: string
+  children: ImpactRef[]
+  // Symbols report their hit count; every other kind reports its child count.
+  total: number
+}
+
+function codeSpan(text: string): string {
+  return text.includes('`') ? `\`\` ${text} \`\`` : `\`${text}\``
+}
+
+function head(name: string, at: ImpactLocation): string {
+  return `- \`${name}\` (diff: ${at.file}:${at.line})`
+}
+
+function firstLocation(list: ImpactLocation[], what: string): ImpactLocation {
+  const at = list[0]
+  if (!at) throw new Error(`Impact ${what} has no diff location`)
+  return at
+}
+
+function shardList(shard: number | null): number[] {
+  return shard === null ? [] : [shard]
+}
+
+// Entries with no facts outside the diff are left out: they tell a reviewer nothing.
+function entriesOf(map: ImpactMap): Entry[] {
+  const entries: Entry[] = []
+  for (const s of map.stores) {
+    if (s.writers.length === 0) continue
+    const anchor = firstLocation(s.usedIn, `store ${s.name}`)
+    entries.push({
+      section: 0,
+      anchor,
+      shards: shardList(s.shard),
+      head: head(s.name, anchor),
+      children: s.writers,
+      total: s.writers.length,
+    })
+  }
+  for (const s of map.symbols) {
+    const common = s.hits > COMMON_NAME_HITS
+    if (!common && s.references.length === 0) continue
+    const anchor = firstLocation(s.definedAt, `symbol ${s.name}`)
+    entries.push({
+      section: s.kind === 'added' ? 2 : 1,
+      anchor,
+      shards: shardList(s.shard),
+      head: common ? `- \`${s.name}\`: ${s.hits} hits, too common to list` : head(s.name, anchor),
+      children: common ? [] : s.references,
+      total: common ? 0 : s.hits,
+    })
+  }
+  for (const u of map.uses) {
+    if (u.definedAt.length === 0) continue
+    entries.push({
+      section: 3,
+      anchor: u.usedIn,
+      shards: shardList(u.shard),
+      head: head(u.name, u.usedIn),
+      children: u.definedAt,
+      total: u.definedAt.length,
+    })
+  }
+  for (const r of map.routes) {
+    if (r.siblings.length === 0) continue
+    entries.push({
+      section: 4,
+      anchor: r.usedIn,
+      shards: shardList(r.shard),
+      head: head(r.path, r.usedIn),
+      children: r.siblings,
+      total: r.siblings.length,
+    })
+  }
+  for (const d of map.docs) {
+    entries.push({
+      section: 5,
+      anchor: { file: d.file, line: d.line },
+      shards: d.shards,
+      head: `- ${d.file}:${d.line} ${codeSpan(d.text)} (names: ${d.mentions.join(', ')})`,
+      children: [],
+      total: 0,
+    })
+  }
+  return entries.sort((a, b) => {
+    if (a.section !== b.section) return a.section - b.section
+    if (a.anchor.file !== b.anchor.file) return a.anchor.file < b.anchor.file ? -1 : 1
+    return a.anchor.line - b.anchor.line
+  })
+}
+
+function entryLines(e: Entry, maxChildren: number): string[] {
+  const shown = e.children.slice(0, maxChildren)
+  const lines = [e.head, ...shown.map((r) => `  - ${r.file}:${r.line} ${codeSpan(r.text)}`)]
+  if (e.total > shown.length) lines.push(`  - ${shown.length} of ${e.total} shown`)
+  return lines
+}
+
+function renderEntries(kept: Entry[], left: number, maxChildren: number): string {
+  const lines: string[] = []
+  let section = -1
+  for (const e of kept) {
+    if (e.section !== section) {
+      if (lines.length > 0) lines.push('')
+      section = e.section
+      lines.push(`### ${SECTIONS[section]}`)
+    }
+    lines.push(...entryLines(e, maxChildren))
+  }
+  if (left > 0) {
+    if (lines.length > 0) lines.push('')
+    lines.push(`${left} more entries in impact.json`)
+  }
+  return lines.join('\n')
+}
+
+function renderCapped(entries: Entry[], capBytes: number, maxChildren: number): string {
+  const fits = (s: string): boolean => Buffer.byteLength(s, 'utf8') <= capBytes
+  let kept: Entry[] = []
+  for (const e of entries) {
+    const trial = [...kept, e]
+    // Counting every entry not yet kept bounds the final count line from above.
+    if (fits(renderEntries(trial, entries.length - trial.length, maxChildren))) kept = trial
+  }
+  const out = renderEntries(kept, entries.length - kept.length, maxChildren)
+  if (!fits(out)) {
+    throw new Error(`Impact render cap of ${capBytes} bytes cannot hold its own count line`)
+  }
+  return out
+}
+
+export function renderImpactMarkdown(
+  map: ImpactMap,
+  opts: { shard: number | null; capBytes: number; maxChildren?: number },
+): string {
+  const { shard } = opts
+  const entries = entriesOf(map).filter((e) => shard === null || e.shards.includes(shard))
+  return renderCapped(entries, opts.capBytes, opts.maxChildren ?? Number.POSITIVE_INFINITY)
+}