@mycodemap/mycodemap 0.5.2-beta.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "0.5.2-beta.1",
+  "version": "2.0.0",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "examples/",
     "scripts/",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "CHANGELOG.md",
     "mycodemap.config.schema.json"
@@ -34,6 +35,7 @@
     "docs:check:ai": "node scripts/validate-ai-docs.js",
     "docs:check:pre-release": "node scripts/pre-release-check.js",
     "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "benchmark": "bash scripts/run-benchmark.sh",
@@ -42,9 +44,7 @@
     "validate-pack": "node scripts/validate-pack.js",
     "release": "./scripts/release.sh",
     "check:all": "npm run typecheck && npm run lint && npm test && npm run docs:check",
-    "check:architecture": "echo 'dependency-cruiser not installed, run: npm i -D dependency-cruiser'",
     "check:security": "npm audit",
-    "check:unused": "echo 'knip not installed, run: npm i -D knip'",
     "fix:all": "npm run lint -- --fix",
     "ai:pre-task": "npm run check:all",
     "ai:post-task": "npm run fix:all && npm run check:all"
@@ -65,6 +65,7 @@
     "chalk": "^5.3.0",
     "chokidar": "^3.5.3",
     "commander": "^11.1.0",
+    "dependency-cruiser": "^17.3.10",
     "globby": "^14.0.0",
     "hono": "^4.12.8",
     "ora": "^8.0.1",
@@ -76,17 +77,19 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
-    "@types/glob": "^8.1.0",
     "@types/node": "^20.10.0",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
     "@vitest/coverage-v8": "^1.6.1",
-    "dependency-cruiser": "^17.3.10",
     "eslint": "^8.57.1",
     "vitest": "^1.1.0"
   },
+  "optionalDependencies": {
+    "web-tree-sitter": "^0.24.0",
+    "sql.js": "^1.12.0"
+  },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public",

package/scripts/hooks/templates/commit-msg

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Commit-msg hook: 仅验证 Commit 消息格式
+
+MSG_FILE=$1
+MSG=$(head -1 "$MSG_FILE")
+
+VALID_TAGS="BUGFIX FEATURE REFACTOR CONFIG DOCS DELETE"
+
+COMMIT_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)
+
+ONLY_DOT_DIRS=true
+if [ -n "$COMMIT_FILES" ]; then
+    NON_DOT_FILES=$(echo "$COMMIT_FILES" | grep -v '^\.' || true)
+    if [ -n "$NON_DOT_FILES" ]; then
+        ONLY_DOT_DIRS=false
+    fi
+fi
+
+if [ "$ONLY_DOT_DIRS" = "true" ]; then
+    echo "Note: Commit only contains files in dot-directories, skipping message format check"
+elif ! echo "$MSG" | grep -qE '^\[(BUGFIX|FEATURE|REFACTOR|CONFIG|DOCS|DELETE)\]'; then
+    echo "ERROR: Commit message must start with an uppercase tag."
+    echo "Format: [TAG] scope: message"
+    echo "Valid tags: $VALID_TAGS"
+    exit 1
+fi
+
+if [ "$ONLY_DOT_DIRS" = "true" ]; then
+    echo "Note: Commit only contains files in dot-directories, skipping scope check"
+elif ! echo "$MSG" | grep -qE '^\[(BUGFIX|FEATURE|REFACTOR|CONFIG|DOCS|DELETE)\]\s+[^:]+:\s+.+'; then
+    echo "ERROR: scope and message are required."
+    echo "Format: [TAG] scope: message"
+    echo "Example: [FEATURE] cli: add new command"
+    exit 1
+fi
+
+echo "Commit message validated"
+exit 0

package/scripts/hooks/templates/pre-commit

