@brainwav/diagram 1.0.8 → 1.1.0

package/scripts/refresh-diagram-context.sh

@@ -1,199 +1,291 @@
 #!/usr/bin/env bash
-#
-# refresh-diagram-context.sh - Generate Mermaid diagrams and compact into AI context
-#
-# Usage:
-#   scripts/refresh-diagram-context.sh --dry-run    # Preview actions without changes
-#   scripts/refresh-diagram-context.sh --force      # Execute refresh
-#
-# Outputs:
-#   .diagram/*.mmd                        - Individual Mermaid diagrams
-#   .diagram/context/diagram-context.md   - Compacted context for AI agents
-#   .diagram/context/diagram-context.meta.json - Metadata with schema version
-#
 set -euo pipefail
 
-# Configuration
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-DIAGRAM_ENTRYPOINT="$REPO_ROOT/src/diagram.js"
-DIAGRAMS_DIR="$REPO_ROOT/.diagram"
-CONTEXT_DIR="$REPO_ROOT/.diagram/context"
+QUIET=0
+FORCE=0
+DRY_RUN=0
+CHECK=0
+
+while [[ $# -gt 0 ]]; do
+	case "$1" in
+		--quiet)
+			QUIET=1
+			shift
+			;;
+		--force)
+			FORCE=1
+			shift
+			;;
+		--dry-run)
+			DRY_RUN=1
+			shift
+			;;
+		--check)
+			CHECK=1
+			shift
+			;;
+		*)
+			echo "Unknown option: $1" >&2
+			exit 2
+			;;
+	esac
+done
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+bash "$ROOT_DIR/scripts/codex-preflight.sh" --mode optional
+
+DIAGRAM_DIR="$ROOT_DIR/.diagram"
+CONTEXT_DIR="$DIAGRAM_DIR/context"
 CONTEXT_FILE="$CONTEXT_DIR/diagram-context.md"
 META_FILE="$CONTEXT_DIR/diagram-context.meta.json"
