chore: cleaning documentation and adding filter to spec

Author: pesap

crates/arco-cli/src/benchmark.rs

@@ -247,7 +247,7 @@ fn to_e2e_summary(
         reports: execution_result
             .reports
             .iter()
-            .map(|report| report.dsl_name.clone())
+            .map(|report| report.name.clone())
             .collect(),
     }
 }
@@ -298,6 +298,7 @@ mod tests {
                 expression: Expr::Number("0".to_string()),
             },
             active_reports: Vec::new(),
+            active_variable_reports: Vec::new(),
             active_dual_reports: Vec::new(),
         }
     }

crates/arco-cli/src/driver.rs

@@ -10,6 +10,7 @@ use arco_kdl::ObjectiveSense;
 use arco_kdl::pipeline::{PipelineError, compile_file, validate_file};
 use miette::Diagnostic;
 use serde::Serialize;
+use std::collections::BTreeMap;
 use std::fmt::Display;
 use std::path::{Path, PathBuf};
 use std::time::Instant;
@@ -37,6 +38,7 @@ pub struct RunSummary {
     pub reports: Vec<ReportSummary>,
     #[serde(skip_serializing_if = "Vec::is_empty")]
     pub dual_reports: Vec<DualReportSummary>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
     pub variables: Vec<VariableSummary>,
     pub counts: ProblemCounts,
     pub timing: TimingSummary,
@@ -52,7 +54,9 @@ pub struct ObjectiveSummary {
 #[derive(Debug, Serialize, PartialEq)]
 pub struct ReportSummary {
     pub name: String,
-    pub value: f64,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub index: Vec<String>,
+    pub values: Vec<BTreeMap<String, serde_json::Value>>,
 }
 
 #[derive(Debug, Serialize, PartialEq)]
@@ -234,9 +238,10 @@ pub fn run_file_with_options_and_backend(
         reports: execution_result
             .reports
             .into_iter()
-            .map(|report| ReportSummary {
-                name: report.dsl_name,
-                value: report.value,
+            .map(|r| ReportSummary {
+                name: r.name,
+                index: r.index,
+                values: r.values,
             })
             .collect(),
         dual_reports: execution_result
@@ -340,6 +345,9 @@ fn summarize_variables(
     variables: &[crate::execution::MappedVariableResult],
     options: &RunOptions,
 ) -> Vec<VariableSummary> {
+    if options.filter_variable.is_none() {
+        return Vec::new();
+    }
     variables
         .iter()
         .filter(|variable| {

crates/arco-cli/src/execution.rs

@@ -66,11 +66,18 @@ pub struct ExecutionResult {
     pub status: SolveStatus,
     pub objective_sense: ObjectiveSense,
     pub objective: MappedScalarResult,
-    pub reports: Vec<MappedScalarResult>,
+    pub reports: Vec<ReportResult>,
     pub variables: Vec<MappedVariableResult>,
     pub dual_reports: Vec<DualReportResult>,
 }
 
+#[derive(Debug, Clone, PartialEq)]
+pub struct ReportResult {
+    pub name: String,
+    pub index: Vec<String>,
+    pub values: Vec<BTreeMap<String, serde_json::Value>>,
+}
+
 #[derive(Debug, Clone, PartialEq)]
 pub struct MappedScalarResult {
     pub dsl_name: String,
@@ -603,23 +610,59 @@ pub fn execute_problem_with_options(
         .map(|variable| (variable.compiled_name.clone(), variable))
         .collect::<BTreeMap<_, _>>();
 
-    let reports = problem
-        .reports
-        .iter()
-        .map(|report| {
-            let value = report_values.get(&report.name).copied().ok_or_else(|| {
-                ExecutionError::MissingReportValue {
-                    backend: backend.to_string(),
-                    compiled_name: report.name.clone(),
-                }
-            })?;
-            Ok(MappedScalarResult {
-                dsl_name: report.name.clone(),
+    // Build unified reports: expression reports (scalar) and variable reports
+    let mut reports = Vec::new();
+
+    for report in &problem.reports {
+        let value = report_values.get(&report.name).copied().ok_or_else(|| {
+            ExecutionError::MissingReportValue {
+                backend: backend.to_string(),
                 compiled_name: report.name.clone(),
-                value,
-            })
-        })
-        .collect::<Result<Vec<_>, _>>()?;
+            }
+        })?;
+        let mut record = BTreeMap::new();
+        record.insert("value".to_string(), serde_json::Value::from(value));
+        reports.push(ReportResult {
+            name: report.name.clone(),
+            index: Vec::new(),
+            values: vec![record],
+        });
+    }
+
+    for vr in &problem.variable_reports {
+        let family_key = format!("{}[{}]", vr.control_name, vr.indices.join(","));
+        if let Some(family) = variable_values.get(&family_key) {
+            let values = family
+                .values
+                .iter()
+                .filter_map(|v| {
+                    let (raw, typed) = extract_index_parts(&vr.control_name, &v.compiled_name);
+                    if let Some(ref filter) = vr.filter {
+                        let bindings: BTreeMap<&str, &str> = vr
+                            .indices
+                            .iter()
+                            .zip(raw.iter())
+                            .map(|(k, v)| (k.as_str(), v.as_str()))
+                            .collect();
+                        if !eval_filter(filter, &bindings) {
+                            return None;
+                        }
+                    }
+                    let mut record = BTreeMap::new();
+                    for (idx_name, idx_val) in vr.indices.iter().zip(typed) {
+                        record.insert(idx_name.clone(), idx_val);
+                    }
+                    record.insert("value".to_string(), serde_json::Value::from(v.value));
+                    Some(record)
+                })
+                .collect();
+            reports.push(ReportResult {
+                name: vr.control_name.clone(),
+                index: vr.indices.clone(),
+                values,
+            });
+        }
+    }
 
     let variables = problem
         .variables
@@ -900,6 +943,77 @@ fn map_solver_status(status: ArcoSolverStatus) -> SolveStatus {
     }
 }
 
+/// Split a variable instance name into raw string parts and typed JSON values.
+/// E.g. `("pc", "pc[1,Li-Ion]")` → `(["1", "Li-Ion"], [Number(1), String("Li-Ion")])`.
+fn extract_index_parts(
+    family_name: &str,
+    instance_name: &str,
+) -> (Vec<String>, Vec<serde_json::Value>) {
+    let inner = instance_name
+        .strip_prefix(family_name)
+        .and_then(|s| s.strip_prefix('['))
+        .and_then(|s| s.strip_suffix(']'))
+        .unwrap_or("");
+    if inner.is_empty() {
+        return (Vec::new(), Vec::new());
+    }
+    let parts: Vec<&str> = inner.split(',').collect();
+    let strings = parts.iter().map(|s| s.to_string()).collect();
+    let typed = parts
+        .iter()
+        .map(|part| {
+            if let Ok(n) = part.parse::<i64>() {
+                serde_json::Value::Number(n.into())
+            } else if let Some(n) = part
+                .parse::<f64>()
+                .ok()
+                .and_then(serde_json::Number::from_f64)
+            {
+                serde_json::Value::Number(n)
+            } else {
+                serde_json::Value::String(part.to_string())
+            }
+        })
+        .collect();
+    (strings, typed)
+}
+
+/// Evaluate a simple filter expression against index bindings.
+/// Evaluate a comparison filter against index bindings. Unsupported expression
+/// types fail closed (exclude the row) to avoid silent pass-through.
+fn eval_filter(expr: &arco_kdl::algebra::Expr, bindings: &BTreeMap<&str, &str>) -> bool {
+    use arco_kdl::algebra::{ComparisonOp, Expr};
+    match expr {
+        Expr::Comparison { op, left, right } => {
+            let lhs = match left.as_ref() {
+                Expr::Identifier(name) => bindings.get(name.as_str()).copied(),
+                Expr::String(s) => Some(s.as_str()),
+                Expr::Number(n) => Some(n.as_str()),
+                _ => None,
+            };
+            let rhs = match right.as_ref() {
+                Expr::Identifier(name) => bindings.get(name.as_str()).copied(),
+                Expr::String(s) => Some(s.as_str()),
+                Expr::Number(n) => Some(n.as_str()),
+                _ => None,
+            };
+            match (lhs, rhs) {
+                (Some(l), Some(r)) => match op {
+                    ComparisonOp::Equal | ComparisonOp::DoubleEqual => l == r,
+                    ComparisonOp::NotEqual => l != r,
+                    ComparisonOp::Less => l < r,
+                    ComparisonOp::LessEqual => l <= r,
+                    ComparisonOp::Greater => l > r,
+                    ComparisonOp::GreaterEqual => l >= r,
+                },
+                _ => false,
+            }
+        }
+        // Unsupported filter expressions fail closed
+        _ => false,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::execution::{MockArcoAdapter, execute_problem_with_options};
@@ -923,6 +1037,7 @@ mod tests {
                 expression: "0".to_string(),
             },
             reports: Vec::new(),
+            variable_reports: Vec::new(),
             dual_reports: Vec::new(),
             traceability: Vec::new(),
             algebra: AlgebraicProblem {

crates/arco-kdl/src/compile/mod.rs

@@ -26,6 +26,7 @@ pub struct CompiledProblem {
     pub constraints: Vec<CompiledConstraint>,
     pub objective: CompiledObjective,
     pub reports: Vec<CompiledReport>,
+    pub variable_reports: Vec<CompiledVariableReport>,
     pub dual_reports: Vec<CompiledDualReport>,
     pub traceability: Vec<TraceabilityRecord>,
     pub algebra: AlgebraicProblem,
@@ -63,6 +64,13 @@ pub struct CompiledReport {
     pub formula: String,
 }
 
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CompiledVariableReport {
+    pub control_name: String,
+    pub indices: Vec<String>,
+    pub filter: Option<crate::algebra::Expr>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct CompiledDualReport {
     pub constraint_name: String,
@@ -227,6 +235,16 @@ pub fn compile_program(
         .map(compile_report)
         .collect::<Vec<_>>();
 
+    let variable_reports = program
+        .active_variable_reports
+        .iter()
+        .map(|vr| CompiledVariableReport {
+            control_name: vr.control_name.clone(),
+            indices: vr.indices.clone(),
+            filter: vr.filter.clone(),
+        })
+        .collect::<Vec<_>>();
+
     let dual_reports = program
         .active_dual_reports
         .iter()
@@ -258,6 +276,7 @@ pub fn compile_program(
         constraints,
         objective,
         reports,
+        variable_reports,
         dual_reports,
         traceability,
         algebra,

crates/arco-kdl/src/semantic/resolution.rs

@@ -12,9 +12,17 @@ pub(crate) fn resolve_model_scenario_reports(
     scenario: &ScenarioDecl,
     active_constraints: &[ResolvedConstraint],
     entrypoint: &Path,
-) -> Result<(Vec<ResolvedReport>, Vec<ResolvedDualReport>), SemanticError> {
+) -> Result<
+    (
+        Vec<ResolvedReport>,
+        Vec<ResolvedDualReport>,
+        Vec<crate::semantic::types::ResolvedVariableReport>,
+    ),
+    SemanticError,
+> {
     let mut reports = Vec::new();
     let mut dual_reports = Vec::new();
+    let mut variable_reports = Vec::new();
 
     for report_decl in &scenario.reports {
         match report_decl.kind {
@@ -28,19 +36,33 @@ pub(crate) fn resolve_model_scenario_reports(
                     continue;
                 }
 
-                let expression = model
+                if let Some(expression) = model
                     .expressions
                     .iter()
                     .find(|expression| expression.name == report_decl.target)
-                    .ok_or_else(|| SemanticError::MissingDeclaration {
-                        kind: "expression",
-                        name: report_decl.target.clone(),
-                        path: entrypoint.to_path_buf(),
-                    })?;
-                reports.push(ResolvedReport {
-                    name: expression.name.clone(),
-                    formula_text: expression.formula.clone(),
-                    formula: expression.parsed_formula.clone(),
+                {
+                    reports.push(ResolvedReport {
+                        name: expression.name.clone(),
+                        formula_text: expression.formula.clone(),
+                        formula: expression.parsed_formula.clone(),
+                    });
+                    continue;
+                }
+
+                if let Some(control) = model.controls.iter().find(|c| c.name == report_decl.target)
+                {
+                    variable_reports.push(crate::semantic::types::ResolvedVariableReport {
+                        control_name: control.name.clone(),
+                        indices: control.indices.iter().map(|i| i.name.clone()).collect(),
+                        filter: report_decl.parsed_filter_expression.clone(),
+                    });
+                    continue;
+                }
+
+                return Err(SemanticError::MissingDeclaration {
+                    kind: "expression or control",
+                    name: report_decl.target.clone(),
+                    path: entrypoint.to_path_buf(),
                 });
             }
             ReportKind::Dual => {
@@ -62,7 +84,7 @@ pub(crate) fn resolve_model_scenario_reports(
         }
     }
 
-    Ok((reports, dual_reports))
+    Ok((reports, dual_reports, variable_reports))
 }
 
 pub(crate) fn resolve_active_model_expressions(

crates/arco-kdl/src/semantic/types.rs

@@ -70,6 +70,7 @@ pub struct SemanticProgram {
     pub active_expressions: Vec<ResolvedExpression>,
     pub active_objective: ResolvedObjective,
     pub active_reports: Vec<ResolvedReport>,
+    pub active_variable_reports: Vec<ResolvedVariableReport>,
     pub active_dual_reports: Vec<ResolvedDualReport>,
 }
 
@@ -137,6 +138,13 @@ pub struct ResolvedReport {
     pub formula: Expr,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedVariableReport {
+    pub control_name: String,
+    pub indices: Vec<String>,
+    pub filter: Option<Expr>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ResolvedDualReport {
     pub constraint_name: String,