@@ -0,0 +1,224 @@
+#!/bin/sh
+# Pre-commit hook: 运行测试和文件头检查
+
+echo "Running pre-commit checks..."
+
+# 1. 运行与变更相关的测试（失败即阻断）
+echo "Running tests for changed files..."
+if [ -f "node_modules/vitest/vitest.mjs" ]; then
+    node node_modules/vitest/vitest.mjs run --changed
+else
+    if [ ! -e "node_modules/vitest" ]; then
+        VITEST_PACKAGE_DIR=$(find node_modules -type d -path '*/.pnpm/*/node_modules/vitest' | head -n 1)
+        if [ -n "$VITEST_PACKAGE_DIR" ]; then
+            ln -sfn "${VITEST_PACKAGE_DIR#node_modules/}" node_modules/vitest
+        fi
+    fi
+
+    if [ -f "node_modules/vitest/vitest.mjs" ]; then
+        node node_modules/vitest/vitest.mjs run --changed
+    else
+        VITEST_ENTRY=$(find node_modules -type f -path '*/.pnpm/*/node_modules/vitest/vitest.mjs' | head -n 1)
+        if [ -z "$VITEST_ENTRY" ]; then
+            VITEST_ENTRY=$(find node_modules -type f -path '*/.vitest-*/vitest.mjs' | head -n 1)
+        fi
+
+        if [ -n "$VITEST_ENTRY" ]; then
+            node "$VITEST_ENTRY" run --changed
+        else
+            npx --yes vitest run --changed
+        fi
+    fi
+fi
+if [ $? -ne 0 ]; then
+    echo "ERROR: Tests failed, commit rejected"
+    exit 1
+fi
+
+echo "Tests passed"
+
+# 2. repo-local 规则校验（按 hard_gate.mode 决定 report-only / enforce）
+RULE_CONFIG_PATH=".claude/rule-system.config.json"
+RULE_HARD_GATE_MODE="report-only"
+
+if [ -f "$RULE_CONFIG_PATH" ]; then
+    RULE_HARD_GATE_MODE=$(python3 - <<'PY'
+import json
+from pathlib import Path
+
+config_path = Path(".claude/rule-system.config.json")
+
+try:
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+except Exception:
+    print("report-only")
+else:
+    print(config.get("hard_gate", {}).get("mode", "report-only"))
+PY
+)
+fi
+
+echo "Running repo-local rule validation (mode: $RULE_HARD_GATE_MODE)..."
+case "$RULE_HARD_GATE_MODE" in
+    enforce)
+        python3 scripts/validate-rules.py code
+        VALIDATE_EXIT=$?
+        case "$VALIDATE_EXIT" in
+            0)
+                echo "Rule validation passed"
+                ;;
+            1)
+                echo "ERROR: Rule validation found blocking P0 failures, commit rejected"
+                exit 1
+                ;;
+            2)
+                echo "WARNING: Rule validation reported warn-only P1 findings, continuing commit"
+                ;;
+            3)
+                echo "WARNING: Rule validation reported notice-only P2 findings, continuing commit"
+                ;;
+            4)
+                echo "ERROR: Rule validation dependencies unavailable, commit rejected"
+                exit 1
+                ;;
+            *)
+                echo "ERROR: Rule validation returned unexpected exit code ($VALIDATE_EXIT), commit rejected"
+                exit 1
+                ;;
+        esac
+        ;;
+    report-only|*)
+        if [ "$RULE_HARD_GATE_MODE" != "report-only" ]; then
+            echo "WARNING: Unknown hard gate mode '$RULE_HARD_GATE_MODE', defaulting to report-only"
+        fi
+        python3 scripts/validate-rules.py code --report-only >/dev/null
+        VALIDATE_EXIT=$?
+        if [ "$VALIDATE_EXIT" -ne 0 ]; then
+            echo "WARNING: Rule validation report-only command exited with $VALIDATE_EXIT, continuing commit"
+        else
+            echo "Rule validation report-only completed"
+        fi
+        ;;
+esac
+
+# 3. 检查 staged 文件数量（初始化 commit 除外）
+MAX_FILES_PER_COMMIT=10
+MAX_FILES_WITH_DOCS=20
+
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+STAGED_FILE_COUNT=$(echo "$STAGED_FILES" | grep -c '^' || echo 0)
+
+ONLY_DOT_DIRS=true
+if [ -n "$STAGED_FILES" ]; then
+    NON_DOT_FILES=$(echo "$STAGED_FILES" | grep -v '^\.' || true)
+    if [ -n "$NON_DOT_FILES" ]; then
+        ONLY_DOT_DIRS=false
+    fi
+fi
+
+IS_INITIAL_COMMIT=false
+git rev-parse --verify HEAD >/dev/null 2>&1
+if [ $? -ne 0 ]; then
+    IS_INITIAL_COMMIT=true
+fi
+
+CONTAINS_DOC_FILES=false
+if [ -n "$STAGED_FILES" ]; then
+    DOC_FILES=$(echo "$STAGED_FILES" | grep -E '(\.md$|^docs/|^README|^CHANGELOG|^LICENSE)' || true)
+    if [ -n "$DOC_FILES" ]; then
+        CONTAINS_DOC_FILES=true
+    fi
+fi
+
+if [ "$CONTAINS_DOC_FILES" = "true" ]; then
+    CURRENT_LIMIT=$MAX_FILES_WITH_DOCS
+else
+    CURRENT_LIMIT=$MAX_FILES_PER_COMMIT
+fi
+
+if [ "$ONLY_DOT_DIRS" = "true" ]; then
+    echo "Note: Only dot-directory files staged, skipping count limit check"
+elif [ "$STAGED_FILE_COUNT" -gt "$CURRENT_LIMIT" ] && [ "$IS_INITIAL_COMMIT" = "false" ]; then
+    echo ""
+    echo "WARNING: Staged files count ($STAGED_FILE_COUNT) exceeds limit ($CURRENT_LIMIT)"
+    echo ""
+    if [ "$CONTAINS_DOC_FILES" = "true" ]; then
+        echo "Note: This commit contains documentation files, so the limit is increased to $MAX_FILES_WITH_DOCS."
+    else
+        echo "Single commit should not contain more than $MAX_FILES_PER_COMMIT files."
+    fi
+    echo "Please consider splitting your changes into smaller, focused commits."
+    echo ""
+    echo "If you have a very good reason for this large commit, you can bypass"
+    echo "this warning with: git commit --no-verify"
+    echo ""
+    echo "Staged files:"
+    git diff --cached --name-only --diff-filter=ACM
+    echo ""
+    exit 1
+fi
+
+# 4. 检查文件头注释（只检查 staged 的 TS 源文件，豁免 . 开头目录）
+echo "Checking file headers..."
+if [ "$ONLY_DOT_DIRS" = "true" ]; then
+    echo "Note: Only dot-directory files staged, skipping header check"
+    STAGED_TS_FILES=""
+else
+    STAGED_TS_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.ts$' | grep -v '\.test\.ts$' | grep -v '\.d\.ts$')
+fi
+
+if [ -n "$STAGED_TS_FILES" ]; then
+    MISSING_HEADERS=0
+
+    for file in $STAGED_TS_FILES; do
+        if [ ! -f "$file" ]; then
+            continue
+        fi
+
+        HEAD_CONTENT=$(head -10 "$file")
+
+        if ! echo "$HEAD_CONTENT" | grep -q '\[META\]'; then
+            echo "ERROR: $file missing [META] comment"
+            MISSING_HEADERS=$((MISSING_HEADERS + 1))
+        fi
+
+        if ! echo "$HEAD_CONTENT" | grep -q '\[WHY\]'; then
+            echo "ERROR: $file missing [WHY] comment"
+            MISSING_HEADERS=$((MISSING_HEADERS + 1))
+        fi
+    done
+
+    if [ $MISSING_HEADERS -gt 0 ]; then
+        echo ""
+        echo "Add header comments at file top:"
+        echo "// [META] since:YYYY-MM | owner:team | stable:false"
+        echo "// [WHY] Explain why this file exists"
+        exit 1
+    fi
+fi
+
+echo "File headers passed"
+
+# 5. 检查文档与 CLI 护栏（仅在相关文件变更时阻断）
+DOC_GUARDRAIL_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^(README\.md|package\.json|docs/|src/cli/index\.ts|vitest\.config\.ts|vitest\.benchmark\.config\.ts|\.github/workflows/ci-gateway\.yml)$' || true)
+
+if [ -n "$DOC_GUARDRAIL_FILES" ]; then
+    echo "Checking documentation guardrails..."
+    npm run docs:check
+    if [ $? -ne 0 ]; then
+        echo "ERROR: Documentation guardrails failed, commit rejected"
+        exit 1
+    fi
+fi
+
+echo "Documentation guardrails passed"
+
+# 6. 生成 AI 饲料（警告级，不阻断）
+echo "Generating AI feed..."
+npx mycodemap generate --quiet >/dev/null 2>&1 &
+if [ $? -ne 0 ]; then
+    echo "WARNING: Failed to start AI feed generation"
+fi
+
+echo "Pre-commit checks passed"
+exit 0

