@mycodemap/mycodemap 0.5.0 → 0.5.2-beta.1

package/scripts/benchmark-governance-graph.mjs

@@ -0,0 +1,132 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const loadModule = async (relativePath) => import(pathToFileURL(path.join(repoRoot, relativePath)).href);
+const { SQLiteStorage } = await loadModule('dist/infrastructure/storage/adapters/SQLiteStorage.js');
+const {
+  CONTRACT_GATE_MAX_CHANGED_FILES_FOR_HARD_GATE,
+  CONTRACT_GATE_MAX_FALSE_POSITIVE_RATE,
+  CONTRACT_GATE_PERF_BUDGET,
+} = await loadModule('dist/cli/contract-gate-thresholds.js');
+
+function parseArgs(argv) {
+  const args = {
+    maxFiles: CONTRACT_GATE_PERF_BUDGET.maxFiles,
+    maxLoadMs: CONTRACT_GATE_PERF_BUDGET.maxLoadMs,
+    maxRssMb: CONTRACT_GATE_PERF_BUDGET.maxRssMb,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    const next = argv[index + 1];
+
+    if (current === '--max-files' && next) {
+      args.maxFiles = Number(next);
+    }
+    if (current === '--max-load-ms' && next) {
+      args.maxLoadMs = Number(next);
+    }
+    if (current === '--max-rss-mb' && next) {
+      args.maxRssMb = Number(next);
+    }
+  }
+
+  return args;
+}
+
+function createLinearGraph(moduleCount) {
+  const modules = Array.from({ length: moduleCount }, (_, index) => ({
+    id: `mod-${index + 1}`,
+    projectId: 'proj-benchmark',
+    path: `src/mod-${index + 1}.ts`,
+    language: 'ts',
+    stats: {
+      lines: 10,
+      codeLines: 8,
+      commentLines: 1,
+      blankLines: 1,
+    },
+  }));
+  const dependencies = modules.slice(1).map((module, index) => ({
+    id: `dep-${index + 1}`,
+    sourceId: module.id,
+    targetId: modules[index]?.id ?? module.id,
+    type: 'import',
+  }));
+
+  return {
+    project: {
+      id: 'proj-benchmark',
+      name: 'governance-benchmark',
+      rootPath: '/fixture',
+      createdAt: new Date('2026-04-15T00:00:00Z'),
+      updatedAt: new Date('2026-04-15T00:00:00Z'),
+    },
+    modules,
+    symbols: [],
+    dependencies,
+  };
+}
+
+async function runCase(moduleCount, thresholds) {
+  const rootDir = mkdtempSync(path.join(tmpdir(), 'codemap-governance-benchmark-'));
+  const storage = new SQLiteStorage(
+    {
+      type: 'sqlite',
+      databasePath: '.codemap/governance.sqlite',
+    },
+    {
+      governanceGraphThresholds: thresholds,
+    }
+  );
+
+  try {
+    await storage.initialize(rootDir);
+    await storage.saveCodeGraph(createLinearGraph(moduleCount));
+    return storage.getGovernanceGraphRuntimeStats();
+  } finally {
+    await storage.close();
+    rmSync(rootDir, { recursive: true, force: true });
+  }
+}
+
+const thresholds = parseArgs(process.argv.slice(2));
+const benchmarkModuleCount = Math.min(Math.max(32, thresholds.maxFiles - 1), 512);
+const benchmarkStats = await runCase(benchmarkModuleCount, thresholds);
+const fallbackStats = await runCase(thresholds.maxFiles + 1, thresholds);
+
+if (benchmarkStats.cacheMode !== 'memory-eager') {
+  throw new Error(
+    `benchmark graph should stay memory-eager, got ${benchmarkStats.cacheMode} (${benchmarkStats.warning ?? 'no warning'})`
+  );
+}
+
+if (benchmarkStats.loadMs > thresholds.maxLoadMs) {
+  throw new Error(
+    `benchmark load time ${benchmarkStats.loadMs.toFixed(2)}ms exceeds maxLoadMs=${thresholds.maxLoadMs}`
+  );
+}
+
+if (benchmarkStats.rssDeltaMb > thresholds.maxRssMb) {
+  throw new Error(
+    `benchmark rss delta ${benchmarkStats.rssDeltaMb.toFixed(2)}MB exceeds maxRssMb=${thresholds.maxRssMb}`
+  );
+}
+
+if (fallbackStats.cacheMode !== 'sqlite-direct') {
+  throw new Error(`oversize rehearsal should fall back to sqlite-direct, got ${fallbackStats.cacheMode}`);
+}
+
+console.log(JSON.stringify({
+  ok: true,
+  thresholds,
+  contractGate: {
+    maxChangedFilesForHardGate: CONTRACT_GATE_MAX_CHANGED_FILES_FOR_HARD_GATE,
+    maxFalsePositiveRate: CONTRACT_GATE_MAX_FALSE_POSITIVE_RATE,
+  },
+  benchmark: benchmarkStats,
+  failureRehearsal: fallbackStats,
+}, null, 2));

