@onlooker-community/ecosystem 0.14.0 → 0.15.0

package/plugins/cartographer/scripts/run-audit.sh

@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+# run-audit.sh — Cartographer audit pipeline (5 phases).
+#
+# Intended to run as a detached background process launched by the SessionStart
+# hook. Also called directly by the /cartographer skill (foreground).
+#
+# Phases:
+#   1. discover   — collect all auditable files
+#   2. extract    — per-file content hash (incremental cache key)
+#   3. relate     — contradiction + dead_rule analysis (LLM)
+#   4. synthesize — stale_ref + scope_collision + finding hash computation
+#   5. emit       — persist findings atomically, emit events for new findings
+#
+# Environment:
+#   CARTOGRAPHER_DIR    — state directory (~/.onlooker/cartographer/<project_key>)
+#   CARTOGRAPHER_TRIGGER — "session_start_interval" | "session_start_first_run" | "post_tool_use" | "manual"
+#   CARTOGRAPHER_TARGET_FILE — (optional) single file for targeted post-write audit
+#   CLAUDE_PLUGIN_ROOT  — plugin root directory
+#
+# Invariant: last_audit_at is written ONLY on full successful completion of all
+# phases. Partial runs leave last_audit_at unchanged so the next session retries.
+
+set -uo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-ulid.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-collect.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh"
+
+CARTOGRAPHER_DIR="${CARTOGRAPHER_DIR:?CARTOGRAPHER_DIR must be set}"
+TRIGGER="${CARTOGRAPHER_TRIGGER:-manual}"
+TARGET_FILE="${CARTOGRAPHER_TARGET_FILE:-}"
+REPO_ROOT="${CARTOGRAPHER_REPO_ROOT:-$(pwd)}"
+AUDIT_ID=$(cartographer_ulid)
+START_TS=$(date +%s)
+
+_TIMEOUT_CMD=$(command -v gtimeout 2>/dev/null || command -v timeout 2>/dev/null || printf 'timeout')
+
+FINDINGS_DIR="$CARTOGRAPHER_DIR/findings"
+DEDUP_DIR="$CARTOGRAPHER_DIR/dedup"
+RUNS_DIR="$CARTOGRAPHER_DIR/runs"
+mkdir -p "$FINDINGS_DIR" "$DEDUP_DIR" "$RUNS_DIR"
+
+PHASES_COMPLETED=()
+PHASES_FAILED=()
+ALL_FINDINGS="[]"
+
+_phase_timeout=$(cartographer_config_phase_timeout)
+_total_timeout=$(cartographer_config_total_timeout)
+log() { printf '[cartographer] %s\n' "$*" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1; }
+[[ "$_total_timeout" -lt $(( _phase_timeout * 3 )) ]] && \
+	log "warning: total_timeout_seconds=${_total_timeout} is less than 3× phase_timeout_seconds=${_phase_timeout}; phases may be killed early"
+_model_extraction=$(cartographer_config_model_extraction)
+_model_synthesis=$(cartographer_config_model_synthesis)
+_max_tokens_extraction=$(cartographer_config_max_output_tokens_extraction)
+_max_tokens_synthesis=$(cartographer_config_max_output_tokens_synthesis)
+_exclude_json=$(cartographer_config_exclude_paths)
+
+emit_safe() {
+	cartographer_emit_event "$1" "$2" 2>>"$CARTOGRAPHER_DIR/audit.log" || true
+}
+
+# ── Phase 1: Discover ──────────────────────────────────────────────────────────
+run_discover() {
+	log "phase=discover starting"
+	local repo_root="$REPO_ROOT"
+
+	if [[ -n "$TARGET_FILE" ]]; then
+		# Targeted post-write audit: only the modified file
+		DISCOVERED_FILES=$(jq -n --arg f "$TARGET_FILE" '[$f]')
+		GLOBAL_FILES="[]"
+	else
+		local raw_files
+		raw_files=$(cartographer_collect_files "$repo_root" "$_exclude_json" 5)
+		DISCOVERED_FILES=$(printf '%s\n' "$raw_files" | grep -v '^$' | jq -R . | jq -s .)
+		local raw_global
+		raw_global=$(cartographer_collect_global_files)
+		GLOBAL_FILES=$(printf '%s\n' "$raw_global" | grep -v '^$' | jq -R . | jq -s .)
+	fi
+
+	local file_count
+	file_count=$(printf '%s' "$DISCOVERED_FILES" | jq 'length')
+	log "phase=discover files=${file_count}"
+	PHASES_COMPLETED+=("discover")
+}
+
+# ── Phase 2: Extract ───────────────────────────────────────────────────────────
+run_extract() {
+	log "phase=extract starting"
+	local cached=0 computed=0
+
+	EXTRACT_CACHE="{}"
+	while IFS= read -r fpath; do
+		[[ -z "$fpath" || ! -f "$fpath" ]] && continue
+		local fhash
+		fhash=$(cartographer_file_content_hash "$fpath") || continue
+		local cache_file="$CARTOGRAPHER_DIR/extracts/${fhash}.json"
+
+		if [[ -f "$cache_file" ]]; then
+			(( cached++ )) || true
+		else
+			mkdir -p "$CARTOGRAPHER_DIR/extracts"
+			printf '{"path":"%s","hash":"%s"}' "$fpath" "$fhash" >"${cache_file}.tmp"
+			mv -f "${cache_file}.tmp" "$cache_file"
+			(( computed++ )) || true
+		fi
+		EXTRACT_CACHE=$(printf '%s' "$EXTRACT_CACHE" \
+			| jq --arg p "$fpath" --arg h "$fhash" '.[$p]=$h')
+	done < <(printf '%s' "$DISCOVERED_FILES" | jq -r '.[]' 2>/dev/null)
+
+	log "phase=extract cached=${cached} computed=${computed}"
+	PHASES_COMPLETED+=("extract")
+}
+
+# ── Phase 3: Relate (contradiction + dead_rule) ────────────────────────────────
+run_relate() {
+	log "phase=relate starting"
+	local findings
+	findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
+		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+		 cartographer_config_load '$REPO_ROOT'
+		 cartographer_analyze_contradiction '$DISCOVERED_FILES' \
+		   '$_model_extraction' '$_max_tokens_extraction' '$_phase_timeout'" \
+		2>>"$CARTOGRAPHER_DIR/audit.log") || {
+		log "phase=relate timeout or error"
+		PHASES_FAILED+=("relate")
+		return 1
+	}
+	RELATE_FINDINGS="${findings:-[]}"
+	local count
+	count=$(printf '%s' "$RELATE_FINDINGS" | jq 'length' 2>/dev/null || printf '0')
+	log "phase=relate findings=${count}"
+	PHASES_COMPLETED+=("relate")
+}
+
+# ── Phase 4: Synthesize (stale_ref + scope_collision + hash) ──────────────────
+run_synthesize() {
+	log "phase=synthesize starting"
+
+	local stale_findings scope_findings
+	stale_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
+		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+		 cartographer_config_load '$REPO_ROOT'
+		 cartographer_analyze_stale_ref '$DISCOVERED_FILES' '$REPO_ROOT' \
+		   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
+		2>>"$CARTOGRAPHER_DIR/audit.log") || stale_findings="[]"
+
+	scope_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
+		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+		 cartographer_config_load '$REPO_ROOT'
+		 cartographer_analyze_scope_collision '$GLOBAL_FILES' '$DISCOVERED_FILES' \
+		   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
+		2>>"$CARTOGRAPHER_DIR/audit.log") || scope_findings="[]"
+
+	# Merge all raw findings
+	local raw_all
+	raw_all=$(jq -n \
+		--argjson relate "${RELATE_FINDINGS:-[]}" \
+		--argjson stale "${stale_findings:-[]}" \
+		--argjson scope "${scope_findings:-[]}" \
+		'$relate + $stale + $scope')
+
+	# Add finding_hash to each finding
+	ALL_FINDINGS="[]"
+	local idx=0
+	while IFS= read -r finding; do
+		[[ -z "$finding" ]] && continue
+		local ftype ffile_a fexcerpt_a ffile_b fexcerpt_b
+		ftype=$(printf '%s' "$finding" | jq -r '.type // "unknown"')
+		ffile_a=$(printf '%s' "$finding" | jq -r '.file_a // ""')
+		fexcerpt_a=$(printf '%s' "$finding" | jq -r '.excerpt_a // ""')
+		ffile_b=$(printf '%s' "$finding" | jq -r '.file_b // ""')
+		fexcerpt_b=$(printf '%s' "$finding" | jq -r '.excerpt_b // ""')
+
+		local fhash
+		fhash=$(cartographer_finding_hash \
+			"$ftype" "$ffile_a" "$fexcerpt_a" "$ffile_b" "$fexcerpt_b")
+
+		local enriched
+		enriched=$(printf '%s' "$finding" \
+			| jq --arg h "$fhash" --arg aid "$AUDIT_ID" \
+			  '. + {"finding_hash":$h,"audit_id":$aid}')
+		ALL_FINDINGS=$(printf '%s' "$ALL_FINDINGS" \
+			| jq --argjson f "$enriched" '. + [$f]')
+		(( idx++ )) || true
+	done < <(printf '%s' "$raw_all" | jq -c '.[]' 2>/dev/null)
+
+	log "phase=synthesize total_findings=$(printf '%s' "$ALL_FINDINGS" | jq 'length')"
+	PHASES_COMPLETED+=("synthesize")
+}
+
+# ── Phase 5: Emit ──────────────────────────────────────────────────────────────
+run_emit() {
+	log "phase=emit starting"
+	local new_count=0 known_count=0
+
+	while IFS= read -r finding; do
+		[[ -z "$finding" ]] && continue
+		local fhash
+		fhash=$(printf '%s' "$finding" | jq -r '.finding_hash')
+		[[ -z "$fhash" ]] && continue
+
+		local finding_file="$FINDINGS_DIR/${fhash}.json"
+		local dedup_sentinel="$DEDUP_DIR/${fhash}"
+		local now
+		now=$(date +%s)
+
+		if [[ -f "$dedup_sentinel" ]]; then
+			# Known finding — update last_seen_at atomically, no bus event
+			(( known_count++ )) || true
+			if [[ -f "$finding_file" ]]; then
+				local updated
+				updated=$(jq --argjson ts "$now" '.last_seen_at=$ts' "$finding_file" 2>/dev/null) || true
+				[[ -n "$updated" ]] && printf '%s\n' "$updated" >"${finding_file}.tmp" \
+					&& mv -f "${finding_file}.tmp" "$finding_file"
+			fi
+		else
+			# New finding — write file atomically, emit bus event, then mark dedup
+			local with_ts
+			with_ts=$(printf '%s' "$finding" \
+				| jq --argjson ts "$now" '. + {"first_seen_at":$ts,"last_seen_at":$ts,"resolved":false}')
+			printf '%s\n' "$with_ts" >"${finding_file}.tmp"
+			mv -f "${finding_file}.tmp" "$finding_file"
+
+			local ftype fseverity ffile_a ffile_b fdesc
+			ftype=$(printf '%s' "$finding" | jq -r '.type // "unknown"')
+			fseverity=$(printf '%s' "$finding" | jq -r '.severity // "warning"')
+			ffile_a=$(printf '%s' "$finding" | jq -r '.file_a // ""')
+			ffile_b=$(printf '%s' "$finding" | jq -r '.file_b // null')
+			fdesc=$(printf '%s' "$finding" | jq -r '.description // ""')
+
+			emit_safe "cartographer.issue.found" "$(jq -n \
+				--arg audit_id "$AUDIT_ID" \
+				--arg finding_hash "$fhash" \
+				--arg finding_type "$ftype" \
+				--arg severity "$fseverity" \
+				--argjson affected_files "$(jq -n --arg a "$ffile_a" --arg b "$ffile_b" \
+					'if $b == "null" or $b == "" then [$a] else [$a,$b] end')" \
+				--arg summary "$fdesc" \
+				'{"audit_id":$audit_id,"finding_hash":$finding_hash,"finding_type":$finding_type,"severity":$severity,"affected_files":$affected_files,"summary":$summary}')"
+
+			touch "$dedup_sentinel"
+			(( new_count++ )) || true
+		fi
+	done < <(printf '%s' "$ALL_FINDINGS" | jq -c '.[]' 2>/dev/null)
+
+	log "phase=emit new=${new_count} known=${known_count}"
+
+	local end_ts duration_ms total_count
+	end_ts=$(date +%s)
+	duration_ms=$(( (end_ts - START_TS) * 1000 ))
+	total_count=$(printf '%s' "$ALL_FINDINGS" | jq 'length')
+
+	# Write run record
+	local run_file="$RUNS_DIR/audit-${AUDIT_ID}.json"
+	jq -n \
+		--arg audit_id "$AUDIT_ID" \
+		--arg trigger "$TRIGGER" \
+		--argjson new_finding_count "$new_count" \
+		--argjson known_finding_count "$known_count" \
+		--argjson total_finding_count "$total_count" \
+		--argjson duration_ms "$duration_ms" \
+		--argjson phases_completed "$(printf '%s\n' "${PHASES_COMPLETED[@]}" | jq -R . | jq -s .)" \
+		--argjson phases_failed "$(printf '%s\n' "${PHASES_FAILED[@]:-}" | jq -R . | jq -s .)" \
+		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"known_finding_count":$known_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms,"phases_completed":$phases_completed,"phases_failed":$phases_failed}' \
+		>"${run_file}.tmp" && mv -f "${run_file}.tmp" "$run_file"
+
+	emit_safe "cartographer.audit.complete" "$(jq -n \
+		--arg audit_id "$AUDIT_ID" \
+		--arg trigger "$TRIGGER" \
+		--argjson new_finding_count "$new_count" \
+		--argjson total_finding_count "$total_count" \
+		--argjson duration_ms "$duration_ms" \
+		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms}')"
+
+	PHASES_COMPLETED+=("emit")
+}
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+main() {
+	log "audit_id=${AUDIT_ID} trigger=${TRIGGER} starting"
+
+	run_discover || { log "discover failed"; exit 1; }
+	run_extract  || { log "extract failed (non-fatal, continuing)"; }
+	run_relate   || { log "relate phase failed"; PHASES_FAILED+=("relate"); }
+	run_synthesize || { log "synthesize phase failed"; PHASES_FAILED+=("synthesize"); }
+	run_emit || { log "emit phase failed"; exit 1; }
+
+	# Only advance last_audit_at for full (non-targeted) audits with no failures.
+	# Targeted post-write audits cover only a single file and must not reset the
+	# interval gate — the next session start would otherwise skip a needed full run.
+	if [[ "${#PHASES_FAILED[@]}" -eq 0 && -z "$TARGET_FILE" ]]; then
+		printf '%d' "$(date +%s)" >"$CARTOGRAPHER_DIR/last_audit_at"
+		log "audit_id=${AUDIT_ID} completed successfully"
+	elif [[ "${#PHASES_FAILED[@]}" -gt 0 ]]; then
+		log "audit_id=${AUDIT_ID} partial — last_audit_at not advanced (failed: ${PHASES_FAILED[*]})"
+	else
+		log "audit_id=${AUDIT_ID} targeted audit complete — last_audit_at not advanced"
+	fi
+}
+
+main "$@"