package/scripts/pre-release-check.js

@@ -710,10 +710,10 @@ async function runPreReleaseChecks() {
     const pkgVersion = JSON.parse(pkg).version;
     console.log(`\n当前版本: v${pkgVersion}`);
     console.log('\n📋 发布步骤:');
-    console.log('  1. npm run docs:check:pre-release  # 运行此检查');
-    console.log('  2. ./scripts/release.sh patch|minor|major  # 或指定版本');
-    console.log('  3. git push origin main --tags  # 推送 tag');
-    console.log('  4. GitHub Actions 自动: 构建 → 测试 → 发布 → 创建 Release');
+    console.log('  1. /release vX.Y  # 统一入口：readiness → closeout → 双确认门');
+    console.log('  2. Gate #2 通过后委托 ./scripts/release.sh X.Y.0  # 机械 helper');
+    console.log('  3. 推送 tag 后由 .github/workflows/publish.yml 自动: 构建 → 测试 → 发布 → 创建 Release');
+    console.log('  4. 若不是 milestone-bound release，才使用人工受控的例外流程');
     console.log('\n🔗 相关链接:');
     console.log(`  - GitHub Actions: https://github.com/mycodemap/mycodemap/actions`);
     console.log(`  - NPM 包: https://www.npmjs.com/package/@mycodemap/mycodemap`);

package/scripts/release.sh

@@ -109,7 +109,7 @@ echo ""
 # 步骤 2: 提交版本更新
 echo -e "${BLUE}2/5 提交版本更新...${NC}"
 git add package.json package-lock.json
-git commit -m "[RELEASE] bump version to v$NEW_VERSION"
+git commit -m "[CONFIG] version: bump to v$NEW_VERSION"
 echo -e "${GREEN}   ✅ 已提交版本更新${NC}"
 echo ""
 

package/scripts/sync-analyze-docs.js

@@ -299,12 +299,12 @@ function renderAnalyzeOptionsTable(rootDir) {
 
 const ANALYZE_DOC_BLOCKS = [
   {
-    relativePath: 'README.md',
+    relativePath: 'README.zh-CN.md',
     marker: 'analyze-readme-examples',
     render: () => renderReadmeAnalyzeExamples(),
   },
   {
-    relativePath: 'README.md',
+    relativePath: 'README.zh-CN.md',
     marker: 'analyze-readme-options',
     render: rootDir => renderAnalyzeOptionsTable(rootDir),
   },