holocron/scripts/check-vale-style-sync.sh

#!/usr/bin/env bash
set -euo pipefail

# Kyberforge's Vale prefilter is duplicated into skill-audit and agent-audit's own
# scripts/assets (per plugins/kyberforge/.apm/skills/skill-author/references/deployment-modes.md's
# no-cross-skill-path rule: a plugin's cache-install copy only includes each skill's own files).
# agent-audit's copy is canonical — it's the superset (Kyberforge + KyberforgeCopilot) that the
# repo root's own pre-commit hook and .pre-commit-hooks.yaml both consume. This fails the build
# if skill-audit's copy has drifted from it, since nothing else would catch a rule fix landing in
# only one of the two. Run from repo root or pass REPO_ROOT as arg.

REPO_ROOT="${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
# A nonexistent REPO_ROOT must fail loudly, not fall through to the "neither
# copy present" no-op below — that guard exists for a repo that legitimately
# has no kyberforge plugin installed, not for a typo'd or stale path, and a
# clean exit 0 here would read as "checked, in sync" when nothing ran at all.
if [[ ! -d "$REPO_ROOT" ]]; then
  echo "Vale style sync check failed: REPO_ROOT '$REPO_ROOT' is not a directory." >&2
  exit 1
fi
# Absolutized because the glob probe below `cd`s into a scratch tree, where a
# relative --config path would stop resolving.
REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
FAIL=0

err() { echo "  FAIL: $1" >&2; FAIL=$((FAIL + 1)); }

SKILL_AUDIT="$REPO_ROOT/plugins/kyberforge/.apm/skills/skill-audit"
AGENT_AUDIT="$REPO_ROOT/plugins/kyberforge/.apm/skills/agent-audit"

if [[ ! -d "$SKILL_AUDIT" && ! -d "$AGENT_AUDIT" ]]; then
  exit 0
fi

# Exactly one present is drift, not absence: the missing copy can't be in sync
# with the surviving one, and treating it as a no-op is how a deleted or
# renamed copy would slip through silently.
if [[ ! -d "$SKILL_AUDIT" ]]; then
  echo "Vale style sync check failed: $AGENT_AUDIT exists but $SKILL_AUDIT does not — run scripts/sync-vale-styles.sh to regenerate skill-audit's copy." >&2
  exit 1
fi
if [[ ! -d "$AGENT_AUDIT" ]]; then
  echo "Vale style sync check failed: $SKILL_AUDIT exists but $AGENT_AUDIT does not — agent-audit holds the canonical copy, so restore it before syncing." >&2
  exit 1
fi

if ! diff -q "$SKILL_AUDIT/scripts/vale-wrap.sh" "$AGENT_AUDIT/scripts/vale-wrap.sh" >/dev/null 2>&1; then
  err "scripts/vale-wrap.sh differs between skill-audit and agent-audit"
fi

if ! diff -rq "$SKILL_AUDIT/assets/vale/styles/Kyberforge" "$AGENT_AUDIT/assets/vale/styles/Kyberforge" >/dev/null 2>&1; then
  err "assets/vale/styles/Kyberforge differs between skill-audit and agent-audit"
fi

# --- .vale.ini coverage ------------------------------------------------------
# The two .vale.ini files are deliberately NOT identical — agent-audit's carries
# an extra [**/*.agent.md] section and the KyberforgeCopilot style — so they
# cannot be diffed like the styles above. Nothing else in the repo read them at
# all, and that is what let a one-character glob typo silently disable the
# prefilter for a whole file type: the hook still MATCHES the file via its
# `files:` regex, so pre-commit reports neither `Skipped` nor an error; vale
# lints zero files, prints `0 errors ... in 1 file` and exits 0, and the hook
# shows `Passed`. So check the parts that must hold in both, not equality.

SKILL_INI="$SKILL_AUDIT/assets/vale/.vale.ini"
AGENT_INI="$AGENT_AUDIT/assets/vale/.vale.ini"

for ini in "$SKILL_INI" "$AGENT_INI"; do
  rel_ini="${ini#"$REPO_ROOT"/}"
  if [[ ! -f "$ini" ]]; then
    err "$rel_ini is missing — without it vale falls back to an upward config search and lints with whatever it finds"
    continue
  fi
  # StylesPath is resolved relative to the .vale.ini, which is the only reason
  # the bundled styles are found from a consuming repo's clone prefix.
  if ! grep -Eq '^[[:space:]]*StylesPath[[:space:]]*=[[:space:]]*styles[[:space:]]*$' "$ini"; then
    err "$rel_ini has no 'StylesPath = styles' — the bundled styles/ directory would not be found"
  fi
  # Matches `Kyberforge` as a whole name, so `KyberforgeCopilot` alone does not
  # satisfy it. Avoids \b, which is a GNU grep extension.
  if ! grep -Eq '^[[:space:]]*BasedOnStyles[[:space:]]*=.*Kyberforge([[:space:],]|$)' "$ini"; then
    err "$rel_ini has no section whose BasedOnStyles names Kyberforge — every rule the audit prefilters on lives in that style"
  fi