package/scripts/calibrate-contract-gate.mjs

@@ -0,0 +1,221 @@
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const loadModule = async (relativePath) => import(pathToFileURL(path.join(repoRoot, relativePath)).href);
+const { runContractCheck } = await loadModule('dist/cli/contract-checker.js');
+const { resolveContractDiffScope } = await loadModule('dist/cli/contract-diff-scope.js');
+const { renderGitHubAnnotations } = await loadModule('dist/cli/commands/check.js');
+const {
+  CONTRACT_GATE_MAX_CHANGED_FILES_FOR_HARD_GATE,
+  CONTRACT_GATE_MAX_FALSE_POSITIVE_RATE,
+  CONTRACT_GATE_PERF_BUDGET,
+} = await loadModule('dist/cli/contract-gate-thresholds.js');
+
+function parseArgs(argv) {
+  const args = {
+    maxChangedFiles: CONTRACT_GATE_MAX_CHANGED_FILES_FOR_HARD_GATE,
+    maxFalsePositiveRate: CONTRACT_GATE_MAX_FALSE_POSITIVE_RATE,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    const next = argv[index + 1];
+    if (current === '--max-changed-files' && next) {
+      args.maxChangedFiles = Number(next);
+    }
+    if (current === '--max-false-positive-rate' && next) {
+      args.maxFalsePositiveRate = Number(next);
+    }
+  }
+
+  return args;
+}
+
+function collectTsFiles(rootDir) {
+  const files = [];
+  const queue = [rootDir];
+
+  while (queue.length > 0) {
+    const currentDir = queue.shift();
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+      const entryPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === '__tests__') {
+          continue;
+        }
+        queue.push(entryPath);
+        continue;
+      }
+
+      if (/\.[cm]?[jt]sx?$/u.test(entry.name) && !/\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(entry.name)) {
+        files.push(entryPath);
+      }
+    }
+  }
+
+  return files.sort();
+}
+
+async function runCalibrationCase(testCase) {
+  const startedAt = performance.now();
+  const diffScope = await resolveContractDiffScope({
+    againstPath: testCase.againstPath,
+    rootDir: repoRoot,
+    changedFiles: testCase.changedFiles,
+    base: testCase.base,
+  });
+  const result = await runContractCheck({
+    contractPath: testCase.contractPath,
+    againstPath: testCase.againstPath,
+    rootDir: repoRoot,
+    scanMode: diffScope.scanMode,
+    changedFiles: diffScope.changedFiles,
+    warnings: diffScope.warnings,
+  });
+  const durationMs = performance.now() - startedAt;
+
+  return {
+    name: testCase.name,
+    kind: testCase.kind,
+    durationMs: Math.round(durationMs * 100) / 100,
+    scanMode: diffScope.scanMode,
+    changedFiles: diffScope.changedFiles,
+    warnings: result.warnings,
+    errorCount: result.summary.error_count,
+    warningCount: result.summary.warn_count,
+    annotationCount: renderGitHubAnnotations(result)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean).length,
+  };
+}
+
+const args = parseArgs(process.argv.slice(2));
+const designFixturesDir = path.join(repoRoot, 'tests', 'fixtures', 'design-contracts');
+const contractFixturesDir = path.join(repoRoot, 'tests', 'fixtures', 'contract-check');
+const repoSourceFiles = collectTsFiles(path.join(repoRoot, 'src')).slice(0, args.maxChangedFiles + 1);
+
+if (repoSourceFiles.length < args.maxChangedFiles + 1) {
+  throw new Error(`无法收集足够的 repo source files 来验证 hard-gate window，至少需要 ${args.maxChangedFiles + 1} 个文件`);
+}
+
+const calibrationCases = [
+  {
+    name: 'good-valid-core-service',
+    kind: 'good',
+    contractPath: path.join(designFixturesDir, 'valid-frontmatter.design.md'),
+    againstPath: path.join(contractFixturesDir, 'valid-project'),
+    changedFiles: [path.join(contractFixturesDir, 'valid-project', 'src', 'core', 'service.ts')],
+  },
+  {
+    name: 'good-valid-reader',
+    kind: 'good',
+    contractPath: path.join(designFixturesDir, 'valid-frontmatter.design.md'),
+    againstPath: path.join(contractFixturesDir, 'valid-project'),
+    changedFiles: [path.join(contractFixturesDir, 'valid-project', 'src', 'infrastructure', 'parser', 'reader.ts')],
+  },
+  {
+    name: 'good-valid-domain-public-api',
+    kind: 'good',
+    contractPath: path.join(designFixturesDir, 'valid-frontmatter.design.md'),
+    againstPath: path.join(contractFixturesDir, 'valid-project'),
+    changedFiles: [path.join(contractFixturesDir, 'valid-project', 'src', 'app', 'use-domain.ts')],
+  },
+  {
+    name: 'bad-invalid-core-layer',
+    kind: 'bad',
+    contractPath: path.join(designFixturesDir, 'valid-frontmatter.design.md'),
+    againstPath: path.join(contractFixturesDir, 'invalid-project'),
+    changedFiles: [path.join(contractFixturesDir, 'invalid-project', 'src', 'core', 'bad.ts')],
+  },
+  {
+    name: 'bad-barrel-downstream',
+    kind: 'bad',
+    contractPath: path.join(designFixturesDir, 'contract-barrel.design.md'),
+    againstPath: path.join(contractFixturesDir, 'barrel-project'),
+    changedFiles: [path.join(contractFixturesDir, 'barrel-project', 'src', 'domain', 'index.ts')],
+  },
+];
+
+const caseResults = [];
+for (const testCase of calibrationCases) {
+  caseResults.push(await runCalibrationCase(testCase));
+}
+
+const windowScope = await resolveContractDiffScope({
+  againstPath: path.join(repoRoot, 'src'),
+  rootDir: repoRoot,
+  changedFiles: repoSourceFiles,
+});
+const fallbackScope = await resolveContractDiffScope({
+  againstPath: path.join(contractFixturesDir, 'invalid-project'),
+  rootDir: repoRoot,
+  base: 'not-a-real-base-ref',
+});
+
+const goodCases = caseResults.filter((entry) => entry.kind === 'good');
+const badCases = caseResults.filter((entry) => entry.kind === 'bad');
+const falsePositives = goodCases.filter((entry) => entry.errorCount > 0);
+const falseNegatives = badCases.filter((entry) => entry.errorCount === 0);
+const missingAnnotations = badCases.filter((entry) => entry.annotationCount === 0);
+const falsePositiveRate = goodCases.length === 0 ? 0 : falsePositives.length / goodCases.length;
+const maxObservedDurationMs = caseResults.reduce((max, entry) => Math.max(max, entry.durationMs), 0);
+
+const failures = [];
+if (falsePositiveRate > args.maxFalsePositiveRate) {
+  failures.push(`false-positive rate ${falsePositiveRate.toFixed(2)} exceeds max ${args.maxFalsePositiveRate.toFixed(2)}`);
+}
+if (falseNegatives.length > 0) {
+  failures.push(`false negatives detected: ${falseNegatives.map((entry) => entry.name).join(', ')}`);
+}
+if (missingAnnotations.length > 0) {
+  failures.push(`annotation output missing for bad cases: ${missingAnnotations.map((entry) => entry.name).join(', ')}`);
+}
+if (maxObservedDurationMs > CONTRACT_GATE_PERF_BUDGET.maxLoadMs) {
+  failures.push(`max case duration ${maxObservedDurationMs.toFixed(2)}ms exceeds perf budget ${CONTRACT_GATE_PERF_BUDGET.maxLoadMs}ms`);
+}
+if (!windowScope.warnings.some((warning) => warning.code === 'hard-gate-window-exceeded')) {
+  failures.push('hard-gate window overrun did not emit hard-gate-window-exceeded warning');
+}
+if (!fallbackScope.warnings.some((warning) => warning.code === 'diff-scope-fallback')) {
+  failures.push('invalid diff base did not emit diff-scope-fallback warning');
+}
+
+const recommendation = failures.length === 0
+  ? 'hard-gate-ok'
+  : failures.some((failure) => failure.includes('false-positive rate') || failure.includes('false negatives') || failure.includes('annotation output'))
+    ? 'warn-only'
+    : 're-scope';
+
+const output = {
+  ok: failures.length === 0,
+  thresholds: {
+    maxChangedFiles: args.maxChangedFiles,
+    maxFalsePositiveRate: args.maxFalsePositiveRate,
+    perfBudget: CONTRACT_GATE_PERF_BUDGET,
+  },
+  summary: {
+    goodCaseCount: goodCases.length,
+    badCaseCount: badCases.length,
+    falsePositiveCount: falsePositives.length,
+    falseNegativeCount: falseNegatives.length,
+    falsePositiveRate: Math.round(falsePositiveRate * 1000) / 1000,
+    maxObservedDurationMs,
+    recommendation,
+  },
+  warnings: {
+    windowScope: windowScope.warnings,
+    fallbackScope: fallbackScope.warnings,
+  },
+  cases: caseResults,
+  failures,
+};
+
+console.log(JSON.stringify(output, null, 2));
+
+if (failures.length > 0) {
+  process.exitCode = 1;
+}

