forgedock 1.0.22 → 1.1.2

package/scripts/code-index.sh

@@ -0,0 +1,454 @@
+#!/usr/bin/env bash
+# code-index.sh — Per-commit symbol index and import graph for ForgeDock agents
+#
+# Builds a deterministic code map (symbols + import graph + file-to-domain mapping)
+# keyed by HEAD SHA. Cached under .forge/index/ to avoid redundant rebuilds.
+#
+# Usage:
+#   scripts/code-index.sh [--repo-path <path>] [--output <dir>] [--force]
+#   scripts/code-index.sh query --symbol <name> [--repo-path <path>]
+#   scripts/code-index.sh query --callers <name> [--repo-path <path>]
+#   scripts/code-index.sh query --importers <file> [--repo-path <path>]
+#   scripts/code-index.sh query --domain <label> [--repo-path <path>]
+#
+# Output files (under CACHE_DIR/{HEAD_SHA}/):
+#   symbols.tsv       — symbol_name TAB file TAB line TAB kind (function|class|method|const)
+#   imports.tsv       — importer_file TAB imported_module TAB imported_symbol
+#   file_domain.tsv   — file_path TAB domain_label
+#   callers.tsv       — callee_symbol TAB caller_file TAB caller_line
+#   index.json        — machine-readable manifest with metadata
+#
+# Tooling:
+#   Primary:  ctags (universal-ctags preferred) for symbol extraction
+#   Fallback: grep-based extraction when ctags is unavailable
+#   Import graph: language-specific grep patterns (Python, JS/TS, Go, Rust, shell)
+#
+# Cache key: HEAD SHA — cache is a hit on unchanged HEAD, miss on new commit.
+# Works on Windows (Git Bash / WSL) and Linux. No bash-only hot-path tooling.
+#
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+QUERY_MODE=""
+QUERY_TYPE=""
+QUERY_ARG=""
+REPO_PATH="${PWD}"
+OUTPUT_DIR=""
+FORCE=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    query)
+      QUERY_MODE=1
+      shift
+      ;;
+    --symbol)
+      QUERY_TYPE="symbol"
+      QUERY_ARG="$2"
+      shift 2
+      ;;
+    --callers)
+      QUERY_TYPE="callers"
+      QUERY_ARG="$2"
+      shift 2
+      ;;
+    --importers)
+      QUERY_TYPE="importers"
+      QUERY_ARG="$2"
+      shift 2
+      ;;
+    --domain)
+      QUERY_TYPE="domain"
+      QUERY_ARG="$2"
+      shift 2
+      ;;
+    --repo-path)
+      REPO_PATH="$2"
+      shift 2
+      ;;
+    --output)
+      OUTPUT_DIR="$2"
+      shift 2
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Resolve paths
+# ---------------------------------------------------------------------------
+REPO_PATH=$(cd "$REPO_PATH" 2>/dev/null && pwd || echo "$REPO_PATH")
+CACHE_BASE="${OUTPUT_DIR:-${REPO_PATH}/.forge/index}"
+
+# Read HEAD SHA (portable: works when git is available, otherwise use timestamp)
+if command -v git >/dev/null 2>&1 && git -C "$REPO_PATH" rev-parse HEAD >/dev/null 2>&1; then
+  HEAD_SHA=$(git -C "$REPO_PATH" rev-parse HEAD)
+else
+  HEAD_SHA="no-git-$(date +%s)"
+fi
+
+CACHE_DIR="${CACHE_BASE}/${HEAD_SHA}"
+
+# ---------------------------------------------------------------------------
+# Query mode — serve cached data without rebuilding
+# ---------------------------------------------------------------------------
+if [[ -n "$QUERY_MODE" ]]; then
+  if [[ ! -d "$CACHE_DIR" ]]; then
+    echo "ERROR: No index found for HEAD ${HEAD_SHA:0:8}. Run code-index.sh to build first." >&2
+    echo "Hint: cd \"${REPO_PATH}\" && scripts/code-index.sh --repo-path \"${REPO_PATH}\"" >&2
+    exit 1
+  fi
+
+  case "$QUERY_TYPE" in
+    symbol)
+      if [[ -f "${CACHE_DIR}/symbols.tsv" ]]; then
+        grep -i "^${QUERY_ARG}"$'\t' "${CACHE_DIR}/symbols.tsv" || true
+      fi
+      ;;
+    callers)
+      if [[ -f "${CACHE_DIR}/callers.tsv" ]]; then
+        grep -i "^${QUERY_ARG}"$'\t' "${CACHE_DIR}/callers.tsv" || true
+      fi
+      ;;
+    importers)
+      if [[ -f "${CACHE_DIR}/imports.tsv" ]]; then
+        grep -i $'\t'"${QUERY_ARG}"$'\t' "${CACHE_DIR}/imports.tsv" || \
+        grep -i $'\t'"${QUERY_ARG}"$   "${CACHE_DIR}/imports.tsv" || true
+      fi
+      ;;
+    domain)
+      if [[ -f "${CACHE_DIR}/file_domain.tsv" ]]; then
+        grep -i $'\t'"${QUERY_ARG}"$ "${CACHE_DIR}/file_domain.tsv" || true
+      fi
+      ;;
+    *)
+      echo "ERROR: Unknown query type. Use --symbol, --callers, --importers, or --domain" >&2
+      exit 1
+      ;;
+  esac
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Build mode — check cache hit first
+# ---------------------------------------------------------------------------
+if [[ -d "$CACHE_DIR" && -f "${CACHE_DIR}/index.json" && "$FORCE" -eq 0 ]]; then
+  echo "INFO: Cache hit for HEAD ${HEAD_SHA:0:8} — skipping rebuild"
+  echo "INFO: Index at ${CACHE_DIR}"
+  cat "${CACHE_DIR}/index.json"
+  exit 0
+fi
+
+echo "INFO: Building code index for HEAD ${HEAD_SHA:0:8}..."
+mkdir -p "$CACHE_DIR"
+
+# ---------------------------------------------------------------------------
+# Step 1: Symbol extraction
+# ---------------------------------------------------------------------------
+SYMBOLS_FILE="${CACHE_DIR}/symbols.tsv"
+> "$SYMBOLS_FILE"
+
+echo "INFO: Extracting symbols..."
+
+if command -v ctags >/dev/null 2>&1; then
+  # Use ctags for precise symbol extraction
+  # --fields=+ne adds line number and end-of-scope — portable across universal-ctags
+  ctags -R --output-format=json \
+    --fields='nkz' \
+    --languages=Python,JavaScript,TypeScript,Go,Rust,Java,C,C++ \
+    -f - "$REPO_PATH" 2>/dev/null \
+  | grep -v '^!' \
+  | while IFS= read -r line; do
+      # Parse JSON output from universal-ctags. Portable (non-PCRE) extraction —
+      # grep -oP is not supported by Git Bash's grep build on Windows, so use a
+      # bash regex instead of a lookbehind.
+      if [[ "$line" =~ \"name\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
+        name="${BASH_REMATCH[1]}"
+      else
+        name=""
+      fi
+      if [[ "$line" =~ \"path\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
+        path="${BASH_REMATCH[1]}"
+      else
+        path=""
+      fi
+      if [[ "$line" =~ \"line\"[[:space:]]*:[[:space:]]*([0-9]+) ]]; then
+        line_num="${BASH_REMATCH[1]}"
+      else
+        line_num="0"
+      fi
+      if [[ "$line" =~ \"kind\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
+        kind="${BASH_REMATCH[1]}"
+      else
+        kind="unknown"
+      fi
+      if [[ -n "$name" && -n "$path" ]]; then
+        echo -e "${name}\t${path}\t${line_num}\t${kind}"
+      fi
+    done >> "$SYMBOLS_FILE" 2>/dev/null || true
+fi
+
+# Fallback: grep-based extraction for Python functions/classes
+if [[ ! -s "$SYMBOLS_FILE" ]] || ! command -v ctags >/dev/null 2>&1; then
+  echo "INFO: Falling back to grep-based symbol extraction"
+
+  # Python: functions and classes
+  find "$REPO_PATH" -name "*.py" -not -path "*/.git/*" -not -path "*/node_modules/*" \
+    -not -path "*/__pycache__/*" 2>/dev/null | while read -r f; do
+    grep -n "^def \|^    def \|^class " "$f" 2>/dev/null | while IFS=: read -r lnum content; do
+      # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
+      # grep build on Windows, so use a bash regex instead of a lookbehind.
+      if [[ "$content" =~ (def|class)[[:space:]]+([A-Za-z_][A-Za-z0-9_]*) ]]; then
+        name="${BASH_REMATCH[2]}"
+      else
+        name=""
+      fi
+      kind=$(echo "$content" | grep -q "^def \|    def " && echo "function" || echo "class")
+      rel_path="${f#$REPO_PATH/}"
+      [[ -n "$name" ]] && echo -e "${name}\t${rel_path}\t${lnum}\t${kind}"
+    done || true
+  done >> "$SYMBOLS_FILE" 2>/dev/null || true
+
+  # JavaScript/TypeScript: functions and classes
+  find "$REPO_PATH" \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" \) \
+    -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null | while read -r f; do
+    grep -n "^export function \|^function \|^export class \|^class \|^const .* = \(function\|async function\|() =>\)" \
+      "$f" 2>/dev/null | while IFS=: read -r lnum content; do
+      # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
+      # grep build on Windows, so use a bash regex instead of lookbehind/lookahead.
+      if [[ "$content" =~ (function|class)[[:space:]]+([A-Za-z_][A-Za-z0-9_]*) ]]; then
+        name="${BASH_REMATCH[2]}"
+      elif [[ "$content" =~ const[[:space:]]+([A-Za-z_][A-Za-z0-9_]*)[[:space:]]*= ]]; then
+        name="${BASH_REMATCH[1]}"
+      else
+        name=""
+      fi
+      rel_path="${f#$REPO_PATH/}"
+      [[ -n "$name" ]] && echo -e "${name}\t${rel_path}\t${lnum}\tfunction"
+    done || true
+  done >> "$SYMBOLS_FILE" 2>/dev/null || true
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2: Import graph extraction
+# ---------------------------------------------------------------------------
+IMPORTS_FILE="${CACHE_DIR}/imports.tsv"
+> "$IMPORTS_FILE"
+
+echo "INFO: Building import graph..."
+
+# Python imports
+find "$REPO_PATH" -name "*.py" -not -path "*/.git/*" -not -path "*/__pycache__/*" \
+  2>/dev/null | while read -r f; do
+  rel_path="${f#$REPO_PATH/}"
+  grep -n "^import \|^from " "$f" 2>/dev/null | while IFS=: read -r lnum content; do
+    # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
+    # grep build on Windows, so use a bash regex instead of lookbehind.
+    if [[ "$content" =~ ^from[[:space:]]+([^[:space:]]+)[[:space:]]+import[[:space:]]+(.+)$ ]]; then
+      module="${BASH_REMATCH[1]}"
+      symbol="${BASH_REMATCH[2]}"
+    elif [[ "$content" =~ ^import[[:space:]]+([^[:space:]]+) ]]; then
+      module="${BASH_REMATCH[1]}"
+      symbol=""
+    else
+      module=""
+      symbol=""
+    fi
+    [[ -n "$module" ]] && echo -e "${rel_path}\t${module}\t${symbol}"
+  done || true
+done >> "$IMPORTS_FILE" 2>/dev/null || true
+
+# JavaScript/TypeScript imports
+find "$REPO_PATH" \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" \) \
+  -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null | while read -r f; do
+  rel_path="${f#$REPO_PATH/}"
+  grep -n "^import \|^} from \|require(" "$f" 2>/dev/null | while IFS=: read -r lnum content; do
+    # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
+    # grep build on Windows, so use a bash regex instead of lookbehind/lookahead.
+    if [[ "$content" =~ from[[:space:]]*[\'\"]([^\'\"]+)[\'\"] ]]; then
+      module="${BASH_REMATCH[1]}"
+    elif [[ "$content" =~ require\([[:space:]]*[\'\"]([^\'\"]+)[\'\"] ]]; then
+      module="${BASH_REMATCH[1]}"
+    else
+      module=""
+    fi
+    [[ -n "$module" ]] && echo -e "${rel_path}\t${module}\t"
+  done || true
+done >> "$IMPORTS_FILE" 2>/dev/null || true
+
+# Go imports
+find "$REPO_PATH" -name "*.go" -not -path "*/.git/*" 2>/dev/null | while read -r f; do
+  rel_path="${f#$REPO_PATH/}"
+  grep -n '"[^"]*"' "$f" 2>/dev/null | grep -v "//\|fmt.Print\|errors.New" | while IFS=: read -r lnum content; do
+    # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
+    # grep build on Windows, so use a bash regex instead of lookbehind/lookahead.
+    if [[ "$content" =~ \"([^\"]+)\" ]]; then
+      module="${BASH_REMATCH[1]}"
+    else
+      module=""
+    fi
+    [[ -n "$module" ]] && echo -e "${rel_path}\t${module}\t"
+  done || true
+done >> "$IMPORTS_FILE" 2>/dev/null || true
+
+# ---------------------------------------------------------------------------
+# Step 3: Caller graph (callee → callers mapping)
+# ---------------------------------------------------------------------------
+CALLERS_FILE="${CACHE_DIR}/callers.tsv"
+> "$CALLERS_FILE"
+
+echo "INFO: Building caller graph..."
+
+# For each symbol, find files that call it (grep for usage)
+if [[ -s "$SYMBOLS_FILE" ]]; then
+  # Process a sample of top symbols (cap at 500 to avoid timeout)
+  head -500 "$SYMBOLS_FILE" | while IFS=$'\t' read -r sym_name sym_file sym_line sym_kind; do
+    # Skip very short or generic names to avoid false positives
+    if [[ ${#sym_name} -lt 3 ]]; then continue; fi
+    # Search for callers (function calls, not definitions)
+    find "$REPO_PATH" -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \
+      -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
+      -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null | \
+      xargs grep -l "\b${sym_name}(" 2>/dev/null | while read -r caller_file; do
+        rel_caller="${caller_file#$REPO_PATH/}"
+        # Skip the file where the symbol is defined
+        if [[ "$rel_caller" == "$sym_file" ]]; then continue; fi
+        caller_line=$(grep -n "\b${sym_name}(" "$caller_file" 2>/dev/null | head -1 | cut -d: -f1 || echo "0")
+        echo -e "${sym_name}\t${rel_caller}\t${caller_line}"
+      done || true
+      # ^ `xargs grep -l` returning 1 (zero callers found for this symbol) propagates
+      # through `pipefail` into this `while` compound statement, which is subject to
+      # `set -e` — guard it here so one symbol with no callers doesn't abort the
+      # remaining symbols in the outer loop.
+  done >> "$CALLERS_FILE" 2>/dev/null || true
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4: File-to-domain mapping
+# ---------------------------------------------------------------------------
+DOMAIN_FILE="${CACHE_DIR}/file_domain.tsv"
+> "$DOMAIN_FILE"
+
+echo "INFO: Building file-domain map..."
+
+# Read forge.yaml domain hints if available
+FORGE_YAML="${REPO_PATH}/forge.yaml"
+declare -A DOMAIN_PATTERNS
+DOMAIN_PATTERNS=(
+  ["commands"]="pipeline-commands"
+  ["scripts"]="pipeline-scripts"
+  ["services/api"]="api"
+  ["services/worker"]="worker"
+  ["web/src/app/billing"]="billing"
+  ["web/src/app/auth"]="auth"
+  ["services/api/auth"]="auth"
+  ["services/api/billing"]="billing"
+  ["services/api/db"]="database"
+  ["migrations"]="database"
+  [".github/workflows"]="ci-cd"
+  ["infra"]="infrastructure"
+  ["web/src"]="frontend"
+)
+
+# Read key_paths from forge.yaml if present (override defaults)
+if [[ -f "$FORGE_YAML" ]]; then
+  # Simple key_paths extraction — reads "domain: [patterns]" blocks under review.key_paths
+  while IFS=: read -r key val; do
+    key=$(echo "$key" | tr -d ' ')
+    val=$(echo "$val" | tr -d ' "')
+    if [[ -n "$key" && -n "$val" ]]; then
+      DOMAIN_PATTERNS["$val"]="$key"
+    fi
+  done < <(grep -A2 'key_paths:' "$FORGE_YAML" 2>/dev/null | grep '^\s*\w\+:' | head -20 || true)
+fi
+
+# Map each file to its domain
+find "$REPO_PATH" -type f -not -path "*/.git/*" -not -path "*/node_modules/*" \
+  -not -path "*/__pycache__/*" -not -path "*/.forge/*" 2>/dev/null | while read -r f; do
+  rel_path="${f#$REPO_PATH/}"
+  domain="unclassified"
+  for pattern in "${!DOMAIN_PATTERNS[@]}"; do
+    if [[ "$rel_path" == $pattern* ]]; then
+      domain="${DOMAIN_PATTERNS[$pattern]}"
+      break
+    fi
+  done
+  echo -e "${rel_path}\t${domain}"
+done >> "$DOMAIN_FILE" 2>/dev/null || true
+
+# ---------------------------------------------------------------------------
+# Step 5: Write index manifest
+# ---------------------------------------------------------------------------
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ")
+SYMBOL_COUNT=$(wc -l < "$SYMBOLS_FILE" 2>/dev/null || echo 0)
+IMPORT_COUNT=$(wc -l < "$IMPORTS_FILE" 2>/dev/null || echo 0)
+CALLER_COUNT=$(wc -l < "$CALLERS_FILE" 2>/dev/null || echo 0)
+FILE_COUNT=$(wc -l < "$DOMAIN_FILE" 2>/dev/null || echo 0)
+
+# Sanity check: if source files that should have produced symbols/imports were
+# found, but extraction came back empty, a loop was truncated somewhere above
+# (or a tool like grep -oP is unavailable/incompatible on this platform) — flag
+# it instead of letting "Index built successfully" silently paper over data loss.
+SRC_FILE_COUNT=$(find "$REPO_PATH" \( -name "*.py" -o -name "*.js" -o -name "*.ts" \
+  -o -name "*.tsx" -o -name "*.jsx" -o -name "*.go" \) -not -path "*/.git/*" \
+  -not -path "*/node_modules/*" -not -path "*/__pycache__/*" 2>/dev/null | wc -l | tr -d ' ')
+INDEX_TRUNCATED=0
+if [[ "$SRC_FILE_COUNT" -gt 0 && "$SYMBOL_COUNT" -eq 0 ]]; then
+  INDEX_TRUNCATED=1
+  echo "WARN: 0 symbols extracted despite ${SRC_FILE_COUNT} matching source file(s) found." >&2
+  echo "WARN: Extraction may have been truncated by a shell/grep failure, or ctags/grep tooling is unavailable/incompatible on this platform." >&2
+fi
+
+cat > "${CACHE_DIR}/index.json" << INDEX_EOF
+{
+  "schema_version": "1",
+  "head_sha": "${HEAD_SHA}",
+  "built_at": "${TIMESTAMP}",
+  "repo_path": "${REPO_PATH}",
+  "cache_dir": "${CACHE_DIR}",
+  "stats": {
+    "symbols": ${SYMBOL_COUNT},
+    "imports": ${IMPORT_COUNT},
+    "callers": ${CALLER_COUNT},
+    "files": ${FILE_COUNT},
+    "truncated": $([[ "$INDEX_TRUNCATED" -eq 1 ]] && echo "true" || echo "false")
+  },
+  "files": {
+    "symbols": "${CACHE_DIR}/symbols.tsv",
+    "imports": "${CACHE_DIR}/imports.tsv",
+    "callers": "${CACHE_DIR}/callers.tsv",
+    "file_domain": "${CACHE_DIR}/file_domain.tsv"
+  },
+  "query_usage": {
+    "symbol_lookup": "scripts/code-index.sh query --symbol <name> --repo-path <path>",
+    "caller_lookup": "scripts/code-index.sh query --callers <name> --repo-path <path>",
+    "importer_lookup": "scripts/code-index.sh query --importers <file> --repo-path <path>",
+    "domain_lookup": "scripts/code-index.sh query --domain <label> --repo-path <path>"
+  }
+}
+INDEX_EOF
+
+if [[ "$INDEX_TRUNCATED" -eq 1 ]]; then
+  echo "WARN: Index build completed but looks truncated — see WARN lines above."
+else
+  echo "INFO: Index built successfully"
+fi
+echo "INFO:   Symbols:  ${SYMBOL_COUNT}"
+echo "INFO:   Imports:  ${IMPORT_COUNT}"
+echo "INFO:   Callers:  ${CALLER_COUNT}"
+echo "INFO:   Files:    ${FILE_COUNT}"
+echo "INFO:   Cache:    ${CACHE_DIR}"
+echo ""
+cat "${CACHE_DIR}/index.json"

package/scripts/conformance-check.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * scripts/conformance-check.mjs — FORGE Annotation Protocol conformance suite (#1293)
+ *
+ * Validates FORGE annotation output (from any producer — Claude Code, Codex adapter,
+ * Cursor, Aider, or fixtures) against the FORGE Annotation Protocol v1.0 as defined
+ * in docs/spec/forge-protocol-v1.md.
+ *
+ * This script is the conformance surface referenced in #1293: once run against
+ * real or fixture-captured Codex-adapter-produced annotations, it closes the loop
+ * on the "second implementation, not just a second document" vendor-neutrality claim.
+ *
+ * Usage:
+ *   node scripts/conformance-check.mjs <input.md|input.json>   # validate from file
+ *   node scripts/conformance-check.mjs -                       # read comment bodies from stdin (one per line JSON or raw text)
+ *   echo '<!-- FORGE:INVESTIGATOR -->\n...' | node scripts/conformance-check.mjs
+ *
+ * Input format:
+ *   - A plain text file containing one or more FORGE annotation blocks (as they would
+ *     appear in a GitHub issue/PR comment body)
+ *   - A JSON file: array of comment body strings (e.g. from `gh api .../comments --jq '[.[].body]'`)
+ *   - stdin: same formats
+ *
+ * Exit codes:
+ *   0 = all annotations conform (or only unknown types found — tolerant by spec §7.2)
+ *   1 = one or more conformance violations found
+ *   2 = input parse error
+ *
+ * Conformance rules:
+ *   This script does NOT reimplement the FORGE Annotation Protocol parsing/validation
+ *   rules itself. It delegates entirely to the spec reference implementation,
+ *   `@forgedock/protocol` (packages/protocol/src/{parse,validate,types}.js), which
+ *   implements §3.1 (opening tag format), §3.2 (completion sentinels), §3.3 (partial
+ *   sentinels), §4.x (per-type required fields and enum values), and §7.2 (tolerant
+ *   handling of unknown/unreserved annotation types). Delegating avoids a second,
+ *   independently-drifting parser (see #1521 — a prior standalone regex here diverged
+ *   from the library and rejected valid `TYPE:COMPLETE` sentinels as new annotations).
+ *
+ *   PARTIAL sentinel exception: `validate()` reports `valid: false` for an annotation
+ *   explicitly marked `:PARTIAL` — that strictness (§3.2 "MUST NOT treat as complete")
+ *   is correct for library consumers deciding whether data is safe to consume, and is
+ *   locked in by packages/protocol/test/validate.test.mjs and fixtures/context-partial.json.
+ *   This CLI's pass/fail gate is a narrower question ("should CI exit non-zero for this
+ *   input?") and, consistent with its pre-#1521 behavior, treats an explicit PARTIAL as
+ *   a WARN, not a failure — the producer was honest about the interruption (§3.3). Only
+ *   a fully missing/interrupted sentinel (no COMPLETE, no PARTIAL) fails the exit code.
+ */
+
+import { readFileSync } from "fs";
+import { parse, validate } from "../packages/protocol/src/index.js";
+import { SentinelState } from "../packages/protocol/src/types.js";
+
+// ── Line-number recovery ──────────────────────────────────────────────────────
+//
+// parse() returns ParsedAnnotation objects ({ type, raw, body, ... }) without a
+// line number — it only needs character-level text, not position, for its own
+// purposes. This script's console output has always reported a 1-indexed line
+// number per annotation, so we recover it here by matching each annotation's
+// opening-tag line against the original comment body, scanning forward from the
+// end of the previous match. Annotations are contiguous in the source (parse()
+// assigns every line from an opening tag onward to that annotation until the
+// next true opening tag), so a single forward-scanning pass is sufficient.
+function withStartLines(commentBody, annotations) {
+  const lines = commentBody.split("\n");
+  let searchFrom = 0;
+  return annotations.map((ann) => {
+    const openingLine = ann.raw.split("\n")[0];
+    let idx = lines.indexOf(openingLine, searchFrom);
+    if (idx === -1) idx = searchFrom;
+    searchFrom = idx + 1;
+    return { ...ann, startLine: idx + 1 };
+  });
+}
+
+// ── Input parsing ─────────────────────────────────────────────────────────────
+
+function parseInput(raw) {
+  // Try JSON array of comment body strings
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[")) {
+    try {
+      const arr = JSON.parse(trimmed);
+      if (Array.isArray(arr)) return arr.map(String);
+    } catch (_) { /* fall through */ }
+  }
+  // Single JSON string
+  if (trimmed.startsWith('"')) {
+    try { return [JSON.parse(trimmed)]; } catch (_) { /* fall through */ }
+  }
+  // Raw text — treat as single comment body
+  return [raw];
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+let raw;
+
+try {
+  if (args.length === 0 || args[0] === "-") {
+    // Read stdin via fd 0 rather than the "/dev/stdin" path — the latter does not
+    // exist on Windows (ENOENT), breaking the piped-stdin mode documented above
+    // despite it being an advertised, supported input mode. Reading fd 0 directly
+    // is the portable idiom and works identically on POSIX. (forge#1594)
+    raw = readFileSync(0, "utf8");
+  } else {
+    raw = readFileSync(args[0], "utf8");
+  }
+} catch (e) {
+  console.error(`conformance-check: cannot read input — ${e.message}`);
+  process.exit(2);
+}
+
+const commentBodies = parseInput(raw);
+if (!commentBodies.length) {
+  console.error("conformance-check: no comment bodies to validate");
+  process.exit(2);
+}
+
+let totalAnnotations = 0;
+let totalViolations = 0;
+let totalWarnings = 0;
+
+for (const [idx, body] of commentBodies.entries()) {
+  const parsed = parse(body);
+  if (!parsed.length) continue;
+
+  const annotations = withStartLines(body, parsed);
+
+  for (const ann of annotations) {
+    totalAnnotations++;
+    const { errors, warnings } = validate(ann);
+
+    const prefix = `[comment ${idx + 1}, line ${ann.startLine}] FORGE:${ann.type}`;
+
+    // An explicit PARTIAL sentinel is an honest producer signal (§3.3), not a silent
+    // contract violation — demote validate()'s PARTIAL-specific error out of this CLI's
+    // exit-code tally. validate() already emits an equivalent entry in `warnings` for
+    // PARTIAL annotations, so dropping the error here (rather than re-printing it) avoids
+    // duplicate WARN lines for the same condition. Any other error on the same annotation
+    // (missing required field, bad enum value, etc.) is unaffected and still fails.
+    const hardErrors =
+      ann.sentinelState === SentinelState.PARTIAL
+        ? errors.filter((e) => !/is marked PARTIAL/.test(e))
+        : errors;
+
+    if (hardErrors.length === 0 && warnings.length === 0) {
+      console.log(`PASS  ${prefix}`);
+    } else {
+      for (const v of hardErrors) {
+        console.error(`FAIL  ${prefix} — ${v}`);
+        totalViolations++;
+      }
+      for (const w of warnings) {
+        console.warn(`WARN  ${prefix} — ${w}`);
+        totalWarnings++;
+      }
+    }
+  }
+}
+
+console.log(`\nSummary: ${totalAnnotations} annotation(s), ${totalViolations} violation(s), ${totalWarnings} warning(s)`);
+
+if (totalAnnotations === 0) {
+  console.log("No FORGE annotations found in input.");
+}
+
+process.exit(totalViolations > 0 ? 1 : 0);