done

# Prints the `files:` regex of every hook, in ONE manifest ($2), whose entry
# is $1's vale-wrap.sh. Records are delimited by their `- id:` line, so the
# check does not depend on `entry:` preceding `files:` within a record.
#
# Deliberately kept per-manifest rather than unioned across both files: the
# validation loop below needs to know whether a probe path is in scope of
# .pre-commit-hooks.yaml (the canonical, external-facing manifest) and
# .pre-commit-config.yaml (this repo's own dev-time copy of the same hook)
# *independently*. A union here previously let a probe that matched only the
# older, looser .pre-commit-hooks.yaml pattern read as "in scope" even after
# .pre-commit-config.yaml's copy of the same hook had been narrowed away from
# it — silently masking exactly the kind of hook-rescoping drift this script
# exists to catch.
#
# Cached per (skill, manifest) pair (parallel HOOK_REGEX_CACHE_KEYS/_VALS
# arrays, populated lazily) because the final validation loop below probes
# agent-audit's two manifests across three probe shapes; without the cache,
# each repeated (skill, manifest) pairing would re-parse the same manifest
# file from scratch for no new information. Plain indexed arrays, not
# `declare -A`: associative arrays are bash 4.0+ and this script must run on
# macOS's stock bash 3.2. Only ${#arr[@]} (always safe on an empty/unset array
# under `set -u`) and index access are used below — never a bare `${arr[@]}`
# expansion, which aborts on bash < 4.4 under nounset.
HOOK_REGEX_CACHE_KEYS=()
HOOK_REGEX_CACHE_VALS=()
hook_file_regexes() {
  local skill="$1" manifest="$2" raw result idx=0
  local cache_key="$skill|$manifest"
  while [[ $idx -lt ${#HOOK_REGEX_CACHE_KEYS[@]} ]]; do
    if [[ "${HOOK_REGEX_CACHE_KEYS[$idx]}" == "$cache_key" ]]; then
      printf '%s' "${HOOK_REGEX_CACHE_VALS[$idx]}"
      return
    fi
    idx=$((idx + 1))
  done
  result="$(
    if [[ -f "$manifest" ]]; then
      awk -v skill="$skill" '
        function flush() {
          if (entry ~ skill "/scripts/vale-wrap.sh" && files != "") print files
          entry = ""; files = ""
        }
        /^[ \t]*-[ \t]*id:/ { flush() }
        /^[ \t]*entry:/ { entry = $0 }
        /^[ \t]*files:/ { files = $0; sub(/^[ \t]*files:[ \t]*/, "", files) }
        END { flush() }
      ' "$manifest" | while IFS= read -r raw; do
        # Strip the surrounding YAML quotes; the regex itself never carries them.
        raw="${raw%\'}"; raw="${raw#\'}"
        raw="${raw%\"}"; raw="${raw#\"}"
        printf '%s\n' "$raw"
      done
    fi
  )"
  HOOK_REGEX_CACHE_KEYS[${#HOOK_REGEX_CACHE_KEYS[@]}]="$cache_key"
  HOOK_REGEX_CACHE_VALS[${#HOOK_REGEX_CACHE_VALS[@]}]="$result"
  printf '%s' "$result"
}

# True if $1 matches at least one newline-delimited regex in $2.
matches_any_regex() {
  local rel="$1" regexes="$2" re
  [[ -n "$regexes" ]] || return 1
  while IFS= read -r re; do
    [[ -n "$re" ]] || continue
    if printf '%s\n' "$rel" | grep -Eq "$re"; then
      return 0
    fi
  done <<EOF_RE
$regexes
EOF_RE
  return 1
}

# Asks vale — the thing that actually applies these globs — whether a config
# covers a path, rather than reimplementing doublestar matching. The probe file
# carries a description with a token Kyberforge.VagueWording flags, so a config
# whose glob matches but whose BasedOnStyles lost Kyberforge fails too: it would
# lint the file and report nothing.
vale_flags_path() {
  local cfg="$1" rel="$2" tmp out
  tmp="$(mktemp -d)"
  mkdir -p "$tmp/$(dirname "$rel")"
  {
    echo "---"
    echo "name: probe"
    echo "description: Use when the caller wants a probe that helps with things."
    echo "---"
    echo ""
    echo "Body."
  } > "$tmp/$rel"
  out="$(cd "$tmp" && vale --config "$cfg" "$rel" 2>&1)" || true
  rm -rf "$tmp"
  printf '%s\n' "$out" | grep -qF "Kyberforge.VagueWording"
}

VALE_AVAILABLE=true
if ! command -v vale >/dev/null 2>&1; then
  VALE_AVAILABLE=false
  echo "  WARNING: vale is not installed — .vale.ini glob coverage was NOT verified. Install it (https://vale.sh/docs/vale-cli/installation/) before trusting a clean run." >&2
fi

# One representative path per file shape the prefilter is supposed to cover,
# tagged with whether that shape is expected to be in scope of BOTH manifests
# ("shared") or only the external-facing .pre-commit-hooks.yaml ("hooks-only"
# — e.g. a Copilot .agent.md file living outside this repo's own plugins/.apm/
# layout, which .pre-commit-config.yaml's repo-scoped regex has no reason to
# cover). Each probe is checked against the two manifests' `files:` regexes
# *separately*, not unioned: a path that goes stale because a hook was
# rescoped fails loudly here instead of quietly probing a shape nothing lints
# any more, and a "shared" path the two manifests disagree on fails loudly
# too — that disagreement is exactly how .pre-commit-config.yaml's regex can
# narrow out of sync with .pre-commit-hooks.yaml's without either manifest's
# own hook breaking (each still matches real files on its own), so nothing
# else would catch it.
while IFS='|' read -r skill rel scope; do
  [[ -n "$skill" ]] || continue
  dir="$REPO_ROOT/plugins/kyberforge/.apm/skills/$skill"
  ini="$dir/assets/vale/.vale.ini"
  [[ -f "$ini" ]] || continue

  hooks_regexes="$(hook_file_regexes "$skill" "$REPO_ROOT/.pre-commit-hooks.yaml")"
  config_regexes="$(hook_file_regexes "$skill" "$REPO_ROOT/.pre-commit-config.yaml")"
  in_hooks=false
  matches_any_regex "$rel" "$hooks_regexes" && in_hooks=true
  in_config=false
  matches_any_regex "$rel" "$config_regexes" && in_config=true

  if [[ "$in_hooks" == false && "$in_config" == false ]]; then
    err "$rel matches no 'files:' regex of any $skill hook — the probe path is stale, or the hook was rescoped away from a shape it still needs to lint"
  elif [[ "$scope" == "shared" && "$in_hooks" != "$in_config" ]]; then
    err "$rel is in scope of $skill's hook in .pre-commit-hooks.yaml but not .pre-commit-config.yaml (or vice versa: hooks=$in_hooks, config=$in_config) — the local and canonical 'files:' regexes have drifted out of sync for this hook"
  fi

  if [[ "$VALE_AVAILABLE" == true ]] && ! vale_flags_path "$ini" "$rel"; then
    err "$skill/assets/vale/.vale.ini raises no Kyberforge alert on $rel — its glob sections do not cover a path its own pre-commit hook is scoped to, so the hook passes that shape without linting it"
  fi
# `demo.md` (bare, no `.agent.md` suffix) is `hooks-only` rather than
# `shared`: it exists only to exercise agent-audit's `[**/agents/*.md]` glob
# section in isolation from `[**/*.agent.md]` (test-check-vale-style-sync.sh's
# case 10), not because any real file under `.apm/agents/` still has that
# shape — per ADR-0016 every `.apm/agents/*` file is named `*.agent.md`, so
# `.pre-commit-config.yaml`'s regex correctly no longer matches it and that's
# not drift. `demo.agent.md` is the real, current shape and is `shared`.
done <<'EOF_PROBE'
skill-audit|plugins/demo/.apm/skills/demo/SKILL.md|shared
agent-audit|plugins/demo/.apm/agents/demo.md|hooks-only
agent-audit|plugins/demo/.apm/agents/demo.agent.md|shared
agent-audit|copilot/demo.agent.md|hooks-only
EOF_PROBE

if [[ $FAIL -gt 0 ]]; then
  echo "Vale style sync check failed: $FAIL error(s). For a drifted wrapper or style, agent-audit's copy is canonical — run scripts/sync-vale-styles.sh to regenerate skill-audit's copy, then commit both. A .vale.ini finding is not drift and sync-vale-styles.sh will not fix it: edit that file's own StylesPath, BasedOnStyles or glob sections." >&2
  exit 1
fi