@mycodemap/mycodemap 1.9.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "1.9.0",
+  "version": "2.7.0",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "repository": {
     "type": "git",
@@ -22,12 +22,14 @@
     "examples/",
     "scripts/",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "CHANGELOG.md",
     "mycodemap.config.schema.json"
   ],
   "scripts": {
     "build": "tsc",
+    "postbuild": "node scripts/copy-build-assets.mjs",
     "dev": "tsc --watch",
     "docs:check": "node scripts/validate-docs.js && node scripts/validate-ai-docs.js",
     "docs:check:human": "node scripts/validate-docs.js",
@@ -43,9 +45,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"
@@ -68,9 +68,13 @@
     "commander": "^11.1.0",
     "dependency-cruiser": "^17.3.10",
     "globby": "^14.0.0",
+    "graphology": "^0.26.0",
+    "graphology-communities-louvain": "^2.0.2",
     "hono": "^4.12.8",
     "ora": "^8.0.1",
+    "smol-toml": "^1.6.1",
     "tree-sitter": "^0.21.1",
+    "tree-sitter-python": "0.23.4",
     "tree-sitter-typescript": "^0.23.2",
     "typescript": "^5.3.3",
     "typhonjs-escomplex": "^0.1.0",
@@ -85,8 +89,12 @@
     "eslint": "^8.57.1",
     "vitest": "^1.1.0"
   },
+  "optionalDependencies": {
+    "sql.js": "^1.12.0",
+    "web-tree-sitter": "^0.24.0"
+  },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public",

package/scripts/copy-build-assets.mjs

@@ -0,0 +1,23 @@
+// Post-tsc copy step: ship non-TS assets that `tsc` does not emit into `dist/`.
+// Phase 53: built-in bootstrap profile JSONs live next to the profile-loader
+// and must be present at runtime in published packages (`files` ships `dist/`,
+// not `src/`).
+
+import { cpSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+
+const copies = [
+  {
+    from: path.join(repoRoot, 'src', 'cli', 'init', 'profiles'),
+    to: path.join(repoRoot, 'dist', 'cli', 'init', 'profiles'),
+  },
+];
+
+for (const { from, to } of copies) {
+  mkdirSync(to, { recursive: true });
+  cpSync(from, to, { recursive: true });
+  console.log(`[copy-build-assets] ${path.relative(repoRoot, from)} -> ${path.relative(repoRoot, to)}`);
+}

package/scripts/hooks/templates/pre-commit

@@ -40,6 +40,35 @@ 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"
+RULE_REPORT_ONLY_TIMEOUT_SECONDS="${RULE_REPORT_ONLY_TIMEOUT_SECONDS:-20}"
+
+run_rule_validation_report_only() {
+    python3 - <<'PY'
+import os
+import subprocess
+import sys
+
+timeout_value = os.environ.get("RULE_REPORT_ONLY_TIMEOUT_SECONDS", "20")
+
+try:
+    timeout_seconds = int(timeout_value)
+except ValueError:
+    timeout_seconds = 20
+
+try:
+    completed = subprocess.run(
+        ["python3", "scripts/validate-rules.py", "code", "--report-only"],
+        check=False,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        timeout=timeout_seconds,
+    )
+except subprocess.TimeoutExpired:
+    sys.exit(124)
+
+sys.exit(completed.returncode)
+PY
+}
 
 if [ -f "$RULE_CONFIG_PATH" ]; then
     RULE_HARD_GATE_MODE=$(python3 - <<'PY'
@@ -91,9 +120,11 @@ case "$RULE_HARD_GATE_MODE" in
         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
+        run_rule_validation_report_only
         VALIDATE_EXIT=$?
-        if [ "$VALIDATE_EXIT" -ne 0 ]; then
+        if [ "$VALIDATE_EXIT" -eq 124 ]; then
+            echo "WARNING: Rule validation report-only timed out after ${RULE_REPORT_ONLY_TIMEOUT_SECONDS}s, continuing commit"
+        elif [ "$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"

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),
   },

package/scripts/tests/test_rule_control_workflow.py

@@ -35,8 +35,12 @@ class RuleControlWorkflowTests(unittest.TestCase):
             ROOT / ".codex/get-shit-done/workflows/execute-phase.md",
             ROOT / ".claude/get-shit-done/workflows/execute-phase.md",
         ]
+        existing_paths = [workflow_path for workflow_path in workflow_paths if workflow_path.exists()]
 
