@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/scripts/validate-app-docs.sh

@@ -0,0 +1,199 @@
+#!/bin/bash
+#
+# validate-app-docs.sh - Validate app repo documentation structure
+#
+# Usage: ./validate-app-docs.sh [--app-root <path>]
+#
+# Checks:
+#   1. service-architecture.md is present
+#   2. feature-tree.md is present (may be at docs/ or repo root)
+#   3. app-platform-dependencies.yaml is present
+#   4. Feature spec files under features/*/ have required sections:
+#      - ## Overview
+#      - ## Acceptance Criteria
+#      - ## Platform Contract Dependencies
+#
+# Does NOT check:
+#   - Glossary alignment (no domain glossary in app repos)
+#   - Cascade completeness (no domain model or capability tier)
+#   - DDD artifacts (no bounded contexts or aggregates)
+#   - Traceability manifests (no capability traceability in app repos)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+# R1: an empty population is "measured nothing", not a pass — the [N/A] tag
+# must start the line (no leading colour escape) so callers can detect it.
+log_na() { echo -e "[N/A] $1"; }
+log_section() {
+    echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+    echo -e "${BLUE}  $1${NC}"
+    echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+APP_ROOT="$ROOT_DIR"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --app-root)
+            APP_ROOT="${2:-}"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: $(basename "$0") [--app-root <path>]"
+            exit 0
+            ;;
+        *)
+            log_fail "Unknown argument: $1"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -d "$APP_ROOT" ]]; then
+    log_fail "App root not found: $APP_ROOT"
+    exit 1
+fi
+
+FAILURES=0
+
+# R1: the feature specs are the population this validator measures. With none,
+# the Group 1 file-presence checks are reported as [INFO] rather than [PASS] so
+# the run reads as "measured nothing", not as a pass.
+FEATURE_SPEC_COUNT="$( (find "$APP_ROOT/features" -type f -name "*.md" 2>/dev/null || true) | wc -l | tr -d ' ')"
+log_found() {
+    if [[ "$FEATURE_SPEC_COUNT" -gt 0 ]]; then log_pass "$1"; else log_info "$1"; fi
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+check_required_files() {
+    log_section "Group 1: Required App Repo Files"
+
+    local checks_passed=0
+    local checks_failed=0
+
+    # 1a. service-architecture.md
+    local service_arch=""
+    if [[ -f "$APP_ROOT/docs/service-architecture.md" ]]; then
+        service_arch="$APP_ROOT/docs/service-architecture.md"
+    elif [[ -f "$APP_ROOT/service-architecture.md" ]]; then
+        service_arch="$APP_ROOT/service-architecture.md"
+    fi
+
+    if [[ -z "$service_arch" ]]; then
+        log_fail "service-architecture.md not found (checked docs/service-architecture.md and service-architecture.md)"
+        checks_failed=$((checks_failed + 1))
+    else
+        log_found "service-architecture.md found: ${service_arch#$APP_ROOT/}"
+        checks_passed=$((checks_passed + 1))
+    fi
+
+    # 1b. feature-tree.md
+    local feature_tree=""
+    if [[ -f "$APP_ROOT/docs/platform/feature-tree.md" ]]; then
+        feature_tree="$APP_ROOT/docs/platform/feature-tree.md"
+    elif [[ -f "$APP_ROOT/docs/feature-tree.md" ]]; then
+        feature_tree="$APP_ROOT/docs/feature-tree.md"
+    elif [[ -f "$APP_ROOT/feature-tree.md" ]]; then
+        feature_tree="$APP_ROOT/feature-tree.md"
+    fi
+
+    if [[ -z "$feature_tree" ]]; then
+        log_warn "feature-tree.md not found (checked docs/platform/, docs/, and repo root) — create when features are classified"
+        # warn only; not a hard fail at exploration stage
+    else
+        log_found "feature-tree.md found: ${feature_tree#$APP_ROOT/}"
+        checks_passed=$((checks_passed + 1))
+    fi
+
+    # 1c. app-platform-dependencies.yaml
+    if [[ -f "$APP_ROOT/app-platform-dependencies.yaml" ]]; then
+        log_found "app-platform-dependencies.yaml found"
+        checks_passed=$((checks_passed + 1))
+    else
+        log_fail "app-platform-dependencies.yaml not found in repo root"
+        checks_failed=$((checks_failed + 1))
+    fi
+
+    if [[ "$checks_failed" -gt 0 ]]; then
+        FAILURES=$((FAILURES + checks_failed))
+    fi
+
+    log_info "Group 1: $checks_passed passed, $checks_failed failed"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+check_feature_specs() {
+    log_section "Group 2: Feature Spec Section Validation"
+
+    local required_sections=("## Overview" "## Acceptance Criteria" "## Platform Contract Dependencies")
+    local specs_found=0
+    local specs_failed=0
+    local specs_passed=0
+
+    # Discover feature specs under features/*/
+    local feature_spec
+    while IFS= read -r feature_spec; do
+        specs_found=$((specs_found + 1))
+        local rel="${feature_spec#$APP_ROOT/}"
+        local file_failures=0
+
+        for section in "${required_sections[@]}"; do
+            if ! grep -q "^${section}" "$feature_spec" 2>/dev/null; then
+                log_fail "$rel: missing required section '$section'"
+                file_failures=$((file_failures + 1))
+            fi
+        done
+
+        if [[ "$file_failures" -eq 0 ]]; then
+            log_pass "$rel: all required sections present"
+            specs_passed=$((specs_passed + 1))
+        else
+            specs_failed=$((specs_failed + 1))
+            FAILURES=$((FAILURES + file_failures))
+        fi
+    done < <(find "$APP_ROOT/features" -type f -name "*.md" 2>/dev/null | sort)
+
+    if [[ "$specs_found" -eq 0 ]]; then
+        log_info "No feature specs found under features/ — skipping section validation"
+        return 0
+    fi
+
+    log_info "Group 2: $specs_passed/$specs_found feature specs passed, $specs_failed failed"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+main() {
+    log_section "App Documentation Validation"
+    log_info "App root: $APP_ROOT"
+
+    check_required_files
+    check_feature_specs
+
+    log_section "Summary"
+
+    if [[ "$FAILURES" -eq 0 && "$FEATURE_SPEC_COUNT" -eq 0 ]]; then
+        log_na "App documentation: required files present, but 0 feature specs found under features/ — nothing to check"
+        exit 0
+    elif [[ "$FAILURES" -eq 0 ]]; then
+        log_pass "All app documentation checks passed."
+        exit 0
+    else
+        log_fail "$FAILURES check(s) failed."
+        exit 1
+    fi
+}
+
+main "$@"