forgedock 1.0.17 → 1.0.19

package/scripts/validate-spec-graph.sh

@@ -0,0 +1,423 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# validate-spec-graph.sh — Self-consistency validator over the Spec Knowledge Graph
+#
+# Consumes the spec knowledge graph produced by `build-spec-graph.mjs`
+# (`.forgedock/graph/spec-graph.json`) and reports drift that is invisible in a
+# ~1.2 MB prose spec corpus. Three classes of inconsistency are checked:
+#
+#   1. Orphan annotations (SOFT — warn)
+#        FORGE:* markers that are WRITTEN but never READ, or READ but never
+#        WRITTEN. These are usually intentional (a one-sided handshake) but
+#        worth a periodic triage. Isolated inline doc-scaffolding markers
+#        (e.g. FORGE:DISPATCHER, FORGE:PHASE_COMPLETE) are reported as INFO
+#        only — they are prose annotations, never posted via `gh comment`.
+#
+#   2. Dangling cross-refs (HARD — fail)
+#        A spec invokes `Skill(skill="X")` where X does not resolve to a real
+#        command/sub-phase node. The graph builder silently DROPS unresolved
+#        Skill/script/devdoc references (it only emits an edge when the target
+#        exists), so this check scans `commands/**/*.md` directly rather than
+#        querying graph edges.
+#
+#   3. Broken label transitions (HARD — fail)
+#        A `workflow:*` label node that is set by NO command (no incoming
+#        TRANSITIONS edge from any `--add-label`). Also surfaces (as INFO) the
+#        add/remove asymmetry where a label is `--remove-label`-d but never
+#        `--add-label`-ed, which signals a state-machine gap.
+#
+# Exit codes:
+#   0  no HARD inconsistencies (SOFT warnings / INFO may still be printed),
+#      or --soft was passed (warn-only mode)
+#   1  one or more HARD inconsistencies (dangling refs, broken transitions),
+#      or a usage / dependency error
+#
+# Usage:
+#   validate-spec-graph.sh [--soft] [--graph <path>] [--root <dir>] [--quiet] [--json] [-h|--help]
+#
+# Flags:
+#   --soft          Warn-only mode: report HARD findings but exit 0 anyway.
+#                   Used when first wiring into CI so the documented baseline
+#                   orphans/refs do not break the build before triage.
+#   --graph <path>  Validate a specific graph JSON (default:
+#                   <repo>/.forgedock/graph/spec-graph.json). If the default is
+#                   absent (it is gitignored), the graph is auto-built on the
+#                   fly via build-spec-graph.mjs — no committed graph required.
+#   --root <dir>    Repo root to scan for Skill() refs and to auto-build from
+#                   (default: parent of this script's dir).
+#   --quiet         Suppress the human-readable report; print only the summary
+#                   line (and set the exit code).
+#   --json          Emit findings as a single JSON object on stdout instead of
+#                   the human-readable report.
+#   -h | --help     Show this help.
+#
+# This is a UNIVERSAL-tier script (ships with the npm package). It is read-only:
+# it never mutates the repo or the committed graph (it only writes a temp graph
+# under $TMPDIR when it must auto-build, removed on exit). See
+# devdocs/project/architecture.md for the scripts-layer precedence model and
+# docs/spec-graph-schema.md for the graph schema.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Paths & dependency checks
+# ---------------------------------------------------------------------------
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+BUILDER="$SCRIPT_DIR/build-spec-graph.mjs"
+DEFAULT_GRAPH="$REPO_ROOT/.forgedock/graph/spec-graph.json"
+
+# Exported so per-repo adaptive scripts can delegate (see architecture.md).
+export FORGEDOCK_SCRIPTS="$SCRIPT_DIR"
+export FORGEDOCK_HOME="$REPO_ROOT"
+
+# Inline doc-scaffolding annotations: real markers in the corpus that are used
+# to annotate the spec prose itself (HTML comments inside the spec body), never
+# posted via `gh ... comment --body`. They legitimately have neither WRITES nor
+# READS edges, so they must NOT be flagged as orphans. Reported as INFO only.
+#
+# Keep this list sorted. Add a marker here only if it is a prose-scaffolding
+# annotation by design (a `<!-- FORGE:X -->` that documents the spec, not a
+# pipeline handshake posted to an issue/PR).
+SCAFFOLDING_ANNOTATIONS=(
+  "FORGE:ANCESTRY_FAILED"
+  "FORGE:DISPATCHER"
+  "FORGE:GATE_FAILED"
+  "FORGE:JSONL_PARSER_UTIL"
+  "FORGE:MILESTONE_INDEX"
+  "FORGE:PHASE"
+  "FORGE:PHASE_COMPLETE"
+  "FORGE:PRIOR_GIST"
+  "FORGE:PUSH_BLOCKED"
+  "FORGE:PUSH_FAILED"
+  "FORGE:REVIEW_STARTED"
+  "FORGE:TYPE"
+)
+
+print_help() {
+  # Echo the leading comment block (between the shebang and `set -euo`).
+  sed -n '3,/^set -euo pipefail/p' "${BASH_SOURCE[0]}" \
+    | sed '$d' \
+    | sed 's/^# \{0,1\}//'
+}
+
+die() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+require_dep() {
+  command -v "$1" >/dev/null 2>&1 || die "required dependency '$1' not found on PATH"
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+SOFT=0
+QUIET=0
+JSON=0
+GRAPH_PATH=""
+ROOT_OVERRIDE=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -h|--help)
+      print_help
+      exit 0
+      ;;
+    --soft)
+      SOFT=1
+      shift
+      ;;
+    --quiet)
+      QUIET=1
+      shift
+      ;;
+    --json)
+      JSON=1
+      shift
+      ;;
+    --graph)
+      [ "$#" -ge 2 ] || die "--graph requires a path"
+      GRAPH_PATH="$2"
+      shift 2
+      ;;
+    --root)
+      [ "$#" -ge 2 ] || die "--root requires a path"
+      ROOT_OVERRIDE="$2"
+      shift 2
+      ;;
+    -*)
+      die "unknown flag: $1 (try --help)"
+      ;;
+    *)
+      die "unexpected argument: $1 (this validator takes no positionals; try --help)"
+      ;;
+  esac
+done
+
+if [ -n "$ROOT_OVERRIDE" ]; then
+  REPO_ROOT="$ROOT_OVERRIDE"
+  DEFAULT_GRAPH="$REPO_ROOT/.forgedock/graph/spec-graph.json"
+fi
+
+require_dep jq
+
+# ---------------------------------------------------------------------------
+# Resolve the graph JSON (auto-build if absent — the graph is gitignored)
+# ---------------------------------------------------------------------------
+
+GRAPH=""
+TMP_GRAPH=""
+
+cleanup() {
+  [ -n "$TMP_GRAPH" ] && [ -f "$TMP_GRAPH" ] && rm -f "$TMP_GRAPH" || true
+}
+trap cleanup EXIT
+
+resolve_graph() {
+  if [ -n "$GRAPH_PATH" ]; then
+    [ -f "$GRAPH_PATH" ] || die "graph file not found: $GRAPH_PATH"
+    GRAPH="$GRAPH_PATH"
+    return
+  fi
+  if [ -f "$DEFAULT_GRAPH" ]; then
+    GRAPH="$DEFAULT_GRAPH"
+    return
+  fi
+  # Auto-build to a temp file (the default path is gitignored / may not exist).
+  require_dep node
+  [ -f "$BUILDER" ] || die "graph is absent and builder not found: $BUILDER"
+  TMP_GRAPH="$(mktemp "${TMPDIR:-/tmp}/spec-graph.XXXXXX.json")"
+  if ! node "$BUILDER" --root "$REPO_ROOT" --stdout --quiet >"$TMP_GRAPH" 2>/dev/null; then
+    die "failed to auto-build spec graph via $BUILDER"
+  fi
+  GRAPH="$TMP_GRAPH"
+}
+
+resolve_graph
+
+# Validate the graph document shape early so jq filters can assume it.
+jq -e '.graph.nodes and .graph.edges' "$GRAPH" >/dev/null 2>&1 \
+  || die "not a valid spec-graph document (missing .graph.nodes/.graph.edges): $GRAPH"
+
+# ---------------------------------------------------------------------------
+# Findings accumulation
+#   Each finding is one line: "<SEVERITY>\t<CLASS>\t<message>"
+#   SEVERITY in {HARD, SOFT, INFO}. Collected then rendered/summarized.
+# ---------------------------------------------------------------------------
+
+FINDINGS=""
+
+add_finding() {
+  # add_finding <severity> <class> <message>
+  FINDINGS="${FINDINGS}${1}"$'\t'"${2}"$'\t'"${3}"$'\n'
+}
+
+# ---------------------------------------------------------------------------
+# Check 1: Orphan annotations
+# ---------------------------------------------------------------------------
+
+check_orphans() {
+  # written-never-read and read-never-written, computed from graph edges.
+  # Emits one finding per annotation. Scaffolding markers (no read AND no write)
+  # are downgraded to INFO via the allowlist; any non-allowlisted isolated
+  # marker is still surfaced (as SOFT) so new scaffolding gets curated.
+  local scaffold_json
+  scaffold_json="$(printf '%s\n' "${SCAFFOLDING_ANNOTATIONS[@]}" | jq -R . | jq -sc .)"
+
+  # Produce TSV rows: <kind>\t<ann-name> where kind is one of:
+  #   WRITTEN_NEVER_READ | READ_NEVER_WRITTEN | ISOLATED_SCAFFOLD | ISOLATED_UNKNOWN
+  local rows
+  rows="$(jq -r --argjson scaffold "$scaffold_json" '
+    .graph as $g
+    | ([$g.edges[] | select(.type=="WRITES") | .to]) as $written
+    | ([$g.edges[] | select(.type=="READS")  | .to]) as $read
+    | $g.nodes[]
+    | select(.type=="annotation")
+    | .id as $id | (.name) as $name
+    | ($written | index($id) != null) as $w
+    | ($read    | index($id) != null) as $r
+    | if ($w and ($r|not)) then "WRITTEN_NEVER_READ\t\($name)"
+      elif (($w|not) and $r) then "READ_NEVER_WRITTEN\t\($name)"
+      elif (($w|not) and ($r|not)) then
+        (if ($scaffold | index($name)) then "ISOLATED_SCAFFOLD\t\($name)"
+         else "ISOLATED_UNKNOWN\t\($name)" end)
+      else empty end
+  ' "$GRAPH")"
+
+  local kind name
+  while IFS=$'\t' read -r kind name; do
+    [ -n "$kind" ] || continue
+    case "$kind" in
+      WRITTEN_NEVER_READ)
+        add_finding SOFT orphan-annotation "$name is WRITTEN but never READ by any spec." ;;
+      READ_NEVER_WRITTEN)
+        add_finding SOFT orphan-annotation "$name is READ but never WRITTEN by any spec." ;;
+      ISOLATED_SCAFFOLD)
+        add_finding INFO scaffold-annotation "$name is an inline doc-scaffolding marker (no WRITES/READS edge — expected)." ;;
+      ISOLATED_UNKNOWN)
+        add_finding SOFT orphan-annotation "$name has neither a WRITES nor a READS edge and is not an allowlisted scaffolding marker — triage or add to the allowlist." ;;
+    esac
+  done <<< "$rows"
+}
+
+# ---------------------------------------------------------------------------
+# Check 2: Dangling cross-refs (Skill() targets)
+# ---------------------------------------------------------------------------
+
+check_dangling() {
+  # The builder DROPS unresolved Skill()/script/devdoc refs, so we scan the spec
+  # corpus directly. We match every structured Skill() invocation form —
+  # positional Skill("X"), keyword Skill(skill="X"), and colon Skill(skill: "X")
+  # — with `/`-delimited sub-phases and uppercase/leading-digit targets, kept in
+  # sync with the builder's CONTAINS regex in build-spec-graph.mjs. The quoted
+  # target form keeps this off illustrative filename mentions in prose.
+  local commands_dir="$REPO_ROOT/commands"
+  [ -d "$commands_dir" ] || return 0
+
+  # Set of known command/sub-phase node names (e.g. "work-on", "work-on:build").
+  local known
+  known="$(jq -r '.graph.nodes[] | select(.type=="command" or .type=="sub-phase") | .name' "$GRAPH" | sort -u)"
+
+  # Extract every Skill(skill="X") / Skill(skill='X') target with file+line.
+  # grep -rn over the whole tree (no fixed -A/-m window that could truncate).
+  local hits
+  hits="$(grep -rnoE "Skill\(\s*(skill\s*[:=]\s*)?[\"'][A-Za-z0-9][A-Za-z0-9:_/-]*[\"']" "$commands_dir" 2>/dev/null || true)"
+
+  [ -n "$hits" ] || return 0
+
+  # Illustrative placeholder targets used in Skill() example snippets in prose —
+  # these are documentation stand-ins, never real command references.
+  local placeholder_targets=" X subcommand "
+  local line target relpath
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    # line form: <path>:<lineno>:Skill( ... "X" )
+    relpath="${line%%:*}"
+    relpath="${relpath#"$REPO_ROOT"/}"
+    # Pull the quoted target.
+    target="$(printf '%s' "$line" | grep -oE "[\"'][A-Za-z0-9][A-Za-z0-9:_/-]*[\"']" | head -1 | tr -d "\"'")"
+    [ -n "$target" ] || continue
+    # Normalize the `/`-delimited sub-phase form (work-on/review) to the graph's
+    # `:` form (work-on:review) before resolution — kept in sync with the builder.
+    target="${target//\//:}"
+    # Skip known illustrative placeholders.
+    case "$placeholder_targets" in *" $target "*) continue ;; esac
+    if ! printf '%s\n' "$known" | grep -qxF "$target"; then
+      add_finding HARD dangling-ref "$relpath references Skill(\"$target\") but no command/sub-phase node \"$target\" exists in the graph."
+    fi
+  done <<< "$hits"
+}
+
+# ---------------------------------------------------------------------------
+# Check 3: Broken label transitions
+# ---------------------------------------------------------------------------
+
+check_transitions() {
+  # A label node set by no --add-label TRANSITIONS edge is a broken transition.
+  local orphan_labels
+  orphan_labels="$(jq -r '
+    .graph as $g
+    | ([$g.edges[] | select(.type=="TRANSITIONS") | .to]) as $set
+    | $g.nodes[] | select(.type=="label")
+    | select(.id as $id | ($set | index($id)) == null)
+    | .name
+  ' "$GRAPH")"
+
+  local lbl
+  while IFS= read -r lbl; do
+    [ -n "$lbl" ] || continue
+    add_finding HARD broken-transition "Label $lbl is defined/referenced but set by NO command (no --add-label transition) — state-machine gap."
+  done <<< "$orphan_labels"
+
+  # Add/remove asymmetry: labels that are --remove-label-d but never
+  # --add-label-ed anywhere in the corpus. INFO — usually a defensive removal,
+  # but flags a potential dead state.
+  local commands_dir="$REPO_ROOT/commands"
+  [ -d "$commands_dir" ] || return 0
+
+  local added removed
+  added="$(jq -r '.graph.edges[] | select(.type=="TRANSITIONS") | .to | sub("^label:"; "")' "$GRAPH" | sort -u)"
+  removed="$(grep -rhoE -- "--remove-label[[:space:]]+[\"'][^\"']*[\"']" "$commands_dir" 2>/dev/null \
+    | grep -oE 'workflow:[a-z][a-z0-9-]*' | sort -u || true)"
+
+  local r
+  while IFS= read -r r; do
+    [ -n "$r" ] || continue
+    if ! printf '%s\n' "$added" | grep -qxF "$r"; then
+      add_finding INFO transition-asymmetry "Label $r is removed (--remove-label) but never added (--add-label) by any command."
+    fi
+  done <<< "$removed"
+}
+
+# ---------------------------------------------------------------------------
+# Run checks
+# ---------------------------------------------------------------------------
+
+check_orphans
+check_dangling
+check_transitions
+
+# Sort findings deterministically (severity rank, then class, then message).
+sev_rank() {
+  case "$1" in
+    HARD) echo 0 ;;
+    SOFT) echo 1 ;;
+    INFO) echo 2 ;;
+    *)    echo 9 ;;
+  esac
+}
+
+SORTED_FINDINGS="$(printf '%s' "$FINDINGS" \
+  | awk -F'\t' 'NF>=3 { r=($1=="HARD"?0:($1=="SOFT"?1:($1=="INFO"?2:9))); print r"\t"$0 }' \
+  | sort -t$'\t' -k1,1n -k3,3 -k4,4 \
+  | cut -f2-)"
+
+HARD_COUNT="$(printf '%s\n' "$SORTED_FINDINGS" | awk -F'\t' 'NF>=3 && $1=="HARD"' | grep -c . || true)"
+SOFT_COUNT="$(printf '%s\n' "$SORTED_FINDINGS" | awk -F'\t' 'NF>=3 && $1=="SOFT"' | grep -c . || true)"
+INFO_COUNT="$(printf '%s\n' "$SORTED_FINDINGS" | awk -F'\t' 'NF>=3 && $1=="INFO"' | grep -c . || true)"
+
+# ---------------------------------------------------------------------------
+# Render
+# ---------------------------------------------------------------------------
+
+if [ "$JSON" -eq 1 ]; then
+  printf '%s\n' "$SORTED_FINDINGS" \
+    | awk -F'\t' 'NF>=3 { print $1"\t"$2"\t"$3 }' \
+    | jq -R -s --argjson hard "$HARD_COUNT" --argjson soft "$SOFT_COUNT" --argjson info "$INFO_COUNT" '
+        split("\n")
+        | map(select(length>0) | split("\t") | {severity: .[0], class: .[1], message: .[2]})
+        | { summary: {hard: $hard, soft: $soft, info: $info}, findings: . }
+      '
+elif [ "$QUIET" -eq 0 ]; then
+  echo "Spec graph self-consistency report"
+  echo "  graph: $GRAPH"
+  echo ""
+  if [ -z "$SORTED_FINDINGS" ]; then
+    echo "  (no findings — graph is internally consistent)"
+  else
+    printf '%s\n' "$SORTED_FINDINGS" \
+      | awk -F'\t' 'NF>=3 { printf "  [%-4s] %-22s %s\n", $1, $2, $3 }'
+  fi
+  echo ""
+fi
+
+if [ "$QUIET" -eq 0 ] && [ "$JSON" -eq 0 ]; then
+  echo "Summary: ${HARD_COUNT} hard, ${SOFT_COUNT} soft, ${INFO_COUNT} info"
+elif [ "$QUIET" -eq 1 ]; then
+  echo "spec-graph-validate: ${HARD_COUNT} hard, ${SOFT_COUNT} soft, ${INFO_COUNT} info"
+fi
+
+# ---------------------------------------------------------------------------
+# Exit code
+# ---------------------------------------------------------------------------
+
+if [ "$HARD_COUNT" -gt 0 ] && [ "$SOFT" -eq 0 ]; then
+  exit 1
+fi
+exit 0

