feat(sql): Phase 3 procedural SQL metrics

crates/mehen-sql/src/composite.rs

@@ -80,8 +80,10 @@ pub(crate) fn compute(
     }
 }
 
-/// SQL Structural Complexity (research foundation §8.1).
-fn structural(f: &SqlFileFacts) -> f64 {
+/// SQL Structural Complexity (research foundation §8.1). Also reused by the
+/// procedural module to score the query constructs embedded in one routine
+/// (`sql.structural_complexity.max_embedded_query`, §9.3).
+pub(crate) fn structural(f: &SqlFileFacts) -> f64 {
     1.00 * f.query_block_count as f64
         + 0.80 * f.ctes.count as f64
         + 1.20 * f.ctes.max_dependency_depth as f64
@@ -175,11 +177,9 @@ fn modularization_credit(f: &SqlFileFacts) -> f64 {
 
 /// SQL Change Risk Score (research foundation §8.4).
 ///
-/// Phase-1 deviation: the spec's `+ 5 * dynamic_sql_count` term is omitted
-/// because dynamic SQL (`EXECUTE IMMEDIATE`, `sp_executesql`, …) is a
-/// procedural-dialect construct not yet tracked (Phase 3). Every other term
-/// matches the spec weights exactly. When dynamic-SQL detection lands, add the
-/// `+ 5 * dynamic_sql_count` term here.
+/// Every term matches the spec weights exactly, including the
+/// `+ 5 × dynamic_sql_count` term (Phase 3 — `EXECUTE IMMEDIATE`,
+/// `sp_executesql`, `EXEC('…')`, `DBMS_SQL`).
 fn change_risk(f: &SqlFileFacts) -> f64 {
     let o = &f.objects;
     ChangeRiskFactor::Drop.amount() * o.drop_count as f64
@@ -188,6 +188,7 @@ fn change_risk(f: &SqlFileFacts) -> f64 {
         + ChangeRiskFactor::DeleteWithoutWhere.amount() * o.delete_without_where_count as f64
         + ChangeRiskFactor::UpdateWithoutWhere.amount() * o.update_without_where_count as f64
         + ChangeRiskFactor::GrantRevoke.amount() * o.grant_revoke_count as f64
+        + ChangeRiskFactor::DynamicSql.amount() * f.procedural.dynamic_sql_count as f64
         + ChangeRiskFactor::Merge.amount() * o.merge_count as f64
         + ChangeRiskFactor::CreateOrReplace.amount() * o.create_or_replace_count as f64
         + ChangeRiskFactor::TransactionControl.amount() * o.transaction_control_count as f64

crates/mehen-sql/src/lib.rs

@@ -32,6 +32,7 @@ mod dialect;
 mod facts;
 mod loc;
 mod metrics;
+mod procedural;
 
 use mehen_core::{
     AnalysisBackend, AnalysisConfig, ContributionCollector, Language, LanguageAnalysis,
@@ -132,7 +133,12 @@ impl LanguageAnalyzer for SqlAnalyzer {
         let line_index = &source.line_index;
         let line_at = |byte: u32| line_index.line_at(byte);
 
-        let mut file_facts = facts::extract(&parsed, &dialect, line_at, config.emit_contributions);
+        let mut file_facts = facts::extract(
+            &parsed,
+            line_at,
+            config.emit_contributions,
+            resolution.effective == DialectKind::Tsql,
+        );
         // Lexer errors (malformed tokens) are distinct from unparsable parse
         // segments. The current sqruff release never populates this vector, but
         // surface them into parser-health so a future version cannot make
@@ -158,6 +164,18 @@ impl LanguageAnalyzer for SqlAnalyzer {
                 item.factor.reason(),
             );
         }
+        // Procedural composites are evidence-backed too: the published value
+        // equals the sum of its contributions by construction (§4.7).
+        for item in &file_facts.procedural.evidence {
+            let metric = match item.metric {
+                procedural::ProceduralMetric::Cyclomatic => "sql.procedural.cyclomatic_complexity",
+                procedural::ProceduralMetric::Cognitive => "sql.procedural.cognitive_complexity",
+                procedural::ProceduralMetric::EmbeddedQueryMax => {
+                    "sql.structural_complexity.max_embedded_query"
+                }
+            };
+            contribution_collector.record(metric, item.span, item.amount, item.reason);
+        }
 
         // Per-statement spaces so top-offenders / nested reporting can attribute
         // metrics to a statement's line range (research foundation §4.4).
@@ -286,6 +304,21 @@ fn attach_procedural_unit_spaces(
             },
         );
         space.name = unit.name.clone();
+        // Per-routine procedural composites (Phase 3): the same keys as the
+        // file-level aggregates, scoped to this routine — the numbers
+        // `mehen top-offenders` shows next to a function name, and the
+        // complexity denominator CRAP will use.
+        space.metrics.insert(
+            "sql.procedural.cyclomatic_complexity",
+            unit.cyclomatic_complexity,
+        );
+        space.metrics.insert(
+            "sql.procedural.cognitive_complexity",
+            unit.cognitive_complexity,
+        );
+        space
+            .metrics
+            .insert("sql.structural_complexity", unit.embedded_query_structural);
         while let Some((_, _, open_end)) = stack.last() {
             if unit.start_byte >= *open_end {
                 close_one(&mut stack, &mut top_level);
@@ -519,6 +552,18 @@ pub const PUBLISHED_METRIC_KEYS: &[&str] = &[
     "sql.predicate.max_boolean_depth",
     "sql.predicate.not_count",
     "sql.predicate.null_semantics_risk_count",
+    "sql.procedural.block_count",
+    "sql.procedural.case_statement_count",
+    "sql.procedural.cognitive_complexity",
+    "sql.procedural.cyclomatic_complexity",
+    "sql.procedural.dynamic_sql_count",
+    "sql.procedural.exception_handler_count",
+    "sql.procedural.if_count",
+    "sql.procedural.loop_count",
+    "sql.procedural.max_block_depth",
+    "sql.procedural.raise_throw_count",
+    "sql.procedural.return_count",
+    "sql.procedural.routine_count",
     "sql.query_block.avg_select_items",
     "sql.query_block.count",
     "sql.query_block.max_depth",
@@ -540,6 +585,7 @@ pub const PUBLISHED_METRIC_KEYS: &[&str] = &[
     "sql.statement.kind_entropy",
     "sql.statement.unparsed_count",
     "sql.structural_complexity",
+    "sql.structural_complexity.max_embedded_query",
     "sql.subquery.correlated_count",
     "sql.subquery.count",
     "sql.subquery.exists_count",

crates/mehen-sql/src/metrics.rs

@@ -15,31 +15,6 @@ use crate::dialect::{DialectResolution, dialect_label};
 use crate::facts::{SqlFileFacts, StatementKind};
 use crate::loc::SqlLoc;
 
-/// All distinct statement kinds, so `kind_count.<kind>` keys are emitted with
-/// an explicit `0` when absent (grepability over silent omission).
-const ALL_STATEMENT_KINDS: &[StatementKind] = &[
-    StatementKind::Select,
-    StatementKind::WithSelect,
-    StatementKind::Insert,
-    StatementKind::Update,
-    StatementKind::Delete,
-    StatementKind::Merge,
-    StatementKind::CreateView,
-    StatementKind::CreateTable,
-    StatementKind::CreateTableAsSelect,
-    StatementKind::CreateOther,
-    StatementKind::AlterTable,
-    StatementKind::Drop,
-    StatementKind::Truncate,
-    StatementKind::Grant,
-    StatementKind::Revoke,
-    StatementKind::TransactionControl,
-    StatementKind::Explain,
-    StatementKind::Procedural,
-    StatementKind::SetOperation,
-    StatementKind::Unknown,
-];
-
 const JOIN_KINDS: &[&str] = &[
     "inner", "left", "right", "full", "cross", "natural", "lateral",
 ];
@@ -66,6 +41,7 @@ pub(crate) fn publish(
     publish_expressions(facts, target);
     publish_output(facts, target);
     publish_objects(facts, target);
+    publish_procedural(facts, target);
     publish_dialect(facts, loc, dialect, target);
     publish_parser(facts, loc, target);
     publish_halstead(facts, target);
@@ -97,8 +73,9 @@ fn publish_loc(loc: &SqlLoc, target: &mut MetricSet) {
 
 fn publish_statements(facts: &SqlFileFacts, target: &mut MetricSet) {
     set(target, "sql.statement.count", facts.statements.len());
-    // kind_count.<kind>
-    for kind in ALL_STATEMENT_KINDS {
+    // kind_count.<kind> — every kind gets an explicit `0` when absent
+    // (grepability over silent omission).
+    for kind in StatementKind::ALL {
         let n = facts.statements.iter().filter(|s| s.kind == *kind).count();
         set(
             target,
@@ -377,6 +354,55 @@ fn publish_objects(facts: &SqlFileFacts, target: &mut MetricSet) {
     );
 }
 
+/// Procedural-SQL metrics (research foundation §6.17, Phase 3). Published
+/// unconditionally — a purely declarative file reports explicit zeros, the
+/// same contract as every other family.
+fn publish_procedural(facts: &SqlFileFacts, target: &mut MetricSet) {
+    let p = &facts.procedural;
+    set(target, "sql.procedural.block_count", p.block_count);
+    set(target, "sql.procedural.routine_count", p.routine_count);
+    set(
+        target,
+        "sql.procedural.cyclomatic_complexity",
+        p.cyclomatic_complexity,
+    );
+    set(
+        target,
+        "sql.procedural.cognitive_complexity",
+        p.cognitive_complexity,
+    );
+    set(target, "sql.procedural.max_block_depth", p.max_block_depth);
+    set(target, "sql.procedural.loop_count", p.loop_count);
+    set(target, "sql.procedural.if_count", p.if_count);
+    set(
+        target,
+        "sql.procedural.case_statement_count",
+        p.case_statement_count,
+    );
+    set(
+        target,
+        "sql.procedural.exception_handler_count",
+        p.exception_handler_count,
+    );
+    set(target, "sql.procedural.return_count", p.return_count);
+    set(
+        target,
+        "sql.procedural.raise_throw_count",
+        p.raise_throw_count,
+    );
+    set(
+        target,
+        "sql.procedural.dynamic_sql_count",
+        p.dynamic_sql_count,
+    );
+    // §9.3: the worst embedded query inside any single routine.
+    set(
+        target,
+        "sql.structural_complexity.max_embedded_query",
+        p.max_embedded_query_structural,
+    );
+}
+
 fn publish_dialect(
     facts: &SqlFileFacts,
     _loc: &SqlLoc,