package/scripts/capability-report.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Generate a repo-local capability baseline report without gating workflows."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+CommandRunner = Callable[[Sequence[str], Path, int], dict[str, Any]]
+
+
+def iso_utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def trim_output(value: str | bytes | None, limit: int = 400) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        value = value.decode("utf-8", errors="replace")
+    text = value.strip()
+    return text[:limit]
+
+
+def run_command(command: Sequence[str], cwd: Path, timeout: int) -> dict[str, Any]:
+    started = time.perf_counter()
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=cwd,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        duration_ms = round((time.perf_counter() - started) * 1000)
+        return {
+            "available": True,
+            "returncode": completed.returncode,
+            "stdout": trim_output(completed.stdout),
+            "stderr": trim_output(completed.stderr),
+            "duration_ms": duration_ms,
+        }
+    except FileNotFoundError as error:
+        duration_ms = round((time.perf_counter() - started) * 1000)
+        return {
+            "available": False,
+            "returncode": None,
+            "stdout": "",
+            "stderr": str(error),
+            "duration_ms": duration_ms,
+        }
+    except subprocess.TimeoutExpired as error:
+        duration_ms = round((time.perf_counter() - started) * 1000)
+        return {
+            "available": True,
+            "returncode": None,
+            "stdout": trim_output(error.stdout),
+            "stderr": trim_output(error.stderr) or f"timeout after {timeout}s",
+            "duration_ms": duration_ms,
+        }
+
+
+def classify_status(kind: str, available: bool, returncode: int | None) -> str:
+    if kind == "required":
+        return "PASS" if available and returncode == 0 else "REQUIRED_FAIL"
+    if kind == "optional":
+        return "PASS" if available and returncode == 0 else "OPTIONAL_DISABLED"
+    if kind == "strategy":
+        return "STRATEGY_PASS" if available and returncode == 0 else "STRATEGY_FAIL"
+    raise ValueError(f"unsupported capability kind: {kind}")
+
+
+def build_item(
+    name: str,
+    kind: str,
+    command: Sequence[str],
+    *,
+    cwd: Path,
+    timeout: int,
+    runner: CommandRunner = run_command,
+    notes: list[str] | None = None,
+) -> dict[str, Any]:
+    outcome = runner(command, cwd, timeout)
+    item: dict[str, Any] = {
+        "name": name,
+        "kind": kind,
+        "command": " ".join(command),
+        "status": classify_status(kind, outcome["available"], outcome["returncode"]),
+        "duration_ms": outcome["duration_ms"],
+        "returncode": outcome["returncode"],
+        "stdout": outcome["stdout"],
+        "stderr": outcome["stderr"],
+    }
+    if notes:
+        item["notes"] = notes
+    return item
+
+
+def build_git_hooks_item(project_root: Path, runner: CommandRunner = run_command) -> dict[str, Any]:
+    item = build_item(
+        "git_hooks",
+        "required",
+        ["git", "config", "core.hooksPath"],
+        cwd=project_root,
+        timeout=10,
+        runner=runner,
+    )
+    configured_path = item["stdout"].strip()
+    if item["returncode"] == 0 and configured_path:
+        item["notes"] = [f"core.hooksPath={configured_path}"]
+        return item
+
+    fallback_dir = project_root / ".githooks"
+    if fallback_dir.is_dir():
+        item["status"] = "PASS"
+        item["notes"] = ["core.hooksPath unset; fallback .githooks directory exists"]
+        return item
+
+    item["status"] = "REQUIRED_FAIL"
+    item["notes"] = ["core.hooksPath unset and .githooks directory missing"]
+    return item
+
+
+def build_optional_validator_item(project_root: Path, runner: CommandRunner = run_command) -> dict[str, Any]:
+    validator_path = project_root / "scripts" / "validate-rules.py"
+    if not validator_path.is_file():
+        return {
+            "name": "validate_rules",
+            "kind": "optional",
+            "command": "python3 scripts/validate-rules.py code --report-only",
+            "status": "OPTIONAL_DISABLED",
+            "duration_ms": None,
+            "returncode": None,
+            "stdout": "",
+            "stderr": "",
+            "notes": ["scripts/validate-rules.py is unavailable"],
+        }
+
+    item = build_item(
+        "validate_rules",
+        "optional",
+        ["python3", "scripts/validate-rules.py", "code", "--report-only"],
+        cwd=project_root,
+        timeout=180,
+        runner=runner,
+    )
+    if item["status"] == "OPTIONAL_DISABLED" and not item.get("notes"):
+        item["notes"] = ["validator exists but report-only command is unavailable"]
+    return item
+
+
+def summarize(items: list[dict[str, Any]]) -> dict[str, dict[str, int]]:
+    summary = {
+        "required": {"passed": 0, "failed": 0, "total": 0},
+        "optional": {"passed": 0, "disabled": 0, "total": 0},
+        "strategy": {"passed": 0, "failed": 0, "total": 0},
+    }
+
+    for item in items:
+        kind = item["kind"]
+        status = item["status"]
+        summary[kind]["total"] += 1
+        if kind == "required":
+            summary[kind]["passed" if status == "PASS" else "failed"] += 1
+        elif kind == "optional":
+            summary[kind]["passed" if status == "PASS" else "disabled"] += 1
+        else:
+            summary[kind]["passed" if status == "STRATEGY_PASS" else "failed"] += 1
+    return summary
+
+
+def build_report(project_root: Path = PROJECT_ROOT, runner: CommandRunner = run_command) -> dict[str, Any]:
+    items = [
+        build_item("python3", "required", ["python3", "--version"], cwd=project_root, timeout=10, runner=runner),
+        build_item("node", "required", ["node", "--version"], cwd=project_root, timeout=10, runner=runner),
+        build_git_hooks_item(project_root, runner=runner),
+        build_item(
+            "typecheck",
+            "strategy",
+            ["npm", "run", "typecheck"],
+            cwd=project_root,
+            timeout=300,
+            runner=runner,
+        ),
+        build_item(
+            "tests",
+            "strategy",
+            ["npm", "test"],
+            cwd=project_root,
+            timeout=300,
+            runner=runner,
+        ),
+        build_item(
+            "lint",
+            "strategy",
+            ["npm", "run", "lint"],
+            cwd=project_root,
+            timeout=300,
+            runner=runner,
+        ),
+        build_item(
+            "codemap_cli",
+            "optional",
+            ["node", "dist/cli/index.js", "--version"],
+            cwd=project_root,
+            timeout=30,
+            runner=runner,
+        ),
+        build_optional_validator_item(project_root, runner=runner),
+    ]
+
+    return {
+        "version": 1,
+        "generated_at": iso_utc_now(),
+        "summary": summarize(items),
+        "items": items,
+    }
+
+
+def write_report(report: dict[str, Any], output_path: Path) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate a capability baseline report for repo-local rule control.")
+    parser.add_argument("--output", type=Path, help="Optional path to write the JSON report.")
+    return parser.parse_args(argv)
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    report_builder: Callable[[], dict[str, Any]] | None = None,
+) -> int:
+    args = parse_args(argv)
+    report = (report_builder or build_report)()
+    if args.output is not None:
+        write_report(report, args.output)
+    json.dump(report, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/pre-release-check.js

@@ -110,8 +110,8 @@ function extractVersionFromText(content) {
 }
 
 function extractVersionFromYAML(content) {
-  // 匹配 YAML 中的 version: "x.x.x" 或 version: x.x.x
-  const match = content.match(/version[:\s]+["']?(\d+\.\d+\.\d+)["']?/i);
+  // 匹配 YAML 中的 version: "x.x.x"、version: x.x.x 或 prerelease 版本
+  const match = content.match(/version[:\s]+["']?(\d+\.\d+\.\d+(?:-[\w.]+)?)["']?/i);
   return match ? match[1] : null;
 }