-        for workflow_path in workflow_paths:
+        if not existing_paths:
+            self.skipTest("execute-phase workflow paths are not vendored in this checkout")
+
+        for workflow_path in existing_paths:
             content = workflow_path.read_text(encoding="utf-8")
             self.assertIn("rule-context.mjs --files", content)
             self.assertIn("<rule_context>", content)
@@ -46,6 +50,16 @@ class RuleControlWorkflowTests(unittest.TestCase):
         self.assertIn("Rule validation backstop", content)
         self.assertIn("python3 scripts/validate-rules.py code", content)
 
+    def test_pre_commit_report_only_timeout_guard_exists(self):
+        for hook_path in [
+            ROOT / ".githooks" / "pre-commit",
+            ROOT / "scripts" / "hooks" / "templates" / "pre-commit",
+        ]:
+            content = hook_path.read_text(encoding="utf-8")
+            self.assertIn("RULE_REPORT_ONLY_TIMEOUT_SECONDS", content)
+            self.assertIn("Rule validation report-only timed out after", content)
+            self.assertIn("subprocess.TimeoutExpired", content)
+
 
 if __name__ == "__main__":
     unittest.main()

package/scripts/validate-docs.js

@@ -1,7 +1,7 @@
 // [META] since:2026-03 | owner:docs-team | stable:true
 // [WHY] Validate high-signal documentation facts against the current repository guardrails
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { collectAnalyzeDocSyncFailures } from './sync-analyze-docs.js';
@@ -273,7 +273,7 @@ function validatePackageScripts(rootDir, failures) {
 }
 
 function validateAnalyzeDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -410,7 +410,7 @@ function validateAnalyzeDocs(rootDir, failures) {
 }
 
 function validateHistoryRiskDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -513,7 +513,7 @@ function validateHistoryRiskDocs(rootDir, failures) {
 }
 
 function validateDesignContractDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -835,8 +835,104 @@ function validateDesignContractDocs(rootDir, failures) {
   }
 }
 