package/templates/workflows/forgedock-review.yml

@@ -0,0 +1,96 @@
+# ForgeDock CI Review — Workflow Template
+#
+# Copy this file to .github/workflows/forgedock-review.yml in your repository
+# to enable automatic AI-powered PR review on every pull request.
+#
+# Prerequisites:
+#   1. Add ANTHROPIC_API_KEY as a repository secret (Settings > Secrets > Actions)
+#   2. Ensure Claude Code is installed: https://docs.anthropic.com/en/docs/claude-code
+#   3. ForgeDock must be installed in the repo running the pipeline (npx forgedock)
+#
+# Security:
+#   - ANTHROPIC_API_KEY is ONLY passed via the env: block — never echoed or logged
+#   - GITHUB_TOKEN is scoped to this workflow run only
+#   - Review findings are posted as PR comments, not stored in workflow logs
+#
+# Fork PR limitation:
+#   - pull_request events from forks do NOT have access to repository secrets
+#   - External contributors' PRs will not trigger this workflow automatically
+#   - To review fork PRs, see the pull_request_target alternative below (with security caveats)
+#
+# See docs/CI.md for full setup guide, customization options, and troubleshooting.
+
+name: ForgeDock PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+# Minimum permissions required for ForgeDock review:
+#   contents: read     — checkout code and read files
+#   pull-requests: write — post review findings as PR comments
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  forgedock-review:
+    name: AI PR Review
+    runs-on: ubuntu-latest
+
+    # Skip review for bot-authored PRs (dependabot, release bots, etc.)
+    # Remove this condition if you want all PRs reviewed.
+    if: github.actor != 'dependabot[bot]' && github.actor != 'github-actions[bot]'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # Fetch full history so /review-pr can access git blame and log
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: '20'
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+        # Installs claude CLI for non-interactive (headless) execution
+
+      - name: Install ForgeDock
+        run: npx forgedock install
+        # Symlinks ForgeDock commands into ~/.claude/commands/
+        # This makes /review-pr available to claude --print
+
+      - name: Run ForgeDock PR Review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Pass PR number via environment — do not echo secrets in run: scripts
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          claude --print "/review-pr $PR_NUMBER" \
+            --dangerously-skip-permissions
+        # --print runs Claude Code in non-interactive (headless) mode
+        # --dangerously-skip-permissions skips the interactive permission prompt
+        #   required for unattended CI execution; safe here because the runner
+        #   is ephemeral and permissions are constrained by the workflow above
+
+      # Optional: set a commit status based on review verdict
+      # Uncomment to enable pass/fail badges on PRs.
+      #
+      # - name: Set Commit Status
+      #   if: always()
+      #   uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+      #   with:
+      #     script: |
+      #       const state = '${{ job.status }}' === 'success' ? 'success' : 'failure';
+      #       await github.rest.repos.createCommitStatus({
+      #         owner: context.repo.owner,
+      #         repo: context.repo.repo,
+      #         sha: context.payload.pull_request.head.sha,
+      #         state: state,
+      #         context: 'ForgeDock Review',
+      #         description: state === 'success' ? 'Review complete' : 'Review found issues',
+      #       });