snipara-companion 3.6.2 → 3.6.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.6.3
+
+- Labels every semantic `confidence` value as an uncalibrated
+  `heuristic_prior`, preserving the numeric compatibility field without
+  presenting it as a measured probability.
+- Loads bounded, literal project naming terms from
+  `.snipara/semantic-rules.json`; teams can extend or replace English defaults
+  without enabling arbitrary regular expressions.
+- Keeps historical regression associations strictly shadow-only and marks
+  their association strength as uncalibrated.
+
 ## New In 3.6.2
 
 - Adds `snipara.semantic.v1` to local code overlays and impact results with

package/dist/index.d.ts

@@ -1825,6 +1825,8 @@ interface LocalSemanticAssertion {
     predicate: LocalSemanticPredicate;
     value: string | boolean;
     confidence: number;
+    scoreKind: "heuristic_prior";
+    calibrated: false;
     source: "typescript-compiler-api" | "language-parser" | "architecture-pattern-rules" | "criticality-rules" | "graph-criticality-rules";
     extractorVersion: 1;
     evidence: LocalSemanticEvidence[];
@@ -1833,6 +1835,29 @@ interface LocalSemanticModel {
     version: "snipara.semantic.v1";
     extractorVersion: 1;
     source: "deterministic-graph-inference";
+    modelType: "rule-based-heuristic";
+    scoreContract: {
+        kind: "heuristic_prior";
+        calibrated: false;
+        probability: false;
+        comparableAcrossProjects: false;
+        basis: "hand-tuned-v1";
+        rulesetVersion: 1;
+        interpretation: string;
+    };
+    ruleConfig: {
+        version: "snipara.semantic.rules.v1";
+        source: "defaults" | "project-file";
+        path: ".snipara/semantic-rules.json";
+        replaceDefaults: boolean;
+        sensitivePathTermCount: number;
+        contractPathTermCount: number;
+        testPathTermCount: number;
+        architectureRoleTermCount: number;
+        configuredRoles: string[];
+        configHash: string;
+        warnings: string[];
+    };
     scope: "repository" | "impact";
     assertions: LocalSemanticAssertion[];
     publicContracts: LocalSemanticAssertion[];

package/dist/index.js

@@ -3822,7 +3822,10 @@ function buildLocalCodeOverlay(options = {}) {
     extractedEdges.push(...extracted.edges);
   }
   const edges = resolveLocalGraphEdges(files, symbols, imports, references2, extractedEdges);
-  const semantic = buildLocalSemanticModel({ symbols, edges });
+  const semantic = buildLocalSemanticModel(
+    { symbols, edges },
+    { semanticRules: loadLocalSemanticRuleConfig(repoRoot) }
+  );
   for (const file of files) {
     file.edgeCount = edges.filter((edge) => edge.filePath === file.path).length;
   }
@@ -4308,9 +4311,125 @@ function uniqueTraversalFiles(nodes, excluded) {
     )
   ].sort();
 }
+var LOCAL_SEMANTIC_RULE_CONFIG_PATH = import_path.default.join(".snipara", "semantic-rules.json");
+var LOCAL_SEMANTIC_RULE_CONFIG_VERSION = "snipara.semantic.rules.v1";
+var LOCAL_SEMANTIC_MAX_TERMS = 64;
+var LOCAL_SEMANTIC_MAX_TERM_LENGTH = 80;
+var LOCAL_SEMANTIC_MAX_ROLES = 24;
 var LOCAL_SEMANTIC_TEST_PATH = /(^|\/)(tests?|__tests__|fixtures?)(\/|$)|\.(test|spec)\./i;
 var LOCAL_SEMANTIC_SENSITIVE_PATH = /(^|\/)(auth|middleware|billing|payments?|stripe|webhooks?|prisma|schema|migrations?|deploy)(\/|\.|$)/i;
 var LOCAL_SEMANTIC_CONTRACT_PATH = /(^|\/)(schemas?|contracts?|protocols?|interfaces?|config|tool_defs)(\/|\.|$)|route\.(ts|tsx|py)$/i;
