add doc-agent

.github/scripts/doc-agent/src/config.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared configuration for doc-agent.
+ *
+ * Paths are resolved relative to the doc-agent directory so the tool works
+ * regardless of where it's invoked from.
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Absolute path to the doc-agent root (parent of src/). */
+export const AGENT_DIR: string = resolve(__dirname, '..');
+
+/** Absolute path to the prompts directory. */
+export const PROMPTS_DIR: string = resolve(AGENT_DIR, 'prompts');
+
+/**
+ * Absolute path to the xrpld repo root.
+ *
+ * Defaults to three levels up from doc-agent (which lives at
+ * .github/scripts/doc-agent/). Override with the XRPLD_ROOT env var when
+ * running against a different checkout.
+ */
+export const XRPLD_ROOT: string = process.env['XRPLD_ROOT'] ?? resolve(AGENT_DIR, '..', '..', '..');
+
+/** Model used for documentation generation and review. */
+export const MODEL: string = process.env['DOC_AGENT_MODEL'] ?? 'claude-opus-4-7';
+
+/** Absolute path to the skills directory inside the xrpld repo. */
+export const SKILLS_DIR: string = resolve(XRPLD_ROOT, 'docs', 'skills');
+
+/**
+ * Map module path prefixes to their skill file name in docs/skills/soul/.
+ *
+ * Used to inject module-specific context into the agent's system prompt
+ * when documenting or reviewing code in that module.
+ */
+export const MODULE_SKILL_MAP: Readonly<Record<string, string | null>> = {
+  'src/libxrpl/basics/': null,
+  'src/libxrpl/crypto/': 'cryptography.md',
+  'src/libxrpl/json/': null,
+  'src/libxrpl/beast/': null,
+  'src/libxrpl/protocol/': 'protocol.md',
+  'src/libxrpl/ledger/': 'ledger.md',
+  'src/libxrpl/tx/': 'transactors.md',
+  'src/libxrpl/nodestore/': 'nodestore.md',
+  'src/libxrpl/shamap/': 'shamap.md',
+  'src/libxrpl/rdb/': 'sql.md',
+  'src/xrpld/consensus/': 'consensus.md',
+  'src/xrpld/overlay/': 'peering.md',
+  'src/xrpld/peerfinder/': 'peering.md',
+  'src/xrpld/rpc/': 'rpc.md',
+  'include/xrpl/crypto/': 'cryptography.md',
+  'include/xrpl/protocol/': 'protocol.md',
+  'include/xrpl/ledger/': 'ledger.md',
+  'include/xrpl/tx/': 'transactors.md',
+  'include/xrpl/nodestore/': 'nodestore.md',
+  'include/xrpl/shamap/': 'shamap.md',
+};
+
+/**
+ * Resolve which skill file applies to a given source path.
+ *
+ * @param sourcePath - Path relative to the xrpld repo root
+ * @returns The skill file name, or null if no skill applies
+ */
+export function skillForPath(sourcePath: string): string | null {
+  for (const [prefix, skillFile] of Object.entries(MODULE_SKILL_MAP)) {
+    if (sourcePath.startsWith(prefix) || sourcePath.includes(`/${prefix}`)) {
+      return skillFile;
+    }
+  }
+  return null;
+}

.github/scripts/doc-agent/src/document.ts

