@sdd-method/verify-cli 0.1.0 → 0.2.0

package/scripts/validate-integration-docs.sh

@@ -0,0 +1,505 @@
+#!/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/templates/feature-grounding-integration-template.md"
+        "docs/method/methods/workflows/integration-delivery-workflow-guide.md"
+        "docs/method/methods/templates/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
+
+    # Interaction patterns (ADR 0171) — optional fields, validated only when present.
+    # Existing manifests predate the field; absence is not a failure. Directionality
+    # mismatch (pattern present but the matching capability flag is false) is a warning.
+    local ingestion invocation
+    ingestion="$(yq e '.ingestionPattern // ""' "$manifest")"
+    invocation="$(yq e '.invocationPattern // ""' "$manifest")"
+
+    if [[ -n "$ingestion" && "$ingestion" != "null" ]]; then
+        case "$ingestion" in
+            event-stream-consume|webhook|socket-listen|poll)
+                log_pass "integration-manifest.yaml: ingestionPattern '$ingestion' valid"
+                # if/fi for the same reason as the invocationPattern warn below:
+                # safe only because more code follows, which is not a property
+                # worth relying on.
+                if [[ "$inbound" != "true" ]]; then
+                    log_warn "integration-manifest.yaml: ingestionPattern set but capabilityFlags.inbound is not true"
+                fi
+                ;;
+            *)
+                log_fail "integration-manifest.yaml: ingestionPattern '$ingestion' not in {event-stream-consume, webhook, socket-listen, poll} — if this provider is none of the four, pick the pattern matching the MECHANICS and move the distinguishing semantics to patternQualifier (free-text); minting a pattern value is a method change"
+                FAILURES=$((FAILURES + 1))
+                ;;
+        esac
+    fi
+
+    if [[ -n "$invocation" && "$invocation" != "null" ]]; then
+        case "$invocation" in
+            request-response|async-request|publish)
+                log_pass "integration-manifest.yaml: invocationPattern '$invocation' valid"
+                # Explicit if/fi, NOT `[[ ... ]] && log_warn`. As the last
+                # statement in this function, a false test made the function
+                # return 1, and under `set -e` that aborted the whole run before
+                # Group 4 — so the check fired on the CORRECT case (a manifest
+                # that declares invocationPattern and properly sets
+                # outbound: true), and the better-formed the manifest, the more
+                # certainly its grounding evidence went unchecked.
+                if [[ "$outbound" != "true" ]]; then
+                    log_warn "integration-manifest.yaml: invocationPattern set but capabilityFlags.outbound is not true"
+                fi
+                ;;
+            *)
+                log_fail "integration-manifest.yaml: invocationPattern '$invocation' not in {request-response, async-request, publish}"
+                FAILURES=$((FAILURES + 1))
+                ;;
+        esac
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Unedited-scaffold-residue lint (WARN-only).
+#
+# WHAT THIS MEASURES, and what it deliberately does not: residue measures
+# **authoring completeness** — how much of the scaffold is still untouched. It is
+# NOT a signal for whether an SDD models a real provider. Those are independent
+# properties, measured to be so: on one estate 5 SDDs are demonstrations and 11
+# carry residue, because six REAL integrations are simply not authored yet. A
+# residue list is therefore an authoring WORK QUEUE, never a census of
+# demonstrations. Do not re-couple it to the `exemplar` trait.
+#
+# THE TEMPLATE IS THE ORACLE. Residue is defined as template text that survived
+# into the authored document, so the shipped template is read at runtime and the
+# comparison is exact. This matters for two reasons:
+#   1. It is self-maintaining. An earlier attempt at this check hardcoded a list
+#      of placeholder strings; the list silently went stale, so tokens from other
+#      templates read as real content.
+#   2. It separates residue from a brace that is legitimately authored. A JSON
+#      example containing `{` is not residue; the exact string `{provider field}`
+#      is, because the template is where it comes from.
+#
+# WHAT IS LEGITIMATELY RETAINED — state this half or the rule flags correct
+# authoring. Template text kept as STRUCTURE is right and must never be reported:
+#   - section headings (`^#`) — a cohort of SDDs sharing one standard deliberately
+#     keeps the method's section shape while filling it with real content, and that
+#     is exactly correct authoring;
+#   - table header and separator rows (`^|`);
+#   - short shared lines — a bare path, a field label — dropped by a length floor.
+# Residue is template text left IN THE SLOTS, never template text AS STRUCTURE.
+#
+# THREE SHAPES OF RESIDUE, and only two are detectable:
+#   1. Unfilled placeholder tokens      — detected (exact token match).
+#   2. Leftover instruction prose       — detected (exact line match).
+#   3. Unmodified example table rows    — NOT ATTEMPTED, on evidence rather than
+#      difficulty: every placeholder-free table row in the shipped templates is a
+#      table HEADER row, which an authored document is supposed to retain. Rows
+#      that do carry placeholders are already caught by shape 1. So verbatim-row
+#      matching would flag precisely the lines that should survive and add no
+#      signal that shape 1 misses.
+# ---------------------------------------------------------------------------
+
+# Templates that may reach an integration SDD (forward via integration-baseline,
+# reverse via reverse-extension-baseline). Whichever are present are used.
+GROUNDING_TEMPLATES=(
+    "docs/method/methods/templates/feature-grounding-integration-template.md"
+    "docs/method/methods/reverse/templates/integration-product/docs/design/integration/feature-grounding.md"
+)
+
+# Cap on reported items per class — an untouched scaffold would otherwise bury
+# the rest of the run. The count is always reported in full, per no-silent-caps.
+RESIDUE_REPORT_CAP=5
+
+check_grounding_residue() {
+    local grounding="$1"
+    local rel="docs/design/integration/feature-grounding.md"
+
+    local -a templates=()
+    local t
+    for t in "${GROUNDING_TEMPLATES[@]}"; do
+        [[ -f "$REPO_ROOT/$t" ]] && templates+=("$REPO_ROOT/$t")
+    done
+
+    # Never pass silently for want of an oracle: "no residue found" and "could
+    # not look" must not be the same output.
+    if [[ ${#templates[@]} -eq 0 ]]; then
+        log_warn "$rel: cannot check scaffold residue — no grounding template present in this repo (expected one of: ${GROUNDING_TEMPLATES[*]})"
+        return
+    fi
+
+    # --- Shape 1: unfilled placeholder tokens -------------------------------
+    # `|| true` on every match pipeline below: grep exits 1 on no-match, and
+    # under `set -euo pipefail` that aborts the run at the assignment. "Found
+    # nothing" is the expected result for a well-authored document, so it must not
+    # be fatal — this is the same trap that was silently killing Group 4.
+    local tokens
+    tokens="$(grep -ohE '\{[^}]{1,80}\}' "${templates[@]}" 2>/dev/null | sort -u || true)"
+
+    local -a hits=()
+    local token
+    while IFS= read -r token; do
+        [[ -z "$token" ]] && continue
+        local lines
+        lines="$(grep -Fn -- "$token" "$grounding" 2>/dev/null | cut -d: -f1 | paste -sd, - || true)"
+        [[ -n "$lines" ]] && hits+=("line ${lines}: ${token}")
+    done <<< "$tokens"
+
+    if [[ ${#hits[@]} -gt 0 ]]; then
+        log_warn "$rel: ${#hits[@]} unfilled placeholder token(s) from the shipped template — authoring incomplete (not a demonstration marker)"
+        local i
+        for ((i = 0; i < ${#hits[@]} && i < RESIDUE_REPORT_CAP; i++)); do
+            echo "    - ${hits[$i]}"
+        done
+        if [[ ${#hits[@]} -gt $RESIDUE_REPORT_CAP ]]; then
+            echo "    - … and $(( ${#hits[@]} - RESIDUE_REPORT_CAP )) more"
+        fi
+    fi
+
+    # --- Shape 2: leftover template instruction prose -----------------------
+    # Prose only: headings and table rows are structure an authored document
+    # legitimately keeps. The length floor drops short shared lines (a bare path
+    # or a field label) that carry no instruction and would false-positive.
+    local -a prose_hits=()
+    local line
+    while IFS= read -r line; do
+        [[ ${#line} -lt 60 ]] && continue
+        if grep -Fxq -- "$line" "$grounding" 2>/dev/null; then
+            prose_hits+=("$line")
+        fi
+    done < <(grep -hvE '^#|^\||^$|^[[:space:]]*$' "${templates[@]}" 2>/dev/null | sort -u || true)
+
+    if [[ ${#prose_hits[@]} -gt 0 ]]; then
+        log_warn "$rel: ${#prose_hits[@]} line(s) of template instruction prose retained verbatim"
+        local j
+        for ((j = 0; j < ${#prose_hits[@]} && j < RESIDUE_REPORT_CAP; j++)); do
+            local shown="${prose_hits[$j]}"
+            [[ ${#shown} -gt 90 ]] && shown="${shown:0:90}…"
+            echo "    - ${shown}"
+        done
+        if [[ ${#prose_hits[@]} -gt $RESIDUE_REPORT_CAP ]]; then
+            echo "    - … and $(( ${#prose_hits[@]} - RESIDUE_REPORT_CAP )) more"
+        fi
+    fi
+
+    if [[ ${#hits[@]} -eq 0 && ${#prose_hits[@]} -eq 0 ]]; then
+        log_pass "$rel: no unedited scaffold residue detected"
+    fi
+}
+
+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
+
+    # Substance, not just presence. The checks above establish that the required
+    # sections EXIST; this one asks whether they were filled in. WARN-only and
+    # never incrementing FAILURES: an estate must not turn red for being honest
+    # about its authoring state, and an exploration-stage integration is a
+    # legitimate thing to have.
+    check_grounding_residue "$grounding"
+}
+
+main() {
+    log_section "Integration Documentation Validation"
+    log_info "Repo root: $REPO_ROOT"
+
+    check_repo_kind
+    check_required_files
+    check_manifest
+    check_grounding_doc
+    check_components_declaration
+
+    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
+}
+
+# Components declaration (M-ADR 0212-era coordination: the agreed four-state design).
+#
+# Asks only for the INVENTORY, never for per-component patterns: `id` is the sole
+# required field of a components[] entry, so an inventory-only block is complete and
+# conformant. Measured authoring cost was under a minute per SDD for the inventory and
+# up to twenty-five for the patterns, and a warn cannot make the second cheaper — a
+# warn nobody can afford to clear becomes a warn everybody filters.
+#
+# Counts components from each repo's OWN `profile` in reverse-metadata.yaml, never from
+# catalogue row counts: catalogue rows include support repos, so row counting over-counts
+# every SDD that mirrors a shared library.
+#
+# Zero is three different facts and they are reported separately. Collapsing them is what
+# would bury the only one that is a defect.
+check_components_declaration() {
+    local manifest="$REPO_ROOT/integration-manifest.yaml"
+    [[ -f "$manifest" ]] || return 0
+
+    local repos_dir="$REPO_ROOT/repos"
+    local components=0 support=0 unreadable=0
+
+    if [[ -d "$repos_dir" ]]; then
+        local d meta profile
+        for d in "$repos_dir"/*/; do
+            meta="$d/reverse-metadata.yaml"
+            [[ -f "$meta" ]] || continue
+            # A file that EXISTS and yields no profile is not the same fact as one that
+            # is absent, and the fallback treats them identically. Say so — this is the
+            # defect that hid a mis-typed repo through an otherwise correct rebuild.
+            if ! profile="$(yq e '.profile // ""' "$meta" 2>/dev/null)" || [[ -z "$profile" || "$profile" == "null" ]]; then
+                unreadable=$((unreadable + 1))
+                log_warn "repos/$(basename "$d")/reverse-metadata.yaml: no readable \`profile\` — this repo is not counted, so the component total below may be low"
+                continue
+            fi
+            case "$profile" in
+                integration-product) components=$((components + 1)) ;;
+                support-repo) support=$((support + 1)) ;;
+            esac
+        done
+    fi
+
+    local catalogue="$REPO_ROOT/catalogues/repositories.csv"
+    local catalogued=-1
+    if [[ -f "$catalogue" ]]; then
+        catalogued="$(awk -F, 'NR>1 && $5=="integration-product"' "$catalogue" 2>/dev/null | wc -l)"
+    fi
+
+    # Fall back to the catalogue only when there is no per-repo evidence at all.
+    if [[ "$components" -eq 0 && "$support" -eq 0 && "$unreadable" -eq 0 && "$catalogued" -gt 0 ]]; then
+        components="$catalogued"
+    fi
+
+    local declared="no"
+    yq e 'has("components")' "$manifest" 2>/dev/null | grep -q true && declared="yes"
+
+    # (c) The two sources disagree in the one direction that is a defect: components
+    # exist on disk and the catalogue holds none. Reported whatever the count bucket,
+    # and deliberately louder than the declaration warn — it is the only state here
+    # that means something is broken rather than merely undeclared.
+    if [[ "$components" -gt 0 && "$catalogued" -eq 0 ]]; then
+        log_warn "catalogues/repositories.csv holds NO integration-product rows while repos/ holds $components — the catalogue was never built for this SDD. Declaring components will not fix it; rebuild the catalogue."
+    fi
+
+    if [[ "$components" -gt 1 ]]; then
+        if [[ "$declared" == "yes" ]]; then
+            local entries
+            entries="$(yq e '.components | length' "$manifest" 2>/dev/null || echo 0)"
+            [[ "$entries" =~ ^[0-9]+$ ]] || entries=0
+            # Asymmetric on purpose. Declaring MORE than repos/ holds is legitimate —
+            # components that are generated or held elsewhere are real and uncloned
+            # (the same case as the support-repo-only SDDs below). Declaring FEWER means
+            # mirrored components the inventory does not mention, which is a declaration
+            # that was true when written and quietly is not now.
+            if [[ "$entries" -lt "$components" ]]; then
+                log_warn "integration-manifest.yaml: \`components:\` declares $entries entr(ies) but repos/ holds $components component repos — the inventory omits $((components - entries)). A declared inventory that stops being true is worse than an absent one."
+            else
+                log_pass "integration-manifest.yaml: components declared ($entries entr(ies), $components component repos in repos/)"
+            fi
+        else
+            log_warn "integration-manifest.yaml: $components component repos in repos/, no \`components:\` block — the inventory is undeclared. Only \`id\` is required per entry; patterns are optional."
+        fi
+        return 0
+    fi
+
+    if [[ "$components" -eq 1 ]]; then
+        log_pass "integration-manifest.yaml: single-component integration — the manifest's own patterns are the whole truth"
+        return 0
+    fi
+
+    # (a) Entries exist, none of them a component: the components live elsewhere.
+    if [[ "$support" -gt 0 ]]; then
+        log_info "0 component repos; $support support repo(s) — components are not cloned into this SDD (generated, or held elsewhere). Nothing owed."
+        return 0
+    fi
+
+    # (b) Nothing mirrored at all: a spec-first SDD being silent about components is
+    # a spec-first SDD behaving correctly.
+    log_info "0 component repos and nothing mirrored — no inventory to declare yet."
+}
+
+main "$@"