atif-sql · Dead code
Section titled “atif-sql · Dead code”Measured 2026-08-28.
Nothing in this workspace is deletable code. Of 314 public top-level
definitions across the 100 files under packages/*/src, 34 have no reference
outside their own file, and zero have no reference anywhere. Every one of the
34 resolves to a call, construction, or annotation site inside its own module.
What the two tables below record is a narrower defect: an export declaration
with no consumer — a name in an __all__ that nothing imports.
Technique, and what it cannot see. No code index covers this repo (there is no .codegraph/, no LSP index, no AST
symbol graph), and no dead-code analyzer is wired into the project: grep -n "vulture|dead|unused|deptry|knip" over pyproject.toml and mise.toml returns
one unrelated hit, ty’s unused-ignore-comment at pyproject.toml:383. The
finding set is therefore derived, in three passes:
- AST enumeration.
ast.parseevery file underpackages/*/src/**/*.py, collecting every top-levelFunctionDef/AsyncFunctionDef/ClassDef/ module-level assignment whose name does not begin with_, together with its__all__membership. 314 definitions across 100 files; 56 of the 100 modules declare an__all__. - Unanchored reference index. For each name, the whole-word pattern
(?<![\w.])NAME(?![\w])against every line of every git-tracked text file —git ls-files -zyields 224 paths, all 224 readable as text — excluding the defining file. Driving the search fromgit ls-filesis what guarantees that no citation here lands in a gitignored path and that.md,.toml, and.ymlsurfaces are searched, not only Python. - Read-back at the use site. Every candidate opened and its intra-file reference read, and every claimed absence re-checked against the specific import form a consumer would have to write.
vulture 2.16 was run as a cross-check (uvx vulture packages --min-confidence 80, exit 3, 19 findings) and contributes no rows: 17 are
pytest fixture parameters requested for their side effect, one is a boto3
keyword-only parameter on a signature-matching stub, and one is the
@classmethod receiver of a pydantic @field_validator. Its unit of analysis is
one file, so it cannot answer the cross-module question.
Four limits of this derivation, stated because no index backs it:
- Name resolution is not namespace-qualified. A bare name match
cross-attributes symbols that share a name across packages, and this repo has
such collisions on purpose:
DomainErroris declared independently in atif-models, atif-converter, and atif-embed, andEmbeddingProviderMismatchin two. The direction of that error is conservative — it inflates reference counts, so it can hide a dead symbol but cannot invent one. - A textual match is not a semantic reference. Every reference that keeps a symbol off these tables was read at its site rather than counted.
- Import position is irrelevant to the method, deliberately. Because
PLC0415is off (pyproject.toml:164) to satisfy the lean-import assertion atpackages/atif-cli/tests/test_lean_import.py:17-32, atif-cli’s cross-package imports sit inside command bodies —packages/atif-cli/src/atif_cli/app.py:201,packages/atif-cli/src/atif_cli/app.py:253, andpackages/atif-cli/src/atif_cli/app.py:615are all indented. The import graph usesast.walk, which descends into function bodies, and the reference regex is unanchored, so a deferred import counts as an inbound edge. - Dynamic dispatch was swept by hand. No first-party module is imported by
string: the only
importlibuses arepackages/atif-cli/src/atif_cli/app.py:83andpackages/atif-converter/src/atif_converter/infrastructure/harbor_adapter.py:128. Nogetattrtargets a module object — all six sites take an instance or an upstream class, includingpackages/atif-models/src/atif_models/infrastructure/settings.py:73andpackages/atif-converter/src/atif_converter/infrastructure/harbor_adapter.py:178.
Two enforced gates are why the list is short rather than thin. ruff runs
select = ["ALL"] (pyproject.toml:146) at zero, so F401, F811, F841 and
ERA001 leave no unused import, no redefinition, no unused local, and no
commented-out code — with exactly one carve-out, pyproject.toml:224
("**/__init__.py" = ["F401", "E402"]). pyright runs
typeCheckingMode = "strict" (pyproject.toml:596) over all seven src/ and
tests/ trees (pyproject.toml:597-613) at zero errors, which enforces
reportUnusedFunction / reportUnusedClass / reportUnusedVariable for every
_-prefixed definition unused inside its own file. Neither gate can see a
public symbol that no other module imports, and that gap is exactly what the
tables below fill.
Unreferenced exports
Section titled “Unreferenced exports”26 names appear in their own module’s __all__ and in no other tracked file.
The symbol is live inside its module — the unreferenced thing is the export
declaration, so the fix is to narrow __all__, not to delete code. Each row’s
intra-module use site is named after the table.
Intra-module use sites, one per file, all opened and read. Where a symbol is used more than once, the citation carries the first site and the remaining line numbers follow it as plain numbers.
CHARS_PER_TOKENis the divisor atpackages/atif-analytics/src/atif_analytics/domain/costs.py:30.- The eleven
*_DIRNAME/*_FILENAMEconstants are each joined ontoanalytics_dirby one property inpackages/atif-analytics/src/atif_analytics/domain/layout.py:58-108, in declaration order. TOOL_INPUT_PREVIEW_CHARSis a default argument atpackages/atif-analytics/src/atif_analytics/domain/transcript.py:90;UUID_HEADER_ESCAPEis the substitution atpackages/atif-analytics/src/atif_analytics/domain/transcript.py:73;main_chainis called atpackages/atif-analytics/src/atif_analytics/domain/transcript.py:162.PART_GLOBis globbed atpackages/atif-analytics/src/atif_analytics/infrastructure/parquet_cache.py:86andis_sharded_diris called atpackages/atif-analytics/src/atif_analytics/infrastructure/parquet_cache.py:97.MAX_ATTEMPTS_DEFAULTis a default argument four times, first atpackages/atif-analytics/src/atif_analytics/infrastructure/sqlite_state/retry_queue.py:150and again on lines 164, 252, and 258 of that file.LaneStatusannotatespackages/atif-cli/src/atif_cli/cron.py:226and is constructed atpackages/atif-cli/src/atif_cli/cron.py:237.emit_row_batchesis the shared writer both public emitters call, atpackages/atif-cli/src/atif_cli/output.py:151and again on line 174 of that file.Categoryfeedsget_argsatpackages/atif-duck/src/atif_duck/domain/examples.py:56and annotatespackages/atif-duck/src/atif_duck/domain/examples.py:124.MIN_TEXT_CHARSis interpolated into SQL atpackages/atif-embed/src/atif_embed/infrastructure/corpus_text_rows.py:106.write_schema_versionis called atpackages/atif-embed/src/atif_embed/infrastructure/lance_store.py:185and again on lines 207 and 210;migrate_pre_stamp_tableatpackages/atif-embed/src/atif_embed/infrastructure/lance_store.py:205;optimize_if_neededatpackages/atif-embed/src/atif_embed/infrastructure/lance_store.py:412.ReasoningEfforttypesDEFAULT_REASONING_EFFORTatpackages/atif-models/src/atif_models/domain/registry.py:34and a model field atpackages/atif-models/src/atif_models/domain/registry.py:56.
Eight further public-by-naming symbols have no outside reference and are not
listed, because their modules make no export claim about them. Seven live in
modules that declare no __all__ at all —
packages/atif-converter/src/atif_converter/domain/edges.py:60,
packages/atif-converter/src/atif_converter/domain/edges.py:93,
packages/atif-converter/src/atif_converter/infrastructure/raw_records.py:45,
packages/atif-corpus/src/atif_corpus/application/materialize.py:108,
packages/atif-corpus/src/atif_corpus/domain/layout.py:22,
packages/atif-corpus/src/atif_corpus/infrastructure/atomic.py:35, and
packages/atif-corpus/src/atif_corpus/infrastructure/atomic.py:43 — so
they are module-internal helpers. The eighth,
packages/atif-embed/src/atif_embed/infrastructure/lance_store.py:77
(DistanceMetric), sits in a module that does declare an __all__ and is
deliberately absent from it, which is the module saying it is not exported.
Unreferenced files
Section titled “Unreferenced files”_none_
The import graph reports 18 of 100 source modules with no inbound first-party import. All 18 are framework-dispatched and none is removable, so the bucket is empty:
- Seventeen package
__init__.pyfiles. The interpreter executes a package’s__init__.pyon any submodule import, soimport atif_analytics.domain.costsrunspackages/atif-analytics/src/atif_analytics/__init__.py. That inbound edge is structural and invisible to an import-statement graph; deleting the file breaks every import of the package. - One module entry point, dispatched by the interpreter’s
-mswitch.packages/atif-cli/src/atif_cli/__main__.py:3names itself thepython -m atif_clientry andpackages/atif-cli/src/atif_cli/__main__.py:5-8callsatif_cli.app.main. It is exercised in-repo by a subprocess test atpackages/atif-cli/tests/test_integration.py:121.
Dead imports
Section titled “Dead imports”__init__.py is the only tree where F401 is off (pyproject.toml:224), so it
is the only place an import with no consumer survives lint. atif-duck is the only
member whose __init__.py files re-export anything, and all 22 re-exports are
consumed by nothing — in-repo or out. Each name is listed in its file’s
__all__, which is what keeps the statement alive to the linter; no tracked file
imports any of them from the package root, and the six members are not
independently installable, so no external consumer exists either.
| Path | Symbol | Imported from |
|---|---|---|
packages/atif-duck/src/atif_duck/__init__.py:17 |
DEFAULT_PRICING |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/__init__.py:18 |
MACRO_NAMES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/__init__.py:19 |
MACRO_SIGNATURES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/__init__.py:20 |
VIEW_NAMES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/__init__.py:21 |
VIEW_SCHEMA |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/__init__.py:24 |
register |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/__init__.py:25 |
register_macros |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/__init__.py:26 |
register_raw |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/__init__.py:27 |
register_views |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:12 |
DEFAULT_PRICING |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:13 |
DESCRIPTIONS |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:14 |
MACRO_NAMES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:15 |
MACRO_SIGNATURES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:16 |
TABLE_MACRO_NAMES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:17 |
VIEW_NAMES |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:18 |
VIEW_SCHEMA |
packages/atif-duck/src/atif_duck/domain/catalog.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:20 |
ExampleQuery |
packages/atif-duck/src/atif_duck/domain/examples.py |
packages/atif-duck/src/atif_duck/domain/__init__.py:20 |
build_examples |
packages/atif-duck/src/atif_duck/domain/examples.py |
packages/atif-duck/src/atif_duck/infrastructure/__init__.py:6 |
register |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/infrastructure/__init__.py:7 |
register_macros |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/infrastructure/__init__.py:8 |
register_raw |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
packages/atif-duck/src/atif_duck/infrastructure/__init__.py:9 |
register_views |
packages/atif-duck/src/atif_duck/infrastructure/registry.py |
The absence is checked against the exact import form a consumer would have to write, over all 224 tracked files:
from atif_duck import ...— no site.from atif_duck.domain import ...— no site.from atif_duck.infrastructure import ...— two sites, and both import the submoduleanalytics, never one of the four re-exportedregister*names:packages/atif-duck/tests/test_analytics_views.py:23andpackages/atif-duck/tests/test_examples.py:42.- No
import atif_duckfollowed by attribute access, and no test anywhere asserts an__all__(grep -rn '__all__' packages/*/tests scriptsis empty), so__all__membership is not itself pinned.
Every real consumer bypasses the facade for the deep module:
packages/atif-cli/src/atif_cli/app.py:615andpackages/atif-cli/src/atif_cli/app.py:906—from atif_duck.infrastructure.registry import register.packages/atif-cli/src/atif_cli/app.py:1022—from atif_duck.domain.examples import ....packages/atif-cli/src/atif_cli/app.py:1099—from atif_duck.domain.catalog import MACRO_SIGNATURES, VIEW_SCHEMA.packages/atif-cli/src/atif_cli/duck_errors.py:26,packages/atif-cli/tests/test_app.py:78, andpackages/atif-cli/tests/test_app.py:98.
The one dynamic reference to the package,
packages/atif-cli/tests/test_lean_import.py:21, names
"atif_duck.infrastructure" inside the _FORBIDDEN_EAGER_IMPORTS tuple at
packages/atif-cli/tests/test_lean_import.py:17-32 — an assertion that the
module must not load on import atif_cli.app, which is the opposite of a
consumer.
Each __init__.py presents the facade as intentional:
packages/atif-duck/src/atif_duck/__init__.py:6 documents
register(con, corpus_root) as the package entry point. Read against
pyproject.toml:17 — one distribution named atif-sql, bundling all seven module
trees in a single wheel rather than shipping any of them as an install target —
the facade has no addressable consumer, and the CLI is the public contract
instead.
See also
Section titled “See also”- module map — 21 shared source citations
- processes — 17 shared source citations
- impact analysis — 17 shared source citations
- business logic — 16 shared source citations
- contract map — 16 shared source citations