sqlbuild-cli 0.164.5__tar.gz → 0.165.0__tar.gz

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/Cargo.lock

@@ -1189,7 +1189,7 @@ checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b"
 
 [[package]]
 name = "sqlbuild-analysis"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "polyglot-sql",
  "polyglot-sql-function-catalogs",
@@ -1211,7 +1211,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-attachments"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "sqlbuild-core",
  "sqlbuild-sqltext",
@@ -1219,7 +1219,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-build-features"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "arrayvec",
  "bstr",
@@ -1234,7 +1234,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-cache"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "blake3",
  "rayon",
@@ -1247,7 +1247,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-cli"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "blake3",
  "ctrlc",
@@ -1265,7 +1265,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-config"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "saphyr-parser",
  "sqlbuild-core",
@@ -1276,7 +1276,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-core"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "regex",
  "sha2",
@@ -1284,14 +1284,14 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-cursor"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "sqlbuild-core",
 ]
 
 [[package]]
 name = "sqlbuild-discovery"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "junction",
  "rayon",
@@ -1305,14 +1305,14 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-host"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "sqlbuild-core",
 ]
 
 [[package]]
 name = "sqlbuild-model-config"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "regex",
  "sqlbuild-core",
@@ -1320,7 +1320,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-project"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "sqlbuild-analysis",
  "sqlbuild-core",
@@ -1329,7 +1329,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-pysource"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "ruff_python_ast",
  "ruff_python_parser",
@@ -1340,7 +1340,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-python"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "fensu-policy",
  "mimalloc",
@@ -1373,7 +1373,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-recall"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "blake3",
  "rusqlite",
@@ -1387,7 +1387,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-refactor"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -1401,7 +1401,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-render"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "serde_json",
  "sqlbuild-cache",
@@ -1411,7 +1411,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-rules"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "blake3",
  "fensu-policy",
@@ -1436,7 +1436,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-scopes"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "serde_json",
  "sha2",
@@ -1449,7 +1449,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-sqltext"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "rayon",
  "serde",
