specline 2.0.0 → 2.0.2

package/templates/.cursor/hooks/specline-pipeline-gate-checks/a2-a3-reverse.sh

@@ -1,171 +0,0 @@
-#!/usr/bin/env bash
-#
-# a2-a3-reverse.sh — A2/A3 反向覆盖验证
-#
-# 从 spec.md 提取所有 Requirement 和 Scenario 名称，
-# 与 tasks.md 中 Covers 字段引用的名称做交叉比对，
-# 输出未被任何任务覆盖的 Requirement 和 Scenario（INFO 级别）。
-#
-# 依赖环境变量:
-#   SPEC_FILE  — spec.md 文件路径
-#   TASKS_FILE — tasks.md 文件路径
-#   SPEC_REVIEW_FILE — 可选，spec-review.json 路径（交叉验证）
-#
-# 使用方式:
-#   source a2-a3-reverse.sh
-#   SPEC_FILE=... TASKS_FILE=... run_a2_a3_reverse
-
-run_a2_a3_reverse() {
-  local spec_file="${SPEC_FILE:-}"
-  local tasks_file="${TASKS_FILE:-}"
-  local review_file="${SPEC_REVIEW_FILE:-}"
-
-  # 验证输入文件
-  if [ -z "$spec_file" ] || [ ! -f "$spec_file" ]; then
-    echo "ERROR: spec.md 文件不存在或未通过 SPEC_FILE 指定: ${spec_file:-未设置}" >&2
-    return 1
-  fi
-  if [ -z "$tasks_file" ] || [ ! -f "$tasks_file" ]; then
-    echo "ERROR: tasks.md 文件不存在或未通过 TASKS_FILE 指定: ${tasks_file:-未设置}" >&2
-    return 1
-  fi
-
-  # =========================================
-  # Step 1: 从 spec.md 提取所有 Requirement 和 Scenario 名称
-  # =========================================
-
-  local tmp_spec_reqs
-  tmp_spec_reqs=$(mktemp) || return 1
-  local tmp_spec_scens
-  tmp_spec_scens=$(mktemp) || return 1
-  local tmp_tasks_reqs
-  tmp_tasks_reqs=$(mktemp) || return 1
-  local tmp_tasks_scens
-  tmp_tasks_scens=$(mktemp) || return 1
-
-  _a2a3_cleanup() {
-    rm -f "${tmp_spec_reqs:-}" "${tmp_spec_scens:-}" "${tmp_tasks_reqs:-}" "${tmp_tasks_scens:-}"
-  }
-  trap _a2a3_cleanup RETURN
-
-  # 从 spec.md 解析 Requirement 和 Scenario
-  local current_req=""
-  while IFS= read -r line; do
-    if [[ "$line" =~ ^###[[:space:]]+Requirement:[[:space:]]+(.+)$ ]]; then
-      current_req="${BASH_REMATCH[1]}"
-      current_req="${current_req%"${current_req##*[![:space:]]}"}"
-      echo "$current_req" >> "$tmp_spec_reqs"
-    elif [[ "$line" =~ ^####[[:space:]]+Scenario:[[:space:]]+(.+)$ ]]; then
-      local scen="${BASH_REMATCH[1]}"
-      scen="${scen%"${scen##*[![:space:]]}"}"
-      if [ -n "$current_req" ]; then
-        printf '%s\t%s\n' "$current_req" "$scen" >> "$tmp_spec_scens"
-      fi
-    fi
-  done < "$spec_file"
-
-  # =========================================
-  # Step 2: 从 tasks.md 提取 Covers 引用的 Requirement 和 Scenario
-  # =========================================
-
-  while IFS= read -r line; do
-    if [[ "$line" =~ \*\*Covers\*\*[[:space:]]*:[[:space:]]*(.+) ]]; then
-      local covers_content="${BASH_REMATCH[1]}"
-
-      # 提取 Requirement 名称
-      if [[ "$covers_content" =~ Requirement:[[:space:]]*([^,，]+) ]]; then
-        local task_req="${BASH_REMATCH[1]}"
-        task_req="${task_req%"${task_req##*[![:space:]]}"}"
-        echo "$task_req" >> "$tmp_tasks_reqs"
-      fi
-
-      # 提取 Scenario 名称
-      if [[ "$covers_content" =~ Scenario:[[:space:]]*(.+)$ ]]; then
-        local scenarios_str="${BASH_REMATCH[1]}"
-        scenarios_str="${scenarios_str%"${scenarios_str##*[![:space:]]}"}"
-
-        # 用 、或 , 或 ，分割 Scenario 名称
-        local cleaned="${scenarios_str//、/ }"
-        cleaned="${cleaned//，/,}"
-        cleaned="${cleaned//,/ }"
-        cleaned="${cleaned//\// }"
-
-        for item in $cleaned; do
-          item="${item#"${item%%[![:space:]]*}"}"
-          item="${item%"${item##*[![:space:]]}"}"
-          if [ -n "$item" ]; then
-            echo "$item" >> "$tmp_tasks_scens"
-          fi
-        done
-      fi
-    fi
-  done < "$tasks_file"
-
-  # =========================================
-  # Step 3: 计算差集 — 未被覆盖的 Requirement 和 Scenario
-  # =========================================
-
-  sort -u "$tmp_spec_reqs" -o "$tmp_spec_reqs" 2>/dev/null || true
-  sort -u "$tmp_spec_scens" -o "$tmp_spec_scens" 2>/dev/null || true
-  sort -u "$tmp_tasks_reqs" -o "$tmp_tasks_reqs" 2>/dev/null || true
-  sort -u "$tmp_tasks_scens" -o "$tmp_tasks_scens" 2>/dev/null || true
-
-  local uncovered_req_count=0
-  local uncovered_scen_count=0
-
-  # 查找未被覆盖的 Requirement
-  if [ -s "$tmp_spec_reqs" ]; then
-    while IFS= read -r req; do
-      if ! grep -qxF "$req" "$tmp_tasks_reqs" 2>/dev/null; then
-        semantic_info "A2/A3" "Requirement \"${req}\" 不被任何任务覆盖"
-        uncovered_req_count=$((uncovered_req_count + 1))
-      fi
-    done < "$tmp_spec_reqs"
-  fi
-
-  # 查找未被覆盖的 Scenario
-  if [ -s "$tmp_spec_scens" ]; then
-    while IFS=$'\t' read -r req scen; do
-      if ! grep -qxF "$scen" "$tmp_tasks_scens" 2>/dev/null; then
-        semantic_info "A2/A3" "Scenario \"${scen}\"（Requirement: \"${req}\"）不被任何任务覆盖"
-        uncovered_scen_count=$((uncovered_scen_count + 1))
-      fi
-    done < "$tmp_spec_scens"
-  fi
-
-  # =========================================
-  # Step 4: 全部覆盖时的汇总信息
-  # =========================================
-  if [ "$uncovered_req_count" -eq 0 ] && [ "$uncovered_scen_count" -eq 0 ]; then
-    semantic_info "A2/A3" "所有 Requirement 和 Scenario 均被 Covers 覆盖"
-  fi
-
-  # =========================================
-  # Step 5: 与 spec-review.json 交叉验证（如果存在）
-  # =========================================
-  if [ -z "$review_file" ]; then
-    local spec_dir
-    spec_dir=$(dirname "$spec_file")
-    if [ -f "${spec_dir}/spec-review.json" ]; then
-      review_file="${spec_dir}/spec-review.json"
-    fi
-  fi
-
-  if [ -n "$review_file" ] && [ -f "$review_file" ]; then
-    local review_reqs_covered
-    local review_reqs_total
-    review_reqs_covered=$(jq -r '.coverage.requirements_covered // "N/A"' "$review_file" 2>/dev/null || echo "N/A")
-    review_reqs_total=$(jq -r '.coverage.requirements_total // "N/A"' "$review_file" 2>/dev/null || echo "N/A")
-
-    if [ "$review_reqs_covered" != "N/A" ] && [ "$review_reqs_total" != "N/A" ]; then
-      local spec_total_reqs
-      local spec_covered_reqs
-      spec_total_reqs=$(wc -l < "$tmp_spec_reqs" | tr -d '[:space:]')
-      spec_covered_reqs=$((spec_total_reqs - uncovered_req_count))
-
-      if [ "$spec_covered_reqs" -ne "$review_reqs_covered" ] || [ "$spec_total_reqs" -ne "$review_reqs_total" ]; then
-        semantic_info "A2/A3" "与 spec-review.json 差异: A2 发现 ${spec_total_reqs} 个 Requirement（${spec_covered_reqs} 被覆盖），spec-review.json 报告 ${review_reqs_total} 个（${review_reqs_covered} 被覆盖）"
-      fi
-    fi
-  fi
-}

package/templates/.cursor/hooks/specline-pipeline-gate-checks/c1-exception.sh

@@ -1,71 +0,0 @@
-#!/usr/bin/env bash
-#
-# c1-exception.sh — C1: 异常场景覆盖率检测
-#
-# 检查 spec.md 中每个 Requirement 是否至少包含一个异常/错误场景。
-# 使用 SPEC_FILE 环境变量定位 spec 文件（由 gate_semantic 设置）。
-#
-# 异常关键词（不区分大小写）：
-#   错误|失败|异常|超时|无效|不存在|未找到|拒绝|过期|冲突|超出|不允许|未授权|已存在
-#
-# Usage（由 gate_semantic source 后调用）:
-#   run_c1_exception
-
-run_c1_exception() {
-  # 检查 spec 文件是否存在
-  if [ ! -f "$SPEC_FILE" ]; then
-    return 0
-  fi
-
-  # 检查是否有 Requirement 区块
-  local req_count
-  req_count=$(grep -c '^### Requirement:' "$SPEC_FILE" 2>/dev/null || true)
-  req_count="${req_count:-0}"
-  if [ "$req_count" = "0" ]; then
-    semantic_warn "C1" "未找到任何 Requirement 区块，跳过异常场景覆盖率检查"
-    return 0
-  fi
-
-  # 异常关键词（不区分大小写，用 grep -iE 扩展正则）
-  local keywords="错误|失败|异常|超时|无效|不存在|未找到|拒绝|过期|冲突|超出|不允许|未授权|已存在"
-
-  # 用 awk 按 Requirement 分组 Scenario 标题
-  # 输出格式: 需求名称|场景标题1|场景标题2|...
-  # 将 awk 输出捕获到变量，再用 here-string 逐行处理，避免管道 subshell 导致计数器丢失
-  local grouped
-  grouped=$(awk '
-    /^### Requirement:/ {
-      if (current_req != "") print current_req "|" scenarios
-      current_req = $0
-      sub(/^### Requirement: /, "", current_req)
-      scenarios = ""
-    }
-    /^#### Scenario:/ {
-      s = $0
-      sub(/^#### Scenario: /, "", s)
-      if (scenarios != "") scenarios = scenarios "|"
-      scenarios = scenarios s
-    }
-    END {
-      if (current_req != "") print current_req "|" scenarios
-    }
-  ' "$SPEC_FILE")
-
-  # 逐行处理每个 Requirement
-  while IFS='|' read -r req_name scenarios_str; do
-    [ -z "$req_name" ] && continue
-
-    # 统计该 Requirement 的 Scenario 数量
-    local scenario_count
-    if [ -z "$scenarios_str" ]; then
-      scenario_count=0
-    else
-      scenario_count=$(echo "$scenarios_str" | awk -F'|' '{print NF}')
-    fi
-
-    # 检查 Scenario 标题集合中是否包含异常关键词
-    if ! echo "$scenarios_str" | grep -qiE "$keywords" 2>/dev/null; then
-      semantic_warn "C1" "Requirement \"${req_name}\" 缺少异常场景（${scenario_count} 个 Scenario 中无异常/错误场景关键词）"
-    fi
-  done <<< "$grouped"
-}

package/templates/.cursor/hooks/specline-pipeline-gate-checks/c2-vague.sh

@@ -1,60 +0,0 @@
-#!/usr/bin/env bash
-#
-# c2-vague.sh — C2 检查：模糊需求检测
-#
-# 扫描 spec.md 中不可量化的模糊表述（如"足够快""适当"等），
-# 跳过代码块（```）内内容，对匹配到的模糊词输出 WARNING。
-#
-# 依赖：common.sh（提供 semantic_warn 函数和 SEMANTIC_WARNINGS 计数器）
-# 环境变量：SPEC_FILE — 指向 spec.md 的路径
-
-# 加载共享工具函数（允许独立测试时直接 source）
-if [ -z "${SEMANTIC_WARNINGS:-}" ]; then
-  COMMON_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  if [ -f "$COMMON_DIR/common.sh" ]; then
-    source "$COMMON_DIR/common.sh"
-  fi
-fi
-
-run_c2_vague() {
-  if [ -z "${SPEC_FILE:-}" ] || [ ! -f "$SPEC_FILE" ]; then
-    echo "⚠️ [WARNING] (C2) SPEC_FILE 未设置或文件不存在，跳过模糊需求检测" >&2
-    return 0
-  fi
-
-  # 模糊词正则模式
-  #   性能良好|足够快|适当[的地]|合理[的地]|必要时|等等|较好[的地]|
-  #   尽量|较大规模|可能[的地]|若干|一定[的地]|一般[的地]|基本的|少量的
-  local VAGUE_PATTERN='性能良好|足够快|适当[的地]|合理[的地]|必要时|等等|较好[的地]|尽量|较大规模|可能[的地]|若干|一定[的地]|一般[的地]|基本的|少量的'
-
-  local in_codeblock=0
-  local line_num=0
-
-  while IFS= read -r line; do
-    line_num=$((line_num + 1))
-
-    # 检测代码块边界：以 ``` 开头（忽略后面的语言标记）
-    if [[ "$line" =~ ^\`\`\` ]]; then
-      if [ "$in_codeblock" -eq 0 ]; then
-        in_codeblock=1
-      else
-        in_codeblock=0
-      fi
-      continue
-    fi
-
-    # 跳过代码块内部的行
-    if [ "$in_codeblock" -eq 1 ]; then
-      continue
-    fi
-
-    # 对普通文本行执行模糊词匹配
-    if echo "$line" | grep -qE "$VAGUE_PATTERN" 2>/dev/null; then
-      # 提取上下文（去除首尾空白）
-      local context
-      context=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-
-      semantic_warn "C2" "模糊需求表述: 第 ${line_num} 行 \"${context}\""
-    fi
-  done < "$SPEC_FILE"
-}

package/templates/.cursor/hooks/specline-pipeline-gate-checks/common.sh

@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-#
-# common.sh — Specline Pipeline Gate 语义检查共享工具
-#
-# 提供:
-#   - 全局计数器: SEMANTIC_ERRORS, SEMANTIC_WARNINGS, SEMANTIC_INFOS
-#   - 严重度报告函数: semantic_error(), semantic_warn(), semantic_info()
-#   - 文件定位函数: find_spec_file(), find_tasks_file()
-#
-# 兼容性: bash 3.2+ (macOS 默认 bash)
-
-set -euo pipefail
-
-# ===== 全局计数器 =====
-SEMANTIC_ERRORS=${SEMANTIC_ERRORS:-0}
-SEMANTIC_WARNINGS=${SEMANTIC_WARNINGS:-0}
-SEMANTIC_INFOS=${SEMANTIC_INFOS:-0}
-
-# ===== 严重度报告函数 =====
-
-# semantic_error <code> <message>
-# 输出 ERROR 级别消息到 stderr，并增加 SEMANTIC_ERRORS 计数
-semantic_error() {
-  local code="$1"
-  local msg="$2"
-  echo "❌ [ERROR] (${code}) ${msg}" >&2
-  SEMANTIC_ERRORS=$((SEMANTIC_ERRORS + 1))
-}
-
-# semantic_warn <code> <message>
-# 输出 WARNING 级别消息到 stdout，并增加 SEMANTIC_WARNINGS 计数
-semantic_warn() {
-  local code="$1"
-  local msg="$2"
-  echo "⚠️ [WARNING] (${code}) ${msg}"
-  SEMANTIC_WARNINGS=$((SEMANTIC_WARNINGS + 1))
-}
-
-# semantic_info <code> <message>
-# 输出 INFO 级别消息到 stdout，并增加 SEMANTIC_INFOS 计数
-semantic_info() {
-  local code="$1"
-  local msg="$2"
-  echo "ℹ️ [INFO] (${code}) ${msg}"
-  SEMANTIC_INFOS=$((SEMANTIC_INFOS + 1))
-}
-
-# ===== 文件定位函数 =====
-
-# find_spec_file
-# 在 specline/changes/$CHANGE/specs/ 下查找 spec.md
-find_spec_file() {
-  if [ -z "${CHANGE:-}" ]; then
-    echo ""
-    return
-  fi
-  find "${PROJECT_ROOT:-.}/specline/changes/${CHANGE}/specs" -name "spec.md" 2>/dev/null | head -1
-}
-
-# find_tasks_file
-# 返回 tasks.md 路径
-find_tasks_file() {
-  if [ -z "${CHANGE:-}" ]; then
-    echo ""
-    return
-  fi
-  echo "${PROJECT_ROOT:-.}/specline/changes/${CHANGE}/tasks.md"
-}

package/templates/.cursor/hooks/specline-pipeline-gate-checks/d1-cycle.sh

@@ -1,149 +0,0 @@
-#!/usr/bin/env bash
-#
-# d1-cycle.sh — D1: 依赖环路检测
-#
-# 使用 awk 实现三色 DFS 检测 tasks.md 中任务依赖关系是否形成环路。
-# 核心逻辑在 awk 中执行，避免 bash 版本兼容性问题（macOS bash 3.2）。
-#
-# 用法：
-#   export TASKS_FILE=/path/to/tasks.md
-#   source d1-cycle.sh && run_d1_cycle
-#
-# 环境变量：
-#   TASKS_FILE — tasks.md 文件路径
-
-# 确保计数器变量已定义（兼容独立 source 运行场景）
-: "${SEMANTIC_ERRORS:=0}"
-: "${SEMANTIC_WARNINGS:=0}"
-: "${SEMANTIC_INFOS:=0}"
-
-run_d1_cycle() {
-  local tasks_file="${TASKS_FILE:-}"
-
-  if [ -z "$tasks_file" ] || [ ! -f "$tasks_file" ]; then
-    echo "⚠️ D1: TASKS_FILE 未设置或文件不存在，跳过依赖环路检测" >&2
-    return 0
-  fi
-
-  # ──────────────────────────────────────────────
-  # 使用 awk 完成全部检测逻辑：
-  #   1. 解析 Depends 行构建邻接表
-  #   2. 三色 DFS 环路检测
-  #   3. 输出 "SELF:task_id" 或 "CYCLE:path" 行
-  # ──────────────────────────────────────────────
-  local result
-  result=$(awk '
-    # 解析任务编号
-    /^## / {
-      task = $2
-      gsub(/\..*/, "", task)
-    }
-    # 解析 Depends 行
-    /\*\*Depends\*\*:/ {
-      deps = $0
-      sub(/.*\*\*Depends\*\*:[ \t]*/, "", deps)
-      gsub(/^[ \t]+|[ \t]+$/, "", deps)
-      if (deps ~ /\(none\)/) {
-        deps = ""
-      }
-      # 清理依赖列表：去空格，过滤非数字字符（防止意外格式变化）
-      gsub(/[ \t]/, "", deps)
-      gsub(/[^0-9,]/, "", deps)
-      gsub(/,/, " ", deps)
-      # 去掉多余的连续空格
-      gsub(/  +/, " ", deps)
-      gsub(/^ | $/, "", deps)
-      adj[task] = deps
-    }
-    END {
-      if (length(adj) == 0) exit 0
-
-      # 收集所有任务 ID
-      for (t in adj) {
-        all_tasks[t] = 1
-      }
-
-      errors = 0
-
-      # 对每个任务执行 DFS（使用参数传递路径，自动处理回溯）
-      for (t in all_tasks) {
-        if (!(t in color) || color[t] == 0) {
-          dfs(t, "")
-        }
-      }
-    }
-
-    function dfs(node, path,   neighbors_str, n, i, arr, cnt, new_path, path_idx) {
-      color[node] = 1
-      new_path = path (path == "" ? "" : " ") node
-
-      neighbors_str = adj[node]
-
-      cnt = split(neighbors_str, arr, " ")
-      for (i = 1; i <= cnt; i++) {
-        n = arr[i]
-        if (n == "") continue
-
-        # 自引用
-        if (n == node) {
-          print "SELF:" node
-          errors++
-          continue
-        }
-
-        # 检查颜色
-        if (n in color && color[n] == 1) {
-          # 发现环路：从 new_path 中提取从 n 开始的路径
-          path_idx = index(" " new_path " ", " " n " ")
-          if (path_idx > 0) {
-            cycle_seg = substr(new_path, path_idx)
-          } else {
-            cycle_seg = new_path
-          }
-          gsub(/ /, " → ", cycle_seg)
-          print "CYCLE:" cycle_seg " → " n
-          errors++
-        } else if (!(n in color) || color[n] == 0) {
-          dfs(n, new_path)
-        }
-      }
-
-      color[node] = 2
-    }
-  ' "$tasks_file" 2>&1)
-
-  # ──────────────────────────────────────────────
-  # 处理 awk 输出，调用 semantic_error
-  # ──────────────────────────────────────────────
-  if [ -z "$result" ]; then
-    echo "✅ D1 依赖环路检测通过（无环路）"
-    return 0
-  fi
-
-  local line
-  while IFS= read -r line; do
-    [ -z "$line" ] && continue
-    case "$line" in
-      SELF:*)
-        local self_task="${line#SELF:}"
-        if type -t semantic_error &>/dev/null; then
-          semantic_error "D1" "依赖环路检测: 任务 ${self_task} 自引用"
-        else
-          echo "❌ [ERROR] (D1) 依赖环路检测: 任务 ${self_task} 自引用" >&2
-          ((SEMANTIC_ERRORS++))
-        fi
-        ;;
-      CYCLE:*)
-        local cycle_path="${line#CYCLE:}"
-        if type -t semantic_error &>/dev/null; then
-          semantic_error "D1" "依赖环路检测: 发现环路 ${cycle_path}"
-        else
-          echo "❌ [ERROR] (D1) 依赖环路检测: 发现环路 ${cycle_path}" >&2
-          ((SEMANTIC_ERRORS++))
-        fi
-        ;;
-    esac
-  done <<< "$result"
-
-  return 0
-}