+function localSemanticTerms(raw, label, warnings) {
+  if (raw === void 0 || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    warnings.push(`${label} terms must be an array.`);
+    return [];
+  }
+  const terms = [];
+  for (const value of raw.slice(0, LOCAL_SEMANTIC_MAX_TERMS)) {
+    const term = String(value).trim().toLowerCase();
+    if (!term) continue;
+    if (term.length > LOCAL_SEMANTIC_MAX_TERM_LENGTH) {
+      warnings.push(
+        `Ignored a ${label} term longer than ${LOCAL_SEMANTIC_MAX_TERM_LENGTH} characters.`
+      );
+      continue;
+    }
+    terms.push(term);
+  }
+  if (raw.length > LOCAL_SEMANTIC_MAX_TERMS) {
+    warnings.push(`Limited ${label} terms to ${LOCAL_SEMANTIC_MAX_TERMS} entries.`);
+  }
+  return [...new Set(terms)];
+}
+function loadLocalSemanticRuleConfig(repoRoot) {
+  const defaults = {
+    replaceDefaults: false,
+    sensitivePathTerms: [],
+    contractPathTerms: [],
+    testPathTerms: [],
+    architectureRoleTerms: {},
+    source: "defaults",
+    warnings: []
+  };
+  const configPath = import_path.default.join(repoRoot, LOCAL_SEMANTIC_RULE_CONFIG_PATH);
+  if (!import_fs.default.existsSync(configPath)) return defaults;
+  try {
+    const parsed = JSON.parse(import_fs.default.readFileSync(configPath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {
+        ...defaults,
+        source: "project-file",
+        warnings: ["Semantic rule config must be a JSON object; defaults were retained."]
+      };
+    }
+    const raw = parsed;
+    const warnings = [];
+    const rawRoles = raw.architectureRoleTerms ?? raw.architecture_role_terms ?? {};
+    const architectureRoleTerms = {};
+    if (rawRoles && typeof rawRoles === "object" && !Array.isArray(rawRoles)) {
+      for (const [rawRole, rawTerms] of Object.entries(rawRoles).slice(
+        0,
+        LOCAL_SEMANTIC_MAX_ROLES
+      )) {
+        const role = rawRole.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+        if (!role) {
+          warnings.push("Ignored an empty or unsupported architecture role name.");
+          continue;
+        }
+        architectureRoleTerms[role] = localSemanticTerms(
+          rawTerms,
+          `architecture role ${role}`,
+          warnings
+        );
+      }
+    } else if (rawRoles) {
+      warnings.push("architectureRoleTerms must be an object of role-to-term arrays.");
+    }
+    return {
+      replaceDefaults: Boolean(raw.replaceDefaults ?? raw.replace_defaults ?? false),
+      sensitivePathTerms: localSemanticTerms(
+        raw.sensitivePathTerms ?? raw.sensitive_path_terms,
+        "sensitive path",
+        warnings
+      ),
+      contractPathTerms: localSemanticTerms(
+        raw.contractPathTerms ?? raw.contract_path_terms,
+        "contract path",
+        warnings
+      ),
+      testPathTerms: localSemanticTerms(
+        raw.testPathTerms ?? raw.test_path_terms,
+        "test path",
+        warnings
+      ),
+      architectureRoleTerms,
+      source: "project-file",
+      warnings
+    };
+  } catch (error) {
+    return {
+      ...defaults,
+      source: "project-file",
+      warnings: [
+        `Could not parse ${LOCAL_SEMANTIC_RULE_CONFIG_PATH}: ${error instanceof Error ? error.message : "invalid JSON"}`
+      ]
+    };
+  }
+}
+function localSemanticMatchesTerms(value, terms) {
+  const normalized = value.replace(/\\/g, "/").toLowerCase();
+  return terms.some((term) => normalized.includes(term));
+}
+function localSemanticIsTestPath(filePath, rules) {
+  return !rules.replaceDefaults && LOCAL_SEMANTIC_TEST_PATH.test(filePath) || localSemanticMatchesTerms(filePath, rules.testPathTerms);
+}
+function localSemanticIsSensitivePath(filePath, rules) {
+  return !rules.replaceDefaults && LOCAL_SEMANTIC_SENSITIVE_PATH.test(filePath) || localSemanticMatchesTerms(filePath, rules.sensitivePathTerms);
+}
+function localSemanticIsContractPath(filePath, rules) {
+  return !rules.replaceDefaults && LOCAL_SEMANTIC_CONTRACT_PATH.test(filePath) || localSemanticMatchesTerms(filePath, rules.contractPathTerms);
+}
 function localSemanticEvidence(kind, detail, metadata = {}) {
   return { kind, detail, ...metadata };
 }
@@ -4322,14 +4441,16 @@ function localSemanticAssertion(subject, predicate, value, confidence, source2,
     predicate,
     value,
     confidence: Math.round(Math.max(0, Math.min(1, confidence)) * 1e3) / 1e3,
+    scoreKind: "heuristic_prior",
+    calibrated: false,
     source: source2,
     extractorVersion: 1,
     evidence
   };
 }
