sigmap 7.5.0 → 7.7.0

package/CHANGELOG.md

@@ -10,6 +10,24 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [7.7.0] — 2026-06-17
+
+Minor release — `sigmap conventions` (grounded codegen, Layer 3).
+
+### Added
+- **`sigmap conventions` — extract & report a repo's coding conventions (#298):** the first slice of Layer 3 (grounded code generation). Detects the dominant **file naming** style, **export style**, and **test framework** for TS/JS/Python so generated code matches the house style instead of drifting (Cause 4: naming/convention drift). New zero-dependency, bundle-safe `src/conventions/extract.js` exposes `classifyNaming` (PascalCase / camelCase / kebab-case / snake_case), `scoreConvention` (a reusable consistency scorer returning `{ dominant, dominantPct, variants, tier }` with tiers at 90% / 70% — Gap 1's scaffold-confidence floor will reuse it), and `extractConventions`. The command writes `.context/conventions.json` and prints a readable report; `--json` emits machine output. `--conflicts`, `--fix`, `--ci`, and CLAUDE.md injection are deferred to follow-ups.
+
+---
+
+## [7.6.0] — 2026-06-17
+
+Minor release — the grounding benchmark (the offline GATE for grounded codegen).
+
+### Added
+- **Grounding benchmark — `npm run benchmark:grounding` (#294):** a deterministic, offline callee-grounding ablation that measures how much ground truth SigMap actually gives an agent. For each corpus repo: `coverage = grounded / universe`, where universe is every symbol defined in the source and grounded is the subset SigMap surfaces in its index (resolvable by `get_callee_signatures`); baseline is 0 (no SigMap → guess every reference). `scripts/run-hallucination-benchmark.mjs` prints per-repo + aggregate coverage; `--save` writes `benchmarks/reports/hallucination.json`; `--gate <pct>` exits non-zero below a threshold. It's an honest *ground-truth-availability proxy*, not a measured LLM hallucination rate (the LLM A/B ablation is a documented follow-up needing an API key). No LLM, no network — runs in CI.
+
+---
+
 ## [7.5.0] — 2026-06-17
 
 Minor release — read-time self-heal completes Layer 1 freshness.

package/gen-context.js

@@ -21,6 +21,166 @@ function __require(key) {
 
 
 // ── ./src/cache/freshen ──
+// ── ./src/conventions/extract ──
+__factories["./src/conventions/extract"] = function(module, exports) {
+  
+  /**
+   * Convention extraction (IMPL.md Layer 3 — grounded code generation).
+   *
+   * Detects a repo's dominant coding conventions so generated code matches the
+   * house style instead of drifting (Cause 4: naming/convention drift). This
+   * first slice covers TS/JS/Python and three conventions: file naming, export
+   * style, and test framework. `scoreConvention` is the reusable consistency
+   * primitive that Gap 1 (scaffold confidence) will also build on.
+   *
+   * Zero dependencies, bundle-safe (fs + path only).
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+
+  const JS_TS_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+  const PY_EXTS = new Set(['.py']);
+  const SCOPED_EXTS = new Set([...JS_TS_EXTS, ...PY_EXTS]);
+
+  // Consistency tiers (IMPL.md §5.1): a convention is only safe to enforce when
+  // it is actually consistent.
+  const TIER_CONSISTENT = 0.9;
+  const TIER_MOSTLY = 0.7;
+
+  /**
+   * Classify a file's base name (without extension) into a naming style.
+   * @param {string} basename a file basename, e.g. "user-service.ts"
+   * @returns {'PascalCase'|'camelCase'|'kebab-case'|'snake_case'|'other'}
+   */
+  function classifyNaming(basename) {
+    let stem = String(basename || '');
+    const dot = stem.indexOf('.');
+    if (dot > 0) stem = stem.slice(0, dot); // strip ext + compound suffix (.test, .d)
+    if (!stem) return 'other';
+    if (/[-]/.test(stem) && /^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(stem)) return 'kebab-case';
+    if (/[_]/.test(stem) && /^[a-z0-9]+(?:_[a-z0-9]+)+$/.test(stem)) return 'snake_case';
+    if (/^[A-Z][A-Za-z0-9]*$/.test(stem) && /[a-z]/.test(stem)) return 'PascalCase';
+    if (/^[a-z][A-Za-z0-9]*$/.test(stem) && /[A-Z]/.test(stem)) return 'camelCase';
+    if (/^[a-z][a-z0-9]*$/.test(stem)) return 'camelCase'; // single lowercase word
+    return 'other';
+  }
+
+  /**
+   * Score a set of categorical observations into a dominant convention plus its
+   * consistency tier. The reusable primitive (IMPL.md §5.2).
+   * @param {string[]} labels observed category for each sample (e.g. naming styles)
+   * @returns {{ dominant: string|null, dominantPct: number, total: number,
+   *             variants: Array<{label:string, count:number, pct:number}>,
+   *             tier: 'consistent'|'mostly'|'inconsistent'|'unknown' }}
+   */
+  function scoreConvention(labels) {
+    const list = (labels || []).filter((l) => l != null && l !== 'other');
+    const total = list.length;
+    if (total === 0) {
+      return { dominant: null, dominantPct: 0, total: 0, variants: [], tier: 'unknown' };
+    }
+    const counts = new Map();
+    for (const l of list) counts.set(l, (counts.get(l) || 0) + 1);
+    const variants = [...counts.entries()]
+      .map(([label, count]) => ({ label, count, pct: count / total }))
+      .sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+    const top = variants[0];
+    let tier = 'inconsistent';
+    if (top.pct >= TIER_CONSISTENT) tier = 'consistent';
+    else if (top.pct >= TIER_MOSTLY) tier = 'mostly';
+    return {
+      dominant: top.label,
+      dominantPct: top.pct,
+      total,
+      variants,
+      tier,
+    };
+  }
+
+  /** Detect JS/TS export style for a single file's source. */
+  function _jsExportStyle(src) {
+    const s = String(src || '');
+    if (/\bexport\s+default\b/.test(s) || /\bmodule\.exports\s*=\s*(?:function|class|\{?\s*[A-Za-z_$])/.test(s)) {
+      // module.exports = { a, b } reads as named; only treat bare assignment as default.
+      if (/\bexport\s+default\b/.test(s)) return 'default';
+      if (/\bmodule\.exports\s*=\s*\{/.test(s)) return 'named';
+      return 'default';
+    }
+    if (/\bexport\s+(?:const|let|var|function|class|async\s+function|\{|type|interface|enum)\b/.test(s)
+      || /\bmodule\.exports\s*=\s*\{/.test(s) || /\bexports\.[A-Za-z_$]/.test(s)) {
+      return 'named';
+    }
+    return 'other';
+  }
+
+  /** Detect the test framework in use from manifests + source heuristics. */
+  function _detectTestFramework(cwd, files) {
+    const deps = {};
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+      Object.assign(deps, pkg.dependencies, pkg.devDependencies);
+    } catch (_) {}
+    for (const fw of ['vitest', 'jest', 'mocha', 'ava', 'jasmine']) {
+      if (deps[fw]) return fw;
+    }
+    // Python: pytest in requirements / pyproject.
+    for (const manifest of ['requirements.txt', 'requirements-dev.txt', 'pyproject.toml', 'setup.cfg']) {
+      try {
+        const raw = fs.readFileSync(path.join(cwd, manifest), 'utf8');
+        if (/\bpytest\b/.test(raw)) return 'pytest';
+        if (/\bunittest\b/.test(raw)) return 'unittest';
+      } catch (_) {}
+    }
+    // Fallback: infer from test file contents.
+    for (const f of files) {
+      if (!/\.(test|spec)\.[jt]sx?$|(^|\/)test_|_test\.py$/.test(f)) continue;
+      let src = '';
+      try { src = fs.readFileSync(f, 'utf8'); } catch (_) { continue; }
+      if (/\bvi\.(fn|mock|spyOn)\b|from ['"]vitest['"]/.test(src)) return 'vitest';
+      if (/\bjest\.(fn|mock|spyOn)\b/.test(src)) return 'jest';
+      if (/\bimport pytest\b|@pytest\./.test(src)) return 'pytest';
+      if (/\bdescribe\(|\bit\(/.test(src)) return 'mocha/jest-style';
+    }
+    return null;
+  }
+
+  /**
+   * Extract repo coding conventions for the scoped languages (TS/JS/Python).
+   * @param {string} cwd repo root
+   * @param {string[]} files absolute paths to source files (e.g. from buildFileList)
+   * @returns {{ fileNaming: object, exportStyle: object, testFramework: string|null,
+   *             scope: string[], scannedFiles: number }}
+   */
+  function extractConventions(cwd, files) {
+    const scoped = (files || []).filter((f) => SCOPED_EXTS.has(path.extname(f).toLowerCase()));
+    const namingLabels = [];
+    const exportLabels = [];
+    for (const f of scoped) {
+      const base = path.basename(f);
+      // Skip test files for the naming convention (they have their own naming).
+      if (!/\.(test|spec)\.[jt]sx?$|(^|\/)test_|_test\.py$/.test(f)) {
+        namingLabels.push(classifyNaming(base));
+      }
+      if (JS_TS_EXTS.has(path.extname(f).toLowerCase())) {
+        let src = '';
+        try { src = fs.readFileSync(f, 'utf8'); } catch (_) {}
+        exportLabels.push(_jsExportStyle(src));
+      }
+    }
+    return {
+      fileNaming: scoreConvention(namingLabels),
+      exportStyle: scoreConvention(exportLabels),
+      testFramework: _detectTestFramework(cwd, scoped),
+      scope: ['typescript', 'javascript', 'python'],
+      scannedFiles: scoped.length,
+    };
+  }
+
+  module.exports = { classifyNaming, scoreConvention, extractConventions };
+  
+};
+
 __factories["./src/cache/freshen"] = function(module, exports) {
   
   /**
@@ -6626,7 +6786,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '7.5.0',
+    version: '7.7.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -12304,7 +12464,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '7.5.0';
+const VERSION = '7.7.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -15473,6 +15633,48 @@ function main() {
     process.exit(0);
   }
 
+  // Layer 3: `sigmap conventions` — extract & report repo coding conventions
+  // (file naming, export style, test framework) for TS/JS/Python so generated
+  // code matches the house style. Writes .context/conventions.json.
+  if (args[0] === 'conventions') {
+    const jsonOut = args.includes('--json');
+    const { extractConventions } = requireSourceOrBundled('./src/conventions/extract');
+    const files = buildFileList(cwd, config);
+    const result = extractConventions(cwd, files);
+
+    const outDir = path.join(cwd, '.context');
+    const outPath = path.join(outDir, 'conventions.json');
+    try {
+      fs.mkdirSync(outDir, { recursive: true });
+      fs.writeFileSync(outPath, JSON.stringify(result, null, 2) + '\n');
+    } catch (e) {
+      console.error(`[sigmap] cannot write ${outPath}: ${e.message}`);
+      process.exit(1);
+    }
+
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(result) + '\n');
+      process.exit(0);
+    }
+
+    const pct = (n) => `${(n * 100).toFixed(0)}%`;
+    const tierLabel = { consistent: 'consistent', mostly: 'mostly', inconsistent: 'mixed', unknown: 'n/a' };
+    const line = (name, conv) => {
+      if (!conv || conv.total === 0) return `  ${name.padEnd(14)} n/a (no samples)`;
+      const variants = conv.variants.slice(1, 3).map((v) => `${v.label} ${pct(v.pct)}`).join(', ');
+      const tail = variants ? `  ·  also: ${variants}` : '';
+      return `  ${name.padEnd(14)} ${conv.dominant} ${pct(conv.dominantPct)} [${tierLabel[conv.tier]}]${tail}`;
+    };
+
+    console.log('[sigmap] conventions  (TS/JS/Python)');
+    console.log(`  scanned        ${result.scannedFiles} file${result.scannedFiles === 1 ? '' : 's'}`);
+    console.log(line('file naming', result.fileNaming));
+    console.log(line('export style', result.exportStyle));
+    console.log(`  ${'test framework'.padEnd(14)} ${result.testFramework || 'none detected'}`);
+    console.log(`\n  → wrote ${path.relative(cwd, outPath)}`);
+    process.exit(0);
+  }
+
   // v7.0.0: `sigmap squeeze <file|->` — minimize a pasted stacktrace / CI-log / JSON blob
   if (args[0] === 'squeeze') {
     const jsonOut = args.includes('--json');

package/llms-full.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.5.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.7.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 

package/llms.txt

@@ -9,7 +9,7 @@ the files relevant to the task — cutting tokens ~97% while keeping answers
 grounded. Deterministic, offline, no embeddings or vector database. Works with
 Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 7.5.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
+# Version: 7.7.0 | Benchmark: sigmap-v7.0-main (2026-06-14)
 # Source: auto-generated from package.json, version.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "7.5.0",
+  "version": "7.7.0",
   "description": "97% token reduction for AI coding. Extracts function & class signatures with TF-IDF ranking to feed only the right files to Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP. Zero dependencies, runs offline via npx.",
   "main": "packages/core/index.js",
   "exports": {
@@ -38,7 +38,8 @@
     "version:sync": "node scripts/sync-versions.mjs",
     "generate:llms": "node scripts/generate-llms.mjs",
     "validate:llms": "node scripts/validate-llms.mjs",
-    "prepublishOnly": "node scripts/check-bundle.mjs && node scripts/check-version-meta.mjs && node scripts/generate-llms.mjs"
+    "prepublishOnly": "node scripts/check-bundle.mjs && node scripts/check-version-meta.mjs && node scripts/generate-llms.mjs",
+    "benchmark:grounding": "node scripts/run-hallucination-benchmark.mjs"
   },
   "files": [
     "gen-context.js",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "7.5.0",
+  "version": "7.7.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "7.5.0",
+  "version": "7.7.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/conventions/extract.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * Convention extraction (IMPL.md Layer 3 — grounded code generation).
+ *
+ * Detects a repo's dominant coding conventions so generated code matches the
+ * house style instead of drifting (Cause 4: naming/convention drift). This
+ * first slice covers TS/JS/Python and three conventions: file naming, export
+ * style, and test framework. `scoreConvention` is the reusable consistency
+ * primitive that Gap 1 (scaffold confidence) will also build on.
+ *
+ * Zero dependencies, bundle-safe (fs + path only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const JS_TS_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const PY_EXTS = new Set(['.py']);
+const SCOPED_EXTS = new Set([...JS_TS_EXTS, ...PY_EXTS]);
+
+// Consistency tiers (IMPL.md §5.1): a convention is only safe to enforce when
+// it is actually consistent.
+const TIER_CONSISTENT = 0.9;
+const TIER_MOSTLY = 0.7;
+
+/**
+ * Classify a file's base name (without extension) into a naming style.
+ * @param {string} basename a file basename, e.g. "user-service.ts"
+ * @returns {'PascalCase'|'camelCase'|'kebab-case'|'snake_case'|'other'}
+ */
+function classifyNaming(basename) {
+  let stem = String(basename || '');
+  const dot = stem.indexOf('.');
+  if (dot > 0) stem = stem.slice(0, dot); // strip ext + compound suffix (.test, .d)
+  if (!stem) return 'other';
+  if (/[-]/.test(stem) && /^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(stem)) return 'kebab-case';
+  if (/[_]/.test(stem) && /^[a-z0-9]+(?:_[a-z0-9]+)+$/.test(stem)) return 'snake_case';
+  if (/^[A-Z][A-Za-z0-9]*$/.test(stem) && /[a-z]/.test(stem)) return 'PascalCase';
+  if (/^[a-z][A-Za-z0-9]*$/.test(stem) && /[A-Z]/.test(stem)) return 'camelCase';
+  if (/^[a-z][a-z0-9]*$/.test(stem)) return 'camelCase'; // single lowercase word
+  return 'other';
+}
+
+/**
+ * Score a set of categorical observations into a dominant convention plus its
+ * consistency tier. The reusable primitive (IMPL.md §5.2).
+ * @param {string[]} labels observed category for each sample (e.g. naming styles)
+ * @returns {{ dominant: string|null, dominantPct: number, total: number,
+ *             variants: Array<{label:string, count:number, pct:number}>,
+ *             tier: 'consistent'|'mostly'|'inconsistent'|'unknown' }}
+ */
+function scoreConvention(labels) {
+  const list = (labels || []).filter((l) => l != null && l !== 'other');
+  const total = list.length;
+  if (total === 0) {
+    return { dominant: null, dominantPct: 0, total: 0, variants: [], tier: 'unknown' };
+  }
+  const counts = new Map();
+  for (const l of list) counts.set(l, (counts.get(l) || 0) + 1);
+  const variants = [...counts.entries()]
+    .map(([label, count]) => ({ label, count, pct: count / total }))
+    .sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+  const top = variants[0];
+  let tier = 'inconsistent';
+  if (top.pct >= TIER_CONSISTENT) tier = 'consistent';
+  else if (top.pct >= TIER_MOSTLY) tier = 'mostly';
+  return {
+    dominant: top.label,
+    dominantPct: top.pct,
+    total,
+    variants,
+    tier,
+  };
+}
+
+/** Detect JS/TS export style for a single file's source. */
+function _jsExportStyle(src) {
+  const s = String(src || '');
+  if (/\bexport\s+default\b/.test(s) || /\bmodule\.exports\s*=\s*(?:function|class|\{?\s*[A-Za-z_$])/.test(s)) {
+    // module.exports = { a, b } reads as named; only treat bare assignment as default.
+    if (/\bexport\s+default\b/.test(s)) return 'default';
+    if (/\bmodule\.exports\s*=\s*\{/.test(s)) return 'named';
+    return 'default';
+  }
+  if (/\bexport\s+(?:const|let|var|function|class|async\s+function|\{|type|interface|enum)\b/.test(s)
+    || /\bmodule\.exports\s*=\s*\{/.test(s) || /\bexports\.[A-Za-z_$]/.test(s)) {
+    return 'named';
+  }
+  return 'other';
+}
+
+/** Detect the test framework in use from manifests + source heuristics. */
+function _detectTestFramework(cwd, files) {
+  const deps = {};
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    Object.assign(deps, pkg.dependencies, pkg.devDependencies);
+  } catch (_) {}
+  for (const fw of ['vitest', 'jest', 'mocha', 'ava', 'jasmine']) {
+    if (deps[fw]) return fw;
+  }
+  // Python: pytest in requirements / pyproject.
+  for (const manifest of ['requirements.txt', 'requirements-dev.txt', 'pyproject.toml', 'setup.cfg']) {
+    try {
+      const raw = fs.readFileSync(path.join(cwd, manifest), 'utf8');
+      if (/\bpytest\b/.test(raw)) return 'pytest';
+      if (/\bunittest\b/.test(raw)) return 'unittest';
+    } catch (_) {}
+  }
+  // Fallback: infer from test file contents.
+  for (const f of files) {
+    if (!/\.(test|spec)\.[jt]sx?$|(^|\/)test_|_test\.py$/.test(f)) continue;
+    let src = '';
+    try { src = fs.readFileSync(f, 'utf8'); } catch (_) { continue; }
+    if (/\bvi\.(fn|mock|spyOn)\b|from ['"]vitest['"]/.test(src)) return 'vitest';
+    if (/\bjest\.(fn|mock|spyOn)\b/.test(src)) return 'jest';
+    if (/\bimport pytest\b|@pytest\./.test(src)) return 'pytest';
+    if (/\bdescribe\(|\bit\(/.test(src)) return 'mocha/jest-style';
+  }
+  return null;
+}
+
+/**
+ * Extract repo coding conventions for the scoped languages (TS/JS/Python).
+ * @param {string} cwd repo root
+ * @param {string[]} files absolute paths to source files (e.g. from buildFileList)
+ * @returns {{ fileNaming: object, exportStyle: object, testFramework: string|null,
+ *             scope: string[], scannedFiles: number }}
+ */
+function extractConventions(cwd, files) {
+  const scoped = (files || []).filter((f) => SCOPED_EXTS.has(path.extname(f).toLowerCase()));
+  const namingLabels = [];
+  const exportLabels = [];
+  for (const f of scoped) {
+    const base = path.basename(f);
+    // Skip test files for the naming convention (they have their own naming).
+    if (!/\.(test|spec)\.[jt]sx?$|(^|\/)test_|_test\.py$/.test(f)) {
+      namingLabels.push(classifyNaming(base));
+    }
+    if (JS_TS_EXTS.has(path.extname(f).toLowerCase())) {
+      let src = '';
+      try { src = fs.readFileSync(f, 'utf8'); } catch (_) {}
+      exportLabels.push(_jsExportStyle(src));
+    }
+  }
+  return {
+    fileNaming: scoreConvention(namingLabels),
+    exportStyle: scoreConvention(exportLabels),
+    testFramework: _detectTestFramework(cwd, scoped),
+    scope: ['typescript', 'javascript', 'python'],
+    scannedFiles: scoped.length,
+  };
+}
+
+module.exports = { classifyNaming, scoreConvention, extractConventions };

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '7.5.0',
+  version: '7.7.0',
   description: 'SigMap MCP server — code signatures on demand',
 };