typedframes 0.5.0__tar.gz → 0.6.0__tar.gz

{typedframes-0.5.0 → typedframes-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typedframes
-Version: 0.5.0
+Version: 0.6.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -66,7 +66,10 @@ typedframes check src/ --coverage-fail-under=90
 ```
 
 `--coverage-fail-under=N` is the same idea as a test-coverage or mypy type-coverage gate, applied to how many DataFrames
-the checker can resolve columns for — see [DataFrame Schema Coverage Thresholds](#dataframe-schema-coverage-thresholds-opt-in).
+the checker can resolve to a concrete column list — a DataFrame it merely recognizes but can't resolve columns for
+(a Feast retrieval whose entity_df isn't itself concrete, a bare `-> pd.DataFrame` return with no attached Schema)
+does not count, and any column accessed on it is flagged `unverifiable-column` rather than passed through silently.
+See [DataFrame Schema Coverage Thresholds](#dataframe-schema-coverage-thresholds-opt-in).
 Add `BaseSchema` classes later for cross-file awareness and IDE autocomplete — see [Quick Start](#quick-start).
 
 ---
@@ -78,6 +81,7 @@ Add `BaseSchema` classes later for cross-file awareness and IDE autocomplete —
 - [Quick Start](#quick-start)
 - [Column Inference](#column-inference)
 - [Static Analysis](#static-analysis)
+- [Jupyter Notebooks](#jupyter-notebooks)
 - [DataFrame Schema Coverage Thresholds](#dataframe-schema-coverage-thresholds-opt-in)
 - [Static Analysis Performance](#static-analysis-performance)
 - [Type Safety With Multiple Backends](#type-safety-with-multiple-backends)
@@ -428,7 +432,10 @@ typedframes check src/ --strict
 # JSON output
 typedframes check src/ --output-format=json
 
-# Skip cross-file index (single-file mode, faster for quick checks)
+# Check a single file (follows that file's own imports, not the whole project)
+typedframes check src/pipeline.py
+
+# Skip the cross-file index entirely (every file in isolation, fastest)
 typedframes check src/ --no-index
 
 # Suppress all warnings (untracked-dataframe, dropped-unknown-column)
@@ -486,6 +493,135 @@ See the full [Method Matrix](https://typedframes.readthedocs.io/en/latest/method
 for the complete list of tracked, passthrough, and untracked operations, plus the error
 code reference.
 
+### Pre-commit Hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: typedframes
+        name: typedframes check
+        entry: typedframes check . --strict
+        language: python
+        additional_dependencies: ["typedframes==0.5.0"]
+        types_or: [python, jupyter]
+        pass_filenames: false
+```
+
+`pass_filenames: false` is deliberate: the checker takes a single path and builds its
+cross-file index from it, so one run per commit still sees the modules the commit didn't
+touch — a per-file invocation would lose that. `--strict` is what makes the hook block
+the commit: `typedframes check` exits 0 by default even when it finds real errors. Add
+the coverage gate to the same line:
+
+```yaml
+        # with coverage gating
+        entry: typedframes check . --strict --coverage-fail-under=90
+```
+
+This repository also ships a `.pre-commit-hooks.yaml`, so once a tagged release contains
+it you can point `repo:` straight at `https://github.com/w-martin/typedframes` with a
+`rev:` and drop the boilerplate above. That form needs a Rust toolchain wherever the hook
+runs — pre-commit's python installer builds the repository from source rather than
+fetching a wheel — so the local hook stays the quicker one to install either way.
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/typedframes.yml
+name: typedframes
+on: [push, pull_request]
+
+jobs:
+  typedframes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # No tagged release contains action.yml yet. Repin this to that tag once one
+      # ships: an unpinned third-party action is a supply-chain risk, and @main is a
+      # stopgap rather than a recommendation.
+      - uses: w-martin/typedframes@main
+        with:
+          path: src/
+          coverage-fail-under: "90"
+```
+
+The action installs the PyPI wheel into a throwaway virtualenv and runs the checker with
+`--output-format=github`, so errors arrive as annotations on the pull request diff.
+
+| Input | Default | |
+|-------|---------|-|
+| `path` | `.` | File or directory to check |
+| `version` | `latest` | PyPI version to install, e.g. `"0.5.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 |
+| `no-warnings` | `false` | Suppress warning-level diagnostics |
+| `args` | *(empty)* | Escape hatch for `--no-index`, `--lenient-ingest`, `--no-info` |
+
+---
+
+## Jupyter Notebooks
+
+The standalone checker reads `.ipynb` files directly — no `nbconvert`, no `jupytext`, no
+flag, no conversion step. Notebooks are parsed with
+[`ruff_notebook`](https://github.com/astral-sh/ruff/tree/main/crates/ruff_notebook), the
+same crate Ruff uses for its own notebook support:
+
+```shell
+# Check one notebook
+typedframes check analysis.ipynb
+
+# Check a directory — .py and .ipynb files are both picked up, no flag needed
+typedframes check notebooks/
+
+# Output — `cell N` is the notebook's Nth cell; line:col are relative to that cell:
+# analysis.ipynb:cell 6:2:1: warning[untracked-dataframe] columns unknown at lint time; specify
+#   `usecols`/`columns`, or annotate the variable's type
+# analysis.ipynb:cell 10:1:1: error[unknown-column] Column 'revenue' does not exist in Orders
+#   {amount, customer_id, order_id} (defined at analysis.ipynb cell 2:8)
+# ✗ Found 1 error, 2 warnings in 1 file (0.0s)
+```
+
+**Features:**
+- ✅ Auto-detected — every `.ipynb` under a checked path, alongside `.py` files
+- ✅ Diagnostics reported as `cell N:line:col`, mapped back to the cell that produced them
+  rather than a line number in the raw notebook JSON — including a same-notebook schema's
+  `(defined at ...)` cross-reference
+- ✅ Same error codes, severities, and flags as `.py` files: `--strict`,
+  `--output-format`, `--no-warnings`, `--lenient-ingest`, coverage thresholds
+- ✅ IPython magics and shell escapes parse natively (`%matplotlib inline`, `%%time`,
+  `!pip install ...`) — nothing has to be stripped first
+- ✅ `# typedframes: ignore` suppresses a diagnostic on a line inside a cell, same as in a
+  `.py` file
+- ✅ A schema imported from a project `.py` module resolves through the cross-file index,
+  so `orders = load_orders()` in a notebook is validated against the schema on
+  `load_orders`' return annotation
+- ✅ `.ipynb_checkpoints/` is pruned by default, so stale checkpoint copies aren't
+  re-reported
+
+**Caveats:**
+- ❌ The mypy plugin ([Option 2](#option-2-mypy-plugin-comprehensive)) is `.py`-only —
+  mypy reads Python source files, so notebook checking is standalone-checker-only
+- ❌ `cell N` counts *every* cell in the notebook, markdown and raw cells included — so
+  the number is a cell's position in the notebook, not "the Nth code cell"
+- ❌ A notebook is never a *source* of schemas for other files (Python can't import an
+  `.ipynb`); a schema defined in a notebook is visible only inside that notebook
+- ❌ A notebook that isn't valid notebook JSON, whose kernel isn't Python, or whose code
+  doesn't parse is skipped with a message on stderr and the run continues — a skip alone
+  never fails the run, `--strict` included
+- ❌ Under `--output-format=github`, the annotation's `line`/`col` stay cell-relative and
+  the cell number moves into the annotation title, since GitHub annotations address raw
+  file lines and an `.ipynb` is JSON rather than source text
+
+### See Also
+
+- [`examples/features/ipynb_example.ipynb`](examples/features/ipynb_example.ipynb) — a
+  runnable notebook with one schema, an IPython magic, and three intentional bugs
+  (`untracked-dataframe`, `dropped-unknown-column`, `unknown-column`), all caught by
+  `typedframes check ipynb_example.ipynb` without running a cell.
+
 ---
 
 ## DataFrame Schema Coverage Thresholds (Opt-In)
@@ -516,6 +652,16 @@ breakdown of exactly which DataFrames cost you coverage (as text or, combined wi
 the
 [DataFrame schema coverage thresholds guide](docs/usage.md#dataframe-schema-coverage-thresholds).
 
+Some DataFrames are recognized but never resolve to a concrete column list — a Feast
+retrieval whose `entity_df` isn't itself concretely typed, or a bare `-> pd.DataFrame`
+return with no attached `Schema`. These do **not** count as covered, and accessing any
+column on one is flagged `unverifiable-column` rather than passed through silently —
+the checker genuinely doesn't know whether the column exists, so it says so instead of
+guessing either way. A Feast retrieval whose `entity_df` argument IS a concretely typed
+DataFrame is fully resolved instead: Feast's real output is `entity_df`'s own columns
+plus the requested features, so both halves get checked normally. See
+[Unresolved schemas](docs/usage.md#unresolved-schemas-recognized-but-not-column-checked).
+
 ## Static Analysis Performance
 
 Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
@@ -537,9 +683,11 @@ Fast feedback reduces development time. The typedframes Rust binary provides nea
 
 The typedframes binary resolves column names within a file and, when a project index is present, across files too.
 Run `typedframes check src/` to build the index automatically and catch errors like `df = load_users(); df["typo"]`
-even when `load_users` is defined in another module. Pass `--no-index` to skip the index and check each file in
-isolation. Full type checkers (mypy, pyright, ty) analyze all Python types across your entire codebase. Use both: the
-binary for fast iteration, mypy for comprehensive checking.
+even when `load_users` is defined in another module. Checking a single file
+(`typedframes check src/pipeline.py`) builds a smaller index from that file's own imports instead of walking the whole
+project, so it still resolves `load_users` without paying for files it never references. Pass `--no-index` to skip the
+index entirely and check each file in isolation. Full type checkers (mypy, pyright, ty) analyze all Python types across
+your entire codebase. Use both: the binary for fast iteration, mypy for comprehensive checking.
 
 The standalone checker is built with [`ruff_python_parser`](https://github.com/astral-sh/ruff) for Python AST
 parsing.
@@ -915,6 +1063,9 @@ Runnable versions of everything shown in [Quick Start](#quick-start) and
   [`multi_file_with_schema/`](examples/features/multi_file_with_schema/) — the same
   cross-file pipeline checked with and without schemas, see
   [`examples/features/README.md`](examples/features/README.md) for what each one catches
+- [`ipynb_example.ipynb`](examples/features/ipynb_example.ipynb) — the same checks in a
+  Jupyter notebook, with `cell N:line:col` locations (see [Jupyter
+  Notebooks](#jupyter-notebooks))
 
 ---
 

{typedframes-0.5.0 → typedframes-0.6.0}/README.md

@@ -32,7 +32,10 @@ typedframes check src/ --coverage-fail-under=90
 ```
 
 `--coverage-fail-under=N` is the same idea as a test-coverage or mypy type-coverage gate, applied to how many DataFrames
-the checker can resolve columns for — see [DataFrame Schema Coverage Thresholds](#dataframe-schema-coverage-thresholds-opt-in).
+the checker can resolve to a concrete column list — a DataFrame it merely recognizes but can't resolve columns for
+(a Feast retrieval whose entity_df isn't itself concrete, a bare `-> pd.DataFrame` return with no attached Schema)
+does not count, and any column accessed on it is flagged `unverifiable-column` rather than passed through silently.
+See [DataFrame Schema Coverage Thresholds](#dataframe-schema-coverage-thresholds-opt-in).
 Add `BaseSchema` classes later for cross-file awareness and IDE autocomplete — see [Quick Start](#quick-start).
 
 ---
@@ -44,6 +47,7 @@ Add `BaseSchema` classes later for cross-file awareness and IDE autocomplete —
 - [Quick Start](#quick-start)
 - [Column Inference](#column-inference)
 - [Static Analysis](#static-analysis)
+- [Jupyter Notebooks](#jupyter-notebooks)
 - [DataFrame Schema Coverage Thresholds](#dataframe-schema-coverage-thresholds-opt-in)
 - [Static Analysis Performance](#static-analysis-performance)
 - [Type Safety With Multiple Backends](#type-safety-with-multiple-backends)
@@ -394,7 +398,10 @@ typedframes check src/ --strict
 # JSON output
 typedframes check src/ --output-format=json
 
-# Skip cross-file index (single-file mode, faster for quick checks)
+# Check a single file (follows that file's own imports, not the whole project)
+typedframes check src/pipeline.py
+
+# Skip the cross-file index entirely (every file in isolation, fastest)
 typedframes check src/ --no-index
 
 # Suppress all warnings (untracked-dataframe, dropped-unknown-column)
@@ -452,6 +459,135 @@ See the full [Method Matrix](https://typedframes.readthedocs.io/en/latest/method
 for the complete list of tracked, passthrough, and untracked operations, plus the error
 code reference.
 
+### Pre-commit Hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: typedframes
+        name: typedframes check
+        entry: typedframes check . --strict
+        language: python
+        additional_dependencies: ["typedframes==0.5.0"]
+        types_or: [python, jupyter]
+        pass_filenames: false
+```
+
+`pass_filenames: false` is deliberate: the checker takes a single path and builds its
+cross-file index from it, so one run per commit still sees the modules the commit didn't
+touch — a per-file invocation would lose that. `--strict` is what makes the hook block
+the commit: `typedframes check` exits 0 by default even when it finds real errors. Add
+the coverage gate to the same line:
+
+```yaml
+        # with coverage gating
+        entry: typedframes check . --strict --coverage-fail-under=90
+```
+
+This repository also ships a `.pre-commit-hooks.yaml`, so once a tagged release contains
+it you can point `repo:` straight at `https://github.com/w-martin/typedframes` with a
+`rev:` and drop the boilerplate above. That form needs a Rust toolchain wherever the hook
+runs — pre-commit's python installer builds the repository from source rather than
+fetching a wheel — so the local hook stays the quicker one to install either way.
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/typedframes.yml
+name: typedframes
+on: [push, pull_request]
+
+jobs:
+  typedframes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # No tagged release contains action.yml yet. Repin this to that tag once one
+      # ships: an unpinned third-party action is a supply-chain risk, and @main is a
+      # stopgap rather than a recommendation.
+      - uses: w-martin/typedframes@main
+        with:
+          path: src/
+          coverage-fail-under: "90"
+```
+
+The action installs the PyPI wheel into a throwaway virtualenv and runs the checker with
+`--output-format=github`, so errors arrive as annotations on the pull request diff.
+
+| Input | Default | |
+|-------|---------|-|
+| `path` | `.` | File or directory to check |
+| `version` | `latest` | PyPI version to install, e.g. `"0.5.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 |
+| `no-warnings` | `false` | Suppress warning-level diagnostics |
+| `args` | *(empty)* | Escape hatch for `--no-index`, `--lenient-ingest`, `--no-info` |
+
+---
+
+## Jupyter Notebooks
+
+The standalone checker reads `.ipynb` files directly — no `nbconvert`, no `jupytext`, no
+flag, no conversion step. Notebooks are parsed with
+[`ruff_notebook`](https://github.com/astral-sh/ruff/tree/main/crates/ruff_notebook), the
+same crate Ruff uses for its own notebook support:
+
+```shell
+# Check one notebook
+typedframes check analysis.ipynb
+
+# Check a directory — .py and .ipynb files are both picked up, no flag needed
+typedframes check notebooks/
+
+# Output — `cell N` is the notebook's Nth cell; line:col are relative to that cell:
+# analysis.ipynb:cell 6:2:1: warning[untracked-dataframe] columns unknown at lint time; specify
+#   `usecols`/`columns`, or annotate the variable's type
+# analysis.ipynb:cell 10:1:1: error[unknown-column] Column 'revenue' does not exist in Orders
+#   {amount, customer_id, order_id} (defined at analysis.ipynb cell 2:8)
+# ✗ Found 1 error, 2 warnings in 1 file (0.0s)
+```
+
+**Features:**
+- ✅ Auto-detected — every `.ipynb` under a checked path, alongside `.py` files
+- ✅ Diagnostics reported as `cell N:line:col`, mapped back to the cell that produced them
+  rather than a line number in the raw notebook JSON — including a same-notebook schema's
+  `(defined at ...)` cross-reference
+- ✅ Same error codes, severities, and flags as `.py` files: `--strict`,
+  `--output-format`, `--no-warnings`, `--lenient-ingest`, coverage thresholds
+- ✅ IPython magics and shell escapes parse natively (`%matplotlib inline`, `%%time`,
+  `!pip install ...`) — nothing has to be stripped first
+- ✅ `# typedframes: ignore` suppresses a diagnostic on a line inside a cell, same as in a
+  `.py` file
+- ✅ A schema imported from a project `.py` module resolves through the cross-file index,
+  so `orders = load_orders()` in a notebook is validated against the schema on
+  `load_orders`' return annotation
+- ✅ `.ipynb_checkpoints/` is pruned by default, so stale checkpoint copies aren't
+  re-reported
+
+**Caveats:**
+- ❌ The mypy plugin ([Option 2](#option-2-mypy-plugin-comprehensive)) is `.py`-only —
+  mypy reads Python source files, so notebook checking is standalone-checker-only
+- ❌ `cell N` counts *every* cell in the notebook, markdown and raw cells included — so
+  the number is a cell's position in the notebook, not "the Nth code cell"
+- ❌ A notebook is never a *source* of schemas for other files (Python can't import an
+  `.ipynb`); a schema defined in a notebook is visible only inside that notebook
+- ❌ A notebook that isn't valid notebook JSON, whose kernel isn't Python, or whose code
+  doesn't parse is skipped with a message on stderr and the run continues — a skip alone
+  never fails the run, `--strict` included
+- ❌ Under `--output-format=github`, the annotation's `line`/`col` stay cell-relative and
+  the cell number moves into the annotation title, since GitHub annotations address raw
+  file lines and an `.ipynb` is JSON rather than source text
+
+### See Also
+
+- [`examples/features/ipynb_example.ipynb`](examples/features/ipynb_example.ipynb) — a
+  runnable notebook with one schema, an IPython magic, and three intentional bugs
+  (`untracked-dataframe`, `dropped-unknown-column`, `unknown-column`), all caught by
+  `typedframes check ipynb_example.ipynb` without running a cell.
+
 ---
 
 ## DataFrame Schema Coverage Thresholds (Opt-In)
@@ -482,6 +618,16 @@ breakdown of exactly which DataFrames cost you coverage (as text or, combined wi
 the
 [DataFrame schema coverage thresholds guide](docs/usage.md#dataframe-schema-coverage-thresholds).
 
+Some DataFrames are recognized but never resolve to a concrete column list — a Feast
+retrieval whose `entity_df` isn't itself concretely typed, or a bare `-> pd.DataFrame`
+return with no attached `Schema`. These do **not** count as covered, and accessing any
+column on one is flagged `unverifiable-column` rather than passed through silently —
+the checker genuinely doesn't know whether the column exists, so it says so instead of
+guessing either way. A Feast retrieval whose `entity_df` argument IS a concretely typed
+DataFrame is fully resolved instead: Feast's real output is `entity_df`'s own columns
+plus the requested features, so both halves get checked normally. See
+[Unresolved schemas](docs/usage.md#unresolved-schemas-recognized-but-not-column-checked).
+
 ## Static Analysis Performance
 
 Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
@@ -503,9 +649,11 @@ Fast feedback reduces development time. The typedframes Rust binary provides nea
 
 The typedframes binary resolves column names within a file and, when a project index is present, across files too.
 Run `typedframes check src/` to build the index automatically and catch errors like `df = load_users(); df["typo"]`
-even when `load_users` is defined in another module. Pass `--no-index` to skip the index and check each file in
-isolation. Full type checkers (mypy, pyright, ty) analyze all Python types across your entire codebase. Use both: the
-binary for fast iteration, mypy for comprehensive checking.
+even when `load_users` is defined in another module. Checking a single file
+(`typedframes check src/pipeline.py`) builds a smaller index from that file's own imports instead of walking the whole
+project, so it still resolves `load_users` without paying for files it never references. Pass `--no-index` to skip the
+index entirely and check each file in isolation. Full type checkers (mypy, pyright, ty) analyze all Python types across
+your entire codebase. Use both: the binary for fast iteration, mypy for comprehensive checking.
 
 The standalone checker is built with [`ruff_python_parser`](https://github.com/astral-sh/ruff) for Python AST
 parsing.
@@ -881,6 +1029,9 @@ Runnable versions of everything shown in [Quick Start](#quick-start) and
   [`multi_file_with_schema/`](examples/features/multi_file_with_schema/) — the same
   cross-file pipeline checked with and without schemas, see
   [`examples/features/README.md`](examples/features/README.md) for what each one catches
+- [`ipynb_example.ipynb`](examples/features/ipynb_example.ipynb) — the same checks in a
+  Jupyter notebook, with `cell N:line:col` locations (see [Jupyter
+  Notebooks](#jupyter-notebooks))
 
 ---
 

{typedframes-0.5.0 → typedframes-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "typedframes"
-version = "0.5.0"
+version = "0.6.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"
@@ -135,7 +135,6 @@ dev = [
     "complexipy>=6.2.0",
     "coverage-threshold>=0.6.2",
     "invoke>=3.0.3",
-    "licensecheck>=2025.1.0",
     "maturin>=1.14.1",
     "pre-commit>=4.6.1",
     "pyrefly>=1.2.0",
@@ -151,11 +150,15 @@ dev = [
     "fastexcel>=0.20.2",
     "pandas-stubs>=3.0.5.260730",
     "mypy>=2.3.1",
+    "trustedlicenses>=0.1.1",
 ]
 
 [tool.bandit]
 exclude_dirs = ["tests", "examples"]
 
+[tool.trustedlicenses]
+allowed-categories = ["Permissive", "Public Domain", "Copyleft Limited"]
+
 [tool.coverage.report]
 exclude_lines = [
     "pragma: no cover",
@@ -237,10 +240,5 @@ invalid-return-type = "ignore"
 enabled = true
 warnings = true
 
-[tool.licensecheck]
-using = "PEP631"
-groups = ["dev"]
-ignore_packages = ["mypy-extensions", "typedframes", "pyrefly"]
-
 [tool.uv.workspace]
 exclude = ["examples/*/*"]

{typedframes-0.5.0 → typedframes-0.6.0}/rust/Cargo.lock

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

{typedframes-0.5.0 → typedframes-0.6.0}/rust/Cargo.toml

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

{typedframes-0.5.0 → typedframes-0.6.0}/rust/src/ast_extract.rs

@@ -265,10 +265,9 @@ pub(crate) fn extract_schema_from_annotation(expr: &Expr) -> Option<&str> {
 // `extract_schema_from_annotation` first; this is the fallback for the shape that
 // leaves with no schema name to extract, which is what most third-party return
 // annotations look like (a `py.typed` package has no reason to know about this
-// project's `Schema` classes). The caller registers a match with an *open* schema
-// (empty column list, `open_schemas`) the same way `register_feast_dataframe` already
-// does -- "we know it's a DataFrame, we don't know its columns" is strictly better
-// than leaving the call untracked, and never manufactures a false unknown-column.
+// project's `Schema` classes). The caller registers this as an unresolved schema
+// (empty column list, `unresolved_schemas`) -- recognized as a DataFrame rather
+// than untracked, with every column access raising `unverifiable-column`.
 //
 // Deliberately narrower than `extract_schema_from_annotation`: no quoted
 // (forward-referenced) form, since a bare `pd.DataFrame`/`pl.DataFrame` return never

{typedframes-0.5.0 → typedframes-0.6.0}/rust/src/config.rs

@@ -99,23 +99,49 @@ pub fn is_enabled(project_root: &Path) -> bool {
 
 /// Walk up the directory tree from `start_path` until a `pyproject.toml` is found.
 ///
-/// Returns the directory containing `pyproject.toml`, or `start_path` itself if no
-/// `pyproject.toml` exists anywhere in the ancestor chain (e.g. standalone scripts).
-pub fn find_project_root(start_path: &Path) -> PathBuf {
+/// Returns `None` when no `pyproject.toml` exists anywhere in the ancestor chain --
+/// i.e. there is no project root to speak of (a standalone script in a scratch
+/// directory, a file under `/tmp`, ...). Callers that need a best-effort directory
+/// regardless should use [`find_project_root`], which substitutes `start_path`.
+///
+/// `pyproject.toml` is the ONE project-root marker this checker recognises, and it is
+/// deliberately the same marker used everywhere else: `load_linter_config` reads
+/// `[tool.typedframes]` out of it, and `find_site_packages_dir` looks for `.venv`
+/// beside it. Single-file and directory checks must agree on where the root is, or the
+/// same file would resolve its imports differently depending on how it was checked.
+pub fn find_project_root_opt(start_path: &Path) -> Option<PathBuf> {
     let mut current = start_path.to_path_buf();
     if current.is_file() {
         current.pop();
     }
     loop {
         if current.join("pyproject.toml").exists() {
-            return current;
+            // `current.pop()` can walk `current` all the way down to the empty
+            // `PathBuf` (when `start_path` was relative and its project root is the
+            // CWD itself). The empty PathBuf is a valid *join* target (joining onto
+            // it is a no-op) but `fs::canonicalize("")` errors -- unlike
+            // `fs::canonicalize(".")`, which resolves to the CWD -- so normalize here
+            // to keep that invariant for every caller that canonicalizes the root.
+            return Some(if current.as_os_str().is_empty() {
+                PathBuf::from(".")
+            } else {
+                current
+            });
         }
         if !current.pop() {
-            return start_path.to_path_buf();
+            return None;
         }
     }
 }
 
+/// Walk up the directory tree from `start_path` until a `pyproject.toml` is found.
+///
+/// Returns the directory containing `pyproject.toml`, or `start_path` itself if no
+/// `pyproject.toml` exists anywhere in the ancestor chain (e.g. standalone scripts).
+pub fn find_project_root(start_path: &Path) -> PathBuf {
+    find_project_root_opt(start_path).unwrap_or_else(|| start_path.to_path_buf())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -132,6 +158,30 @@ mod tests {
         assert_eq!(find_project_root(root), root);
     }
 
+    #[test]
+    fn test_find_project_root_opt_reports_when_there_is_no_root_at_all() {
+        // arrange: a directory tree with no pyproject.toml anywhere above it. The
+        // best-effort `find_project_root` still has to return *something*, which is
+        // exactly why the Option-returning variant exists -- a caller that needs to
+        // skip gracefully (single-file indexing) can't tell "root found" from "gave
+        // up and handed back the start path" through the infallible one.
+        let temp = tempfile::tempdir().unwrap();
+        let sub = temp.path().join("a/b/c");
+        fs::create_dir_all(&sub).unwrap();
+
+        // act / assert -- no pyproject.toml exists in the tempdir, but a real one may
+        // well exist further up (e.g. checked-out under a repo), so only assert the
+        // agreement between the two functions rather than an absolute None.
+        match find_project_root_opt(&sub) {
+            Some(found) => assert_eq!(find_project_root(&sub), found),
+            None => assert_eq!(find_project_root(&sub), sub),
+        }
+
+        // A root that genuinely exists is reported as Some(that root).
+        fs::write(temp.path().join("pyproject.toml"), "").unwrap();
+        assert_eq!(find_project_root_opt(&sub), Some(temp.path().to_path_buf()));
+    }
+
     #[test]
     fn test_is_enabled() {
         let temp = tempfile::tempdir().unwrap();

{typedframes-0.5.0 → typedframes-0.6.0}/rust/src/errors.rs

@@ -16,6 +16,12 @@ pub(crate) const CODE_RESERVED_NAME: &str = "reserved-name";
 pub(crate) const CODE_UNTRACKED_DATAFRAME: &str = "untracked-dataframe";
 pub(crate) const CODE_DROPPED_UNKNOWN_COLUMN: &str = "dropped-unknown-column";
 pub(crate) const CODE_MISSING_COLUMN: &str = "missing-column";
+// A recognized DataFrame with no resolvable column list (unresolved entity_df in
+// a Feast retrieval, a bare `-> pd.DataFrame` return with no attached Schema).
+// Unlike CODE_UNKNOWN_COLUMN, there's no schema to check against, so access is
+// unverifiable rather than definitely wrong. Raised at every access site, since
+// the unresolved state propagates through returns, reassignment, and merge/concat.
+pub(crate) const CODE_UNVERIFIABLE_COLUMN: &str = "unverifiable-column";
 
 // Return true if the source line at `line` (1-indexed) carries a
 // `# typedframes: ignore` or `# typedframes: ignore[code]` comment.
@@ -48,6 +54,10 @@ pub(crate) fn is_line_ignored(source: &str, line: usize, code: &str) -> bool {
 /// known column set (`dataframes_typed`). This is informational — a low ratio
 /// means the check had little to validate, not that the file has fewer
 /// problems. See [`crate::linter::Linter`] for exactly what is counted.
+///
+/// An origin with no resolvable column list (see `CODE_UNVERIFIABLE_COLUMN`) does
+/// NOT count toward `dataframes_typed` — it falls into `untyped_sites` like any
+/// other unresolved DataFrame.
 #[derive(Debug, Serialize, Default)]
 pub struct FileStats {
     pub dataframes_total: usize,