@@ -0,0 +1,114 @@
+/**
+ * Document mode: add Doxygen docs to a file or all files in a directory.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { MODEL, XRPLD_ROOT } from './config.js';
+import { loadSystemPrompt } from './prompt-loader.js';
+
+const CPP_EXTENSIONS: ReadonlySet<string> = new Set(['.h', '.hpp', '.cpp']);
+
+/**
+ * Recursively find all C++ source files under a target path.
+ *
+ * @param target - File or directory path (relative to xrpld root or absolute)
+ * @returns Absolute paths of all matching files
+ */
+function findCppFiles(target: string): string[] {
+  const absTarget = resolve(XRPLD_ROOT, target);
+  if (!existsSync(absTarget)) {
+    throw new Error(`Target does not exist: ${absTarget}`);
+  }
+
+  const stat = statSync(absTarget);
+  if (stat.isFile()) {
+    return [absTarget];
+  }
+
+  const results: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        const dotIdx = entry.name.lastIndexOf('.');
+        if (dotIdx === -1) continue;
+        const ext = entry.name.slice(dotIdx);
+        if (CPP_EXTENSIONS.has(ext)) {
+          results.push(full);
+        }
+      }
+    }
+  };
+  walk(absTarget);
+  return results;
+}
+
+/**
+ * Document a single file by running the documentation agent against it.
+ */
+async function documentFile(absPath: string): Promise<void> {
+  const relPath = relative(XRPLD_ROOT, absPath);
+  console.log(`\n=== Documenting: ${relPath} ===`);
+
+  const systemPrompt = await loadSystemPrompt('document-file', relPath);
+  const userPrompt = `Add Doxygen documentation to: ${relPath}
+
+The file is rooted at ${XRPLD_ROOT}. Use the Read tool to read it, the Edit
+tool to add documentation, and Glob/Grep to find related tests or callers
+when needed.
+
+Do not modify any code logic — only add documentation comments.`;
+
+  const result = query({
+    prompt: userPrompt,
+    options: {
+      model: MODEL,
+      systemPrompt,
+      cwd: XRPLD_ROOT,
+      allowedTools: ['Read', 'Edit', 'Glob', 'Grep', 'Bash'],
+      permissionMode: 'acceptEdits',
+    },
+  });
+
+  for await (const message of result) {
+    if (message.type === 'assistant') {
+      const content = message.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text') {
+            process.stdout.write(block.text);
+          }
+        }
+      }
+    }
+    if (message.type === 'result') {
+      const cost = message.total_cost_usd?.toFixed(4) ?? '?';
+      const inTok = message.usage?.['input_tokens'] ?? 0;
+      const outTok = message.usage?.['output_tokens'] ?? 0;
+      console.log(`\n[Cost: $${cost}, Tokens: ${inTok}/${outTok}]`);
+    }
+  }
+}
+
+/**
+ * Document a file or every C++ file under a directory.
+ *
+ * @param target - File or directory path
+ */
+export async function documentTarget(target: string): Promise<void> {
+  const files = findCppFiles(target);
+  console.log(`Found ${files.length} C++ file(s) to document.`);
+
+  for (const file of files) {
+    try {
+      await documentFile(file);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Failed to document ${file}: ${message}`);
+    }
+  }
+}

.github/scripts/doc-agent/src/index.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * xrpld doc-agent CLI entry point.
+ *
+ * @example
+ *   doc-agent document src/libxrpl/basics/base_uint.h
+ *   doc-agent document include/xrpl/basics/
+ *   doc-agent review develop..HEAD
+ *   doc-agent review --pr 1234
+ */
+
+import { documentTarget } from './document.js';
+import { reviewDiff } from './review.js';
+
+const USAGE = `
+xrpld doc-agent
+
+Usage:
+  doc-agent document <file-or-directory>   Add Doxygen documentation
+  doc-agent review <base>..<head>          Detect doc drift in range
+  doc-agent review --pr <number>           Detect doc drift for a PR
+
+Environment:
+  ANTHROPIC_API_KEY  (required)  Anthropic API key
+  XRPLD_ROOT         (optional)  Path to xrpld repo root (default: repo root)
+  DOC_AGENT_MODEL    (optional)  Model override (default: claude-opus-4-7)
+`;
+
+function printUsageAndExit(code: number): never {
+  console.error(USAGE);
+  process.exit(code);
+}
+
+const HELP_MODES: ReadonlySet<string> = new Set(['help', '--help', '-h']);
+
+async function main(): Promise<void> {
+  const [mode, ...args] = process.argv.slice(2);
+
+  if (process.env['ANTHROPIC_API_KEY'] === undefined) {
+    console.error('ERROR: ANTHROPIC_API_KEY environment variable is required.');
+    process.exit(1);
+  }
+
+  if (mode === undefined || HELP_MODES.has(mode)) {
+    printUsageAndExit(0);
+  }
+
+  if (mode === 'document') {
+    const target = args[0];
+    if (target === undefined) printUsageAndExit(1);
+    await documentTarget(target);
+    return;
+  }
+
+  if (mode === 'review') {
+    if (args.length === 0) printUsageAndExit(1);
+    await reviewDiff(args);
+    return;
+  }
+
+  console.error(`Unknown mode: ${mode}`);
+  printUsageAndExit(1);
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+  console.error('FATAL:', message);
+  process.exit(1);
+});

.github/scripts/doc-agent/src/prompt-loader.ts

@@ -0,0 +1,34 @@
+/**
+ * Loads system prompts and injects module-specific skill context.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { PROMPTS_DIR, SKILLS_DIR, skillForPath } from './config.js';
+
+/**
+ * Load a system prompt from prompts/ and append the relevant module skill
+ * if one applies to the given source path.
+ *
+ * @param promptName - Base name of the prompt file (without .md extension)
+ * @param sourcePath - Path relative to the xrpld repo root
+ * @returns The fully-assembled system prompt
+ */
+export async function loadSystemPrompt(promptName: string, sourcePath: string): Promise<string> {
+  const basePromptPath = resolve(PROMPTS_DIR, `${promptName}.md`);
+  const basePrompt = await readFile(basePromptPath, 'utf8');
+
+  const skillFile = skillForPath(sourcePath);
+  if (skillFile === null) {
+    return basePrompt;
+  }
+
+  const skillPath = resolve(SKILLS_DIR, 'soul', skillFile);
+  if (!existsSync(skillPath)) {
+    return basePrompt;
+  }
+
+  const skill = await readFile(skillPath, 'utf8');
+  return `${basePrompt}\n\n## Module Skill (${skillFile})\n\n${skill}`;
+}

.github/scripts/doc-agent/src/review.ts

@@ -0,0 +1,222 @@
+/**
+ * Review mode: detect documentation drift in a git diff range.
+ *
+ * Used by the doc-review GitHub Action and locally for testing.
+ */
+
+import { execSync } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { MODEL, XRPLD_ROOT } from './config.js';
+import { loadSystemPrompt } from './prompt-loader.js';
+import type { FileReviewResult, GitRange, ReviewIssue, ReviewOutput } from './types.js';
+
+const MAX_DIFF_CHARS = 12_000;
+const TRACKED_PATH_PATTERN = /^(include|src\/libxrpl|src\/xrpld)\//;
+const CPP_FILE_PATTERN = /\.(h|hpp|cpp)$/;
+
+/**
+ * Parse the CLI arguments into a base..head git range.
+ *
+ * Accepts either:
+ *   - `base..head` (e.g. `develop..HEAD`)
+ *   - `--pr <number>` (resolves via `gh pr view`)
+ */
+function parseRangeArgs(args: readonly string[]): GitRange {
+  const first = args[0];
+  if (first === undefined) {
+    throw new Error('Expected range as base..head or --pr <number>');
+  }
+
+  if (first === '--pr') {
+    const pr = args[1];
+    if (pr === undefined) {
+      throw new Error('--pr requires a PR number');
+    }
+    const base = execSync(`gh pr view ${pr} --json baseRefOid -q .baseRefOid`, {
+      cwd: XRPLD_ROOT,
+    })
+      .toString()
+      .trim();
+    const head = execSync(`gh pr view ${pr} --json headRefOid -q .headRefOid`, {
+      cwd: XRPLD_ROOT,
+    })
+      .toString()
+      .trim();
+    return { base, head };
+  }
+
+  const match = first.match(/^([^.]+)\.\.([^.]+)$/);
+  if (match === null || match[1] === undefined || match[2] === undefined) {
+    throw new Error('Expected range as base..head or --pr <number>');
+  }
+  return { base: match[1], head: match[2] };
+}
+
+/**
+ * Get the list of C++ source files changed in the given git range,
+ * filtered to paths the doc-agent cares about.
+ */
+function getChangedCppFiles(range: GitRange): string[] {
+  const out = execSync(`git diff --name-only ${range.base}...${range.head}`, {
+    cwd: XRPLD_ROOT,
+  }).toString();
+
+  return out
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .filter((file) => CPP_FILE_PATTERN.test(file))
+    .filter((file) => TRACKED_PATH_PATTERN.test(file));
+}
+
+/** Get the unified diff for a single file in the given range. */
+function getFileDiff(range: GitRange, file: string): string {
+  return execSync(`git diff ${range.base}...${range.head} -- "${file}"`, {
+    cwd: XRPLD_ROOT,
+    maxBuffer: 10 * 1024 * 1024,
+  }).toString();
+}
+
+/** Extract a JSON object from a possibly-fenced model response. */
+function extractJson(response: string): ReviewOutput | null {
+  const fenced = response.match(/```json\s*([\s\S]*?)```/);
+  const raw = fenced?.[1] ?? response.match(/(\{[\s\S]*\})/)?.[1];
+  if (raw === undefined) return null;
+  try {
+    return JSON.parse(raw) as ReviewOutput;
+  } catch {
+    return null;
+  }
+}
+
+/** Send one file's diff to the agent and parse the response. */
+async function reviewFile(range: GitRange, file: string): Promise<FileReviewResult | null> {
+  console.log(`\n=== Reviewing: ${file} ===`);
+  const diff = getFileDiff(range, file);
+  if (diff.trim().length === 0) return null;
+
+  const systemPrompt = await loadSystemPrompt('review-diff', file);
+  const userPrompt = `Review this diff for documentation drift:
+
+## File: ${file}
+
+## Diff
+\`\`\`
+${diff.slice(0, MAX_DIFF_CHARS)}
+\`\`\`
+
+Use the Read tool to inspect the current state of the file, related tests,
+or callers if needed. Output findings as JSON per the schema in the system
+prompt.`;
+
+  let response = '';
+  const result = query({
+    prompt: userPrompt,
+    options: {
+      model: MODEL,
+      systemPrompt,
+      cwd: XRPLD_ROOT,
+      allowedTools: ['Read', 'Glob', 'Grep', 'Bash'],
+      permissionMode: 'acceptEdits',
+    },
+  });
+
+  for await (const message of result) {
+    if (message.type === 'assistant') {
+      const content = message.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text') {
+            response += block.text;
+          }
+        }
+      }
+    }
+  }
+
+  const parsed = extractJson(response);
+  if (parsed === null) {
+    console.warn(`  No JSON output for ${file}, skipping`);
+    return null;
+  }
+
+  const issues: ReviewIssue[] = parsed.issues.map((issue) => ({
+    file: issue.file ?? file,
+    line: issue.line,
+    severity: issue.severity,
+    message: issue.message,
+    ...(issue.suggested_doc !== undefined && { suggestedDoc: issue.suggested_doc }),
+  }));
+
+  return { file, summary: parsed.summary, issues };
+}
+
+/** Build the markdown report posted to the PR. */
+function buildReport(fileCount: number, results: readonly FileReviewResult[]): string {
+  const issues = results.flatMap((r) => r.issues);
+  const warnings = issues.filter((i) => i.severity === 'warning').length;
+  const suggestions = issues.length - warnings;
+
+  const lines: string[] = ['## Documentation Review Report', ''];
+  lines.push(
+    issues.length === 0
+      ? 'No documentation issues found.'
+      : `Found **${issues.length}** issue(s) across **${fileCount}** changed file(s): ${warnings} warning(s), ${suggestions} suggestion(s).`,
+  );
+  lines.push('');
+
+  for (const result of results) {
+    if (result.issues.length === 0) continue;
+    lines.push(`### \`${result.file}\``, '', result.summary, '');
+    for (const issue of result.issues) {
+      const tag = issue.severity === 'warning' ? '**Warning:**' : '**Suggestion:**';
+      lines.push(`- ${tag} Line ${issue.line}: ${issue.message}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---', '*Automated review by doc-agent.*');
+  return lines.join('\n');
+}
+
+/**
+ * Review the documentation drift introduced by a git range or PR.
+ *
+ * Writes two output files in the current working directory:
+ *   - doc-review-report.md (markdown summary for PR comment)
+ *   - doc-review-comments.json (inline review comments)
+ */
+export async function reviewDiff(args: readonly string[]): Promise<void> {
+  const range = parseRangeArgs(args);
+  console.log(`Reviewing range: ${range.base}...${range.head}`);
+
+  const files = getChangedCppFiles(range);
+  if (files.length === 0) {
+    console.log('No C++ files changed in this range.');
+    await writeFile('doc-review-report.md', '## Documentation Review\n\nNo C++ files changed.\n');
+    await writeFile('doc-review-comments.json', '[]');
+    return;
+  }
+
+  console.log(`Found ${files.length} changed C++ file(s).`);
+
+  const results: FileReviewResult[] = [];
+  for (const file of files) {
+    try {
+      const result = await reviewFile(range, file);
+      if (result !== null) results.push(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`  Review failed for ${file}: ${message}`);
+    }
+  }
+
+  const report = buildReport(files.length, results);
+  const allIssues = results.flatMap((r) => r.issues);
+
+  await writeFile('doc-review-report.md', report);
+  await writeFile('doc-review-comments.json', JSON.stringify(allIssues, null, 2));
+
+  console.log('\nReport: doc-review-report.md');
+  console.log(`Inline comments: doc-review-comments.json (${allIssues.length} issues)`);
+}

.github/scripts/doc-agent/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared type definitions for the doc-agent.
+ */
+
+export type Severity = 'warning' | 'suggestion';
+
+export interface ReviewIssue {
+  file: string;
+  line: number;
+  severity: Severity;
+  message: string;
+  suggestedDoc?: string;
+}
+
+export interface FileReviewResult {
+  file: string;
+  summary: string;
+  issues: ReviewIssue[];
+}
+
+export interface ReviewOutput {
+  summary: string;
+  issues: Array<{
+    file?: string;
+    line: number;
+    severity: Severity;
+    message: string;
+    suggested_doc?: string;
+  }>;
+}
+
+export interface GitRange {
+  base: string;
+  head: string;
+}
+
+export type AgentMode = 'document' | 'review';