specline 1.2.1 → 1.3.0

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

@@ -0,0 +1,71 @@
+#!/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

@@ -0,0 +1,60 @@
+#!/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

@@ -0,0 +1,68 @@
+#!/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

@@ -0,0 +1,149 @@
+#!/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
+}

package/templates/.cursor/hooks/specline-pipeline-gate-checks/d3-type-file.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+#
+# d3-type-file.sh - D3: Type-File 一致性检测
+#
+# 检测 tasks.md 中每个任务的 Type 字段与 Files 字段的扩展名是否一致。
+# 通过 source 加载，定义 run_d3_type_file() 函数。
+#
+# 依赖:
+#   - common.sh（提供 semantic_warn / semantic_info 和全局计数器）
+#   - 环境变量 TASKS_FILE（由 gate_semantic 设置）
+#
+# 兼容性: bash 3.2+ (macOS 默认 bash)
+
+set -euo pipefail
+
+# ===== Type -> 期望扩展名匹配函数（兼容 bash 3.2，无关联数组）=====
+#
+# is_extension_for_type <type> <extension>
+# 返回: 0 = 匹配, 1 = 不匹配
+is_extension_for_type() {
+  local t="$1"
+  local e="$2"
+
+  case "$t" in
+    frontend)
+      case "$e" in
+        tsx|jsx|css|scss|less|html|vue|svelte) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    backend)
+      case "$e" in
+        py|go|rs|java|rb|php) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    infra)
+      case "$e" in
+        yaml|yml|tf|toml) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    db)
+      case "$e" in
+        sql|prisma) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    config)
+      case "$e" in
+        json|yaml|yml|toml|cfg|env) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    docs)
+      case "$e" in
+        md|rst|txt) return 0 ;;
+        *) return 1 ;;
+      esac
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+# ===== 特殊文件名匹配 =====
+# infra 类型下的无扩展名特殊文件
+is_infra_special_name() {
+  local name="$1"
+  local lc_name
+  lc_name=$(echo "$name" | tr '[:upper:]' '[:lower:]')
+  case "$lc_name" in
+    dockerfile|docker-compose|docker-compose.yml|docker-compose.yaml) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# ===== check_file_against_type =====
+# 参数: $1 = task_id, $2 = type, $3 = file_path
+# 返回: 0 = 一致, 1 = 不匹配
+check_file_against_type() {
+  local task_id="$1"
+  local task_type="$2"
+  local file_path="$3"
+
+  # 提取扩展名
+  local ext=""
+  local basename
+  basename=$(basename "$file_path")
+
+  # 判断是否有扩展名（文件名包含点号且点号不在开头）
+  case "$basename" in
+    *.*)
+      ext="${basename##*.}"
+      ext=$(echo "$ext" | tr '[:upper:]' '[:lower:]')
+      ;;
+    *)
+      ext=""
+      ;;
+  esac
+
+  # --- 特殊规则 1: infra 类型下，无扩展名或特殊名称文件 ---
+  if [ "$task_type" = "infra" ]; then
+    if is_infra_special_name "$basename"; then
+      return 0
+    fi
+    # 也检查扩展名以 yml/yaml 结尾的 docker-compose 变体
+    local lc_basename
+    lc_basename=$(echo "$basename" | tr '[:upper:]' '[:lower:]')
+    case "$lc_basename" in
+      docker-compose.yml|docker-compose.yaml) return 0 ;;
+    esac
+  fi
+
+  # --- 特殊规则 2: .ts + server/ 路径 + Type: backend -> 一致 ---
+  if [ "$ext" = "ts" ] && [ "$task_type" = "backend" ]; then
+    local lc_path
+    lc_path=$(echo "$file_path" | tr '[:upper:]' '[:lower:]')
+    case "$lc_path" in
+      *server/*|*/server|*server*) return 0 ;;
+    esac
+    # 如果 .ts 文件不在 server/ 路径下且 Type 是 backend，不算匹配
+    # 继续执行下面的通用检查（.ts 不在 backend 列表中，会失败）
+  fi
+
+  # --- 特殊规则 3: db 类型下，路径包含 migration 或 schema 关键词 -> 一致 ---
+  if [ "$task_type" = "db" ]; then
+    local lc_path
+    lc_path=$(echo "$file_path" | tr '[:upper:]' '[:lower:]')
+    case "$lc_path" in
+      *migration*|*schema*) return 0 ;;
+    esac
+  fi
+
+  # --- 特殊规则 4: config 类型下，.env.xxx 变体文件（如 .env.example）-> 一致 ---
+  if [ "$task_type" = "config" ]; then
+    local lc_basename
+    lc_basename=$(echo "$basename" | tr '[:upper:]' '[:lower:]')
+    case "$lc_basename" in
+      .env|.env.*|*.env) return 0 ;;
+    esac
+  fi
+
+  # --- 通用规则: 检查扩展名 ---
+  if [ -z "$ext" ]; then
+    return 1
+  fi
+
+  if is_extension_for_type "$task_type" "$ext"; then
+    return 0
+  fi
+
+  return 1
+}
+
+# ===== run_d3_type_file =====
+# 主入口函数，由 gate_semantic 在 source 后调用
+run_d3_type_file() {
+  if [ -z "${TASKS_FILE:-}" ] || [ ! -f "$TASKS_FILE" ]; then
+    echo "[WARN] TASKS_FILE 未设置或不存在，跳过 D3 检查" >&2
+    return 0
+  fi
+
+  local all_pass=true
+  local skipped_count=0
+  local mismatch_count=0
+
+  # 用 awk 解析 tasks.md，输出结构化的任务信息
+  # 输出格式：
+  #   FILE|<task_id>|<type>|<file_path>
+  #   NOFILES|<task_id>|<type>
+  local parsed_data
+  parsed_data=$(awk '
+    /^## [0-9]+\./ {
+      # 新任务开始前，处理上一个任务
+      if (task_id != "" && has_type == 1 && has_files == 0) {
+        print "NOFILES|" task_id "|" task_type
+      }
+      # 提取新任务编号
+      task_id = $2
+      gsub(/\..*/, "", task_id)
+      task_type = ""
+      has_type = 0
+      has_files = 0
+    }
+    /\*\*Type\*\*:/ {
+      task_type = $0
+      sub(/.*\*\*Type\*\*:[ \t]*/, "", task_type)
+      sub(/[ \t]+$/, "", task_type)
+      has_type = 1
+    }
+    /\*\*Files\*\*:/ {
+      has_files = 1
+      files_str = $0
+      sub(/.*\*\*Files\*\*:[ \t]*/, "", files_str)
+      # 分割逗号分隔的文件列表
+      n = split(files_str, file_list, /,[ \t]*/)
+      for (i = 1; i <= n; i++) {
+        gsub(/^[ \t]+|[ \t]+$/, "", file_list[i])
+        if (file_list[i] != "") {
+          print "FILE|" task_id "|" task_type "|" file_list[i]
+        }
+      }
+    }
+    END {
+      # 处理最后一个任务
+      if (task_id != "" && has_type == 1 && has_files == 0) {
+        print "NOFILES|" task_id "|" task_type
+      }
+    }
+  ' "$TASKS_FILE")
+
+  # 逐行处理解析结果
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+
+    local field1 field2 field3 field4
+    field1=$(echo "$line" | cut -d'|' -f1)
+    field2=$(echo "$line" | cut -d'|' -f2)
+    field3=$(echo "$line" | cut -d'|' -f3)
+    field4=$(echo "$line" | cut -d'|' -f4)
+
+    case "$field1" in
+      FILE)
+        local tid="$field2"
+        local ttype="$field3"
+        local fpath="$field4"
+
+        if ! check_file_against_type "$tid" "$ttype" "$fpath"; then
+          semantic_warn "D3" "任务 ${tid} (Type: ${ttype}) 的 Files 可能不匹配 — ${fpath}"
+          all_pass=false
+          mismatch_count=$((mismatch_count + 1))
+        fi
+        ;;
+      NOFILES)
+        local tid="$field2"
+        local ttype="$field3"
+        semantic_info "D3" "任务 ${tid} 无 Files 字段，跳过 Type-File 一致性检查"
+        skipped_count=$((skipped_count + 1))
+        ;;
+    esac
+  done <<< "$parsed_data"
+
+  # 输出汇总信息
+  if [ "$all_pass" = true ]; then
+    echo "[OK] D3 Type-File 一致性检查全部通过"
+  fi
+
+  return 0
+}
+
+# 如果直接执行此脚本（非 source），运行检查
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  if [ -z "${TASKS_FILE:-}" ]; then
+    echo "用法: TASKS_FILE=<path> bash $0"
+    exit 1
+  fi
+  run_d3_type_file
+fi