ljwx-health/.githooks/pre-commit

#!/bin/bash
# =============================================================================
# Git Pre-Commit Hook - 文档规范检查
# 用途: 在提交前自动检查文档命名和位置是否符合规范
# 作者: Claude Code
# 日期: 2026-01-18
# =============================================================================

set -e

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# 获取暂存的 .md 文件
STAGED_MD_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$' || true)

# 如果没有 .md 文件被修改，直接通过
if [ -z "$STAGED_MD_FILES" ]; then
    exit 0
fi

echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${BLUE}检查文档规范...${NC}"
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo

# 统计
TOTAL=0
VIOLATIONS=0
declare -a VIOLATION_LIST

# 允许的根目录文档
ALLOWED_ROOT_DOCS=(
    "README.md"
    "CLAUDE.md"
    "CONTRIBUTING.md"
    "CHANGELOG.md"
    "PROMPT_BLUEPRINT.md"
    "LICENSE.md"
)

# =============================================================================
# 检查文件名是否符合 kebab-case
# =============================================================================
check_kebab_case() {
    local filename="$1"

    # 允许的特殊文件
    for allowed in "${ALLOWED_ROOT_DOCS[@]}"; do
        if [ "$filename" == "$allowed" ]; then
            return 0
        fi
    done

    # 检查是否是纯中文（跳过）
    if [[ "$filename" =~ ^[^a-zA-Z0-9]+\.md$ ]]; then
        return 0
    fi

    # 检查大写字母
    if [[ "$filename" =~ [A-Z] ]]; then
        return 1
    fi

    # 检查下划线
    if [[ "$filename" =~ _ ]]; then
        return 1
    fi

    # 检查日期后缀
    if [[ "$filename" =~ -[0-9]{8}\.md$ ]] || [[ "$filename" =~ -[0-9]{4}-[0-9]{2}-[0-9]{2}\.md$ ]]; then
        return 1
    fi

    return 0
}

# =============================================================================
# 检查文件路径是否合规
# =============================================================================
check_file_path() {
    local filepath="$1"
    local filename=$(basename "$filepath")
    local dirname=$(dirname "$filepath")

    # 根目录文档检查
    if [ "$dirname" == "." ]; then
        # 检查是否在允许列表中
        for allowed in "${ALLOWED_ROOT_DOCS[@]}"; do
            if [ "$filename" == "$allowed" ]; then
                return 0
            fi
        done

        echo -e "${RED}[违规]${NC} 根目录文档: $filepath"
        echo "       根目录仅允许以下文档:"
        for allowed in "${ALLOWED_ROOT_DOCS[@]}"; do
            echo "       - $allowed"
        done
        echo "       建议: 移动到 docs/{category}/ 或 archive/"
        return 1
    fi

    # 子项目根目录文档检查（除了 README.md, CHANGELOG.md）
    if [[ "$dirname" =~ ^(ljwx-admin|ljwx-boot|ljwx-bigscreen)$ ]]; then
        if [[ "$filename" != "README.md" && "$filename" != "CHANGELOG.md" ]]; then
            echo -e "${RED}[违规]${NC} 子项目文档: $filepath"
            echo "       子项目根目录仅允许 README.md 和 CHANGELOG.md"
            echo "       建议: 移动到 docs/06-development/{backend|frontend}/"
            return 1
        fi
    fi

    # docs/ 目录结构检查
    if [[ "$dirname" =~ ^docs ]]; then
        # 检查是否在标准分类目录中
        if [[ ! "$dirname" =~ ^docs/(01-getting-started|02-architecture|03-deployment|04-operations|05-features|06-development|07-compliance|08-reference) ]]; then
            echo -e "${YELLOW}[警告]${NC} 非标准分类: $filepath"
            echo "       标准分类: 01-getting-started, 02-architecture, ..."
        fi
    fi

    # archive/ 目录结构检查
    if [[ "$dirname" =~ ^archive ]]; then
        if [[ ! "$dirname" =~ ^archive/(20[0-9]{2}/(fixes|implementations|experiments)|deprecated) ]]; then
            echo -e "${YELLOW}[警告]${NC} 非标准归档路径: $filepath"
            echo "       标准路径: archive/{year}/{fixes|implementations|experiments}/"
        fi
    fi

    return 0
}

# =============================================================================
# 主检查逻辑
# =============================================================================
for file in $STAGED_MD_FILES; do
    ((TOTAL++))

    filename=$(basename "$file")
    echo -e "${BLUE}检查:${NC} $file"

    # 检查命名规范
    if ! check_kebab_case "$filename"; then
        ((VIOLATIONS++))
        echo -e "${RED}  ✗ 命名不符合 kebab-case 规范${NC}"
        echo "    建议: $(echo "$filename" | tr '[:upper:]' '[:lower:]' | tr '_' '-')"
        VIOLATION_LIST+=("$file|命名不符合规范")
        continue
    fi

    # 检查路径规范
    if ! check_file_path "$file"; then
        ((VIOLATIONS++))
        VIOLATION_LIST+=("$file|路径不符合规范")
        continue
    fi

    echo -e "${GREEN}  ✓ 符合规范${NC}"
done

echo
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

# =============================================================================
# 结果汇总
# =============================================================================
if [ $VIOLATIONS -gt 0 ]; then
    echo -e "${RED}❌ 检查失败: $VIOLATIONS/$TOTAL 个文档违反规范${NC}"
    echo
    echo -e "${YELLOW}违规详情:${NC}"
    for violation in "${VIOLATION_LIST[@]}"; do
        IFS='|' read -r file reason <<< "$violation"
        echo -e "  ${RED}✗${NC} $file"
        echo -e "    原因: $reason"
    done
    echo
    echo -e "${YELLOW}修复建议:${NC}"
    echo "  1. 运行自动修复: ./scripts/organize-docs.sh"
    echo "  2. 手动移动文件到正确位置"
    echo "  3. 使用创建脚本: ./scripts/create-doc.sh"
    echo
    echo -e "${YELLOW}如需跳过检查（不推荐）:${NC}"
    echo "  git commit --no-verify"
    echo
    exit 1
else
    echo -e "${GREEN}✅ 所有文档符合规范 ($TOTAL/$TOTAL)${NC}"
    echo
    exit 0
fi