@datafog/fogclaw 0.2.0 → 0.3.0

package/scripts/ci/he-docs-lint.sh

@@ -1,234 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# ── Constants ────────────────────────────────────────────────────────────────
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-DEFAULT_CONFIG_PATH="scripts/ci/he-docs-config.json"
-
-# ── Globals ──────────────────────────────────────────────────────────────────
-ERRORS=0
-WARNINGS=0
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-_env_flag() {
-  local name="$1"
-  local default="${2:-0}"
-  local val="${!name:-$default}"
-  [[ "$val" == "1" ]]
-}
-
-_load_config() {
-  local config_path="${HARNESS_DOCS_CONFIG:-$DEFAULT_CONFIG_PATH}"
-  local path="$REPO_ROOT/$config_path"
-  if [[ ! -f "$path" ]]; then
-    echo "Error: he-docs-lint missing/invalid config: Missing config '$config_path'. Fix: create it (bootstrap should do this) or set HARNESS_DOCS_CONFIG." >&2
-    return 1
-  fi
-  # Validate it is a JSON object
-  if ! jq -e 'type == "object"' "$path" >/dev/null 2>&1; then
-    echo "Error: he-docs-lint missing/invalid config: Config must be a JSON object." >&2
-    return 1
-  fi
-  cat "$path"
-}
-
-_gh_annotate() {
-  local level="$1" file="$2" title="$3" msg="$4"
-  if [[ -n "$file" ]]; then
-    echo "::${level} file=${file},title=${title}::${msg}"
-  else
-    echo "::${level} title=${title}::${msg}"
-  fi
-}
-
-_emit() {
-  local level="$1" file="$2" title="$3" msg="$4"
-  _gh_annotate "$level" "$file" "$title" "$msg"
-  local upper
-  upper="$(echo "$level" | tr '[:lower:]' '[:upper:]')"
-  echo "${upper}: ${msg}" >&2
-  if [[ "$level" == "error" ]]; then
-    ERRORS=$((ERRORS + 1))
-  else
-    WARNINGS=$((WARNINGS + 1))
-  fi
-}
-
-_has_exact_line() {
-  local path="$1" needle="$2"
-  grep -Fxq "$needle" "$path" 2>/dev/null
-}
-
-# ── Checks ───────────────────────────────────────────────────────────────────
-
-_check_required_docs() {
-  local cfg="$1"
-  local count
-  count="$(echo "$cfg" | jq -r '.required_docs | if type == "array" then length else 0 end')"
-  if [[ "$count" -eq 0 ]]; then
-    return
-  fi
-  local i doc
-  for ((i = 0; i < count; i++)); do
-    doc="$(echo "$cfg" | jq -r ".required_docs[$i]")"
-    if [[ "$doc" == "null" ]] || [[ -z "$doc" ]]; then
-      continue
-    fi
-    if [[ ! -e "$REPO_ROOT/$doc" ]]; then
-      _emit "error" "$doc" "Required doc missing" \
-        "Missing required doc: '$doc'. Fix: create it (run he-bootstrap if this repo is not bootstrapped) or adjust required_docs in config."
-    fi
-  done
-}
-
-_check_domain_doc_headings() {
-  local cfg="$1"
-  local is_obj
-  is_obj="$(echo "$cfg" | jq -r '.required_headings | type')"
-  if [[ "$is_obj" != "object" ]]; then
-    return
-  fi
-
-  local docs
-  docs="$(echo "$cfg" | jq -r '.required_headings | keys[]')"
-  if [[ -z "$docs" ]]; then
-    return
-  fi
-
-  local doc
-  while IFS= read -r doc; do
-    [[ -z "$doc" ]] && continue
-    local path="$REPO_ROOT/$doc"
-    if [[ ! -f "$path" ]]; then
-      continue  # on-demand domain docs
-    fi
-
-    local headings_count
-    headings_count="$(echo "$cfg" | jq -r --arg d "$doc" '.required_headings[$d] | if type == "array" then length else 0 end')"
-    if [[ "$headings_count" -eq 0 ]]; then
-      _emit "error" "$doc" "Missing config headings" \
-        "No required headings configured for '$doc'. Fix: add required_headings['$doc'] in config or remove the entry."
-      continue
-    fi
-
-    local missing=()
-    local j heading
-    for ((j = 0; j < headings_count; j++)); do
-      heading="$(echo "$cfg" | jq -r --arg d "$doc" ".required_headings[\$d][$j]")"
-      if [[ "$heading" == "null" ]] || [[ -z "$heading" ]]; then
-        continue
-      fi
-      if ! _has_exact_line "$path" "$heading"; then
-        missing+=("$heading")
-      fi
-    done
-
-    if [[ ${#missing[@]} -gt 0 ]]; then
-      local joined
-      joined="$(printf "%s; " "${missing[@]}")"
-      joined="${joined%; }"  # trim trailing "; "
-      _emit "error" "$doc" "Missing headings" \
-        "Missing required headings in '$doc': ${joined}. Fix: add them."
-    fi
-  done <<< "$docs"
-}
-
-_check_seed_markers() {
-  local cfg="$1"
-  local fail_level="warning"
-  if _env_flag "HARNESS_FAIL_ON_SEED_MARKERS" "0"; then
-    fail_level="error"
-  fi
-
-  local count
-  count="$(echo "$cfg" | jq -r '.domain_docs | if type == "array" then length else 0 end')"
-  if [[ "$count" -eq 0 ]]; then
-    return
-  fi
-
-  local i doc path
-  for ((i = 0; i < count; i++)); do
-    doc="$(echo "$cfg" | jq -r ".domain_docs[$i]")"
-    if [[ "$doc" == "null" ]] || [[ -z "$doc" ]]; then
-      continue
-    fi
-    path="$REPO_ROOT/$doc"
-    if [[ ! -f "$path" ]]; then
-      continue
-    fi
-    if grep -q '<!-- seed:' "$path" 2>/dev/null; then
-      _emit "$fail_level" "$doc" "Seed markers present" \
-        "Template seed markers remain in '$doc'. Fix: replace/remove <!-- seed: ... --> blocks once this repo has real domain context."
-    fi
-  done
-}
-
-_check_generated_last_updated() {
-  local gen_dir="$REPO_ROOT/docs/generated"
-  if [[ ! -d "$gen_dir" ]]; then
-    return
-  fi
-
-  local fail_level="warning"
-  if _env_flag "HARNESS_FAIL_ON_GENERATED_PLACEHOLDERS" "0"; then
-    fail_level="error"
-  fi
-
-  local path rel
-  for path in "$gen_dir"/*.md; do
-    [[ -e "$path" ]] || continue  # handle no-match glob
-    rel="${path#"$REPO_ROOT/"}"
-    # Skip known non-generated docs
-    if [[ "$rel" == "docs/generated/README.md" ]] || [[ "$rel" == "docs/generated/memory.md" ]]; then
-      continue
-    fi
-    local text
-    text="$(cat "$path")"
-
-    # Check for missing last_updated line (BSD/GNU portable; avoid grep -P)
-    if ! echo "$text" | grep -Eq '^[[:space:]]*-[[:space:]]*last_updated:[[:space:]]*'; then
-      _emit "error" "$rel" "Missing last_updated" \
-        "Generated doc '$rel' must include a 'last_updated' line. Fix: add e.g. '- last_updated: 2026-02-15 12:34'."
-    fi
-
-    # Check for placeholder last_updated value
-    if echo "$text" | grep -Eq 'last_updated:[[:space:]]*<YYYY-'; then
-      _emit "$fail_level" "$rel" "Placeholder last_updated" \
-        "Generated doc '$rel' has a placeholder last_updated value. Fix: replace with a real timestamp."
-    fi
-  done
-}
-
-# ── Main ─────────────────────────────────────────────────────────────────────
-
-main() {
-  local cfg
-  if ! cfg="$(_load_config)"; then
-    exit 2
-  fi
-
-  echo "he-docs-lint: starting"
-  echo "Repro: bash scripts/ci/he-docs-lint.sh"
-
-  _check_required_docs "$cfg"
-
-  # Runbooks lint is its own script. Fail fast if it fails.
-  if ! bash "$REPO_ROOT/scripts/ci/he-runbooks-lint.sh"; then
-    exit 1
-  fi
-
-  _check_domain_doc_headings "$cfg"
-  _check_seed_markers "$cfg"
-  _check_generated_last_updated
-
-  if [[ "$ERRORS" -gt 0 ]]; then
-    echo "he-docs-lint: FAIL ($ERRORS error(s), $WARNINGS warning(s))" >&2
-    exit 1
-  fi
-
-  echo "he-docs-lint: OK ($WARNINGS warning(s))"
-  exit 0
-}
-
-main "$@"

package/scripts/ci/he-plans-lint.sh

@@ -1,354 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# ── Repo root (two levels above this script) ──────────────────────────
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-
-DEFAULT_CONFIG_PATH="scripts/ci/he-docs-config.json"
-
-# ── Default required headings ─────────────────────────────────────────
-DEFAULT_REQUIRED_HEADINGS=(
-  "## Purpose / Big Picture"
-  "## Progress"
-  "## Surprises & Discoveries"
-  "## Decision Log"
-  "## Outcomes & Retrospective"
-  "## Context and Orientation"
-  "## Milestones"
-  "## Plan of Work"
-  "## Concrete Steps"
-  "## Validation and Acceptance"
-  "## Idempotence and Recovery"
-  "## Artifacts and Notes"
-  "## Interfaces and Dependencies"
-  "## Pull Request"
-  "## Review Findings"
-  "## Verify/Release Decision"
-  "## Revision Notes"
-)
-
-# ── Counters ──────────────────────────────────────────────────────────
-ERRORS=0
-WARNINGS=0
-
-# ── Emit a finding (GitHub annotation + stderr) ──────────────────────
-emit() {
-  local level="$1" file="$2" title="$3" msg="$4"
-  if [[ -n "$file" ]]; then
-    echo "::${level} file=${file},title=${title}::${msg}"
-  else
-    echo "::${level} title=${title}::${msg}"
-  fi
-  echo "${level^^}: ${msg}" >&2
-  if [[ "$level" == "error" ]]; then
-    (( ERRORS++ )) || true
-  else
-    (( WARNINGS++ )) || true
-  fi
-}
-
-# ── Load config ───────────────────────────────────────────────────────
-load_config() {
-  local config_rel="${HARNESS_DOCS_CONFIG:-$DEFAULT_CONFIG_PATH}"
-  local config_path="$REPO_ROOT/$config_rel"
-  if [[ ! -f "$config_path" ]]; then
-    echo "Error: he-plans-lint missing/invalid config: Missing config '${config_rel}'. Fix: create it (bootstrap should do this) or set HARNESS_DOCS_CONFIG." >&2
-    exit 2
-  fi
-  # Validate it is a JSON object
-  if ! jq -e 'type == "object"' "$config_path" >/dev/null 2>&1; then
-    echo "Error: he-plans-lint missing/invalid config: Config must be a JSON object." >&2
-    exit 2
-  fi
-  CONFIG_PATH="$config_path"
-}
-
-# ── Config helpers ────────────────────────────────────────────────────
-cfg_get() {
-  # $1 = jq expression, returns raw output
-  jq -r "$1" "$CONFIG_PATH"
-}
-
-cfg_get_array() {
-  # $1 = jq path to array, outputs one element per line
-  jq -r "$1 // [] | if type == \"array\" then .[] else empty end" "$CONFIG_PATH" 2>/dev/null
-}
-
-# ── Extract YAML frontmatter (between first --- and second ---) ──────
-# Sets FRONTMATTER variable. Returns 1 if no frontmatter found.
-extract_frontmatter() {
-  local file="$1"
-  FRONTMATTER=""
-  local first_line
-  first_line="$(head -1 "$file")"
-  if [[ "$(echo "$first_line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')" != "---" ]]; then
-    return 1
-  fi
-  # Find closing --- (skip line 1, find next ---)
-  local end_line
-  end_line="$(awk 'NR > 1 && /^[[:space:]]*---[[:space:]]*$/ { print NR; exit }' "$file")"
-  if [[ -z "$end_line" ]]; then
-    return 1
-  fi
-  # Extract lines between line 2 and end_line-1
-  FRONTMATTER="$(sed -n "2,$((end_line - 1))p" "$file")"
-  return 0
-}
-
-# ── Parse frontmatter key-value pairs ────────────────────────────────
-# Reads FRONTMATTER, outputs "key=value" lines
-frontmatter_keys=()
-frontmatter_vals=()
-
-parse_frontmatter_kv() {
-  frontmatter_keys=()
-  frontmatter_vals=()
-  while IFS= read -r raw; do
-    local line
-    line="$(echo "$raw" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
-    # Skip empty / comment lines
-    [[ -z "$line" || "$line" == \#* ]] && continue
-    # Must contain a colon
-    [[ "$line" != *:* ]] && continue
-    local key val
-    key="$(echo "$line" | cut -d: -f1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
-    val="$(echo "$line" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
-    frontmatter_keys+=("$key")
-    frontmatter_vals+=("$val")
-  done <<< "$FRONTMATTER"
-}
-
-# ── Lookup a frontmatter value by key ────────────────────────────────
-fm_get() {
-  local needle="$1"
-  for i in "${!frontmatter_keys[@]}"; do
-    if [[ "${frontmatter_keys[$i]}" == "$needle" ]]; then
-      echo "${frontmatter_vals[$i]}"
-      return 0
-    fi
-  done
-  return 1
-}
-
-fm_has_key() {
-  local needle="$1"
-  for k in "${frontmatter_keys[@]}"; do
-    [[ "$k" == "$needle" ]] && return 0
-  done
-  return 1
-}
-
-# ── Extract section lines (between heading and next ## heading) ──────
-# Outputs section body lines to stdout
-section_lines() {
-  local file="$1" heading="$2"
-  awk -v h="$heading" '
-    BEGIN { found=0 }
-    $0 == h { found=1; next }
-    found && /^## / { exit }
-    found { print }
-  ' "$file"
-}
-
-# ── Check: exact heading line exists in file ─────────────────────────
-has_exact_line() {
-  local file="$1" needle="$2"
-  grep -qxF "$needle" "$file"
-}
-
-# ── Check: Progress section ──────────────────────────────────────────
-check_progress() {
-  local file_rel="$1" file_abs="$2"
-  local body
-  body="$(section_lines "$file_abs" "## Progress")"
-
-  # Check non-empty (has at least one non-blank line)
-  if ! echo "$body" | grep -q '[^[:space:]]'; then
-    emit "error" "$file_rel" "Missing Progress content" \
-      "Plan '${file_rel}' has an empty ## Progress section."
-    return
-  fi
-
-  # Check timestamped checkbox pattern
-  if ! echo "$body" | grep -qE '^- \[[ xX]\] \([0-9]{4}-[0-9]{2}-[0-9]{2}[^)]*\) P[0-9]+'; then
-    emit "error" "$file_rel" "Progress format" \
-      "Plan '${file_rel}' must include timestamped progress checkboxes with IDs (e.g. '- [ ] (2026-02-15T12:00:00Z) P1 ...')."
-  fi
-}
-
-# ── Check: checklists only in Progress ───────────────────────────────
-check_checklists_only_in_progress() {
-  local file_rel="$1" file_abs="$2"
-  local bad=0
-  local in_progress=0
-  while IFS= read -r line; do
-    if [[ "$line" == "## Progress" ]]; then
-      in_progress=1
-      continue
-    fi
-    if [[ "$line" == "## "* ]]; then
-      in_progress=0
-    fi
-    if [[ $in_progress -eq 0 ]] && echo "$line" | grep -qE '^- \[[ xX]\]'; then
-      bad=1
-      break
-    fi
-  done < "$file_abs"
-
-  if [[ $bad -eq 1 ]]; then
-    emit "error" "$file_rel" "Checklist scope" \
-      "Plan '${file_rel}' contains checklist items outside ## Progress."
-  fi
-}
-
-# ── Check: Decision Log ──────────────────────────────────────────────
-check_decision_log() {
-  local file_rel="$1" file_abs="$2"
-  local body
-  body="$(section_lines "$file_abs" "## Decision Log")"
-
-  if ! echo "$body" | grep -q '[^[:space:]]'; then
-    emit "error" "$file_rel" "Missing Decision Log content" \
-      "Plan '${file_rel}' has an empty ## Decision Log section."
-    return
-  fi
-
-  if ! echo "$body" | grep -q '^- Decision:'; then
-    emit "error" "$file_rel" "Decision format" \
-      "Plan '${file_rel}' should record decisions using '- Decision:' entries."
-  fi
-}
-
-# ── Check: Revision Notes ────────────────────────────────────────────
-check_revision_notes() {
-  local file_rel="$1" file_abs="$2"
-  local body
-  body="$(section_lines "$file_abs" "## Revision Notes")"
-
-  if ! echo "$body" | grep -q '[^[:space:]]'; then
-    emit "error" "$file_rel" "Missing Revision Notes content" \
-      "Plan '${file_rel}' has an empty ## Revision Notes section."
-    return
-  fi
-
-  if ! echo "$body" | grep -q '^- '; then
-    emit "error" "$file_rel" "Revision Notes format" \
-      "Plan '${file_rel}' should include at least one bullet in ## Revision Notes."
-  fi
-}
-
-# ── Check: placeholder tokens ────────────────────────────────────────
-check_placeholders() {
-  local file_rel="$1" file_abs="$2"
-  local fail_ph=0
-  [[ "${HARNESS_FAIL_ON_ARTIFACT_PLACEHOLDERS:-0}" == "1" ]] && fail_ph=1
-
-  local text
-  text="$(cat "$file_abs")"
-
-  while IFS= read -r pattern; do
-    [[ -z "$pattern" ]] && continue
-    if echo "$text" | grep -qF "$pattern"; then
-      local level="warning"
-      local msg="Plan '${file_rel}' contains placeholder token '${pattern}'."
-      if [[ $fail_ph -eq 1 ]]; then
-        level="error"
-      else
-        msg="${msg} (Set HARNESS_FAIL_ON_ARTIFACT_PLACEHOLDERS=1 to enforce.)"
-      fi
-      emit "$level" "$file_rel" "Placeholder token" "$msg"
-      break
-    fi
-  done < <(cfg_get_array '.artifact_placeholder_patterns')
-}
-
-# ── Check a single plan file ─────────────────────────────────────────
-check_plan() {
-  local file_abs="$1"
-  local file_rel="${file_abs#"$REPO_ROOT/"}"
-
-  # Frontmatter
-  if ! extract_frontmatter "$file_abs"; then
-    emit "error" "$file_rel" "Missing YAML frontmatter" \
-      "Plan '${file_rel}' must start with YAML frontmatter delimited by '---' lines."
-    return
-  fi
-
-  parse_frontmatter_kv
-
-  # Required frontmatter keys
-  while IFS= read -r key; do
-    [[ -z "$key" ]] && continue
-    if ! fm_has_key "$key"; then
-      emit "error" "$file_rel" "Missing frontmatter key" \
-        "Plan '${file_rel}' missing YAML frontmatter key '${key}:'."
-    fi
-  done < <(cfg_get_array '.required_plan_frontmatter_keys')
-
-  # plan_mode validation
-  local plan_mode
-  plan_mode="$(fm_get "plan_mode" 2>/dev/null || true)"
-  plan_mode="$(echo "$plan_mode" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
-  if [[ -n "$plan_mode" && "$plan_mode" != "trivial" && "$plan_mode" != "lightweight" && "$plan_mode" != "execution" ]]; then
-    emit "error" "$file_rel" "Invalid plan_mode" \
-      "Plan '${file_rel}' has invalid plan_mode '${plan_mode}' (must be 'trivial', 'lightweight', or 'execution')."
-  fi
-
-  # Required headings
-  for h in "${DEFAULT_REQUIRED_HEADINGS[@]}"; do
-    if ! has_exact_line "$file_abs" "$h"; then
-      emit "error" "$file_rel" "Missing heading" \
-        "Plan '${file_rel}' missing required heading line '${h}'."
-    fi
-  done
-
-  # Section-level checks
-  check_progress "$file_rel" "$file_abs"
-  check_checklists_only_in_progress "$file_rel" "$file_abs"
-  check_decision_log "$file_rel" "$file_abs"
-  check_revision_notes "$file_rel" "$file_abs"
-  check_placeholders "$file_rel" "$file_abs"
-}
-
-# ══════════════════════════════════════════════════════════════════════
-# Main
-# ══════════════════════════════════════════════════════════════════════
-load_config
-
-echo "he-plans-lint: starting"
-echo "Repro: bash scripts/ci/he-plans-lint.sh"
-
-plans_active="$REPO_ROOT/docs/plans/active"
-plans_completed="$REPO_ROOT/docs/plans/completed"
-
-files=()
-if [[ -d "$plans_active" ]]; then
-  while IFS= read -r -d '' f; do
-    files+=("$f")
-  done < <(find "$plans_active" -maxdepth 1 -name '*.md' -print0 | sort -z)
-fi
-
-lint_completed="$(cfg_get '.lint_completed_plans // true')"
-if [[ "$lint_completed" != "false" && -d "$plans_completed" ]]; then
-  while IFS= read -r -d '' f; do
-    files+=("$f")
-  done < <(find "$plans_completed" -maxdepth 1 -name '*.md' -print0 | sort -z)
-fi
-
-if [[ ${#files[@]} -eq 0 ]]; then
-  echo "he-plans-lint: OK (no plan files)"
-  exit 0
-fi
-
-for f in "${files[@]}"; do
-  check_plan "$f"
-done
-
-if [[ $ERRORS -gt 0 ]]; then
-  echo "he-plans-lint: FAIL (${ERRORS} error(s), ${WARNINGS} warning(s))" >&2
-  exit 1
-fi
-
-echo "he-plans-lint: OK (${WARNINGS} warning(s))"
-exit 0