typedframes 0.8.0__tar.gz → 0.9.0__tar.gz

{typedframes-0.8.0 → typedframes-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typedframes
-Version: 0.8.0
+Version: 0.9.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -42,7 +42,7 @@ Project-URL: Repository, https://github.com/w-martin/typedframes
 
 > ⚠️ **Project Status: Proof of Concept**
 >
-> `typedframes` (v0.8.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
+> `typedframes` (v0.9.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
 > integrations work, but expect rough edges. The codebase prioritizes demonstrating the viability of static DataFrame
 > column checking over production-grade stability.
 >
@@ -504,7 +504,7 @@ repos:
         name: typedframes check
         entry: typedframes check . --strict
         language: python
-        additional_dependencies: ["typedframes==0.8.0"]
+        additional_dependencies: ["typedframes==0.9.0"]
         types_or: [python, jupyter]
         pass_filenames: false
 ```
@@ -553,7 +553,7 @@ The action installs the PyPI wheel into a throwaway virtualenv and runs the chec
 | Input | Default | |
 |-------|---------|-|
 | `path` | `.` | File or directory to check |
-| `version` | `latest` | PyPI version to install, e.g. `"0.8.0"` |
+| `version` | `latest` | PyPI version to install, e.g. `"0.9.0"` |
 | `strict` | `true` | Fail the step on errors — `typedframes check` exits 0 without it |
 | `coverage-fail-under` | *(unset)* | Minimum DataFrame schema coverage, e.g. `"90"` |
 | `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown, `explain` to diagnose a lower-than-expected total |
@@ -667,17 +667,17 @@ plus the requested features, so both halves get checked normally. See
 Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
 
 **Benchmark results** (20 runs, 3 warmup, caches cleared between runs):
-*2026-09-28 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
+*2026-09-30 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
 
 | Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
 |------|---------|--------------|------------------------|--------------------------------|
-| typedframes | 0.8.0 | DataFrame column checker | 49ms ±349µs (IQR 513µs) | 258ms ±2ms (IQR 2ms) |
-| ruff | 0.16.3 | Linter (no type checking) | 30ms ±981µs (IQR 1ms) | 236ms ±4ms (IQR 6ms) |
-| ty | 0.0.72 | Type checker | 72ms ±1ms (IQR 959µs) | 773ms ±8ms (IQR 14ms) |
-| pyrefly | 1.2.0 | Type checker | 98ms ±1ms (IQR 1ms) | 273ms ±8ms (IQR 11ms) |
-| mypy | 2.3.1 | Type checker (no plugin) | 2.79s ±93ms (IQR 61ms) | 4.14s ±41ms (IQR 52ms) |
-| mypy + typedframes | 2.3.1 | Type checker + column checker | 2.78s ±13ms (IQR 14ms) | 4.50s ±26ms (IQR 33ms) |
-| pyright | 1.1.411 | Type checker | 841ms ±35ms (IQR 46ms) | 3.30s ±24ms (IQR 32ms) |
+| typedframes | 0.9.0 | DataFrame column checker | 51ms ±613µs (IQR 997µs) | 268ms ±4ms (IQR 5ms) |
+| ruff | 0.16.3 | Linter (no type checking) | 31ms ±735µs (IQR 882µs) | 237ms ±4ms (IQR 6ms) |
+| ty | 0.0.72 | Type checker | 74ms ±2ms (IQR 3ms) | 782ms ±12ms (IQR 17ms) |
+| pyrefly | 1.2.0 | Type checker | 98ms ±1ms (IQR 2ms) | 276ms ±8ms (IQR 14ms) |
+| mypy | 2.3.1 | Type checker (no plugin) | 2.73s ±37ms (IQR 43ms) | 4.30s ±72ms (IQR 106ms) |
+| mypy + typedframes | 2.3.1 | Type checker + column checker | 2.72s ±19ms (IQR 23ms) | 4.61s ±22ms (IQR 23ms) |
+| pyright | 1.1.411 | Type checker | 826ms ±11ms (IQR 11ms) | 3.34s ±26ms (IQR 40ms) |
 
 *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
 

{typedframes-0.8.0 → typedframes-0.9.0}/README.md

@@ -8,7 +8,7 @@
 
 > ⚠️ **Project Status: Proof of Concept**
 >
-> `typedframes` (v0.8.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
+> `typedframes` (v0.9.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
 > integrations work, but expect rough edges. The codebase prioritizes demonstrating the viability of static DataFrame
 > column checking over production-grade stability.
 >
@@ -470,7 +470,7 @@ repos:
         name: typedframes check
         entry: typedframes check . --strict
         language: python
-        additional_dependencies: ["typedframes==0.8.0"]
+        additional_dependencies: ["typedframes==0.9.0"]
         types_or: [python, jupyter]
         pass_filenames: false
 ```
@@ -519,7 +519,7 @@ The action installs the PyPI wheel into a throwaway virtualenv and runs the chec
 | Input | Default | |
 |-------|---------|-|
 | `path` | `.` | File or directory to check |
-| `version` | `latest` | PyPI version to install, e.g. `"0.8.0"` |
+| `version` | `latest` | PyPI version to install, e.g. `"0.9.0"` |
 | `strict` | `true` | Fail the step on errors — `typedframes check` exits 0 without it |
 | `coverage-fail-under` | *(unset)* | Minimum DataFrame schema coverage, e.g. `"90"` |
 | `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown, `explain` to diagnose a lower-than-expected total |
@@ -633,17 +633,17 @@ plus the requested features, so both halves get checked normally. See
 Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
 
 **Benchmark results** (20 runs, 3 warmup, caches cleared between runs):
-*2026-09-28 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
+*2026-09-30 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
 
 | Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
 |------|---------|--------------|------------------------|--------------------------------|
-| typedframes | 0.8.0 | DataFrame column checker | 49ms ±349µs (IQR 513µs) | 258ms ±2ms (IQR 2ms) |
-| ruff | 0.16.3 | Linter (no type checking) | 30ms ±981µs (IQR 1ms) | 236ms ±4ms (IQR 6ms) |
-| ty | 0.0.72 | Type checker | 72ms ±1ms (IQR 959µs) | 773ms ±8ms (IQR 14ms) |
-| pyrefly | 1.2.0 | Type checker | 98ms ±1ms (IQR 1ms) | 273ms ±8ms (IQR 11ms) |
-| mypy | 2.3.1 | Type checker (no plugin) | 2.79s ±93ms (IQR 61ms) | 4.14s ±41ms (IQR 52ms) |
-| mypy + typedframes | 2.3.1 | Type checker + column checker | 2.78s ±13ms (IQR 14ms) | 4.50s ±26ms (IQR 33ms) |
-| pyright | 1.1.411 | Type checker | 841ms ±35ms (IQR 46ms) | 3.30s ±24ms (IQR 32ms) |
+| typedframes | 0.9.0 | DataFrame column checker | 51ms ±613µs (IQR 997µs) | 268ms ±4ms (IQR 5ms) |
+| ruff | 0.16.3 | Linter (no type checking) | 31ms ±735µs (IQR 882µs) | 237ms ±4ms (IQR 6ms) |
+| ty | 0.0.72 | Type checker | 74ms ±2ms (IQR 3ms) | 782ms ±12ms (IQR 17ms) |
+| pyrefly | 1.2.0 | Type checker | 98ms ±1ms (IQR 2ms) | 276ms ±8ms (IQR 14ms) |
+| mypy | 2.3.1 | Type checker (no plugin) | 2.73s ±37ms (IQR 43ms) | 4.30s ±72ms (IQR 106ms) |
+| mypy + typedframes | 2.3.1 | Type checker + column checker | 2.72s ±19ms (IQR 23ms) | 4.61s ±22ms (IQR 23ms) |
+| pyright | 1.1.411 | Type checker | 826ms ±11ms (IQR 11ms) | 3.34s ±26ms (IQR 40ms) |
 
 *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
 

{typedframes-0.8.0 → typedframes-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "typedframes"
-version = "0.8.0"
+version = "0.9.0"
 description = "Static analysis for pandas and polars DataFrames. Catch column errors at lint-time, not runtime."
 keywords = ["pandas", "polars", "type-checking", "static-analysis", "dataframe", "linter", "mypy-plugin"]
 readme = "README.md"

{typedframes-0.8.0 → typedframes-0.9.0}/rust/Cargo.lock

@@ -1347,7 +1347,7 @@ checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
 
 [[package]]
 name = "typedframes_checker"
-version = "0.8.0"
+version = "0.9.0"
 dependencies = [
  "anyhow",
  "criterion",

{typedframes-0.8.0 → typedframes-0.9.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "typedframes_checker"
-version = "0.8.0"
+version = "0.9.0"
 edition = "2021"
 description = "A high-performance Rust-based checker for typedframes DataFrame column schemas"
 license = "MIT"

{typedframes-0.8.0 → typedframes-0.9.0}/rust/src/ast_extract.rs

@@ -29,6 +29,31 @@ pub(crate) fn decorator_name(expr: &Expr) -> Option<&str> {
     }
 }
 
+// Column names for `pd.DataFrame([{...}, {...}])` -- a literal list of per-row dict
+// literals (pandas' "records" orientation). Every element must be a dict literal with
+// only string-literal keys; the result is the union of every row's keys, in
+// first-seen order (matching how pandas itself orders the resulting columns) -- a row
+// missing a key another row has doesn't invalidate the inference, it's just NaN for
+// that row.
+pub(crate) fn extract_records_list_columns(list: &ast::ExprList) -> Option<Vec<String>> {
+    if list.elts.is_empty() {
+        return None;
+    }
+    let mut columns = Vec::new();
+    for elt in &list.elts {
+        let Expr::Dict(dict) = elt else {
+            return None;
+        };
+        for item in &dict.items {
+            let key = item.key.as_ref().and_then(|k| extract_string_literal(k))?;
+            if !columns.iter().any(|c: &String| c == key) {
+                columns.push(key.to_string());
+            }
+        }
+    }
+    Some(columns)
+}
+
 pub(crate) fn extract_string_literal(expr: &Expr) -> Option<&str> {
     if let Expr::StringLiteral(s) = expr {
         Some(s.value.to_str())

{typedframes-0.8.0 → typedframes-0.9.0}/rust/src/linter.rs

@@ -293,6 +293,19 @@ pub struct Linter {
     // Names bound exactly once in the whole file, to a `True`/`False` literal -- the
     // boolean counterpart of `string_var_candidates`, for `inplace=flag`.
     pub(crate) bool_var_candidates: HashMap<String, bool>,
+    // Names initialized as `name = []` and thereafter only ever added to via
+    // `name.append({...})` with a literal dict of string-literal keys, right up to
+    // being read (as the first positional argument) by a `DataFrame(name)` call --
+    // the accumulator counterpart of `pd.DataFrame([{...}, {...}])`. Maps to the
+    // union of every append's keys, in first-seen order. Populated by a
+    // `DictListBindingCollector` pre-pass alongside `string_var_candidates`; poisoned
+    // (absent from this map) by a second `= []`, any other reassignment, any
+    // `.append()` call whose argument isn't such a dict literal, or any other bare
+    // reference to the name at all (passed to a function, checked for truthiness,
+    // indexed, ...) -- same "give up rather than guess" policy as
+    // `string_var_candidates`, deliberately conservative since a missed mutation here
+    // would mean inferring a schema real code could add columns past.
+    pub(crate) dict_list_var_candidates: HashMap<String, Vec<String>>,
     // Names bound to a resolved SQLAlchemy Core `select(...)` column list — e.g.
     // `stmt = select(Order.id, Order.amount)`. Populated inline during the main
     // top-to-bottom statement walk (unlike `string_var_candidates`, which needs a
@@ -729,6 +742,232 @@ impl<'a> Visitor<'a> for StringBindingCollector<'a> {
     }
 }
 
+// One `name = []` candidate's state -- see `Linter::dict_list_var_candidates`.
+enum DictListBinding {
+    // The union of every recognized `.append({...})` call's keys, in first-seen
+    // order.
+    Building(Vec<String>),
+    Poisoned,
+}
+
+// AST visitor backing `Linter::dict_list_var_candidates` -- see that field's doc
+// comment for the exact policy. `accounted_for` holds the source range of every Name
+// node already explained by a recognized `.append({...})` receiver or `DataFrame(name)`
+// argument, so the generic "any other appearance poisons it" rule in `visit_expr`
+// doesn't also fire for those two approved occurrences.
+struct DictListBindingCollector {
+    bindings: HashMap<String, DictListBinding>,
+    accounted_for: std::collections::HashSet<ruff_text_size::TextRange>,
+}
+
+impl DictListBindingCollector {
+    fn poison(&mut self, name: &str) {
+        self.bindings
+            .insert(name.to_string(), DictListBinding::Poisoned);
+    }
+
+    // Poison every bare name an assignment/for/with/del target touches -- mirrors
+    // `StringBindingCollector::record_target_names`.
+    fn record_target_names(&mut self, target: &Expr) {
+        match target {
+            Expr::Name(n) => self.poison(n.id.as_str()),
+            Expr::Tuple(t) => t.elts.iter().for_each(|e| self.record_target_names(e)),
+            Expr::List(l) => l.elts.iter().for_each(|e| self.record_target_names(e)),
+            Expr::Starred(s) => self.record_target_names(&s.value),
+            _ => {}
+        }
+    }
+
+    // `name.append(arg)`: extends the candidate with `arg`'s keys if it's a dict
+    // literal of string-literal keys, else poisons it. A no-op for a name that was
+    // never initialized as `= []` in the first place.
+    fn record_append(&mut self, name: &str, arg: Option<&Expr>) {
+        if !self.bindings.contains_key(name) {
+            return;
+        }
+        let extracted = match arg {
+            Some(Expr::Dict(dict)) => dict
+                .items
+                .iter()
+                .map(|item| {
+                    item.key
+                        .as_ref()
+                        .and_then(|k| ast_extract::extract_string_literal(k))
+                        .map(str::to_string)
+                })
+                .collect::<Option<Vec<String>>>(),
+            _ => None,
+        };
+        let Some(binding) = self.bindings.get_mut(name) else {
+            return;
+        };
+        match (binding, extracted) {
+            (DictListBinding::Poisoned, _) => {}
+            (binding, None) => *binding = DictListBinding::Poisoned,
+            (DictListBinding::Building(keys), Some(new_keys)) => {
+                for key in new_keys {
+                    if !keys.contains(&key) {
+                        keys.push(key);
+                    }
+                }
+            }
+        }
+    }
+}
+
+impl<'a> Visitor<'a> for DictListBindingCollector {
+    fn visit_stmt(&mut self, stmt: &'a Stmt) {
+        match stmt {
+            Stmt::Assign(assign) => {
+                if let [Expr::Name(target)] = assign.targets.as_slice() {
+                    let name = target.id.as_str();
+                    if matches!(&*assign.value, Expr::List(list) if list.elts.is_empty()) {
+                        if self.bindings.contains_key(name) {
+                            self.poison(name);
+                        } else {
+                            self.bindings
+                                .insert(name.to_string(), DictListBinding::Building(Vec::new()));
+                            // The defining target itself is a bare Name reference too --
+                            // exempt it from the generic poison-on-any-appearance rule
+                            // below, the same way an `.append` receiver or a
+                            // `DataFrame(name)` argument is.
+                            self.accounted_for.insert(target.range());
+                        }
+                    } else {
+                        self.poison(name);
+                    }
+                } else {
+                    for target in &assign.targets {
+                        self.record_target_names(target);
+                    }
+                }
+            }
+            Stmt::AnnAssign(ann) => {
+                if let Expr::Name(n) = &*ann.target {
+                    self.poison(n.id.as_str());
+                }
+            }
+            Stmt::AugAssign(aug) => self.record_target_names(&aug.target),
+            Stmt::For(for_stmt) => self.record_target_names(&for_stmt.target),
+            Stmt::Global(g) => {
+                for name in &g.names {
+                    self.poison(name.as_str());
+                }
+            }
+            Stmt::Nonlocal(nl) => {
+                for name in &nl.names {
+                    self.poison(name.as_str());
+                }
+            }
+            Stmt::Delete(del) => {
+                for target in &del.targets {
+                    self.record_target_names(target);
+                }
+            }
+            Stmt::Import(imp) => {
+                for alias in &imp.names {
+                    let bound = alias.asname.as_ref().unwrap_or(&alias.name);
+                    self.poison(bound.as_str());
+                }
+            }
+            Stmt::ImportFrom(imp) => {
+                for alias in &imp.names {
+                    let bound = alias.asname.as_ref().unwrap_or(&alias.name);
+                    self.poison(bound.as_str());
+                }
+            }
+            _ => {}
+        }
+        ast_visitor::walk_stmt(self, stmt);
+    }
+
+    fn visit_except_handler(&mut self, handler: &'a ast::ExceptHandler) {
+        let ast::ExceptHandler::ExceptHandler(h) = handler;
+        if let Some(name) = &h.name {
+            self.poison(name.as_str());
+        }
+        ast_visitor::walk_except_handler(self, handler);
+    }
+
+    fn visit_parameter(&mut self, parameter: &'a ast::Parameter) {
+        self.poison(parameter.name.as_str());
+        ast_visitor::walk_parameter(self, parameter);
+    }
+
+    fn visit_with_item(&mut self, item: &'a ast::WithItem) {
+        if let Some(vars) = &item.optional_vars {
+            self.record_target_names(vars);
+        }
+        ast_visitor::walk_with_item(self, item);
+    }
+
+    fn visit_comprehension(&mut self, comp: &'a ast::Comprehension) {
+        self.record_target_names(&comp.target);
+        ast_visitor::walk_comprehension(self, comp);
+    }
+
+    fn visit_expr(&mut self, expr: &'a Expr) {
+        if let Expr::Call(call) = expr {
+            if let Expr::Attribute(attr) = &*call.func {
+                if attr.attr.as_str() == "append" {
+                    if let Expr::Name(recv) = &*attr.value {
+                        self.accounted_for.insert(attr.value.range());
+                        self.record_append(recv.id.as_str(), call.arguments.args.first());
+                    }
+                }
+            }
+            if is_dataframe_constructor_callee(&call.func) {
+                if let Some(first @ Expr::Name(_)) = call.arguments.args.first() {
+                    self.accounted_for.insert(first.range());
+                }
+            }
+        }
+        if let Expr::Named(named) = expr {
+            if let Expr::Name(n) = &*named.target {
+                self.poison(n.id.as_str());
+            }
+        }
+        if let Expr::Name(name) = expr {
+            if !self.accounted_for.contains(&expr.range()) {
+                if let Some(DictListBinding::Building(_)) = self.bindings.get(name.id.as_str()) {
+                    self.poison(name.id.as_str());
+                }
+            }
+        }
+        ast_visitor::walk_expr(self, expr);
+    }
+}
+
+// `DataFrame(...)` or `<anything>.DataFrame(...)` -- the constructor shape
+// `dict_list_var_candidates`/`extract_load_columns` both recognize, matching how the
+// rest of the checker treats a `DataFrame` call regardless of its receiver (`pd.`,
+// `pl.`, an aliased import, ...).
+fn is_dataframe_constructor_callee(func: &Expr) -> bool {
+    match func {
+        Expr::Name(name) => name.id.as_str() == "DataFrame",
+        Expr::Attribute(attr) => attr.attr.as_str() == "DataFrame",
+        _ => false,
+    }
+}
+
+fn collect_dict_list_var_candidates(body: &[Stmt]) -> HashMap<String, Vec<String>> {
+    let mut collector = DictListBindingCollector {
+        bindings: HashMap::new(),
+        accounted_for: std::collections::HashSet::new(),
+    };
+    for stmt in body {
+        collector.visit_stmt(stmt);
+    }
+    collector
+        .bindings
+        .into_iter()
+        .filter_map(|(name, binding)| match binding {
+            DictListBinding::Building(keys) if !keys.is_empty() => Some((name, keys)),
+            _ => None,
+        })
+        .collect()
+}
+
 // The row indexer of a `df.loc[rows, cols]` target.
 fn loc_row_indexer(target: &Expr) -> Option<&Expr> {
     let Expr::Subscript(subscript) = target else {
@@ -1148,6 +1387,7 @@ impl Linter {
             sql_dialect: sql::SqlDialect::Generic,
             project_root: None,
             string_var_candidates: HashMap::new(),
+            dict_list_var_candidates: HashMap::new(),
             bool_var_candidates: HashMap::new(),
             stmt_var_candidates: HashMap::new(),
             retrieval_jobs: HashMap::new(),
@@ -1271,6 +1511,7 @@ impl Linter {
         self.line_index = Some(LineIndex::from_source_text(source));
         (self.string_var_candidates, self.bool_var_candidates) =
             self.collect_literal_var_candidates(&module.body, path);
+        self.dict_list_var_candidates = collect_dict_list_var_candidates(&module.body);
         let mut df_usage_collector = DataFrameShapedUsageCollector {
             names: std::collections::HashSet::new(),
         };
@@ -1724,18 +1965,35 @@ impl Linter {
         // never fires for read_csv/read_json/etc., whose first positional argument is
         // a path or buffer, not column data — a dict there means something else
         // entirely and inferring columns from it would be wrong.
+        // `DataFrame([{...}, {...}])` -- a literal list of per-row dict literals
+        // (records orientation), or `DataFrame(records)` where `records` is a name
+        // this file's own pre-pass traced back to such a list built via `.append()`
+        // in a loop -- see `Linter::dict_list_var_candidates`.
         if func_name == "DataFrame" {
-            if let Some(Expr::Dict(dict)) = call.arguments.args.first() {
-                let keys: Vec<String> = dict
-                    .items
-                    .iter()
-                    .filter_map(|item| item.key.as_ref())
-                    .filter_map(|k| ast_extract::extract_string_literal(k))
-                    .map(|s| s.to_string())
-                    .collect();
-                if !keys.is_empty() {
-                    return (Some(keys), LoadKind::File);
+            match call.arguments.args.first() {
+                Some(Expr::Dict(dict)) => {
+                    let keys: Vec<String> = dict
+                        .items
+                        .iter()
+                        .filter_map(|item| item.key.as_ref())
+                        .filter_map(|k| ast_extract::extract_string_literal(k))
+                        .map(|s| s.to_string())
+                        .collect();
+                    if !keys.is_empty() {
+                        return (Some(keys), LoadKind::File);
+                    }
+                }
+                Some(Expr::List(list)) => {
+                    if let Some(cols) = ast_extract::extract_records_list_columns(list) {
+                        return (Some(cols), LoadKind::File);
+                    }
+                }
+                Some(Expr::Name(name)) => {
+                    if let Some(cols) = self.dict_list_var_candidates.get(name.id.as_str()) {
+                        return (Some(cols.clone()), LoadKind::File);
+                    }
                 }
+                _ => {}
             }
         }
 
@@ -8429,6 +8687,301 @@ print(df["a"])
         assert_eq!(linter.dataframes_typed, 1);
     }
 
+    #[test]
+    fn test_should_infer_columns_from_a_literal_list_of_dict_literals() {
+        // arrange: pandas' "records" orientation -- one dict literal per row, passed
+        // directly as a list literal. Columns are the union of every row's keys.
+        let source = r#"
+import pandas as pd
+
+df = pd.DataFrame([{"a": 1, "b": 2}, {"a": 3, "c": 4}])
+print(df["a"])
+print(df["c"])
+print(df["nope"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert: union is {a, b, c}, in first-seen order; only the genuine typo flags.
+        assert_eq!(linter.dataframes_total, 1);
+        assert_eq!(linter.dataframes_typed, 1);
+        assert_eq!(errors.len(), 1, "errors: {errors:?}");
+        assert!(errors[0].message.contains("'nope'"));
+        assert!(errors[0].message.contains("{a, b, c}"));
+    }
+
+    #[test]
+    fn test_should_leave_a_list_of_non_dict_elements_untracked() {
+        // arrange: not every element is a dict literal -- can't infer columns from it.
+        let source = r#"
+import pandas as pd
+
+df = pd.DataFrame([{"a": 1}, "not a dict"])
+print(df["a"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert: recognized as a DataFrame origin, but not typed -- no false claim.
+        assert_eq!(linter.dataframes_total, 1);
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_should_infer_columns_from_an_append_loop_accumulator() {
+        // arrange: `records = []` then `.append({literal dict})` calls in a loop --
+        // the shape a `pd.DataFrame([{...}])` literal can't cover on its own.
+        let source = r#"
+import pandas as pd
+
+records = []
+for row in rows:
+    records.append({"a": row.a, "b": row.b})
+
+df = pd.DataFrame(records)
+print(df["a"])
+print(df["nope"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(linter.dataframes_total, 1);
+        assert_eq!(linter.dataframes_typed, 1);
+        assert_eq!(errors.len(), 1, "errors: {errors:?}");
+        assert!(errors[0].message.contains("'nope'"));
+        assert!(errors[0].message.contains("{a, b}"));
+    }
+
+    #[test]
+    fn test_should_union_keys_across_nested_loop_appends_in_first_seen_order() {
+        // arrange: a nested loop, appending the same shape of dict every iteration --
+        // the pattern this feature exists for.
+        let source = r#"
+import pandas as pd
+
+records = []
+for x in xs:
+    for y in ys:
+        records.append({"sku": x, "date": y, "price": 1})
+
+df = pd.DataFrame(records)
+print(df["sku"])
+print(df["price"])
+print(df["nope"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(errors.len(), 1, "errors: {errors:?}");
+        assert!(errors[0].message.contains("'nope'"));
+        assert!(errors[0].message.contains("{sku, date, price}"));
+    }
+
+    #[test]
+    fn test_should_leave_an_accumulator_untracked_when_mutated_by_another_function() {
+        // arrange: `helper` could append anything -- a call we can't see into must not
+        // be silently assumed harmless.
+        let source = r#"
+import pandas as pd
+
+def helper(records):
+    records.append({"weird_key": 1})
+
+records = []
+records.append({"a": 1})
+helper(records)
+df = pd.DataFrame(records)
+print(df["a"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert: no false unknown-column against an incomplete {a}-only schema.
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_should_leave_an_accumulator_untracked_after_a_non_append_mutation() {
+        // arrange
+        let source = r#"
+import pandas as pd
+
+records = []
+records.append({"a": 1})
+records.extend([{"b": 2}])
+df = pd.DataFrame(records)
+print(df["a"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_should_leave_an_accumulator_untracked_after_an_append_with_a_dynamic_key() {
+        // arrange
+        let source = r#"
+import pandas as pd
+
+records = []
+key = "a"
+records.append({key: 1})
+df = pd.DataFrame(records)
+print(df["a"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_should_leave_an_accumulator_untracked_after_a_read_only_reference() {
+        // arrange: even a harmless-looking `len(records)` before construction poisons
+        // it -- deliberately conservative, since distinguishing "definitely read-only"
+        // calls from ones that might mutate isn't attempted.
+        let source = r#"
+import pandas as pd
+
+records = []
+records.append({"a": 1})
+print(len(records))
+df = pd.DataFrame(records)
+print(df["a"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_should_leave_an_accumulator_untracked_after_being_reinitialized() {
+        // arrange: two separate `records = []` bindings -- ambiguous which loop's
+        // appends belong to "the" list by the time DataFrame(records) is reached.
+        let source = r#"
+import pandas as pd
+
+records = []
+records.append({"a": 1})
+records = []
+records.append({"b": 2})
+df = pd.DataFrame(records)
+print(df["b"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_should_not_infer_columns_for_an_unrelated_name_that_happens_to_hold_a_list() {
+        // arrange: `items` is never initialized as `[]`, so it's simply never a
+        // candidate -- not poisoned, just never tracked in the first place.
+        let source = r#"
+import pandas as pd
+
+items = get_items()
+df = pd.DataFrame(items)
+print(df["anything"])
+"#;
+        let mut linter = Linter::new();
+
+        // act
+        let errors = linter
+            .check_file_internal(source, Path::new("test.py"))
+            .unwrap();
+
+        // assert
+        assert_eq!(linter.dataframes_typed, 0);
+        assert!(
+            errors
+                .iter()
+                .all(|e| e.code != CODE_UNKNOWN_COLUMN && e.code != CODE_UNVERIFIABLE_COLUMN),
+            "errors: {errors:?}"
+        );
+    }
+
     #[test]
     fn test_should_infer_columns_from_dataframe_constructor_dict_literal() {
         // arrange: a dict literal passed directly to DataFrame() names its columns as

{typedframes-0.8.0 → typedframes-0.9.0}/src/typedframes/__init__.py

@@ -37,7 +37,7 @@ Usage:
     df.filter(UserSchema.user_id.col > 10)  # ✓ Refactor-safe polars expression
 """
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 from .base_schema import BaseSchema as BaseSchema
 from .column import Column as Column

{typedframes-0.8.0 → typedframes-0.9.0}/src/typedframes/cli.py

@@ -671,6 +671,80 @@ class RunStats:
     dataframes_typed: int
 
 
+def _split_errors_by_confidence(errors_only: list[dict]) -> tuple[list[dict], list[dict]]:
+    """Split error-severity diagnostics into confirmed and unverifiable ones.
+
+    "Confirmed" means definitely wrong; "unverifiable" means the checker couldn't
+    check the access at all, not "checked and it's wrong" -- the summary line
+    counts them separately so "1 error" never quietly means "1 access the checker
+    had no basis to judge".
+    """
+    confirmed = [e for e in errors_only if e.get("code") != "unverifiable-column"]
+    unverifiable = [e for e in errors_only if e.get("code") == "unverifiable-column"]
+    return confirmed, unverifiable
+
+
+def _error_summary_parts(errors_only: list[dict], warnings: list[dict]) -> list[str]:
+    """The comma-joined pieces of the "Found ..." summary line.
+
+    Confirmed errors, unverifiable ones, and warnings, each omitted when there are
+    none of that kind. Confirmed and unverifiable are only split into two phrases
+    when at least one unverifiable-column diagnostic is present -- with none, this
+    reads exactly as it always has ("N errors"), so the common case is unchanged.
+    """
+    confirmed, unverifiable = _split_errors_by_confidence(errors_only)
+    parts = []
+    if confirmed or not unverifiable:
+        label = "error" if len(confirmed) == 1 else "errors"
+        parts.append(f"{len(confirmed)} {label}")
+    if unverifiable:
+        label = "unverifiable error" if len(unverifiable) == 1 else "unverifiable errors"
+        parts.append(f"{len(unverifiable)} {label}")
+    if warnings:
+        label = "warning" if len(warnings) == 1 else "warnings"
+        parts.append(f"{len(warnings)} {label}")
+    return parts
+
+
+# Below this fraction of tracked DataFrames having a concrete column list, the
+# error/warning summary leads with a coverage caveat instead of trailing it -- see
+# `_low_coverage_caveat`.
+_LOW_COVERAGE_THRESHOLD = 0.5
+
+
+def _low_coverage_caveat(stats: RunStats, all_errors: list[dict]) -> str | None:
+    """A coverage-ratio line noting that the diagnostics below only reflect what little could be tracked.
+
+    Printed FIRST, ahead of the diagnostics themselves, whenever under half the
+    DataFrames the checker saw had a concrete column list. Below that threshold a
+    small "N errors" count reads as reassuring ("only N problems") when the more
+    important fact is that most of the run was never actually checked;
+    `_coverage_message` carries the same caveat in its usual, easy-to-miss spot at
+    the very end of the output, for everything above the threshold.
+
+    `all_errors` must be the exact list about to be printed (post `--no-warnings`/
+    `--no-info`/`--lenient-ingest` filtering, done by `_apply_diagnostic_policy`
+    before this is ever called) -- not `errors_only`/`warnings`, which exclude
+    info-severity diagnostics (e.g. `--lenient-ingest`'s untracked-dataframe
+    downgrade) that still print in the body, and would otherwise undercount. With
+    `all_errors` empty -- genuinely nothing found, or everything filtered out by one
+    of those flags -- this returns `None` rather than a "0 findings below" caveat
+    with nothing actually below it; `_coverage_message`'s own plain wording already
+    covers that case correctly, with no claim about what's printed alongside it.
+    """
+    if not all_errors:
+        return None
+    if stats.dataframes_total == 0 or stats.dataframes_typed / stats.dataframes_total >= _LOW_COVERAGE_THRESHOLD:
+        return None
+    pct = round(100 * stats.dataframes_typed / stats.dataframes_total)
+    findings = len(all_errors)
+    noun, verb = ("finding", "covers") if findings == 1 else ("findings", "cover")
+    return (
+        f"\u2139 {stats.dataframes_typed}/{stats.dataframes_total} DataFrames had column info "
+        f"({pct}%) \u2014 the {findings} {noun} below only {verb} what little could be tracked"
+    )
+
+
 def _coverage_message(stats: RunStats) -> str:
     """Build the low-key DataFrame schema coverage summary line.
 
@@ -1151,12 +1225,19 @@ def _print_results(
     use_color = output_format == "text" and hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
 
     if output_format == "github":
+        caveat = _low_coverage_caveat(stats, all_errors) if show_info else None
+        if caveat:
+            print(f"::notice title=typedframes DataFrame schema coverage::{caveat[2:]}")
         if all_errors:
             print(_format_github(all_errors))
-        if show_info:
+        if show_info and not caveat:
             print(f"::notice title=typedframes DataFrame schema coverage::{_coverage_message(stats)[2:]}")
         return
 
+    caveat = _low_coverage_caveat(stats, all_errors) if show_info else None
+    if caveat:
+        print(f"{_DIM}{caveat}{_RESET}" if use_color else caveat)
+
     # text format
     if all_errors:
         print(_format_text(all_errors, color=use_color))
@@ -1164,21 +1245,14 @@ def _print_results(
 
     file_label = "file" if len(files) == 1 else "files"
     if errors_only or warnings:
-        parts = []
-        if errors_only:
-            error_label = "error" if len(errors_only) == 1 else "errors"
-            parts.append(f"{len(errors_only)} {error_label}")
-        if warnings:
-            warn_label = "warning" if len(warnings) == 1 else "warnings"
-            parts.append(f"{len(warnings)} {warn_label}")
-        summary = ", ".join(parts)
+        summary = ", ".join(_error_summary_parts(errors_only, warnings))
         msg = f"\u2717 Found {summary} in {len(files)} {file_label} ({stats.elapsed:.1f}s)"
         print(f"{_BOLD_RED}{msg}{_RESET}" if use_color else msg)
     else:
         msg = f"\u2713 Checked {len(files)} {file_label} in {stats.elapsed:.1f}s"
         print(f"{_BOLD_GREEN}{msg}{_RESET}" if use_color else msg)
 
-    if show_info:
+    if show_info and not caveat:
         coverage_msg = _coverage_message(stats)
         print(f"{_DIM}{coverage_msg}{_RESET}" if use_color else coverage_msg)