-SCHEMA_VERSION="1.0"
-
-# State
-DRY_RUN=false
-FORCE=false
-
-usage() {
-  cat <<'USAGE'
-Usage:
-  scripts/refresh-diagram-context.sh --dry-run    # Preview actions without changes
-  scripts/refresh-diagram-context.sh --force      # Execute refresh
-
-Options:
-  --dry-run    Show what would be done without making changes
-  --force      Execute the refresh (required for actual changes)
-  -h, --help   Show this help message
-
-Outputs:
-  .diagram/*.mmd                        Individual Mermaid diagrams
-  .diagram/context/diagram-context.md   Compacted context for AI agents
-  .diagram/context/diagram-context.meta.json  Metadata with schema version
-USAGE
-}
-
-parse_args() {
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --dry-run)
-        DRY_RUN=true
-        shift
-        ;;
-      --force)
-        FORCE=true
-        shift
-        ;;
-      -h|--help)
-        usage
-        exit 0
-        ;;
-      *)
-        echo "Unknown option: $1" >&2
-        usage >&2
-        exit 2
-        ;;
-    esac
-  done
-}
+GIT_STATE_FILE="$(git -C "$ROOT_DIR" rev-parse --git-path archscope/refresh-state.local.json 2>/dev/null || true)"
+if [[ -n "$GIT_STATE_FILE" && "$GIT_STATE_FILE" != /* ]]; then
+	GIT_STATE_FILE="$ROOT_DIR/$GIT_STATE_FILE"
+fi
+ROOT_STATE_HASH="$(printf '%s' "$ROOT_DIR" | shasum -a 256 | awk '{print $1}')"
+FALLBACK_STATE_DIR="${DIAGRAM_REFRESH_STATE_DIR:-${TMPDIR:-/tmp}/archscope-refresh-state/$ROOT_STATE_HASH}"
+STATE_FILE="${GIT_STATE_FILE:-$FALLBACK_STATE_DIR/refresh-state.local.json}"
+LOG_FILE="$(dirname "$STATE_FILE")/refresh.log"
+MIN_SECONDS="${DIAGRAM_REFRESH_MIN_SECONDS:-1800}"
+MAX_FILES="${DIAGRAM_REFRESH_MAX_FILES:-1000}"
+CONTEXT_MAX_BYTES="${DIAGRAM_CONTEXT_MAX_BYTES:-12000}"
+CONTEXT_MAX_LINES_PER_DIAGRAM="${DIAGRAM_CONTEXT_MAX_LINES_PER_DIAGRAM:-140}"
+CONTEXT_MAX_EMBEDDED_DIAGRAMS="${DIAGRAM_CONTEXT_MAX_EMBEDDED_DIAGRAMS:-3}"
+NOW_EPOCH="$(date +%s)"
+
+if ! mkdir -p "$(dirname "$STATE_FILE")" 2>/dev/null; then
+	STATE_FILE="$FALLBACK_STATE_DIR/refresh-state.local.json"
+	mkdir -p "$(dirname "$STATE_FILE")"
+fi
+LOG_FILE="$(dirname "$STATE_FILE")/refresh.log"
+if [[ "$CHECK" -ne 1 && "$DRY_RUN" -ne 1 ]]; then
+	mkdir -p "$DIAGRAM_DIR" "$CONTEXT_DIR"
+fi
 
 log() {
-  echo "[refresh] $1"
-}
-
-log_dry() {
-  echo "[dry-run] $1"
-}
-
-ensure_dirs() {
-  if [[ "$DRY_RUN" == "true" ]]; then
-    log_dry "Would use: $DIAGRAMS_DIR"
-    log_dry "Would create: $CONTEXT_DIR"
-  else
-    mkdir -p "$DIAGRAMS_DIR"
-    mkdir -p "$CONTEXT_DIR"
-  fi
-}
-
-generate_diagrams() {
-  if [[ "$DRY_RUN" == "true" ]]; then
-    log_dry "Would generate diagrams to: $DIAGRAMS_DIR"
-    log_dry "  - All diagram types via 'diagram all'"
-    return 0
-  fi
-
-  if [[ "$FORCE" != "true" ]]; then
-    echo "Error: --force required to execute refresh" >&2
-    exit 1
-  fi
-
-  log "Generating diagrams to: $DIAGRAMS_DIR"
-
-  # Use 'diagram all' command with .diagram output directory
-  node "$DIAGRAM_ENTRYPOINT" all "$REPO_ROOT" --output-dir "$DIAGRAMS_DIR"
+	local message="$1"
+	printf '[%s] %s\n' "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$message" >> "$LOG_FILE"
+	if [[ "$QUIET" -ne 1 ]]; then
+		printf '%s\n' "$message"
+	fi
 }
 
-compact_context() {
-  if [[ "$DRY_RUN" == "true" ]]; then
-    log_dry "Would compact diagrams into: $CONTEXT_FILE"
-    return 0
-  fi
-
-  log "Compacting diagrams into: $CONTEXT_FILE"
-
-  # Build header
-  cat > "$CONTEXT_FILE" <<'HEADER'
-# Diagram Context Pack
-
-Auto-generated architecture context from Mermaid diagrams.
-Do not edit manually - regenerate with `scripts/refresh-diagram-context.sh --force`.
-
----
-
-HEADER
-
-  # Diagram types to include (matches diagram all output)
-  local diagram_types=("architecture" "dependency" "class" "sequence" "flow" "database" "user" "events" "auth" "security")
-
-  for dtype in "${diagram_types[@]}"; do
-    local mmd_file="$DIAGRAMS_DIR/${dtype}.mmd"
-    if [[ -f "$mmd_file" ]]; then
-      echo "## ${dtype^} Diagram" >> "$CONTEXT_FILE"
-      echo "" >> "$CONTEXT_FILE"
-      echo '```mermaid' >> "$CONTEXT_FILE"
-      cat "$mmd_file" >> "$CONTEXT_FILE"
-      echo '```' >> "$CONTEXT_FILE"
-      echo "" >> "$CONTEXT_FILE"
-      echo "---" >> "$CONTEXT_FILE"
-      echo "" >> "$CONTEXT_FILE"
-    fi
-  done
-
-  log "Context file created: $CONTEXT_FILE"
+if [[ "$DRY_RUN" -eq 1 ]]; then
+	log "dry-run: would refresh diagrams into $DIAGRAM_DIR and context at $CONTEXT_FILE"
+	exit 0
+fi
+
+COOLDOWN_FILE=""
+if [[ -f "$STATE_FILE" ]]; then
+	COOLDOWN_FILE="$STATE_FILE"
+elif [[ -f "$META_FILE" ]]; then
+	COOLDOWN_FILE="$META_FILE"
+fi
+
+if [[ "$CHECK" -ne 1 && "$FORCE" -ne 1 && -n "$COOLDOWN_FILE" ]]; then
+	last_epoch="$(jq -r '.last_generated_epoch // 0' "$COOLDOWN_FILE" 2>/dev/null || echo 0)"
+	if [[ "$last_epoch" =~ ^[0-9]+$ ]]; then
+		age=$((NOW_EPOCH - last_epoch))
+		if (( age < MIN_SECONDS )); then
+			log "skip: cooldown active (${age}s < ${MIN_SECONDS}s)"
+			exit 0
+		fi
+	fi
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+	log "error: node runtime is not available"
+	exit 1
+fi
+
+TRUNC_DIR=".tmp-diagram-refresh-XXXXXX"
+TMP_DIR="$(mktemp -d "$ROOT_DIR/${TRUNC_DIR}")"
+TMP_BASENAME="$(basename "$TMP_DIR")"
+EXCLUDE_PATTERNS="node_modules/**,.git/**,dist/**,${TMP_BASENAME}/**"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+pushd "$ROOT_DIR" >/dev/null
+GENERATE_ALL_CMD=(
+	node src/diagram.js generate-all .
+	--output-dir "$TMP_BASENAME/diagrams"
+	--artifact-profile agent
+	--deterministic
+	--exclude "$EXCLUDE_PATTERNS"
+	--max-files "$MAX_FILES"
+)
+if [[ "$QUIET" -eq 1 ]]; then
+	GENERATE_ALL_CMD+=(--quiet)
+fi
+"${GENERATE_ALL_CMD[@]}"
+popd >/dev/null
+
+if ! ls "$TMP_DIR/diagrams"/*.mmd >/dev/null 2>&1; then
+	log "error: no .mmd files produced"
+	exit 1
+fi
+
+MANIFEST_PATH="$TMP_DIR/diagrams/manifest.json"
+# shellcheck disable=SC2097,SC2098
+ROOT_DIR="$ROOT_DIR" TMP_DIR="$TMP_DIR" MANIFEST_PATH="$MANIFEST_PATH" \
+	node "$ROOT_DIR/src/context/normalize-diagram-manifest.js"
+
+TMP_CONTEXT="$TMP_DIR/diagram-context.md"
+TMP_CONTEXT_META="$TMP_DIR/diagram-context.meta.json"
+# shellcheck disable=SC2097,SC2098,SC2034
+ROOT_DIR="$ROOT_DIR" \
+TMP_DIR="$TMP_DIR" \
+CONTEXT_MAX_BYTES="$CONTEXT_MAX_BYTES" \
+CONTEXT_MAX_LINES_PER_DIAGRAM="$CONTEXT_MAX_LINES_PER_DIAGRAM" \
+CONTEXT_MAX_EMBEDDED_DIAGRAMS="$CONTEXT_MAX_EMBEDDED_DIAGRAMS" \
+CONTEXT_DETERMINISTIC=1 \
+CONTEXT_OUTPUT_PATH="$TMP_CONTEXT" \
+CONTEXT_META_OUTPUT_PATH="$TMP_CONTEXT_META" \
+	node "$ROOT_DIR/src/context/build-context-pack.js"
+
+CONTEXT_SHA="$(shasum -a 256 "$TMP_CONTEXT" | awk '{print $1}')"
+GIT_HEAD="$(git -C "$ROOT_DIR" rev-parse --short HEAD 2>/dev/null || echo "unknown")"
+# shellcheck disable=SC2012
+DIAGRAM_COUNT="$(ls "$TMP_DIR/diagrams"/*.mmd | wc -l | tr -d ' ')"
+TMP_STABLE_META="$TMP_DIR/diagram-context.stable-meta.json"
+TMP_STATE="$TMP_DIR/refresh-state.local.json"
+
+if [[ ! -f "$TMP_CONTEXT_META" ]]; then
+	log "error: context pack metadata sidecar missing at $TMP_CONTEXT_META"
+	exit 1
+fi
+
+jq --tab \
+	--arg context_sha256 "$CONTEXT_SHA" \
+	--argjson diagram_count "$DIAGRAM_COUNT" \
+	--argjson context_max_bytes "$CONTEXT_MAX_BYTES" \
+	--argjson context_max_lines_per_diagram "$CONTEXT_MAX_LINES_PER_DIAGRAM" \
+	--argjson context_max_embedded_diagrams "$CONTEXT_MAX_EMBEDDED_DIAGRAMS" \
+	--argjson context_bytes "$(wc -c < "$TMP_CONTEXT" | tr -d ' ')" \
+	'
+		. as $packer
+		| ($packer // {})
+		| del(.rootPath)
+		| .schema_version = 1
+		| .generated_at = (.generatedAt // "1970-01-01T00:00:00.000Z")
+		| .context_sha256 = $context_sha256
+		| .context_bytes = $context_bytes
+		| .context_max_bytes = $context_max_bytes
+		| .context_max_lines_per_diagram = $context_max_lines_per_diagram
+		| .context_max_embedded_diagrams = $context_max_embedded_diagrams
+		| .diagram_count = $diagram_count
+		| .context_path = ".diagram/context/diagram-context.md"
+		| .context_meta_path = ".diagram/context/diagram-context.meta.json"
+		| .diagram_manifest_path = ".diagram/manifest.json"
+		| .embedded_diagram_count = ((.embeddedCount // 0) | tonumber)
+		| .omittedTypes = ((.omittedTypes // []) | sort)
+		| .omitted_types = .omittedTypes
+		| .omitted_count = (.omittedTypes | length)
+	' "$TMP_CONTEXT_META" > "$TMP_STABLE_META"
+
+CHANGED=false
+changed_files=()
+
+mark_changed() {
+	CHANGED=true
+	changed_files+=("$1")
 }
 
-write_metadata() {
-  if [[ "$DRY_RUN" == "true" ]]; then
-    log_dry "Would write metadata to: $META_FILE"
-    return 0
-  fi
-
-  local timestamp
-  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-  local diagram_count
-  diagram_count=$(find "$DIAGRAMS_DIR" -maxdepth 1 -name "*.mmd" -type f 2>/dev/null | wc -l | tr -d ' ')
-
-  cat > "$META_FILE" <<EOF
-{
-  "schema_version": "$SCHEMA_VERSION",
-  "generated_at": "$timestamp",
-  "repo_root": "$REPO_ROOT",
-  "diagrams_dir": ".diagram",
-  "context_file": ".diagram/context/diagram-context.md",
-  "diagram_count": $diagram_count,
-  "diagram_types": ["architecture", "dependency", "class", "sequence", "flow", "database", "user", "events", "auth", "security"]
+compare_file() {
+	local source_file="$1"
+	local target_file="$2"
+	local label="$3"
+	if [[ ! -f "$target_file" ]] || ! cmp -s "$source_file" "$target_file"; then
+		mark_changed "$label"
+	fi
 }
-EOF
 
-  log "Metadata file created: $META_FILE"
+collect_mmd_names() {
+	local source_dir="$1"
+	local names=()
+	local file
+	for file in "$source_dir"/*.mmd; do
+		[[ -e "$file" ]] || continue
+		names+=("$(basename "$file")")
+	done
+	if [[ "${#names[@]}" -gt 0 ]]; then
+		printf '%s\n' "${names[@]}" | sort
+	fi
 }
 
-main() {
-  parse_args "$@"
-
-  echo "== Diagram Context Refresh =="
-  echo "Repo: $REPO_ROOT"
-  echo "Dry-run: $DRY_RUN"
-  echo "Force: $FORCE"
-  echo ""
-
-  ensure_dirs
-  generate_diagrams
-  compact_context
-  write_metadata
-
-  if [[ "$DRY_RUN" == "true" ]]; then
-    echo ""
-    echo "Dry-run complete. Run with --force to execute."
-  else
-    echo ""
-    echo "Refresh complete."
-    echo "  Diagrams: .diagram/"
-    echo "  Context:  .diagram/context/diagram-context.md"
-    echo "  Metadata: .diagram/context/diagram-context.meta.json"
-  fi
+compare_file "$TMP_CONTEXT" "$CONTEXT_FILE" ".diagram/context/diagram-context.md"
+compare_file "$TMP_DIR/diagrams/manifest.json" "$DIAGRAM_DIR/manifest.json" ".diagram/manifest.json"
+compare_file "$TMP_STABLE_META" "$META_FILE" ".diagram/context/diagram-context.meta.json"
+
+tmp_mmd_list="$(collect_mmd_names "$TMP_DIR/diagrams")"
+current_mmd_list="$(collect_mmd_names "$DIAGRAM_DIR")"
+if [[ "$tmp_mmd_list" != "$current_mmd_list" ]]; then
+	mark_changed ".diagram/*.mmd"
+else
+	while IFS= read -r mmd_name; do
+		[[ -n "$mmd_name" ]] || continue
+		compare_file "$TMP_DIR/diagrams/$mmd_name" "$DIAGRAM_DIR/$mmd_name" ".diagram/$mmd_name"
+	done <<< "$tmp_mmd_list"
+fi
+
+if [[ "$CHECK" -eq 1 ]]; then
+	if [[ "$CHANGED" == "true" ]]; then
+		log "check: diagram context is stale"
+		{
+			printf 'diagram context is stale; refresh required for:\n'
+			printf '  %s\n' "${changed_files[@]}"
+		} >&2
+		exit 1
+	fi
+	log "check: diagram context is current"
+	exit 0
+fi
+
+copy_if_changed() {
+	local source_file="$1"
+	local target_file="$2"
+	if [[ ! -f "$target_file" ]] || ! cmp -s "$source_file" "$target_file"; then
+		cp "$source_file" "$target_file"
+	fi
 }
 
-main "$@"
+while IFS= read -r mmd_name; do
+	[[ -n "$mmd_name" ]] || continue
+	copy_if_changed "$TMP_DIR/diagrams/$mmd_name" "$DIAGRAM_DIR/$mmd_name"
+done <<< "$tmp_mmd_list"
+
+while IFS= read -r mmd_name; do
+	[[ -n "$mmd_name" ]] || continue
+	if ! printf '%s\n' "$tmp_mmd_list" | grep -Fxq "$mmd_name"; then
+		rm -f "$DIAGRAM_DIR/$mmd_name"
+	fi
+done <<< "$current_mmd_list"
+
+copy_if_changed "$TMP_DIR/diagrams/manifest.json" "$DIAGRAM_DIR/manifest.json"
+copy_if_changed "$TMP_CONTEXT" "$CONTEXT_FILE"
+copy_if_changed "$TMP_STABLE_META" "$META_FILE"
+
+jq --tab \
+	--arg generated_at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+	--arg git_head "$GIT_HEAD" \
+	--arg context_sha256 "$CONTEXT_SHA" \
+	--argjson context_bytes "$(wc -c < "$TMP_CONTEXT" | tr -d ' ')" \
+	--argjson last_generated_epoch "$NOW_EPOCH" \
+	--argjson min_interval_seconds "$MIN_SECONDS" \
+	--arg changed "$CHANGED" \
+	--arg root_path "$ROOT_DIR" \
+	'
+		{
+			schema_version: 1,
+			generated_at: $generated_at,
+			root_path: $root_path,
+			git_head: $git_head,
+			context_sha256: $context_sha256,
+			context_bytes: $context_bytes,
+			last_generated_epoch: $last_generated_epoch,
+			min_interval_seconds: $min_interval_seconds,
+			changed: ($changed == "true")
+		}
+	' "$TMP_STABLE_META" > "$TMP_STATE"
+copy_if_changed "$TMP_STATE" "$STATE_FILE"
+
+log "ok: refreshed ${DIAGRAM_COUNT} diagrams (changed=${CHANGED})"

package/src/analyzers/default-analyzer.js

@@ -0,0 +1,11 @@
+const { analyze } = require('../core/analysis-generation');
+
+const defaultAnalyzer = {
+  name: 'default',
+  version: '1.0.0',
+  analyze(rootPath, options) {
+    return analyze(rootPath, options);
+  },
+};
+
+module.exports = { defaultAnalyzer };

package/src/analyzers/index.js

@@ -0,0 +1,34 @@
+const { defaultAnalyzer } = require('./default-analyzer');
+
+const ANALYZERS = new Map([
+  [defaultAnalyzer.name, defaultAnalyzer],
+]);
+
+function listAnalyzers() {
+  return [...ANALYZERS.values()].map((analyzer) => ({
+    name: analyzer.name,
+    version: analyzer.version,
+  }));
+}
+
+async function runAnalyzer(name, rootPath, options) {
+  const analyzerName = name || 'default';
+  const analyzer = ANALYZERS.get(analyzerName);
+  if (!analyzer) {
+    throw new Error(`Unknown analyzer plugin: ${analyzerName}`);
+  }
+
+  const analysis = await analyzer.analyze(rootPath, options);
+  return {
+    analyzer: {
+      name: analyzer.name,
+      version: analyzer.version,
+    },
+    analysis,
+  };
+}
+
+module.exports = {
+  runAnalyzer,
+  listAnalyzers,
+};

package/src/artifacts/agent-context.js

@@ -0,0 +1,105 @@
+const fs = require('fs');
+const path = require('path');
+const { summarizeAnalysis } = require('./evidence-summary');
+
+function normalizeStringArray(value) {
+  return Array.isArray(value)
+    ? [...new Set(value
+      .filter((entry) => typeof entry === 'string' && entry.trim())
+      .map((entry) => entry.trim()))].sort()
+    : [];
+}
+
+function buildComponentMetadata(analysis) {
+  return Array.isArray(analysis?.components)
+    ? analysis.components
+      .map((component) => ({
+        kind: 'component',
+        name: component.name || component.originalName || component.filePath || 'unknown',
+        path: component.filePath || '',
+        type: component.type || 'unknown',
+        roleTags: normalizeStringArray(component.roleTags),
+        dependencyCount: Array.isArray(component.dependencies) ? component.dependencies.length : 0,
+        source: 'analysis.components',
+        derivation: 'static-analysis',
+      }))
+      .sort((left, right) =>
+        `${left.path}:${left.name}`.localeCompare(`${right.path}:${right.name}`)
+      )
+    : [];
+}
+
+function buildAgentContext({
+  manifest,
+  analysis = {},
+  prImpact = null,
+  warnings = [],
+  errors = [],
+  mode = 'repository',
+}) {
+  const summary = summarizeAnalysis(analysis);
+  const artifacts = manifest.artifacts
+    .map((entry) => ({
+      id: entry.id,
+      path: entry.path,
+      role: entry.role,
+      status: entry.status,
+      ...(entry.reason ? { reason: entry.reason } : {}),
+      ...(entry.errorCategory ? { errorCategory: entry.errorCategory } : {}),
+    }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+
+  const payload = {
+    schemaVersion: '1.0',
+    generatedBy: 'archscope scan',
+    mode: prImpact ? 'pr' : mode,
+    partial: artifacts.some((entry) => entry.status === 'partial' || entry.status === 'failed'),
+    summary: {
+      componentCount: summary.componentCount,
+      entryPointCount: summary.entryPointCount,
+      totalFilesFound: summary.totalFilesFound,
+      languages: Object.fromEntries(summary.languages),
+      architectureAreas: Object.fromEntries(summary.areas),
+    },
+    artifacts,
+    components: buildComponentMetadata(analysis),
+    readOrder: [...manifest.artifactReadOrder],
+    warnings: [...warnings].sort(),
+    errors: errors
+      .map((error) => ({
+        category: error.category,
+        artifact: error.artifact,
+        message: error.message,
+      }))
+      .sort((left, right) =>
+        `${left.artifact || ''}:${left.category}`.localeCompare(`${right.artifact || ''}:${right.category}`)
+      ),
+  };
+
+  if (prImpact) {
+    payload.pr = {
+      status: prImpact._meta?.status || 'complete',
+      changedFiles: prImpact.changedFiles || [],
+      changedComponents: prImpact.changedComponents || [],
+      blastRadius: prImpact.blastRadius || null,
+      reviewerChecks: prImpact.agentSummary?.suggestedReviewerChecks || [],
+    };
+    payload.base = prImpact.base;
+    payload.head = prImpact.head;
+    payload.risk = prImpact.risk || null;
+  }
+
+  return payload;
+}
+
+function writeAgentContext(filePath, input) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const payload = buildAgentContext(input);
+  fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+module.exports = {
+  buildAgentContext,
+  writeAgentContext,
+};