package/plugins/cartographer/skills/cartographer/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: cartographer
+description: Audit CLAUDE.md, AGENTS.md, and .claude/rules/ instruction files for contradictions, stale references, dead rules, and scope collisions. Runs a full audit in the foreground (with lock). Use when the user explicitly invokes /cartographer, or when they want immediate feedback after editing an instruction file. Supports --scope, --phase, --verbose, --status, and --force flags.
+---
+
+# Cartographer Skill
+
+Cartographer audits the persistent instruction layer of the current project and reports findings in the conversation. The automated SessionStart path handles periodic background audits; this skill is for on-demand use.
+
+## Setup
+
+```bash
+set -uo pipefail
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-collect.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh"
+```
+
+Load config and resolve project context:
+
+```bash
+REPO_ROOT=$(cartographer_project_repo_root "$(pwd)")
+cartographer_config_load "$REPO_ROOT"
+
+if ! cartographer_config_enabled; then
+  echo "Cartographer is disabled. Set cartographer.enabled=true in .claude/settings.json to enable."
+  exit 0
+fi
+
+PROJECT_KEY=$(cartographer_project_key "$(pwd)")
+CARTOGRAPHER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}/cartographer/$PROJECT_KEY"
+mkdir -p "$CARTOGRAPHER_DIR"
+```
+
+## Invocation Modes
+
+### `/cartographer` — full audit
+
+Runs all phases in the foreground. Acquires the audit lock (non-blocking).
+
+```bash
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+
+if ! cartographer_lock_acquire "$LOCK_FILE"; then
+  echo "An audit is already in progress."
+  echo "Run \`/cartographer --status\` to follow it, or \`/cartographer --force\` to restart."
+  exit 0
+fi
+
+export CARTOGRAPHER_DIR CARTOGRAPHER_TRIGGER="manual" ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}"
+bash "$PLUGIN_ROOT/scripts/run-audit.sh"
+cartographer_lock_release "$LOCK_FILE"
+```
+
+After the audit completes, read findings and render them to the conversation grouped by severity (see Rendering section).
+
+### `/cartographer --verbose` — all findings
+
+Shows ALL known findings (new + previously seen) from `$CARTOGRAPHER_DIR/findings/`. Does NOT re-emit bus events — renders to in-conversation output only.
+
+```bash
+echo "## Known Cartographer Findings"
+echo ""
+for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
+  [[ -f "$f" ]] || continue
+  jq -r '"**[\(.severity | ascii_upcase)]** \(.type) — \(.description)\n  Files: \(.file_a // "n/a") / \(.file_b // "n/a")\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null
+done
+```
+
+### `/cartographer --status` — audit status
+
+Reports the running state and last completion time. No LLM calls.
+
+```bash
+echo "## Cartographer Status"
+if cartographer_lock_is_held "$CARTOGRAPHER_DIR/audit.lock"; then
+  pid=$(cat "$CARTOGRAPHER_DIR/audit.lock" 2>/dev/null)
+  echo "Audit running (PID $pid)"
+else
+  echo "No audit in progress"
+fi
+
+if [[ -f "$CARTOGRAPHER_DIR/last_audit_at" ]]; then
+  ts=$(cat "$CARTOGRAPHER_DIR/last_audit_at")
+  echo "Last completed: $(date -r "$ts" 2>/dev/null || date -d "@$ts" 2>/dev/null || echo "$ts")"
+fi
+
+runs=$(ls "$CARTOGRAPHER_DIR/runs/" 2>/dev/null | wc -l | tr -d ' ')
+total=$(ls "$CARTOGRAPHER_DIR/findings/" 2>/dev/null | wc -l | tr -d ' ')
+echo "Total findings on disk: $total"
+echo "Audit runs recorded: $runs"
+```
+
+### `/cartographer --force` — force restart
+
+Kills the running audit (if any) and starts fresh.
+
+```bash
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+if cartographer_lock_is_held "$LOCK_FILE"; then
+  pid=$(cat "$LOCK_FILE" 2>/dev/null)
+  if [[ -n "$pid" ]]; then
+    kill "$pid" 2>/dev/null || true
+    sleep 1
+  fi
+  rm -f "$LOCK_FILE"
+fi
+# Then proceed as a normal full audit
+```
+
+### `/cartographer --phase=<phase>` — single phase
+
+Runs only one analysis phase: `contradiction`, `stale_ref`, `dead_rule`, or `scope_collision`.
+Pass `CARTOGRAPHER_PHASE_FILTER` to run-audit.sh (the script checks this env var and skips other phases).
+
+### `/cartographer --scope=<path>` — scoped audit
+
+Limits discovery to files under `<path>`. Set `CARTOGRAPHER_SCOPE_PATH` before running.
+
+## Rendering Findings
+
+After a manual audit completes, render findings grouped by severity:
+
+```bash
+echo "## Cartographer Findings"
+echo ""
+
+for severity in error warning informational; do
+  count=0
+  output=""
+  for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
+    [[ -f "$f" ]] || continue
+    fsev=$(jq -r '.severity // "warning"' "$f" 2>/dev/null)
+    [[ "$fsev" != "$severity" ]] && continue
+    (( count++ )) || true
+    output+=$(jq -r '"- **\(.type)**: \(.description)\n  `\(.file_a // "n/a")`\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null)
+    output+=$'\n'
+  done
+  if [[ "$count" -gt 0 ]]; then
+    echo "### ${severity^} ($count)"
+    printf '%s\n' "$output"
+  fi
+done
+```
+
+## Event Contract
+
+- `cartographer.issue.found` — emitted for NEW findings only (not in dedup store). Downstream consumers must deduplicate on `payload.finding_hash`.
+- `cartographer.audit.complete` — emitted when all phases complete (or partial with `status: "partial"`).
+- Manual `--verbose` renders known findings as in-conversation output only — no bus events.

package/release-please-config.json

@@ -62,6 +62,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/cartographer": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-bump-minor-pre-major": false,
+      "component": "cartographer",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

package/test/bats/cartographer-config.bats

@@ -0,0 +1,107 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/cartographer"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/cartographer-config.sh"
+}
+
+@test "config defaults: disabled by default" {
+  cartographer_config_load ""
+  run cartographer_config_enabled
+  [ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable cartographer" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+  cartographer_config_load ""
+  run cartographer_config_enabled
+  [ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level enabled" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+  local repo="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "${repo}/.claude"
+  printf '%s\n' '{"cartographer":{"enabled":false}}' > "${repo}/.claude/settings.json"
+  cartographer_config_load "$repo"
+  run cartographer_config_enabled
+  [ "$status" -ne 0 ]
+}
+
+@test "deep merge: user-level partial override preserves plugin defaults" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"audit_interval_hours":12}}' > "${HOME}/.claude/settings.json"
+  cartographer_config_load ""
+  local interval model
+  interval=$(cartographer_config_audit_interval_hours)
+  model=$(cartographer_config_model_extraction)
+  [ "$interval" = "12" ]
+  [ "$model" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "deep merge: repo overrides user but preserves user keys not in repo" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"audit_interval_hours":6,"phase_timeout_seconds":30}}' > "${HOME}/.claude/settings.json"
+  local repo="${BATS_TEST_TMPDIR}/repo2"
+  mkdir -p "${repo}/.claude"
+  printf '%s\n' '{"cartographer":{"audit_interval_hours":48}}' > "${repo}/.claude/settings.json"
+  cartographer_config_load "$repo"
+  local interval timeout_s
+  interval=$(cartographer_config_audit_interval_hours)
+  timeout_s=$(cartographer_config_phase_timeout)
+  [ "$interval" = "48" ]
+  [ "$timeout_s" = "30" ]
+}
+
+@test "model_extraction falls back to default when not configured" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_model_extraction)
+  [ "$v" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "model_synthesis falls back to default when not configured" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_model_synthesis)
+  [ "$v" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "model_extraction respects user-level override" {
+  mkdir -p "${HOME}/.claude"
+  printf '%s\n' '{"cartographer":{"extraction":{"model":"claude-sonnet-4-6"}}}' > "${HOME}/.claude/settings.json"
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_model_extraction)
+  [ "$v" = "claude-sonnet-4-6" ]
+}
+
+@test "phase_timeout_seconds defaults to 60" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_phase_timeout)
+  [ "$v" = "60" ]
+}
+
+@test "audit_interval_hours defaults to 24" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_audit_interval_hours)
+  [ "$v" = "24" ]
+}
+
+@test "exclude_paths defaults are non-empty JSON array" {
+  cartographer_config_load ""
+  local v
+  v=$(cartographer_config_exclude_paths)
+  # Must be a non-empty JSON array containing node_modules
+  echo "$v" | jq -e 'type == "array" and length > 0' >/dev/null
+  echo "$v" | jq -e 'any(. == "node_modules")' >/dev/null
+}

package/test/bats/cartographer-lock.bats

@@ -0,0 +1,77 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+  # shellcheck disable=SC1091
+  source "${REPO_ROOT}/plugins/cartographer/scripts/lib/cartographer-lock.sh"
+
+  LOCK_FILE="${BATS_TEST_TMPDIR}/test.lock"
+}
+
+teardown() {
+  cartographer_lock_release "$LOCK_FILE" 2>/dev/null || true
+}
+
+@test "acquire succeeds when lock is free" {
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "acquire fails immediately when lock is already held" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "release allows re-acquire" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  cartographer_lock_release "$LOCK_FILE"
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "is_held returns true while lock is held" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  run cartographer_lock_is_held "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "is_held returns false after release" {
+  cartographer_lock_acquire "$LOCK_FILE"
+  cartographer_lock_release "$LOCK_FILE"
+  run cartographer_lock_is_held "$LOCK_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "release is idempotent (safe to call when not held)" {
+  run cartographer_lock_release "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "two independent lock paths do not interfere" {
+  local lock_a="${BATS_TEST_TMPDIR}/a.lock"
+  local lock_b="${BATS_TEST_TMPDIR}/b.lock"
+  cartographer_lock_acquire "$lock_a"
+  run cartographer_lock_acquire "$lock_b"
+  [ "$status" -eq 0 ]
+  cartographer_lock_release "$lock_a"
+  cartographer_lock_release "$lock_b"
+}
+
+@test "background child holds lock after parent releases its reference" {
+  # Acquire in a background subprocess, then verify is_held from this process.
+  bash -c "
+    source '${REPO_ROOT}/plugins/cartographer/scripts/lib/cartographer-lock.sh'
+    cartographer_lock_acquire '${LOCK_FILE}'
+    sleep 2
+    cartographer_lock_release '${LOCK_FILE}'
+  " &
+  sleep 0.1
+  run cartographer_lock_is_held "$LOCK_FILE"
+  [ "$status" -eq 0 ]
+  # Second acquire from this process must fail while child holds it
+  run cartographer_lock_acquire "$LOCK_FILE"
+  [ "$status" -ne 0 ]
+  wait
+}