@@ -1458,7 +1458,7 @@ dependencies = [
 
 [[package]]
 name = "sqlbuild-state"
-version = "0.164.5"
+version = "0.165.0"
 dependencies = [
  "serde_json",
  "sha2",

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/Cargo.toml

@@ -33,7 +33,7 @@ python-boundary = "sqlbuild-python"
 polyglot-floor = "sqlbuild-analysis"
 
 [workspace.package]
-version = "0.164.5"
+version = "0.165.0"
 edition = "2024"
 license = "Apache-2.0"
 publish = false

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild-cli
-Version: 0.164.5
+Version: 0.165.0
 License-File: LICENSE
 Summary: The native sqb and sqlbuild executables of SQLBuild
 License-Expression: Apache-2.0

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-analysis/src/assembly/analysis_session/_helpers/session.rs

@@ -133,6 +133,7 @@ impl AnalysisSession {
                 dependency_ordered: self.dependency_ordered,
                 cyclic: self.cyclic,
                 legacy_models: self.legacy_models.clone(),
+                families: self.request.dynamic_families_by_table.clone(),
             });
         let (schema_additions, analysis_names) = self.catalog.into_changes();
         let mut request: SessionRequest = self.request;

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-analysis/src/assembly/analysis_session/models.rs

@@ -199,6 +199,8 @@ pub struct RelationTables {
     pub cyclic: bool,
     /// Models whose analysis took the legacy path, which reads every relation's facts.
     pub legacy_models: Vec<String>,
+    /// The request's dynamic column families by table, in request order.
+    pub families: Vec<(String, Vec<DynamicFamily>)>,
 }
 
 /// One inferred output column; nullability is Python's `InferredNullability` value.

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-analysis/src/column_references/_helpers/references.rs

@@ -346,6 +346,7 @@ impl Analysis<'_> {
         let Some(body) = select_body(expression) else {
             return;
         };
+        let shadowed: HashSet<(usize, usize)> = self.lambda_parameter_uses(body);
         for node in walk_in_scope(body, false) {
             let Expression::Column(column) = node else {
                 continue;
@@ -353,10 +354,44 @@ impl Analysis<'_> {
             if column.name.name == STAR || column.name.name.to_lowercase() != self.column {
                 continue;
             }
+            if column.table.is_none()
+                && column
+                    .span
+                    .is_some_and(|span| shadowed.contains(&(span.start, span.end)))
+            {
+                continue;
+            }
             self.record_column(column, select, chain, role);
         }
     }
 
+    /// Spans of unqualified uses of a lambda parameter named like the column, which read the parameter.
+    fn lambda_parameter_uses(&self, body: &Expression) -> HashSet<(usize, usize)> {
+        let mut shadowed: HashSet<(usize, usize)> = HashSet::new();
+        for node in walk_in_scope(body, false) {
+            let Expression::Lambda(lambda) = node else {
+                continue;
+            };
+            if !lambda
+                .parameters
+                .iter()
+                .any(|parameter| parameter.name.to_lowercase() == self.column)
+            {
+                continue;
+            }
+            for inner in walk_in_scope(&lambda.body, false) {
+                if let Expression::Column(column) = inner
+                    && column.table.is_none()
+                    && column.name.name.to_lowercase() == self.column
+                    && let Some(span) = column.span
+                {
+                    shadowed.insert((span.start, span.end));
+                }
+            }
+        }
+        shadowed
+    }
+
     fn record_column(
         &mut self,
         column: &polyglot_sql::expressions::Column,

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-analysis/src/column_references/tests/test_column_references.rs

@@ -76,6 +76,21 @@ fn given_column_uses_when_analyzing_then_reports_rename_sites() -> Result<(), St
             expected_output_aliases: &[],
             expected_outputs: 0,
         },
+        ColumnReferenceTestCase {
+            description: "a lambda parameter named like the column shadows it in the body",
+            sql: "SELECT list_filter([amount], amount -> amount > 0) AS kept, \
+                  list_filter([1], lambda amount: amount > 0) AS other FROM orders_fact",
+            output_ctes: &[],
+            expected_parsed: true,
+            expected_names: &["amount"],
+            expected_scopes: &["root"],
+            expected_bare_projections: 0,
+            expected_aliases: &[],
+            expected_star_scopes: &[],
+            expected_joins: 0,
+            expected_output_aliases: &[],
+            expected_outputs: 0,
+        },
         ColumnReferenceTestCase {
             description: "output scopes report aliased and bare projections of every branch",
             sql: "WITH fixture AS (SELECT 1 AS amount UNION ALL SELECT 2 AS amount) \

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-attachments/src/audits/_helpers/rendering.rs

@@ -1,6 +1,8 @@
 //! Python's argument merge, SQL rendering and policy resolution for one attachment.
 
-use crate::audits::_helpers::parameters::{RenderStop, render_parameterized_sql};
+use crate::audits::_helpers::parameters::{
+    RenderStop, parameter_matches, render_parameterized_sql,
+};
 use crate::audits::_helpers::policies::{resolve_run_scope, resolve_severity};
 use crate::audits::constants::{MODEL_RESOURCE, SEED_RESOURCE, SOURCE_RESOURCE};
 use crate::audits::models::{ArgumentValue, AuditAttachment, PolicySource};
@@ -94,3 +96,36 @@ pub(crate) fn merged_arguments(
     }
     Ok(merged)
 }
+
+/// The error for the first explicit argument neither the audit SQL nor its evidence SQL reads.
+pub(crate) fn unused_argument(attachment: &AuditAttachment) -> Option<String> {
+    let mut used: Vec<&str> = parameter_matches(&attachment.sql_body)
+        .into_iter()
+        .map(|item| item.name)
+        .collect();
+    if let Some(evidence) = &attachment.evidence_sql {
+        used.extend(
+            parameter_matches(evidence)
+                .into_iter()
+                .map(|item| item.name),
+        );
+    }
+    let implicit: Vec<&str> = attachment
+        .implicit_arguments
+        .iter()
+        .map(|(name, _)| name.as_str())
+        .collect();
+    let (name, _) = attachment
+        .explicit_arguments
+        .iter()
+        .find(|(name, _)| !used.contains(&name.as_str()) && !implicit.contains(&name.as_str()))?;
+    let definition: String = attachment
+        .definition_path
+        .as_deref()
+        .map_or_else(|| "its built-in definition".to_owned(), str::to_owned);
+    Some(format!(
+        "{} audit '{}' passes argument '{name}', which the audit's SQL in {definition} never \
+         uses; remove '{name}' from the attachment",
+        attachment.owner_label, attachment.definition_name
+    ))
+}

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-attachments/src/audits/main/render_attached_audit.rs

@@ -1,6 +1,6 @@
 //! Attached generic audit rendering: argument merge, SQL, severity and run scope.
 
-use crate::audits::_helpers::rendering::{merged_arguments, policies, rendered};
+use crate::audits::_helpers::rendering::{merged_arguments, policies, rendered, unused_argument};
 use crate::audits::models::{ArgumentValue, AuditAttachment, AuditRendering, RenderedAudit};
 
 /// Render one attachment, or the error rendering raises.
@@ -14,6 +14,9 @@ pub fn render_attached_audit(attachment: &AuditAttachment) -> AuditRendering {
             .as_deref()
             .map(|evidence| rendered(attachment, evidence, &arguments))
             .transpose()?;
+        if let Some(message) = unused_argument(attachment) {
+            return Err(message);
+        }
         Ok(RenderedAudit {
             sql_body,
             evidence_sql,

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-attachments/src/audits/models.rs

@@ -28,6 +28,8 @@ pub struct AuditAttachment {
     /// Python's `str(owner_file)` and the generic audit name, which its error messages quote.
     pub owner_label: String,
     pub definition_name: String,
+    /// The project file defining the audit, or `None` for a built-in audit.
+    pub definition_path: Option<String>,
     pub sql_body: String,
     pub evidence_sql: Option<String>,
     /// Arguments from the attached resource, such as `model` and `column`; always text.

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-attachments/src/audits/tests/helpers.rs

@@ -40,6 +40,7 @@ pub(super) fn attachment(
     AuditAttachment {
         owner_label: "models/schema.yml".to_owned(),
         definition_name: "accepted_values".to_owned(),
+        definition_path: None,
         sql_body: "SELECT * FROM t WHERE @column NOT IN (@'values')".to_owned(),
         evidence_sql: Some("SELECT @column FROM t".to_owned()),
         implicit_arguments: vec![("column".to_owned(), "status".to_owned())],

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-attachments/src/audits/tests/test_render_attached_audit.rs

@@ -80,6 +80,28 @@ fn given_attached_audits_when_rendering_then_python_rendering_is_returned() {
                  implicit column from attached context",
             ),
         },
+        AttachedAuditTestCase {
+            description: "an argument the audit SQL never reads names itself for removal",
+            attachment: AuditAttachment {
+                definition_path: Some("audits/generic/accepted_values.sql".to_owned()),
+                ..attachment(
+                    vec![
+                        values.clone(),
+                        (
+                            "where_condition".to_owned(),
+                            ArgumentValue::Text("status <> 'void'".to_owned()),
+                        ),
+                    ],
+                    None,
+                    None,
+                )
+            },
+            expected_rendering: failed(
+                "models/schema.yml audit 'accepted_values' passes argument 'where_condition', \
+                 which the audit's SQL in audits/generic/accepted_values.sql never uses; remove \
+                 'where_condition' from the attachment",
+            ),
+        },
         AttachedAuditTestCase {
             description: "a missing argument is Python's error before the policies",
             attachment: attachment(Vec::new(), Some("fatal"), None),

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-cache/src/project_reuse/_helpers/attempt.rs

@@ -30,7 +30,13 @@ use crate::project_snapshot::models::PathStamp;
 const NO_STORED_COMPILE: &str = "no stored compile";
 const REUSE_BYPASSED: &str = "compile reuse is off";
 const OUTPUT_UNREADABLE: &str = "the stored output cannot be replayed";
-const IDENTITY_CHANGED: &str = "the invocation, runtime, environment or settings changed";
+const INVOCATION_CHANGED: &str = "the command invocation changed";
+const RUNTIME_CHANGED: &str = "the Python runtime changed";
+const SEARCH_PATH_CHANGED: &str = "a Python search path entry changed";
+const ENVIRONMENT_NAMES_CHANGED: &str = "the set of tracked environment variables changed";
+const ENVIRONMENT_CHANGED: &str = "a tracked environment variable changed";
+const SETTINGS_CHANGED: &str = "provider settings inputs changed";
+const MODULES_CHANGED: &str = "an imported Python module outside the project changed";
 const TARGET_CHANGED: &str = "the compiled target changed";
 
 fn now_ns() -> i64 {
@@ -115,8 +121,8 @@ pub(crate) fn check(check: ReuseCheck<'_>) -> ReuseAttempt {
         attempt.restamped = restamped_paths(&inputs.project_files, &attempt.snapshot);
         if comparison.unchanged {
             attempt.delta = DeltaCandidate::Unavailable(OUTPUT_UNREADABLE);
-        } else if !comparison.identity_unchanged {
-            attempt.delta = DeltaCandidate::Unavailable(IDENTITY_CHANGED);
+        } else if let Some(reason) = comparison.identity_change {
+            attempt.delta = DeltaCandidate::Unavailable(reason);
         } else if !target_files_unchanged(
             &inputs.target_files,
             &attempt.project_dir,
@@ -146,21 +152,16 @@ pub(crate) fn check(check: ReuseCheck<'_>) -> ReuseAttempt {
 /// Whether a stored compile still matches, with the digests still valid either way.
 struct Comparison {
     unchanged: bool,
-    identity_unchanged: bool,
+    /// The first identity component that differs, if any.
+    identity_change: Option<&'static str>,
     digests: HashMap<String, String>,
     digested_files: usize,
 }
 
 /// Compare every stored identity, carrying forward digests still valid either way.
 fn checked(attempt: &ReuseAttempt, inputs: &StoredInputs, rules: &ReuseRules) -> Comparison {
-    let identity_unchanged: bool = inputs.invocation_digest == attempt.identity.invocation_digest
-        && inputs.runtime == attempt.identity.runtime
-        && inputs.search_path == attempt.search_path
-        && tracked_environment_names(&inputs.environment_names, rules) == inputs.environment_names
-        && environment_digest(&inputs.environment_names, rules) == inputs.environment_digest
-        && settings_inputs_digest(&inputs.settings_inputs, rules) == inputs.settings_digest
-        && module_stamps_unchanged(&inputs.modules);
-    let (files_unchanged, verified, digested_files) = if identity_unchanged {
+    let identity_change: Option<&'static str> = identity_change(attempt, inputs, rules);
+    let (files_unchanged, verified, digested_files) = if identity_change.is_none() {
         compare_project_files(
             &attempt.project_dir,
             &inputs.project_files,
@@ -170,7 +171,7 @@ fn checked(attempt: &ReuseAttempt, inputs: &StoredInputs, rules: &ReuseRules) ->
         (false, HashMap::new(), 0)
     };
     Comparison {
-        identity_unchanged,
+        identity_change,
         unchanged: files_unchanged
             && target_files_unchanged(
                 &inputs.target_files,
@@ -183,6 +184,33 @@ fn checked(attempt: &ReuseAttempt, inputs: &StoredInputs, rules: &ReuseRules) ->
     }
 }
 
+/// The first stored identity component that no longer matches, in checking order.
+fn identity_change(
+    attempt: &ReuseAttempt,
+    inputs: &StoredInputs,
+    rules: &ReuseRules,
+) -> Option<&'static str> {
+    if inputs.invocation_digest != attempt.identity.invocation_digest {
+        Some(INVOCATION_CHANGED)
+    } else if inputs.runtime != attempt.identity.runtime {
+        Some(RUNTIME_CHANGED)
+    } else if inputs.search_path != attempt.search_path {
+        Some(SEARCH_PATH_CHANGED)
+    } else if tracked_environment_names(&inputs.environment_names, rules)
+        != inputs.environment_names
+    {
+        Some(ENVIRONMENT_NAMES_CHANGED)
+    } else if environment_digest(&inputs.environment_names, rules) != inputs.environment_digest {
+        Some(ENVIRONMENT_CHANGED)
+    } else if settings_inputs_digest(&inputs.settings_inputs, rules) != inputs.settings_digest {
+        Some(SETTINGS_CHANGED)
+    } else if !module_stamps_unchanged(&inputs.modules) {
+        Some(MODULES_CHANGED)
+    } else {
+        None
+    }
+}
+
 pub(crate) fn record(
     attempt: &ReuseAttempt,
     record: &CompileRecord,

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-cli/src/dispatch/main/event_export_warning.rs

@@ -1,5 +1,7 @@
 //! The stderr warning for lifecycle events dropped or failed at command exit.
 
+use sqlbuild_core::event_export::constants::DEFAULT_EVENT_EXPORT_INVOCATION_TIMEOUT_SECONDS;
+
 use crate::dispatch::constants::SHUTDOWN_TIMEOUT_SETTING;
 use crate::dispatch::models::{ExportSummary, ExporterLoss};
 
@@ -32,7 +34,9 @@ pub fn event_export_warning(summary: &ExportSummary, command_succeeded: bool) ->
     };
     Some(format!(
         "{prefix}: {} of {} {unit} dropped, {} failed ({sink_label} {names}). \
-         Increase {SHUTDOWN_TIMEOUT_SETTING} or check sink health.",
+         Check sink health: a sink call slower than {DEFAULT_EVENT_EXPORT_INVOCATION_TIMEOUT_SECONDS}s \
+         drops that sink's events until it returns; events still queued at exit need a longer \
+         {SHUTDOWN_TIMEOUT_SETTING}.",
         summary.dropped, summary.accepted, summary.failed
     ))
 }

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-cli/src/dispatch/tests/test_event_export_warning.rs

@@ -18,7 +18,9 @@ fn given_final_export_summary_when_formatting_warning_then_reports_loss_only() {
             expected_warning: Some(
                 "Warning: command completed successfully, but lifecycle event export was \
                  incomplete: 140 of 248 events dropped, 0 failed (sink 'orders_events'). \
-                 Increase sinks.lifecycle.shutdown_timeout or check sink health.",
+                 Check sink health: a sink call slower than 1s drops that sink's events until it \
+                 returns; events still queued at exit need a longer \
+                 sinks.lifecycle.shutdown_timeout.",
             ),
         },
         EventExportWarningTestCase {
@@ -28,7 +30,9 @@ fn given_final_export_summary_when_formatting_warning_then_reports_loss_only() {
             expected_warning: Some(
                 "Warning: lifecycle event export was incomplete: 0 of 10 events dropped, \
                  1 failed (sink 'orders_events'). \
-                 Increase sinks.lifecycle.shutdown_timeout or check sink health.",
+                 Check sink health: a sink call slower than 1s drops that sink's events until it \
+                 returns; events still queued at exit need a longer \
+                 sinks.lifecycle.shutdown_timeout.",
             ),
         },
         EventExportWarningTestCase {
@@ -41,7 +45,9 @@ fn given_final_export_summary_when_formatting_warning_then_reports_loss_only() {
             expected_warning: Some(
                 "Warning: command completed successfully, but lifecycle event export was \
                  incomplete: 4 of 40 event deliveries dropped, 1 failed (sink 'orders_events'). \
-                 Increase sinks.lifecycle.shutdown_timeout or check sink health.",
+                 Check sink health: a sink call slower than 1s drops that sink's events until it \
+                 returns; events still queued at exit need a longer \
+                 sinks.lifecycle.shutdown_timeout.",
             ),
         },
     ];

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-model-config/src/header_metadata/_helpers/audits.rs

@@ -90,12 +90,12 @@ fn configured_audit<N: AuthoredNode>(
     let minimum_samples = optional_count(
         entry(options, "minimum_samples"),
         option_site,
-        (definition, "minimum_samples"),
+        (definition, "minimum_samples", options),
     )?;
     let evidence_limit = optional_count(
         entry(options, "evidence_limit"),
         option_site,
-        (definition, "evidence_limit"),
+        (definition, "evidence_limit", options),
     )?;
     let meta = optional_meta(entry(options, "meta"), option_site)?;
     let arguments: Vec<(N, N)> = options

{sqlbuild_cli-0.164.5 → sqlbuild_cli-0.165.0}/crates/sqlbuild-model-config/src/header_metadata/_helpers/text.rs

@@ -57,13 +57,13 @@ pub(crate) fn optional_bool<N: AuthoredNode>(
     }
 }
 
-/// Read a non-negative non-boolean integer option of audit `definition` that fits in 64 bits.
+/// Read a non-negative integer option of audit `definition` that fits in 64 bits; help repeats `options`.
 pub(crate) fn optional_count<N: AuthoredNode>(
     node: Option<&N>,
     site: Site<'_>,
-    option: (&str, &str),
+    option: (&str, &str, &[(N, N)]),
 ) -> Result<Option<N>, ConfigError> {
-    let (definition, key) = option;
+    let (definition, key, options) = option;
     match (
         node.map(AuthoredNode::kind),
         node.and_then(AuthoredNode::integer),
@@ -75,14 +75,29 @@ pub(crate) fn optional_count<N: AuthoredNode>(
                 "'{key}' {} is larger than a 64-bit integer",
                 node.map(AuthoredNode::python_str).unwrap_or_default()
             ))
-            .with_help(count_help(site, definition, key))),
+            .with_help(count_help(site, (definition, options), key))),
         (Some(_), _) => Err(site.error(&format!("'{key}' must be a non-negative integer"))),
     }
 }
 
-/// The MODEL header help that sets audit option `key` to the largest 64-bit integer.
-fn count_help(site: Site<'_>, definition: &str, key: &str) -> String {
-    let audits: String = format!("audits [{definition} ({key} {})]", i64::MAX);
+/// The MODEL header help repeating the audit call with option `key` set to the largest 64-bit integer.
+fn count_help<N: AuthoredNode>(
+    site: Site<'_>,
+    (definition, options): (&str, &[(N, N)]),
+    key: &str,
+) -> String {
+    let rendered: Vec<String> = options
+        .iter()
+        .map(|(name, value)| {
+            let name: String = name.text().unwrap_or_else(|| name.python_str());
+            if name == key {
+                format!("{name} {}", i64::MAX)
+            } else {
+                format!("{name} {}", header_value(value))
+            }
+        })
+        .collect();
+    let audits: String = format!("audits [{definition} ({})]", rendered.join(", "));
     let entry: String = site.column.map_or_else(
         || audits.clone(),
         |column| format!("columns ({column} ({audits}))"),
@@ -94,6 +109,34 @@ fn count_help(site: Site<'_>, definition: &str, key: &str) -> String {
     )
 }
 
+/// One authored value as MODEL header syntax: quoted strings, `[...]` lists and `(key value)` maps.
+fn header_value<N: AuthoredNode>(node: &N) -> String {
+    match node.kind() {
+        NodeKind::Null => "null".to_owned(),
+        NodeKind::Bool(value) => value.to_string(),
+        NodeKind::Str => {
+            let text: String = node.text().unwrap_or_default();
+            format!("\"{}\"", text.replace('\\', "\\\\").replace('"', "\\\""))
+        }
+        NodeKind::List | NodeKind::Tuple => {
+            let items: Vec<String> = node.items().iter().map(header_value).collect();
+            format!("[{}]", items.join(", "))
+        }
+        NodeKind::Map => {
+            let entries: Vec<String> = node
+                .entries()
+                .iter()
+                .map(|(key, value)| {
+                    let key: String = key.text().unwrap_or_else(|| key.python_str());
+                    format!("{key} {}", header_value(value))
+                })
+                .collect();
+            format!("({})", entries.join(", "))
+        }
+        NodeKind::Int { .. } | NodeKind::Other => node.python_str(),
+    }
+}
+
 /// Return the mapping entry whose key is the string `key`.
 pub(crate) fn entry<'entries, N: AuthoredNode>(
     entries: &'entries [(N, N)],