-function localArchitectureRoles(symbol) {
+function localArchitectureRoles(symbol, rules) {
   const haystack = `${symbol.filePath} ${symbol.name}`;
-  const candidates = [
+  const defaultCandidates = [
     { role: "repository", pattern: /repository|(^|[_.])repo($|[_.])/i, confidence: 0.9 },
     { role: "adapter", pattern: /adapter/i, confidence: 0.9 },
     { role: "facade", pattern: /facade/i, confidence: 0.9 },
@@ -4356,7 +4477,7 @@ function localArchitectureRoles(symbol) {
       )
     );
   }
-  if (LOCAL_SEMANTIC_TEST_PATH.test(symbol.filePath)) {
+  if (localSemanticIsTestPath(symbol.filePath, rules)) {
     roles.push(
       localSemanticAssertion(
         symbol.localKey,
@@ -4368,7 +4489,7 @@ function localArchitectureRoles(symbol) {
       )
     );
   }
-  for (const candidate of candidates) {
+  for (const candidate of rules.replaceDefaults ? [] : defaultCandidates) {
     if (!candidate.pattern.test(haystack)) continue;
     roles.push(
       localSemanticAssertion(
@@ -4387,9 +4508,29 @@ function localArchitectureRoles(symbol) {
       )
     );
   }
+  const existingRoles = new Set(roles.map((assertion) => String(assertion.value)));
+  for (const [role, terms] of Object.entries(rules.architectureRoleTerms)) {
+    if (existingRoles.has(role) || !localSemanticMatchesTerms(haystack, terms)) continue;
+    roles.push(
+      localSemanticAssertion(
+        symbol.localKey,
+        "architecture_role",
+        role,
+        0.7,
+        "architecture-pattern-rules",
+        [
+          localSemanticEvidence(
+            "project_role_term",
+            `Name or path matches a configured ${role} project term.`,
+            { filePath: symbol.filePath, line: symbol.line }
+          )
+        ]
+      )
+    );
+  }
   return roles;
 }
-function localSymbolSemanticAssertions(symbol) {
+function localSymbolSemanticAssertions(symbol, rules) {
   const assertions = [];
   const routeSurface = /\/app\/api\//i.test(symbol.filePath) || /\/route\.(ts|tsx|py)$/i.test(symbol.filePath);
   const toolSurface = /(^|\/)(mcp|tool_defs)(\/|\.|$)/i.test(symbol.filePath);
@@ -4445,7 +4586,7 @@ function localSymbolSemanticAssertions(symbol) {
     contractEvidence.push(
       localSemanticEvidence("symbol_kind", `Exported ${symbol.kind} defines a structural contract.`)
     );
-  } else if (LOCAL_SEMANTIC_CONTRACT_PATH.test(symbol.filePath)) {
+  } else if (localSemanticIsContractPath(symbol.filePath, rules)) {
     contractKind = "repository_boundary_contract";
     contractEvidence.push(
       localSemanticEvidence(
@@ -4469,17 +4610,17 @@ function localSymbolSemanticAssertions(symbol) {
       )
     );
   }
-  assertions.push(...localArchitectureRoles(symbol));
+  assertions.push(...localArchitectureRoles(symbol, rules));
   let criticality = "ordinary";
   let criticalityConfidence = 0.58;
   let criticalityEvidence = [
     localSemanticEvidence("default", "No critical or incidental evidence matched.")
   ];
-  if (LOCAL_SEMANTIC_TEST_PATH.test(symbol.filePath)) {
+  if (localSemanticIsTestPath(symbol.filePath, rules)) {
     criticality = "incidental";
     criticalityConfidence = 0.95;
     criticalityEvidence = [localSemanticEvidence("test_path", "Test-only dependency.")];
-  } else if (LOCAL_SEMANTIC_SENSITIVE_PATH.test(symbol.filePath) || routeSurface || toolSurface) {
+  } else if (localSemanticIsSensitivePath(symbol.filePath, rules) || routeSurface || toolSurface) {
     criticality = "critical";
     criticalityConfidence = 0.92;
     criticalityEvidence = [
@@ -4517,8 +4658,9 @@ function localSymbolSemanticAssertions(symbol) {
   return assertions;
 }
 function buildLocalSemanticModel(manifest, options = {}) {
+  const rules = options.semanticRules ?? loadLocalSemanticRuleConfig(process.cwd());
   const symbols = options.symbolKeys ? manifest.symbols.filter((symbol) => options.symbolKeys?.has(symbol.localKey)) : manifest.symbols;
-  const assertions = symbols.flatMap(localSymbolSemanticAssertions);
+  const assertions = symbols.flatMap((symbol) => localSymbolSemanticAssertions(symbol, rules));
   const symbolByKey = new Map(manifest.symbols.map((symbol) => [symbol.localKey, symbol]));
   const criticalityBySymbol = new Map(
     assertions.filter((assertion) => assertion.predicate === "dependency_criticality").map((assertion) => [assertion.subject, String(assertion.value)])
@@ -4555,7 +4697,7 @@ function buildLocalSemanticModel(manifest, options = {}) {
     ];
     let value = "ordinary";
     let confidence = 0.62;
-    if (LOCAL_SEMANTIC_TEST_PATH.test(fromFile) || LOCAL_SEMANTIC_TEST_PATH.test(toFile)) {
+    if (localSemanticIsTestPath(fromFile, rules) || localSemanticIsTestPath(toFile, rules)) {
       value = "incidental";
       confidence = 0.92;
       evidence.push(localSemanticEvidence("test_path", "At least one edge endpoint is test-only."));
@@ -4626,6 +4768,40 @@ function buildLocalSemanticModel(manifest, options = {}) {
     version: "snipara.semantic.v1",
     extractorVersion: 1,
     source: "deterministic-graph-inference",
+    modelType: "rule-based-heuristic",
+    scoreContract: {
+      kind: "heuristic_prior",
+      calibrated: false,
+      probability: false,
+      comparableAcrossProjects: false,
+      basis: "hand-tuned-v1",
+      rulesetVersion: 1,
+      interpretation: "Relative rule strength for ranking and explanation; not an observed probability."
+    },
+    ruleConfig: {
+      version: LOCAL_SEMANTIC_RULE_CONFIG_VERSION,
+      source: rules.source,
+      path: ".snipara/semantic-rules.json",
+      replaceDefaults: rules.replaceDefaults,
+      sensitivePathTermCount: rules.sensitivePathTerms.length,
+      contractPathTermCount: rules.contractPathTerms.length,
+      testPathTermCount: rules.testPathTerms.length,
+      architectureRoleTermCount: Object.values(rules.architectureRoleTerms).reduce(
+        (total, terms) => total + terms.length,
+        0
+      ),
+      configuredRoles: Object.keys(rules.architectureRoleTerms).sort(),
+      configHash: sha2563(
+        JSON.stringify({
+          replaceDefaults: rules.replaceDefaults,
+          sensitivePathTerms: rules.sensitivePathTerms,
+          contractPathTerms: rules.contractPathTerms,
+          testPathTerms: rules.testPathTerms,
+          architectureRoleTerms: rules.architectureRoleTerms
+        })
+      ).slice(0, 16),
+      warnings: rules.warnings
+    },
     scope: options.scope ?? "repository",
     assertions: returnedAssertions,
     publicContracts,
@@ -4663,7 +4839,9 @@ function buildLocalSemanticModel(manifest, options = {}) {
     },
     caveats: [
       "Semantic assertions are deterministic inferences, not declarations of author intent.",
-      "Name-only architecture patterns use lower confidence than explicit export or path evidence.",
+      "Confidence is an uncalibrated rule-based prior, not a probability or measured accuracy.",
+      "Priors are not comparable across projects with different semantic rule configuration.",
+      "Name-only architecture patterns use a lower prior than explicit export or path evidence.",
       "Historical regression learning requires hosted outcome evidence and remains shadow-only."
     ]
   };
@@ -4735,7 +4913,8 @@ function buildLocalRisk(manifest, changedFiles, traversal, depth, semantic) {
   const changedSymbolKeys = new Set(
     manifest.symbols.filter((symbol) => changedFiles.includes(symbol.filePath)).map((symbol) => symbol.localKey)
   );
-  const changedContracts = manifest.symbols.filter((symbol) => changedSymbolKeys.has(symbol.localKey)).flatMap(localSymbolSemanticAssertions).filter(
+  const semanticRules = loadLocalSemanticRuleConfig(manifest.repoRoot);
+  const changedContracts = manifest.symbols.filter((symbol) => changedSymbolKeys.has(symbol.localKey)).flatMap((symbol) => localSymbolSemanticAssertions(symbol, semanticRules)).filter(
     (assertion) => assertion.predicate === "public_api" || assertion.predicate === "implicit_contract"
   ).length;
   const semanticRiskPoints = Math.min(20, criticalSemanticDependencies * 3) + Math.min(10, changedContracts * 2);
@@ -5800,7 +5979,8 @@ function buildLocalImpactResult(options) {
   const semantic = buildLocalSemanticModel(manifest, {
     scope: "impact",
     symbolKeys: semanticSymbolKeys,
-    edges: traversalEdges
+    edges: traversalEdges,
+    semanticRules: loadLocalSemanticRuleConfig(manifest.repoRoot)
   });
   const transitiveFiles = uniqueTraversalFiles(traversal.nodes, selectedFiles);
   const impactedFiles = [.../* @__PURE__ */ new Set([...directImpactedFiles, ...transitiveFiles])].sort();

package/docs/CODE_GRAPH.md

@@ -14,7 +14,9 @@ contains:
 - `predicate`: `public_api`, `implicit_contract`, `architecture_role`, or
   `dependency_criticality`;
 - `value`: the inferred classification;
-- `confidence`: a bounded score from `0` to `1`;
+- `confidence`: a backward-compatible bounded rule-strength prior from `0` to
+  `1`, explicitly qualified by `scoreKind: "heuristic_prior"` and
+  `calibrated: false`;
 - `source` and `extractorVersion`;
 - `evidence`: the export modifier, symbol kind, file/path pattern, or graph edge
   that produced the assertion.
@@ -22,8 +24,37 @@ contains:
 The extractor recognizes explicit TypeScript and Go exports, route and MCP
 surfaces, exported type contracts, and common Repository, Adapter, Facade,
 Controller, Service, Worker, Factory, schema, route-handler, and test roles.
-Name-only patterns have lower confidence than explicit export, route, or graph
-evidence.
+`confidence` is not a probability, measured accuracy, or cross-project metric.
+It is a deterministic prior used for relative ranking and explanation inside
+one rule configuration. `semantic.scoreContract.basis` is
+`hand-tuned-v1`; the values must be calibrated against measured outcomes before
+that status can change. Name-only patterns have a lower prior than explicit
+export, route, or graph evidence.
+
+### Project naming rules
+
+Projects can extend or replace built-in English naming conventions with
+`.snipara/semantic-rules.json`:
+
+```json
+{
+  "replaceDefaults": false,
+  "sensitivePathTerms": ["securite", "facturation"],
+  "contractPathTerms": ["contrats"],
+  "testPathTerms": ["essais"],
+  "architectureRoleTerms": {
+    "repository": ["depot"],
+    "service": ["metier"]
+  }
+}
+```
+
+Terms are case-insensitive literal strings, not regular expressions. Each group
+is limited to 64 terms of at most 80 characters and role names are normalized.
+Invalid config is reported in `semantic.ruleConfig.warnings`; it never aborts
+overlay construction. Set `replaceDefaults: true` only when the project wants
+configured naming terms to replace built-in naming conventions. Explicit
+exports, route surfaces, and graph evidence continue to apply.
 
 ## Dependency criticality
 
@@ -51,8 +82,9 @@ does not manufacture cross-source edges or assertions.
 ## Historical regression paths
 
 Hosted impact can associate sanitized warning/error execution traces with
-graph paths by their tracked files. Version 1 reports sample count, confidence,
-event IDs, and a suggested risk delta. This surface is intentionally
+graph paths by their tracked files. Version 1 reports sample count, an
+uncalibrated shadow association strength, event IDs, and a suggested risk
+delta. This surface is intentionally
 `mode: shadow` and `riskContributionEnabled: false`: temporal association is
 not causal proof, and it cannot affect risk until separately calibrated and
 promoted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.6.2",
+  "version": "3.6.3",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {