@kabran-tecnologia/kabran-config 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",
@@ -11,7 +11,9 @@
   "bin": {
     "kabran-setup": "src/scripts/setup.mjs",
     "kabran-ci": "src/scripts/ci/ci-runner.sh",
-    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs"
+    "kabran-pr-comment": "src/scripts/pr-quality-comment.mjs",
+    "kabran-traceability": "src/scripts/traceability/validate-traceability.sh",
+    "kabran-coverage": "src/scripts/traceability/coverage-report.sh"
   },
   "exports": {
     "./eslint": "./src/eslint.mjs",
@@ -29,6 +31,7 @@
     "./scripts/env-validator": "./src/scripts/env-validator.mjs",
     "./scripts/ci/*": "./src/scripts/ci/*",
     "./scripts/deploy/*": "./src/scripts/deploy/*",
+    "./scripts/traceability/*": "./src/scripts/traceability/*",
     "./scripts/setup": "./src/scripts/setup.mjs",
     "./scripts/quality-standard-validator": "./src/scripts/quality-standard-validator.mjs",
     "./scripts/generate-ci-result": "./src/scripts/generate-ci-result.mjs",

package/src/scripts/traceability/coverage-report.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Coverage Report
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+#
+# Generates a report of spec coverage in the codebase.
+# Shows which specs have code implementing them and which ACs are covered.
+# ==============================================================================
+
+set -euo pipefail
+
+# Source core functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=traceability-core.sh
+source "$SCRIPT_DIR/traceability-core.sh"
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+
+SEARCH_PATH="${1:-.}"
+SPEC_FILTER="${2:-}"
+OUTPUT_FORMAT="${OUTPUT_FORMAT:-text}"
+
+# ==============================================================================
+# Report Functions
+# ==============================================================================
+
+# Generate report for a specific spec
+report_spec() {
+  local spec="$1"
+  local files
+
+  files=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null || true)
+
+  if [ -z "$files" ]; then
+    return
+  fi
+
+  echo ""
+  echo "=== $spec ==="
+  echo ""
+  echo "Files:"
+  echo "$files" | while read -r file; do
+    [ -n "$file" ] && echo "  - $file"
+  done
+
+  echo ""
+  echo "ACs Implemented:"
+  echo "$files" | while read -r file; do
+    [ -n "$file" ] && extract_implements "$file"
+  done | sort -u | while read -r ac; do
+    [ -n "$ac" ] && echo "  - $ac"
+  done
+}
+
+# Generate summary report
+report_summary() {
+  log_section "Traceability Coverage Report v${TRACEABILITY_VERSION}"
+  log_info "Search path: $SEARCH_PATH"
+  echo ""
+
+  local total_files
+  local tagged_files
+  local specs
+
+  total_files=$(count_total_files "$SEARCH_PATH")
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+
+  echo "## Overview"
+  echo ""
+  echo "| Metric | Value |"
+  echo "|--------|-------|"
+  echo "| Total TypeScript files | $total_files |"
+  echo "| Files with @spec | $tagged_files |"
+
+  if [ "$total_files" -gt 0 ]; then
+    local coverage=$((tagged_files * 100 / total_files))
+    echo "| Coverage | $coverage% |"
+  fi
+
+  echo ""
+  echo "## Specs Found"
+  echo ""
+
+  # Find all unique specs
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  if [ -z "$specs" ]; then
+    echo "No @spec tags found in codebase."
+    return
+  fi
+
+  echo "$specs" | while read -r spec; do
+    if [ -n "$spec" ]; then
+      local file_count
+      file_count=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | wc -l)
+      echo "- **$spec**: $file_count files"
+    fi
+  done
+}
+
+# Generate detailed report for all specs
+report_detailed() {
+  report_summary
+
+  echo ""
+  echo "## Detailed Coverage"
+
+  local specs
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  if [ -n "$specs" ]; then
+    echo "$specs" | while read -r spec; do
+      [ -n "$spec" ] && report_spec "$spec"
+    done
+  fi
+}
+
+# Generate JSON report
+report_json() {
+  local total_files
+  local tagged_files
+  local specs
+
+  total_files=$(count_total_files "$SEARCH_PATH")
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+  specs=$(grep -roh '@spec S[0-9]*' --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | sed 's/@spec //' | sort -u || true)
+
+  local coverage=0
+  if [ "$total_files" -gt 0 ]; then
+    coverage=$((tagged_files * 100 / total_files))
+  fi
+
+  echo "{"
+  echo "  \"version\": \"${TRACEABILITY_VERSION}\","
+  echo "  \"searchPath\": \"$SEARCH_PATH\","
+  echo "  \"totalFiles\": $total_files,"
+  echo "  \"taggedFiles\": $tagged_files,"
+  echo "  \"coverage\": $coverage,"
+  echo "  \"specs\": ["
+
+  local first=true
+  if [ -n "$specs" ]; then
+    echo "$specs" | while read -r spec; do
+      if [ -n "$spec" ]; then
+        local file_count
+        file_count=$(grep -rl "@spec $spec" --include="*.ts" --include="*.tsx" "$SEARCH_PATH" 2>/dev/null | wc -l)
+        if [ "$first" = true ]; then
+          first=false
+        else
+          echo ","
+        fi
+        echo -n "    { \"id\": \"$spec\", \"files\": $file_count }"
+      fi
+    done
+  fi
+
+  echo ""
+  echo "  ]"
+  echo "}"
+}
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Kabran Traceability Coverage Report v${TRACEABILITY_VERSION}
+
+Usage: coverage-report.sh [path] [spec] [options]
+
+Arguments:
+  path              Directory to scan (default: current directory)
+  spec              Filter by specific spec ID (e.g., S25)
+
+Environment Variables:
+  OUTPUT_FORMAT     Output format: text, detailed, json (default: text)
+
+Examples:
+  coverage-report.sh ./src
+  coverage-report.sh ./src S25
+  OUTPUT_FORMAT=json coverage-report.sh ./src
+  OUTPUT_FORMAT=detailed coverage-report.sh ./src
+
+Output Formats:
+  text              Summary with spec counts
+  detailed          Full breakdown with files and ACs per spec
+  json              Machine-readable JSON output
+
+EOF
+}
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+  exit 0
+fi
+
+# Handle specific spec filter
+if [ -n "$SPEC_FILTER" ]; then
+  report_spec "$SPEC_FILTER"
+  exit 0
+fi
+
+# Generate report based on format
+case "$OUTPUT_FORMAT" in
+  json)
+    report_json
+    ;;
+  detailed)
+    report_detailed
+    ;;
+  *)
+    report_summary
+    ;;
+esac

