@sdd-method/sdd-cli 0.9.0

package/scripts/validate-app-docs.sh

@@ -0,0 +1,185 @@
+#!/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"; }
+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
+
+# ──────────────────────────────────────────────────────────────────────────────
+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_pass "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_pass "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_pass "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 ]]; then
+        log_pass "All app documentation checks passed."
+        exit 0
+    else
+        log_fail "$FAILURES check(s) failed."
+        exit 1
+    fi
+}
+
+main "$@"

package/scripts/validate-integration-docs.sh

@@ -0,0 +1,222 @@
+#!/bin/bash
+#
+# validate-integration-docs.sh - Validate integration repo documentation structure
+#
+# Usage: ./validate-integration-docs.sh [--repo-root <path>]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+REPO_ROOT="$ROOT_DIR"
+EXPECTED_REPO_KIND="integration-product"
+
+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"; }
+log_section() {
+    echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+    echo -e "${BLUE}  $1${NC}"
+    echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo-root)
+            REPO_ROOT="${2:-}"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: $(basename "$0") [--repo-root <path>]"
+            exit 0
+            ;;
+        *)
+            log_fail "Unknown argument: $1"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -d "$REPO_ROOT" ]]; then
+    log_fail "Repo root not found: $REPO_ROOT"
+    exit 1
+fi
+
+command -v yq >/dev/null 2>&1 || {
+    log_fail "yq is required. Install it before running $(basename "$0")."
+    exit 1
+}
+
+FAILURES=0
+
+check_repo_kind() {
+    log_section "Group 1: Repo Kind"
+
+    local marker="$REPO_ROOT/.sdd-repo-kind"
+    if [[ ! -f "$marker" ]]; then
+        log_fail ".sdd-repo-kind not found"
+        FAILURES=$((FAILURES + 1))
+        return
+    fi
+
+    local value
+    value="$(tr -d '[:space:]' < "$marker")"
+    if [[ "$value" != "$EXPECTED_REPO_KIND" ]]; then
+        log_fail "Expected repo kind '$EXPECTED_REPO_KIND', found '$value'"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "Repo kind marker present: $value"
+    fi
+}
+
+check_required_files() {
+    log_section "Group 2: Required Files"
+
+    local files=(
+        "integration-manifest.yaml"
+        "docs/service-architecture.md"
+        "docs/method/methods/feature-grounding-integration-template.md"
+        "docs/method/methods/integration-delivery-workflow-guide.md"
+        "docs/method/methods/integration-service-architecture-template.md"
+    )
+    local rel
+
+    for rel in "${files[@]}"; do
+        if [[ -f "$REPO_ROOT/$rel" ]]; then
+            log_pass "$rel found"
+        else
+            log_fail "$rel missing"
+            FAILURES=$((FAILURES + 1))
+        fi
+    done
+}
+
+check_manifest() {
+    log_section "Group 3: Manifest Structure"
+
+    local manifest="$REPO_ROOT/integration-manifest.yaml"
+    if [[ ! -f "$manifest" ]]; then
+        log_fail "integration-manifest.yaml missing; cannot validate structure"
+        FAILURES=$((FAILURES + 1))
+        return
+    fi
+
+    local required_scalars=("integrationId" "providerName" "version" "profileType" "sdkVersion" "publishedBy" "bindingModel")
+    local field value
+    for field in "${required_scalars[@]}"; do
+        value="$(yq e ".${field} // \"\"" "$manifest")"
+        if [[ -z "$value" || "$value" == "null" || "$value" == "TBD" ]]; then
+            log_fail "integration-manifest.yaml: '$field' missing or placeholder"
+            FAILURES=$((FAILURES + 1))
+        else
+            log_pass "integration-manifest.yaml: '$field' set"
+        fi
+    done
+
+    local inbound outbound asset_count profile
+    inbound="$(yq e '.capabilityFlags.inbound' "$manifest")"
+    outbound="$(yq e '.capabilityFlags.outbound' "$manifest")"
+    profile="$(yq e '.profileType // ""' "$manifest")"
+    asset_count="$(yq e '.supportedAssetTypes | length' "$manifest" 2>/dev/null || echo 0)"
+
+    if [[ "$inbound" != "true" && "$inbound" != "false" ]]; then
+        log_fail "integration-manifest.yaml: capabilityFlags.inbound must be true or false"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "integration-manifest.yaml: capabilityFlags.inbound set"
+    fi
+
+    if [[ "$outbound" != "true" && "$outbound" != "false" ]]; then
+        log_fail "integration-manifest.yaml: capabilityFlags.outbound must be true or false"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "integration-manifest.yaml: capabilityFlags.outbound set"
+    fi
+
+    if [[ "$asset_count" -lt 1 ]]; then
+        log_fail "integration-manifest.yaml: supportedAssetTypes must contain at least one value"
+        FAILURES=$((FAILURES + 1))
+    else
+        log_pass "integration-manifest.yaml: supportedAssetTypes populated"
+    fi
+
+    case "$profile" in
+        workflow|financial-services|data-hub|data-feed)
+            if [[ "$outbound" != "false" ]]; then
+                log_fail "integration-manifest.yaml: profileType '$profile' should default outbound capability to false"
+                FAILURES=$((FAILURES + 1))
+            else
+                log_pass "integration-manifest.yaml: inbound-only profile directionality is coherent"
+            fi
+            ;;
+        *)
+            ;;
+    esac
+}
+
+check_grounding_doc() {
+    log_section "Group 4: Grounding Evidence"
+
+    local grounding="$REPO_ROOT/docs/design/integration/feature-grounding.md"
+    if [[ ! -f "$grounding" ]]; then
+        log_warn "docs/design/integration/feature-grounding.md not found — create before lock-in"
+        return
+    fi
+
+    local manifest="$REPO_ROOT/integration-manifest.yaml"
+    local outbound
+    outbound="$(yq e '.capabilityFlags.outbound' "$manifest" 2>/dev/null || echo "")"
+
+    local sections=("## Overview" "## Platform Contract Boundary" "## Provider-to-Canonical Field Mapping" "## Identity Resolution and Routing" "## Security and Secrets")
+    local section
+    local missing=0
+    for section in "${sections[@]}"; do
+        if ! grep -q "^${section}" "$grounding"; then
+            log_fail "docs/design/integration/feature-grounding.md missing section '$section'"
+            FAILURES=$((FAILURES + 1))
+            missing=1
+        fi
+    done
+
+    if [[ "$missing" -eq 0 ]]; then
+        log_pass "docs/design/integration/feature-grounding.md contains required sections"
+    fi
+
+    if [[ "$outbound" == "true" ]]; then
+        if grep -q "^## Command Mapping" "$grounding"; then
+            log_pass "docs/design/integration/feature-grounding.md includes command mapping for bidirectional integration"
+        else
+            log_fail "docs/design/integration/feature-grounding.md missing section '## Command Mapping' for bidirectional integration"
+            FAILURES=$((FAILURES + 1))
+        fi
+    fi
+}
+
+main() {
+    log_section "Integration Documentation Validation"
+    log_info "Repo root: $REPO_ROOT"
+
+    check_repo_kind
+    check_required_files
+    check_manifest
+    check_grounding_doc
+
+    log_section "Summary"
+
+    if [[ "$FAILURES" -eq 0 ]]; then
+        log_pass "All integration documentation checks passed."
+        exit 0
+    fi
+
+    log_fail "$FAILURES check(s) failed."
+    exit 1
+}
+
+main "$@"