+function validateNpmScriptsAreReal(rootDir, failures) {
+  const packageJsonText = readText(rootDir, 'package.json', failures);
+  if (!packageJsonText) {
+    return;
+  }
+
+  let packageJson;
+  try {
+    packageJson = JSON.parse(packageJsonText);
+  } catch {
+    failures.push('package.json is not valid JSON — cannot validate npm scripts');
+    return;
+  }
+
+  const scripts = packageJson.scripts;
+  if (!scripts || typeof scripts !== 'object') {
+    return;
+  }
+
+  /** Pattern matching echo stubs like: echo 'dependency-cruiser not installed, run: npm i -D dependency-cruiser' */
+  const ECHO_STUB_PATTERN = /^echo\s+['"].*not installed/i;
+
+  // Check all referenced npm scripts in docs are real (not echo stubs)
+  const docsDir = path.join(rootDir, 'docs');
+  const githubDir = path.join(rootDir, '.github');
+  const npmRunPattern = /npm\s+run\s+([a-zA-Z0-9:_-]+)/g;
+
+  function scanFileForNpmRun(filePath, label) {
+    if (!existsSync(filePath)) {
+      return;
+    }
+
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      return;
+    }
+
+    let match;
+    while ((match = npmRunPattern.exec(content)) !== null) {
+      const scriptName = match[1].replace(/[.,;:!?`'"()\[\]{}]+$/, '');
+      // Skip known npm lifecycle scripts that don't need to be in package.json
+      const npmLifecycleScripts = new Set([
+        'postinstall', 'preinstall', 'prepare', 'prepublish', 'prepublishOnly',
+        'prerestart', 'postrestart', 'prestart', 'poststart', 'prestop', 'poststop',
+        'pretest', 'posttest', 'preversion', 'postversion',
+      ]);
+      if (npmLifecycleScripts.has(scriptName)) {
+        continue;
+      }
+
+      // Skip if not a defined script
+      if (!(scriptName in scripts)) {
+        failures.push(`[docs-script-ghost] ${label} references undefined npm script: "npm run ${scriptName}"`);
+        continue;
+      }
+
+      const scriptValue = scripts[scriptName];
+      if (typeof scriptValue === 'string' && ECHO_STUB_PATTERN.test(scriptValue)) {
+        failures.push(`[docs-script-stub] ${label} references npm script "${scriptName}" which is an echo stub, not a real command`);
+      }
+    }
+  }
+
+  function scanDirectory(dirPath, labelPrefix) {
+    if (!existsSync(dirPath)) {
+      return;
+    }
+
+    // Walk directory recursively
+    function walk(currentPath, relativePath) {
+      const items = readdirSync(currentPath, { withFileTypes: true });
+      for (const item of items) {
+        const itemPath = path.join(currentPath, item.name);
+        const itemRelPath = path.join(relativePath, item.name);
+        if (item.isDirectory()) {
+          // Skip historical artifact directories
+          if (item.name === 'exec-plans' || item.name === 'ideation' || item.name === 'references' || item.name === 'archive') {
+            continue;
+          }
+          walk(itemPath, itemRelPath);
+        } else if (item.isFile() && item.name.endsWith('.md')) {
+          scanFileForNpmRun(itemPath, `${labelPrefix}/${itemRelPath}`);
+        }
+      }
+    }
+    walk(dirPath, '');
+  }
+
+  scanDirectory(docsDir, 'docs');
+  scanDirectory(githubDir, '.github');
+  // Note: docs/exec-plans/ and docs/ideation/ contain historical artifacts
+  // that reference scripts from their time period — skip them
+}
+
 function validatePositioningBaselineDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const aiGuideIndex = readText(rootDir, 'docs/ai-guide/README.md', failures);
   const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
@@ -844,7 +940,7 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 
   if (readme) {
     const requiredReadmeSnippets = [
-      'AI-first 代码地图工具',
+      'AI-Native',
       'AI/Agent 是主要消费者',
       '`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。'
     ];
@@ -863,8 +959,8 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 
   if (aiGuide) {
     const requiredAiGuideSnippets = [
-      'CodeMap 是一个 AI-first 代码地图工具',
-      '当前 CLI 过渡现实',
+      'CodeMap 是一个 AI-Native 优先',
+      'JSON/NDJSON 默认输出',
       '`Server Layer` 是内部架构层，不等于公共 `mycodemap server` 命令',
       '后者已从 public CLI 移除'
     ];
@@ -876,7 +972,7 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 
   if (aiGuideIndex) {
     const requiredIndexSnippets = [
-      'AI-first 代码地图工具',
+      'AI-Native 优先、人类友好的代码架构治理基础设施',
       'AI/Agent 是主要消费者',
       '`server`、`watch`、`report`、`logs` 已从 public CLI 移除'
     ];
@@ -909,7 +1005,7 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 }
 
 function validateCliSurfaceDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const aiGuideIndex = readText(rootDir, 'docs/ai-guide/README.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -997,7 +1093,7 @@ function validateCliSurfaceDocs(rootDir, failures) {
 }
 
 function validateConfigDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const setupGuide = readText(rootDir, 'docs/SETUP_GUIDE.md', failures);
   const assistantGuide = readText(rootDir, 'docs/AI_ASSISTANT_SETUP.md', failures);
@@ -1109,7 +1205,7 @@ function validateConfigDocs(rootDir, failures) {
 }
 
 function validatePluginRuntimeDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
   const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
@@ -1184,7 +1280,7 @@ function validatePluginRuntimeDocs(rootDir, failures) {
 }
 
 function validateGraphStorageDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -1331,7 +1427,7 @@ function validateTestingDocs(rootDir, failures) {
 }
 
 function validateWorkflowAndDiscoveryDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
   const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
@@ -1531,7 +1627,7 @@ function validateProductSpecsDocs(rootDir, failures) {
 }
 
 function validateGuardrailDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const engineeringRule = readText(rootDir, 'docs/rules/engineering-with-codex-openai.md', failures);
   const validationRule = readText(rootDir, 'docs/rules/validation.md', failures);
   const ciWorkflow = readText(rootDir, '.github/workflows/ci-gateway.yml', failures);
@@ -1593,7 +1689,7 @@ function validateGuardrailDocs(rootDir, failures) {
 }
 
 function validateValidationTruthDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const validationRule = readText(rootDir, 'docs/rules/validation.md', failures);
   const engineeringRule = readText(rootDir, 'docs/rules/engineering-with-codex-openai.md', failures);
@@ -1651,6 +1747,7 @@ function validateDocs(rootDir) {
   const failures = [];
 
   validatePackageScripts(rootDir, failures);
+  validateNpmScriptsAreReal(rootDir, failures);
   validatePositioningBaselineDocs(rootDir, failures);
   validateCliSurfaceDocs(rootDir, failures);
   validateConfigDocs(rootDir, failures);