big-code-analysis 1.0.0__tar.gz → 1.1.0__tar.gz

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/CHANGELOG.md

@@ -18,8 +18,19 @@ why no value stability is offered until `1.0`. Entries above the
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-05-25
+
 ### Added
 
+- `bca --exclude-from <FILE>` global flag reads `--exclude` glob
+  patterns from a file (one per line, `.gitignore`-style: blank lines
+  and `#`-prefixed comments are skipped). Patterns union with any
+  inline `--exclude <GLOB>` flags into a single deny-set. The
+  convention is a `.bcaignore` at the repo root so workflow,
+  recipe, and local baseline-bootstrap can share one source of truth.
+  Use `-` for stdin. Fixes
+  [#355](https://github.com/dekobon/big-code-analysis/issues/355).
+
 - **Python bindings shipped** — close-out of
   [#103](https://github.com/dekobon/big-code-analysis/issues/103)
   (umbrella) via phase 9/9 in
@@ -480,6 +491,72 @@ why no value stability is offered until `1.0`. Entries above the
 
 ### Changed
 
+- **README badges replaced.** Dropped the four upstream
+  `mozilla/rust-code-analysis` badges that no longer worked for this
+  fork: the Mozilla TaskCluster job (URL pinned at `/master/`; the
+  fork's default branch is `main` and no TaskCluster job is wired up),
+  the codecov badge (rendered `coverage: unknown` since no CI job
+  uploads coverage), and the Mozilla Matrix chat badge (link
+  resolved to the upstream `#rust-code-analysis:mozilla.org` room,
+  not a room this fork owns). Replaced them with the badge set the
+  fork can actually back: crates.io version, MSRV (sourced
+  dynamically from `Cargo.toml`'s `rust-version`), CI workflow
+  status, CodeQL status, docs.rs, and license. No coverage badge is
+  re-added — CI does not currently upload coverage; revisit only if
+  a `cargo-llvm-cov` job lands
+  ([#148](https://github.com/dekobon/big-code-analysis/issues/148)).
+- Removed four dead per-route `.app_data(web::Json::<T>)` calls from
+  `big-code-analysis-web`'s `HttpServer` builder. Each was a bare
+  tuple-struct constructor function-item, not a `JsonConfig`, so the
+  `Json<T>` extractor never looked them up. The global
+  `JsonConfig::default().limit(max_size)` registered one line earlier
+  is what actually bounds JSON payload size; the per-route lines were
+  misleading no-ops from PR #883's actix-web 4.1 bump. Added a 413
+  Payload-Too-Large regression test against a small global limit
+  ([#336](https://github.com/dekobon/big-code-analysis/issues/336)).
+- `xtask`'s `render_man_page` now returns
+  `io::Error::new(io::ErrorKind::AlreadyExists, ...)` when two
+  rendered pages would write to the same `{name}.1` filename. The
+  previous blind `fs::write` plus `expected.push(filename)` would
+  silently overwrite the first page and mask the collision from the
+  orphan sweep, so a hypothetical future `bca web` subcommand
+  colliding with the `bca-web` top-level binary would ship only one
+  of the two pages. The collision check is ASCII-case-insensitive
+  so case-insensitive filesystems (APFS on macOS, NTFS on Windows)
+  treat `Bca.1` and `bca.1` as colliding even though Rust string
+  equality does not
+  ([#337](https://github.com/dekobon/big-code-analysis/issues/337)).
+- `enums/templates/foo.rs` has been deleted. The file was an
+  unreferenced early scaffold (no `#[template(path = ...)]` pointed
+  at it) containing syntactically invalid Rust — semicolons instead
+  of commas as enum-variant separators, plus missing `Eq`/`Clone`/
+  `FromPrimitive` derives that real production templates require —
+  and would have misled anyone using it as a copy-paste starting
+  point
+  ([#342](https://github.com/dekobon/big-code-analysis/issues/342)).
+- Four `unwrap()` sites in non-test code have been replaced with
+  either `expect("invariant")` carrying the proof in the panic text
+  or restructured `match`/`while let` patterns that make the
+  impossibility lexical: `dump_spans` in `src/function.rs` now uses
+  `into_iter().enumerate()` with an `i == last_idx` flag; `consumer`
+  in `src/concurrent_files.rs` uses `while let Ok(Some(job)) =
+  receiver.recv()`; `get_regex` and `get_paths_dist` in
+  `src/tools.rs` carry `.expect("constant regex must compile")` and
+  `.expect("ancestor verified by starts_with above")` respectively.
+  Regression tests added for the `dump_spans` n=0/1/many paths and
+  the `consumer` poison-pill loop
+  ([#343](https://github.com/dekobon/big-code-analysis/issues/343)).
+- `enums::mk_langs!` and `enums::mk_get_language!` no longer accept
+  the unused grammar-crate ident as a tuple second element. The
+  macro expansion never referenced `$name`, so the
+  `(Cpp, tree_sitter_cpp)` declaration was decorative — and
+  misleading, since `get_language(&Lang::Cpp)` actually resolves to
+  `tree_sitter_mozcpp::LANGUAGE`. Variants that resolve against a
+  non-obvious grammar (`Cpp` → mozcpp, `Mozjs` → mozjs, the vendored
+  `bca-tree-sitter-*` forks, the `LANGUAGE_TYPESCRIPT` / `LANGUAGE_PHP`
+  per-language consts) now carry an inline `// -> <crate>` comment
+  pinned to each entry
+  ([#344](https://github.com/dekobon/big-code-analysis/issues/344)).
 - **Vendored grammar forks renamed to `bca-tree-sitter-*`** to unblock
   first-time crates.io publication of `big-code-analysis`. The five
   in-tree path-dep crates — `tree-sitter-ccomment`, `tree-sitter-mozcpp`,
@@ -892,6 +969,59 @@ why no value stability is offered until `1.0`. Entries above the
 
 ### Fixed
 
+- `extract_summaries_inner` in the CLI's markdown-report walker now
+  walks the `FuncSpace` tree iteratively (explicit `Vec<&FuncSpace>`
+  stack with children pushed in reverse for source order). The prior
+  recursive form reintroduced the unbounded-recursion DoS that #292
+  closed elsewhere — an adversarially deep AST (chained lambdas,
+  generated parser fixtures) would overflow the worker thread's
+  default 2 MiB stack during `bca report` execution. Mirrors the
+  iterative pattern in `ThresholdSet::evaluate_with_policy`; see
+  lesson 13
+  ([#338](https://github.com/dekobon/big-code-analysis/issues/338)).
+- `MetricSet`'s internal bitfield is now `u32`. `Metric::bit()` shifted
+  `1 << (self as u32)` but the storage was `u16`, so adding a 17th
+  variant (the enum is `#[non_exhaustive]` precisely so that can
+  happen) would panic in debug or silently wrap in release, corrupting
+  every `MetricSet` operation. Widened storage and bit-width to `u32`
+  for 32 metrics of headroom, with three regression tests pinning the
+  invariants: every variant maps to a distinct non-zero bit, every
+  variant round-trips through `MetricSet::all().contains()`, and the
+  variant count stays within the storage width
+  ([#339](https://github.com/dekobon/big-code-analysis/issues/339)).
+- `XmlAttr` in the Checkstyle XML output now escapes TAB, LF, and CR
+  as numeric character references (`&#x9;`, `&#xA;`, `&#xD;`). The
+  previous implementation passed these bytes through literally on the
+  belief they would survive — but XML 1.0 §3.3.3 mandates that any
+  whitespace character inside an attribute value (other than via a
+  numeric character reference) is normalized to a single space on
+  read. POSIX paths with embedded newlines and any future multi-line
+  message template would silently lose their whitespace structure on
+  every conforming consumer (Jenkins, SonarQube, IDE plugins).
+  Round-trip test added that re-parses the emitted XML with
+  `quick-xml` and asserts the bytes survive
+  ([#340](https://github.com/dekobon/big-code-analysis/issues/340)).
+- `to_sarif` in the Python bindings now silently skips `None`
+  iterable entries alongside its existing `AnalysisError` skip
+  semantics, **and** accepts a scalar `None` (yielding a
+  well-formed empty SARIF run). The natural compositions
+  `bca.to_sarif([bca.analyze(p) for p in paths])` and
+  `bca.to_sarif(bca.analyze(p))` previously raised `TypeError`
+  whenever any input file was classified as generated — the
+  documented return of `analyze()` for those files is `None`. Both
+  `None` and `AnalysisError` now represent "no record emitted for
+  this file". The TypeError message for genuinely-unsupported items
+  now lists `None` as an accepted shape
+  ([#341](https://github.com/dekobon/big-code-analysis/issues/341)).
+- `sanitize_identifier` in the `enums` crate now matches both the
+  canonical `\u{FEFF}` BOM (the shape tree-sitter actually emits
+  from `node_kind_for_id` after UTF-8 decoding) and the
+  three-codepoint `\u{00EF}\u{00BB}\u{00BF}` mojibake form the
+  previous `""` literal decoded to. A future grammar that
+  surfaces a BOM token now gets a stable `BOM` identifier instead of
+  falling through to the `Anon<N>` fallback. New `tests` module
+  anchors both BOM shapes plus the reserved-keyword table
+  ([#345](https://github.com/dekobon/big-code-analysis/issues/345)).
 - TypeScript and TSX Halstead now classify the `string` type-keyword
   alias as an operand, matching `Checker::is_string`. The tree-sitter
   TS / TSX grammars expose the `string` keyword used in type
@@ -1682,10 +1812,10 @@ why no value stability is offered until `1.0`. Entries above the
   the blocking thread pool (`fix(web): track orphaned blocking
   tasks and reject when threshold exceeded`, commit `94c8141`).
 
-<!-- Release-cutter: when the v1.0.0 tag is created, retarget both
-links below at `v1.0.0` (Unreleased: `v1.0.0...HEAD`; 1.0.0:
-`007ee15...v1.0.0`). They currently point at `HEAD` so the
-comparison links resolve before the tag exists. -->
+<!-- Release-cutter: when a new vX.Y.Z tag is created, retarget the
+[Unreleased] link to `vX.Y.Z...HEAD` and add a `[X.Y.Z]:` line
+pointing at `<prev-tag>...vX.Y.Z`. -->
 
-[Unreleased]: https://github.com/dekobon/big-code-analysis/compare/HEAD...HEAD
-[1.0.0]: https://github.com/dekobon/big-code-analysis/compare/007ee15...HEAD
+[Unreleased]: https://github.com/dekobon/big-code-analysis/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/dekobon/big-code-analysis/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/dekobon/big-code-analysis/compare/007ee15...v1.0.0

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/Cargo.lock

@@ -355,7 +355,7 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "bca-tree-sitter-ccomment"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "cc",
  "tree-sitter-language",
@@ -363,7 +363,7 @@ dependencies = [
 
 [[package]]
 name = "bca-tree-sitter-mozcpp"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "cc",
  "tree-sitter-cpp",
@@ -372,7 +372,7 @@ dependencies = [
 
 [[package]]
 name = "bca-tree-sitter-mozjs"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "cc",
  "tree-sitter-javascript",
@@ -381,7 +381,7 @@ dependencies = [
 
 [[package]]
 name = "bca-tree-sitter-preproc"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "cc",
  "tree-sitter-language",
@@ -389,7 +389,7 @@ dependencies = [
 
 [[package]]
 name = "bca-tree-sitter-tcl"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "cc",
  "tree-sitter-language",
@@ -397,7 +397,7 @@ dependencies = [
 
 [[package]]
 name = "big-code-analysis"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "aho-corasick",
  "bca-tree-sitter-ccomment",
@@ -443,7 +443,7 @@ dependencies = [
 
 [[package]]
 name = "big-code-analysis-cli"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "assert_cmd",
  "big-code-analysis",
@@ -465,7 +465,7 @@ dependencies = [
 
 [[package]]
 name = "big-code-analysis-py"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "big-code-analysis",
  "pyo3",
@@ -477,7 +477,7 @@ dependencies = [
 
 [[package]]
 name = "big-code-analysis-web"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "actix-rt",
  "actix-web",
@@ -3695,7 +3695,7 @@ checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 
 [[package]]
 name = "xtask"
-version = "1.0.0"
+version = "1.1.0"
 dependencies = [
  "big-code-analysis-cli",
  "big-code-analysis-web",

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/Cargo.toml

@@ -11,7 +11,7 @@ exclude = [
 ]
 
 [workspace.package]
-version = "1.0.0"
+version = "1.1.0"
 edition = "2024"
 rust-version = "1.94"
 license = "MPL-2.0"
@@ -51,11 +51,11 @@ tree-sitter-typescript = "=0.23.2"
 # Rationale and the rejected alternatives live on the umbrella
 # issue (dekobon/big-code-analysis#149); the operational details
 # (publish order, first-bootstrap workflow) live in `RELEASING.md`.
-tree-sitter-ccomment = { package = "bca-tree-sitter-ccomment", path = "./tree-sitter-ccomment", version = "=1.0.0" }
-tree-sitter-mozcpp = { package = "bca-tree-sitter-mozcpp", path = "./tree-sitter-mozcpp", version = "=1.0.0" }
-tree-sitter-mozjs = { package = "bca-tree-sitter-mozjs", path = "./tree-sitter-mozjs", version = "=1.0.0" }
-tree-sitter-preproc = { package = "bca-tree-sitter-preproc", path = "./tree-sitter-preproc", version = "=1.0.0" }
-tree-sitter-tcl = { package = "bca-tree-sitter-tcl", path = "./tree-sitter-tcl", version = "=1.0.0" }
+tree-sitter-ccomment = { package = "bca-tree-sitter-ccomment", path = "./tree-sitter-ccomment", version = "=1.1.0" }
+tree-sitter-mozcpp = { package = "bca-tree-sitter-mozcpp", path = "./tree-sitter-mozcpp", version = "=1.1.0" }
+tree-sitter-mozjs = { package = "bca-tree-sitter-mozjs", path = "./tree-sitter-mozjs", version = "=1.1.0" }
+tree-sitter-preproc = { package = "bca-tree-sitter-preproc", path = "./tree-sitter-preproc", version = "=1.1.0" }
+tree-sitter-tcl = { package = "bca-tree-sitter-tcl", path = "./tree-sitter-tcl", version = "=1.1.0" }
 
 # PyO3 powers the `big-code-analysis-py` cdylib. Pinned to a major
 # series; bumping is a deliberate, separate change because the Bound

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: big-code-analysis
-Version: 1.0.0
+Version: 1.1.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/README.md

@@ -1,11 +1,11 @@
 # big-code-analysis
 
-[![Crates.io](https://img.shields.io/crates/v/big-code-analysis.svg)](https://crates.io/crates/big-code-analysis)
-[![Task Status](https://community-tc.services.mozilla.com/api/github/v1/repository/dekobon/big-code-analysis/master/badge.svg)](https://community-tc.services.mozilla.com/api/github/v1/repository/dekobon/big-code-analysis/master/latest)
-[![codecov](https://codecov.io/gh/dekobon/big-code-analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/dekobon/big-code-analysis)
-<a href="https://chat.mozilla.org/#/room/#big-code-analysis:mozilla.org" target="_blank">
-   <img alt="Chat on Matrix" src="https://img.shields.io/badge/chat%20on%20[m]-%23rust--code--analysis%3Amozilla.org-blue">
-</a>
+[![crates.io](https://img.shields.io/crates/v/big-code-analysis.svg)](https://crates.io/crates/big-code-analysis)
+[![MSRV](https://img.shields.io/crates/msrv/big-code-analysis.svg)](Cargo.toml)
+[![CI](https://github.com/dekobon/big-code-analysis/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/dekobon/big-code-analysis/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush)
+[![CodeQL](https://github.com/dekobon/big-code-analysis/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/dekobon/big-code-analysis/actions/workflows/codeql.yml?query=branch%3Amain)
+[![docs.rs](https://docs.rs/big-code-analysis/badge.svg)](https://docs.rs/big-code-analysis)
+[![License](https://img.shields.io/crates/l/big-code-analysis.svg)](LICENSE)
 
 **big-code-analysis** is a hard fork of the [rust-code-analysis](https://github.com/mozilla/rust-code-analysis) project.
 This project is an unapologetic vibe-coded fork that seeks to add as many features and functions as fast as possible.
@@ -27,6 +27,21 @@ This tool can be used to:
 
 In addition, we provide a **bca-web** tool to use the library through a REST API.
 
+## Live example reports
+
+`bca` runs against its own source on every push to `main` and publishes
+the result alongside the documentation:
+
+- HTML hotspot report:
+  <https://dekobon.github.io/big-code-analysis/reports/index.html>
+- Markdown PR/MR comment:
+  <https://dekobon.github.io/big-code-analysis/reports/report.md>
+
+The wiring lives in
+[`.github/workflows/pages.yml`](.github/workflows/pages.yml); see the
+book's [CI integration recipe](https://dekobon.github.io/big-code-analysis/recipes/ci.html)
+for adapting it to your own project.
+
 ## Usage
 
 **big-code-analysis** supports many types of programming languages and
@@ -66,7 +81,7 @@ Every tree-sitter grammar is gated behind a per-language Cargo
 feature. The default feature set is `all-languages`, so a bare
 
 ```toml
-big-code-analysis = "1.0.0"
+big-code-analysis = "1.1.0"
 ```
 
 pulls every grammar in (matching the library's historical behaviour
@@ -75,7 +90,7 @@ only need a subset of languages can opt out of the defaults and
 re-enable just the grammars they want:
 
 ```toml
-big-code-analysis = { version = "1.0.0", default-features = false, features = ["rust", "typescript"] }
+big-code-analysis = { version = "1.1.0", default-features = false, features = ["rust", "typescript"] }
 ```
 
 Supported language features: `bash`, `cpp`, `csharp`, `elixir`,

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/big-code-analysis-py/src/sarif.rs

@@ -455,11 +455,16 @@ fn collect_offenders(
 /// `result` accepts:
 /// * a single ``dict`` matching :func:`analyze` / :func:`analyze_source`
 ///   output, or
-/// * any iterable yielding such dicts and/or
-///   :class:`AnalysisError` instances (e.g. the return of
-///   :func:`analyze_batch`). `AnalysisError` entries are skipped
-///   silently — they represent files the pipeline could not analyse,
-///   not findings.
+/// * a scalar ``None`` (the documented return of :func:`analyze` for
+///   generated files); produces a well-formed empty SARIF run, or
+/// * any iterable yielding such dicts, :class:`AnalysisError`
+///   instances, and/or ``None`` (e.g. the return of
+///   :func:`analyze_batch`, or a list comprehension over
+///   :func:`analyze` which returns ``None`` for generated files).
+///   :class:`AnalysisError` and ``None`` entries are skipped silently
+///   — they represent files for which no record was emitted (either
+///   the pipeline could not analyse them, or they were classified as
+///   generated), not findings.
 ///
 /// Pass ``thresholds={"cyclomatic": 15, "loc.lloc": 200, …}`` to drive
 /// finding emission. ``thresholds=None`` (the default) is equivalent
@@ -478,64 +483,107 @@ pub(crate) fn to_sarif(
     result: &Bound<'_, PyAny>,
     thresholds: Option<&Bound<'_, PyDict>>,
 ) -> PyResult<String> {
+    let offenders = collect_offenders_for_input(result, thresholds)?;
+    render(py, &offenders)
+}
+
+fn collect_offenders_for_input(
+    result: &Bound<'_, PyAny>,
+    thresholds: Option<&Bound<'_, PyDict>>,
+) -> PyResult<Vec<OffenderRecord>> {
     let thresholds = resolve_thresholds(thresholds)?;
     let mut offenders: Vec<OffenderRecord> = Vec::new();
+    dispatch_by_input_kind(result, &thresholds, &mut offenders)?;
+    Ok(offenders)
+}
 
+fn dispatch_by_input_kind(
+    result: &Bound<'_, PyAny>,
+    thresholds: &[Threshold],
+    offenders: &mut Vec<OffenderRecord>,
+) -> PyResult<()> {
+    // Scalar `None` — symmetric with the iterable arm's silent-skip
+    // contract below. `analyze()` returns `None` for generated files
+    // (the documented default), so the natural single-call pattern
+    // `bca.to_sarif(bca.analyze(generated_file))` must yield an empty
+    // SARIF run rather than raise `TypeError: 'NoneType' is not
+    // iterable`. Issue #341 closed the list-comprehension form; this
+    // closes the scalar form so both compose with `analyze()`.
+    if result.is_none() {
+        return Ok(());
+    }
     // Single dict — accept as a result without forcing the caller to
     // wrap it in a list.
     if let Ok(dict) = result.clone().cast_into::<PyDict>() {
-        collect_offenders(&dict, &thresholds, &mut offenders)?;
-        return render(py, &offenders);
+        return collect_offenders(&dict, thresholds, offenders);
+    }
+    // Reject Mapping-but-not-dict and `str` early with clear errors —
+    // see [`mapping_or_str_error`] for the rationale on each branch.
+    if let Some(err) = mapping_or_str_error(result) {
+        return Err(err);
     }
+    collect_offenders_from_iter(result, thresholds, offenders)
+}
 
-    // Reject Mapping-but-not-dict (e.g. `types.MappingProxyType`) with
-    // a clear error. Without this branch the value would fall through
-    // to the iterable path, iterate dict keys as strings, and fail the
-    // per-item dict cast with a confusing "got str" — see Phase-3
-    // review.
+/// Return a `TypeError` for the two iterable-shaped inputs that would
+/// otherwise yield confusing per-item failures: `Mapping`s that are
+/// not `dict` (e.g. `types.MappingProxyType`) iterate as keys, and
+/// `str` iterates as one-character substrings. Both fall through the
+/// iterable path to a masked "got str" error from the per-item dict
+/// cast unless caught here.
+fn mapping_or_str_error(result: &Bound<'_, PyAny>) -> Option<PyErr> {
     if result.cast::<PyMapping>().is_ok() {
-        return Err(PyTypeError::new_err(concat!(
+        return Some(PyTypeError::new_err(concat!(
             "to_sarif: result must be a plain dict ",
             "(got a Mapping that is not a dict — pass `dict(mapping)` ",
             "if you need to wrap a MappingProxyType or similar)",
         )));
     }
-
-    // Reject `str` / `bytes` explicitly: they ARE iterable in Python
-    // and would otherwise yield one-character/byte items that fail
-    // the dict downcast with a confusing message.
     if result.is_instance_of::<PyString>() {
-        return Err(PyTypeError::new_err(
+        return Some(PyTypeError::new_err(
             "to_sarif: result must be a dict or an iterable of dicts, not str",
         ));
     }
+    None
+}
 
-    // Iterable path. `try_iter()` errors if the value is not iterable
-    // — let that propagate to the caller as a `TypeError`. Per the
-    // documented contract, `AnalysisError` entries are skipped
-    // silently (they represent files we couldn't analyse); anything
-    // else that isn't a dict is a programmer error.
+fn collect_offenders_from_iter(
+    result: &Bound<'_, PyAny>,
+    thresholds: &[Threshold],
+    offenders: &mut Vec<OffenderRecord>,
+) -> PyResult<()> {
+    // `try_iter()` errors if the value is not iterable — let that
+    // propagate to the caller as a `TypeError`. Per the documented
+    // contract, `AnalysisError` entries are skipped silently (they
+    // represent files we couldn't analyse) and `None` entries are
+    // likewise skipped (the documented return of :func:`analyze` for
+    // generated files — issue #341); anything else that isn't a dict
+    // is a programmer error.
     for item in result.try_iter()? {
         let item = item?;
-        if item.is_instance_of::<PyAnalysisError>() {
+        if item.is_none() || item.is_instance_of::<PyAnalysisError>() {
             continue;
         }
-        let Ok(dict) = item.clone().cast_into::<PyDict>() else {
-            // `get_type().name()` can itself fail on objects with a
-            // broken `__class__` — fall back to a literal placeholder
-            // so the caller still sees a clear "wrong type" error
-            // instead of the masked introspection error.
-            let type_name = item
-                .get_type()
-                .name()
-                .map_or_else(|_| "<unknown type>".to_string(), |n| n.to_string());
-            return Err(PyTypeError::new_err(format!(
-                "to_sarif expected a result dict or AnalysisError, got {type_name}"
-            )));
-        };
-        collect_offenders(&dict, &thresholds, &mut offenders)?;
+        let dict = cast_iter_item_to_dict(&item)?;
+        collect_offenders(&dict, thresholds, offenders)?;
     }
-    render(py, &offenders)
+    Ok(())
+}
+
+fn cast_iter_item_to_dict<'py>(item: &Bound<'py, PyAny>) -> PyResult<Bound<'py, PyDict>> {
+    item.clone().cast_into::<PyDict>().map_err(|_| {
+        // `get_type().name()` can itself fail on objects with a broken
+        // `__class__` — fall back to a literal placeholder so the
+        // caller still sees a clear "wrong type" error instead of the
+        // masked introspection error.
+        let type_name = item
+            .get_type()
+            .name()
+            .map_or_else(|_| "<unknown type>".to_string(), |n| n.to_string());
+        PyTypeError::new_err(format!(
+            "to_sarif expected a result dict, AnalysisError, or None, got {type_name}"
+        ))
+    })
 }
 
 fn render(py: Python<'_>, offenders: &[OffenderRecord]) -> PyResult<String> {

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/big-code-analysis-py/tests/test_sarif.py

@@ -298,6 +298,69 @@ def test_to_sarif_does_not_raise_on_pure_analysis_error_input(
     assert parsed["runs"][0]["results"] == []
 
 
+def test_to_sarif_filters_none_entries_silently(tmp_path: Path) -> None:
+    """``None`` entries in an iterable must be skipped, not raised
+    (issue #341).
+
+    ``analyze()`` documents that it returns ``None`` for files
+    classified as generated, so the natural pattern
+    ``bca.to_sarif([bca.analyze(p) for p in paths])`` MUST tolerate
+    ``None`` siblings alongside successful dicts. The skip mirrors
+    the ``AnalysisError`` contract — both represent "no record
+    emitted for this file".
+
+    Uses ``cyclomatic=0`` so the ok.py finding is positively
+    asserted alongside the silent-skip behaviour, mirroring
+    ``test_to_sarif_filters_analysis_errors_silently``: a regression
+    that dropped successful dicts together with ``None`` would emit
+    zero findings and slip past a bare "no errors raised" check.
+    """
+    ok = tmp_path / "ok.py"
+    ok.write_text("def f(x):\n    return x + 1\n")
+    good = bca.analyze(ok)
+    assert isinstance(good, dict), "fixture must produce an analysed dict"
+
+    parsed = _parse(bca.to_sarif([good, None], thresholds={"cyclomatic": 0}))
+    findings = parsed["runs"][0]["results"]
+    assert len(findings) == 1, (
+        f"expected one finding from ok.py (None skipped, dict kept), got {findings!r}"
+    )
+    assert findings[0]["ruleId"] == "cyclomatic"
+    assert findings[0]["locations"][0]["physicalLocation"]["artifactLocation"][
+        "uri"
+    ] == _expected_sarif_uri(ok)
+
+
+def test_to_sarif_does_not_raise_on_pure_none_input() -> None:
+    """An iterable containing **only** ``None`` still yields a
+    well-formed empty SARIF run (issue #341 — generated-file lists
+    that happen to be entirely generated)."""
+    parsed = _parse(bca.to_sarif([None, None], thresholds={"cyclomatic": 1}))
+    assert parsed["runs"][0]["results"] == []
+
+
+def test_to_sarif_accepts_scalar_none() -> None:
+    """A scalar ``None`` (the documented return of :func:`analyze`
+    for a single generated file) must produce a well-formed empty
+    SARIF run, mirroring the iterable arm's silent-skip contract.
+
+    Without this, the natural per-file pattern
+    ``bca.to_sarif(bca.analyze(generated_file))`` raised
+    ``TypeError: 'NoneType' is not iterable`` — asymmetric with the
+    list-comprehension form ``bca.to_sarif([bca.analyze(p) for p in
+    paths])`` that the #341 fix already accepted. Closes the
+    follow-up gap surfaced by code review on branch
+    fix/batch-2026-05-25.
+    """
+    parsed = _parse(bca.to_sarif(None, thresholds={"cyclomatic": 1}))
+    assert parsed["runs"][0]["results"] == []
+    # The empty run is still SARIF-shaped — tool driver and schema
+    # URL must be present so SARIF consumers don't trip on missing
+    # metadata.
+    assert parsed["runs"][0]["tool"]["driver"]["name"]
+    assert parsed["$schema"]
+
+
 # ─────────────────────────────────────────────────────────────────
 # Input validation
 # ─────────────────────────────────────────────────────────────────

{big_code_analysis-1.0.0 → big_code_analysis-1.1.0}/python/big_code_analysis/_native.pyi

@@ -409,7 +409,7 @@ def language_extensions(language: str, /) -> list[str]:
     """
 
 def to_sarif(
-    result: dict[str, Any] | Iterable[dict[str, Any] | AnalysisError],
+    result: dict[str, Any] | None | Iterable[dict[str, Any] | AnalysisError | None],
     /,
     *,
     thresholds: dict[str, float] | None = None,
@@ -417,11 +417,16 @@ def to_sarif(
     """Render a SARIF 2.1.0 JSON document from analysis results.
 
     ``result`` accepts either a single ``dict`` returned by
-    :func:`analyze` / :func:`analyze_source`, or any iterable
-    yielding such dicts and/or :class:`AnalysisError` instances
-    (the natural shape of :func:`analyze_batch`'s return value).
-    ``AnalysisError`` entries are skipped silently — they represent
-    files that could not be analysed, not findings.
+    :func:`analyze` / :func:`analyze_source`, a scalar ``None`` (the
+    documented return of :func:`analyze` for generated files; yields
+    an empty SARIF run), or any iterable yielding such dicts,
+    :class:`AnalysisError` instances, and/or ``None`` (the natural
+    shape of :func:`analyze_batch`'s return value, or a list
+    comprehension over :func:`analyze` which returns ``None`` for
+    generated files). ``AnalysisError`` and ``None`` entries are
+    skipped silently — they represent files for which no record was
+    emitted (either the pipeline could not analyse them, or they
+    were classified as generated), not findings.
 
     Pass ``thresholds={"cyclomatic": 15, "loc.lloc": 200, …}`` to
     drive finding emission. ``thresholds=None`` (the default) is