package/src/scripts/traceability/traceability-core.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Core - Shared Functions
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+# ==============================================================================
+
+# Version - Dynamically resolve from package.json
+_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_PKG_JSON="$_SCRIPT_DIR/../../../package.json"
+if [ -f "$_PKG_JSON" ]; then
+  TRACEABILITY_VERSION=$(grep '"version":' "$_PKG_JSON" | head -1 | sed -E 's/.*"version": "([^"]+)".*/\1/')
+else
+  TRACEABILITY_VERSION="unknown"
+fi
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+GRAY='\033[0;90m'
+NC='\033[0m'
+
+# ==============================================================================
+# Logging Functions
+# ==============================================================================
+
+log_info() {
+  echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+  echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}[FAIL]${NC} $1"
+}
+
+log_warn() {
+  echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_section() {
+  echo -e "\n${BLUE}====${NC} $1 ${BLUE}====${NC}"
+}
+
+# ==============================================================================
+# Tag Patterns (PROP-006 Standard)
+# ==============================================================================
+
+# Valid @spec format: @spec SXX (ID only, not full name)
+PATTERN_SPEC_VALID='@spec S[0-9]+'
+PATTERN_SPEC_INVALID='@spec S[0-9]+-'
+
+# Valid @implements format: @implements AC-XX or @implements SXX:AC-XX
+PATTERN_IMPLEMENTS='@implements'
+
+# Valid @task format: @task XXX-NNN
+PATTERN_TASK='@task [A-Z]+-[0-9]+'
+
+# Valid @prd format: @prd RF-XXX or @prd RNF-XXX
+PATTERN_PRD='@prd R(N)?F-[0-9]+'
+
+# ==============================================================================
+# Validation Functions
+# ==============================================================================
+
+# Check if a file has @implements without @spec (integrity error)
+# Usage: check_orphan_implements "path/to/file.ts"
+# Returns: 0 if valid, 1 if orphan found
+check_orphan_implements() {
+  local file="$1"
+
+  if grep -qE "$PATTERN_IMPLEMENTS" "$file" 2>/dev/null; then
+    if ! grep -qE "$PATTERN_SPEC_VALID" "$file" 2>/dev/null; then
+      return 1  # Orphan found
+    fi
+  fi
+  return 0  # Valid
+}
+
+# Check if a file uses invalid @spec format (full name instead of ID)
+# Usage: check_spec_format "path/to/file.ts"
+# Returns: 0 if valid, 1 if invalid format found
+check_spec_format() {
+  local file="$1"
+
+  if grep -qE "$PATTERN_SPEC_INVALID" "$file" 2>/dev/null; then
+    return 1  # Invalid format
+  fi
+  return 0  # Valid
+}
+
+# Extract all @spec tags from a file
+# Usage: extract_specs "path/to/file.ts"
+extract_specs() {
+  local file="$1"
+  grep -oE '@spec S[0-9]+' "$file" 2>/dev/null | sed 's/@spec //' | sort -u
+}
+
+# Extract all @implements tags from a file
+# Usage: extract_implements "path/to/file.ts"
+extract_implements() {
+  local file="$1"
+  grep -oE '@implements [^*]+' "$file" 2>/dev/null | sed 's/@implements //' | tr ',' '\n' | sed 's/^ *//' | sort -u
+}
+
+# Count files with traceability tags
+# Usage: count_tagged_files "path/to/search"
+count_tagged_files() {
+  local search_path="${1:-.}"
+  grep -rl "@spec" --include="*.ts" --include="*.tsx" "$search_path" 2>/dev/null | wc -l
+}
+
+# Count total TypeScript files
+# Usage: count_total_files "path/to/search"
+count_total_files() {
+  local search_path="${1:-.}"
+  find "$search_path" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null | wc -l
+}

package/src/scripts/traceability/validate-traceability.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Kabran Traceability Validator
+# Part of @kabran-owner/kabran-config
+# Implements PROP-006: JSDoc Traceability Tags
+#
+# Validates FORMAT of traceability tags (not presence).
+# Tags are optional - this script only checks:
+# 1. @implements without @spec (integrity error)
+# 2. @spec with full name instead of ID (format warning)
+# ==============================================================================
+
+set -uo pipefail
+
+# Source core functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=traceability-core.sh
+source "$SCRIPT_DIR/traceability-core.sh"
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+
+SEARCH_PATH="${1:-.}"
+STRICT_MODE="${STRICT_MODE:-false}"
+EXIT_CODE=0
+
+# ==============================================================================
+# Main Validation
+# ==============================================================================
+
+main() {
+  log_section "Traceability Validation v${TRACEABILITY_VERSION}"
+  log_info "Search path: $SEARCH_PATH"
+  log_info "Strict mode: $STRICT_MODE"
+
+  local orphan_count=0
+  local format_count=0
+  local files_checked=0
+
+  # Find all TypeScript files
+  local files
+  files=$(find "$SEARCH_PATH" -type f \( -name "*.ts" -o -name "*.tsx" \) 2>/dev/null || true)
+
+  if [ -z "$files" ]; then
+    log_info "No TypeScript files found"
+    return 0
+  fi
+
+  while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    files_checked=$((files_checked + 1))
+
+    # Check for orphan @implements (ERROR)
+    if ! check_orphan_implements "$file"; then
+      log_error "Orphan @implements (no @spec): $file"
+      orphan_count=$((orphan_count + 1))
+    fi
+
+    # Check for invalid @spec format (WARNING)
+    if ! check_spec_format "$file"; then
+      log_warn "Invalid @spec format (use ID only): $file"
+      format_count=$((format_count + 1))
+    fi
+
+  done <<< "$files"
+
+  # Summary
+  log_section "Validation Summary"
+  log_info "Files checked: $files_checked"
+
+  if [ "$orphan_count" -gt 0 ]; then
+    log_error "Orphan @implements found: $orphan_count"
+    EXIT_CODE=1
+  else
+    log_success "No orphan @implements found"
+  fi
+
+  if [ "$format_count" -gt 0 ]; then
+    log_warn "Invalid @spec format: $format_count"
+    if [ "$STRICT_MODE" = "true" ]; then
+      EXIT_CODE=1
+    fi
+  else
+    log_success "All @spec tags use correct format"
+  fi
+
+  # Coverage stats (informational)
+  local tagged_files
+  local total_files
+  tagged_files=$(count_tagged_files "$SEARCH_PATH")
+  total_files=$(count_total_files "$SEARCH_PATH")
+
+  if [ "$total_files" -gt 0 ]; then
+    local coverage=$((tagged_files * 100 / total_files))
+    log_info "Traceability coverage: $tagged_files/$total_files files ($coverage%)"
+  fi
+
+  return $EXIT_CODE
+}
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Kabran Traceability Validator v${TRACEABILITY_VERSION}
+
+Usage: validate-traceability.sh [path] [options]
+
+Arguments:
+  path              Directory to validate (default: current directory)
+
+Environment Variables:
+  STRICT_MODE       If "true", format warnings become errors (default: false)
+
+Exit Codes:
+  0                 Validation passed
+  1                 Validation failed (orphan @implements or strict mode violations)
+
+Examples:
+  validate-traceability.sh ./src
+  STRICT_MODE=true validate-traceability.sh ./src
+
+Tags Validated (PROP-006):
+  @spec S25         Link to spec (ID only, not full name)
+  @implements AC-01 Acceptance criteria implemented
+  @task AGT-123     Link to Linear task
+  @prd RF-007       Link to PRD requirement
+
+Rules:
+  - All tags are OPTIONAL
+  - @implements WITHOUT @spec is an ERROR
+  - @spec with full name (S25-name) is a WARNING
+
+EOF
+}
+
+# ==============================================================================
+# Entry Point
+# ==============================================================================
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+  exit 0
+fi
+
+main
+exit $EXIT_CODE