anatomize 0.2.0__tar.gz → 0.2.1__tar.gz

{anatomize-0.2.0 → anatomize-0.2.1}/.github/workflows/ci.yml

@@ -48,8 +48,8 @@ jobs:
           . .venv-smoke/bin/activate
           python -m pip install -U pip
           python -m pip install dist/*.whl
-          anatomize generate tests/fixtures/project_src/src --output .skeleton-smoke -f json
-          anatomize validate .skeleton-smoke --source tests/fixtures/project_src/src
+          anatomize generate tests/fixtures/project_src/src --output .anatomy-smoke -f json
+          anatomize validate .anatomy-smoke --source tests/fixtures/project_src/src
 
   pyright-e2e:
     runs-on: ubuntu-latest
@@ -69,7 +69,7 @@ jobs:
       - name: Install Pyright
         run: |
           npm i -g pyright
-          pyright --version
+          command -v pyright
           command -v pyright-langserver
 
       - name: Install

{anatomize-0.2.0 → anatomize-0.2.1}/.gitignore

@@ -16,8 +16,10 @@ dist/
 build/
 *.egg-info/
 
-.skeleton/
-.skeleton-*/
+.anatomy/
+.anatomy-*/
+.runtime/
+.runtime-*/
 
 .DS_Store
 Thumbs.db

{anatomize-0.2.0 → anatomize-0.2.1}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.1 - 2026-02-01
+
+### Added
+- `anatomize pack --prefix standard|minimal` to control pack prefix verbosity (token overhead vs guidance).
+- `anatomize pack --explain-selection` to write a deterministic selection report for debugging include/ignore/slice behavior.
+
+### Changed
+- Hybrid mode now supports markdown/plain output (JSONL is optional, and required only for `--fit-to-max-output`).
+- Pack ignore rules now retain rule provenance (default vs standard ignore files vs CLI) for selection reporting.
+- Binary sniffing reads only a small prefix for performance (instead of reading entire files).
+- Dependency-closure failures now include an import chain for faster debugging.
+
+### Infrastructure
+- CI Pyright job avoids invoking commands that require an LSP transport without `--stdio`.
+
 ## 0.2.0 - 2026-02-01
 
 ### Added

{anatomize-0.2.0 → anatomize-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anatomize
-Version: 0.2.0
+Version: 0.2.1
 Summary: Deterministic, token-efficient codebase packs and skeleton maps for AI review (Python)
 Project-URL: Homepage, https://github.com/BradSegal/anatomize
 Project-URL: Documentation, https://github.com/BradSegal/anatomize#readme
@@ -114,6 +114,13 @@ anatomize pack . --output codebase.md
 # Full bundle
 anatomize pack . --format markdown --output codebase.md
 
+# Minimal prefix (lower token overhead)
+anatomize pack . --prefix minimal --output codebase.md
+
+# Explain selection (why files were included/excluded)
+# (writes `codebase.md.selection.json` by default)
+anatomize pack . --explain-selection --output codebase.md
+
 # Filter by globs
 anatomize pack . --include "src/**" --ignore "**/__pycache__/**" --output src-only.md
 
@@ -147,13 +154,13 @@ anatomize pack . --token-count-tree --output codebase.md
 # JSONL (stream-friendly)
 anatomize pack . --format jsonl --output codebase.jsonl
 
-# Hybrid mode (skeleton-style summaries + selective fill)
-# - defaults to JSONL when --mode hybrid is set
+# Hybrid mode (summaries + selective fill; token-efficient)
+# - defaults to markdown when --format and the output extension are not specified
 # - Python files default to summary; non-Python defaults to metadata-only
-anatomize pack . --mode hybrid --output hybrid.jsonl
+anatomize pack . --mode hybrid --output hybrid.md
 
-# Hybrid: include full content for a slice and fit within a hard token budget
-anatomize pack . --mode hybrid --max-output 50_000t --fit-to-max-output \
+# Hybrid: include full content for a slice and fit within a hard token budget (JSONL only)
+anatomize pack . --mode hybrid --format jsonl --max-output 50_000t --fit-to-max-output \
   --content "src/pkg/**" --output hybrid.slice.jsonl
 ```
 
@@ -219,8 +226,9 @@ symlinks: forbid # forbid|files|dirs|all
 workers: 0 # 0 = auto
 
 pack:
-  format: markdown # markdown|plain|json|xml|jsonl
-  mode: bundle # bundle|hybrid
+  format: markdown # markdown|plain|json|xml|jsonl (hybrid supports markdown|plain|jsonl)
+  mode: bundle # bundle|hybrid (hybrid is token-efficient summaries + selective fill)
+  prefix: standard # standard|minimal
   output: anatomize-pack.md # if the extension is known, it must match `format`
   include: []
   ignore: []
@@ -281,8 +289,10 @@ When `anatomize generate` runs from `.anatomize.yaml`, it writes one skeleton di
 Each pack artifact starts with a lightweight, deterministic overview (and, if enabled, a structure tree) before file blocks/records.
 
 Token reporting:
-- **Artifact tokens**: exact tokens of the written output file(s).
-- **Content tokens**: tokens of file contents only (useful for budgeting and “what’s expensive”).
+- **Artifact tokens**: exact tokens of the written output file(s) (returned by the Python API).
+- **Content tokens**: tokens of file contents only (returned by the Python API; useful for budgeting).
+
+Pack artifacts intentionally do **not** embed token counts (agents don’t need them; they waste tokens).
 
 ---
 

{anatomize-0.2.0 → anatomize-0.2.1}/README.md

@@ -75,6 +75,13 @@ anatomize pack . --output codebase.md
 # Full bundle
 anatomize pack . --format markdown --output codebase.md
 
+# Minimal prefix (lower token overhead)
+anatomize pack . --prefix minimal --output codebase.md
+
+# Explain selection (why files were included/excluded)
+# (writes `codebase.md.selection.json` by default)
+anatomize pack . --explain-selection --output codebase.md
+
 # Filter by globs
 anatomize pack . --include "src/**" --ignore "**/__pycache__/**" --output src-only.md
 
@@ -108,13 +115,13 @@ anatomize pack . --token-count-tree --output codebase.md
 # JSONL (stream-friendly)
 anatomize pack . --format jsonl --output codebase.jsonl
 
-# Hybrid mode (skeleton-style summaries + selective fill)
-# - defaults to JSONL when --mode hybrid is set
+# Hybrid mode (summaries + selective fill; token-efficient)
+# - defaults to markdown when --format and the output extension are not specified
 # - Python files default to summary; non-Python defaults to metadata-only
-anatomize pack . --mode hybrid --output hybrid.jsonl
+anatomize pack . --mode hybrid --output hybrid.md
 
-# Hybrid: include full content for a slice and fit within a hard token budget
-anatomize pack . --mode hybrid --max-output 50_000t --fit-to-max-output \
+# Hybrid: include full content for a slice and fit within a hard token budget (JSONL only)
+anatomize pack . --mode hybrid --format jsonl --max-output 50_000t --fit-to-max-output \
   --content "src/pkg/**" --output hybrid.slice.jsonl
 ```
 
@@ -180,8 +187,9 @@ symlinks: forbid # forbid|files|dirs|all
 workers: 0 # 0 = auto
 
 pack:
-  format: markdown # markdown|plain|json|xml|jsonl
-  mode: bundle # bundle|hybrid
+  format: markdown # markdown|plain|json|xml|jsonl (hybrid supports markdown|plain|jsonl)
+  mode: bundle # bundle|hybrid (hybrid is token-efficient summaries + selective fill)
+  prefix: standard # standard|minimal
   output: anatomize-pack.md # if the extension is known, it must match `format`
   include: []
   ignore: []
@@ -242,8 +250,10 @@ When `anatomize generate` runs from `.anatomize.yaml`, it writes one skeleton di
 Each pack artifact starts with a lightweight, deterministic overview (and, if enabled, a structure tree) before file blocks/records.
 
 Token reporting:
-- **Artifact tokens**: exact tokens of the written output file(s).
-- **Content tokens**: tokens of file contents only (useful for budgeting and “what’s expensive”).
+- **Artifact tokens**: exact tokens of the written output file(s) (returned by the Python API).
+- **Content tokens**: tokens of file contents only (returned by the Python API; useful for budgeting).
+
+Pack artifacts intentionally do **not** embed token counts (agents don’t need them; they waste tokens).
 
 ---
 

{anatomize-0.2.0 → anatomize-0.2.1}/docs/GUIDE.md

@@ -163,7 +163,7 @@ Hybrid mode is intended for token efficiency and navigability:
 - Python files default to `summary` (signatures/imports/line numbers).
 - Non-Python files default to `meta` (metadata only) unless explicitly summarized or included as content.
 - If `--format` is omitted, it is inferred from `--output` when the extension is known (`.md|.txt|.json|.xml|.jsonl`).
-- Hybrid output is **JSONL**. If `--format` is not provided, it defaults to JSONL when `--mode hybrid` is used. Non-`.jsonl` output paths are rejected.
+- Hybrid supports **markdown**, **plain**, and **jsonl** output. If `--format` is not provided, it defaults to markdown when `--mode hybrid` is used and the output extension is unknown.
 
 ### Output formats
 - `--format markdown` (best for human review)
@@ -171,6 +171,11 @@ Hybrid mode is intended for token efficiency and navigability:
 - `--format json` / `--format xml` (best for machine processing)
 - `--format jsonl` (stream-friendly, line-delimited JSON)
 
+### Prefix style (token overhead vs guidance)
+Control the amount of non-code guidance emitted at the top of markdown/plain pack artifacts:
+- `--prefix standard` (default): includes a short “How to use” section.
+- `--prefix minimal`: omits guidance and keeps only a compact, deterministic summary.
+
 ### Content encoding (robustness)
 File contents can break Markdown structure (e.g. embedded ``` fences). Control how content is emitted with:
 - `--content-encoding fence-safe` (default): picks a fence length that cannot occur in the content.
@@ -178,6 +183,11 @@ File contents can break Markdown structure (e.g. embedded ``` fences). Control h
 
 Note: Markdown output intentionally disallows `--content-encoding verbatim`.
 
+### Selection report (debugging file inclusion)
+If you need to understand why paths were included or excluded, use:
+- `--explain-selection` to write a deterministic selection report.
+- `--explain-selection-output PATH` to choose where it is written.
+
 ### Hybrid representations (fill-in controls)
 In hybrid mode, each file record has an explicit representation:
 - `meta`: path/language/is_binary/size/content_tokens
@@ -197,7 +207,7 @@ Supported non-Python summaries:
 - Markdown: headings outline
 
 ### Fit-to-budget (explicit)
-Hybrid mode can deterministically fit within a hard cap:
+Hybrid mode can deterministically fit within a hard cap (JSONL only):
 - `--max-output 50_000t --fit-to-max-output`
 
 If enabled, `pack` may downgrade representations (e.g. `summary` → `meta`) to satisfy `--max-output` and emits an auditable `selection_trace`.
@@ -205,8 +215,10 @@ If it cannot satisfy the cap, it fails.
 
 ### Token metrics
 `pack` reports:
-- **Artifact tokens**: exact tokens of the written output file(s).
-- **Content tokens**: tokens for file contents only (useful for budgeting per-file).
+- **Artifact tokens**: exact tokens of the written output file(s) (returned by the Python API).
+- **Content tokens**: tokens for file contents only (returned by the Python API; useful for budgeting per-file).
+
+Pack artifacts intentionally do **not** embed token counts (agents don’t need them; they waste tokens).
 
 Encoding is controlled by:
 - `--token-encoding` (default: `cl100k_base`)

{anatomize-0.2.0 → anatomize-0.2.1}/docs/REPOMIX_VS_ANATOMIZE.md

@@ -2,7 +2,7 @@
 
 ### Versions
 - `repomix`: 1.11.1
-- `anatomize`: 0.1.0
+- `anatomize`: 0.2.1
 - `tiktoken`: 0.12.0
 
 ### Method

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/__init__.py

@@ -9,7 +9,7 @@ Example
 >>> from anatomize.formats import write_skeleton
 >>> gen = SkeletonGenerator(sources=["./src"])
 >>> skeleton = gen.generate(level="modules")
->>> write_skeleton(skeleton, ".skeleton", formats=[OutputFormat.YAML])
+>>> write_skeleton(skeleton, ".anatomy", formats=[OutputFormat.YAML])
 """
 
 from anatomize.core.types import (

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/cli.py

@@ -23,7 +23,7 @@ from anatomize.core.policy import SymlinkPolicy
 from anatomize.core.types import ResolutionLevel
 from anatomize.formats import OutputFormat, write_skeleton
 from anatomize.generators.main import SkeletonGenerator
-from anatomize.pack.formats import ContentEncoding, PackFormat
+from anatomize.pack.formats import ContentEncoding, PackFormat, PrefixStyle, default_output_path
 from anatomize.pack.limit import OutputLimit, parse_output_limit
 from anatomize.pack.mode import PackMode
 from anatomize.pack.slicing import SliceBackend
@@ -259,7 +259,7 @@ def generate(
     Examples
     --------
         anatomize generate ./src
-        anatomize generate ./src --output .skeleton --level signatures
+        anatomize generate ./src --output .anatomy --level signatures
         anatomize generate ./src -f yaml -f json -f markdown
     """
     try:
@@ -530,8 +530,8 @@ def validate(
 
     Examples
     --------
-        anatomize validate .skeleton --source ./src
-        anatomize validate .skeleton -s ./src -s ./tests --fix
+        anatomize validate .anatomy --source ./src
+        anatomize validate .anatomy -s ./src -s ./tests --fix
     """
     try:
         from anatomize.validation import validate_skeleton_dir
@@ -644,6 +644,24 @@ def pack(
         str | None,
         typer.Option("--mode", help="Pack mode: bundle or hybrid (hybrid requires jsonl)."),
     ] = None,
+    prefix: Annotated[
+        str | None,
+        typer.Option("--prefix", help="Pack prefix style: standard or minimal."),
+    ] = None,
+    explain_selection: Annotated[
+        bool,
+        typer.Option(
+            "--explain-selection",
+            help="Write a deterministic selection report (why files were included/excluded).",
+        ),
+    ] = False,
+    explain_selection_output: Annotated[
+        Path | None,
+        typer.Option(
+            "--explain-selection-output",
+            help="Selection report output path (default derived from --output).",
+        ),
+    ] = None,
     include: Annotated[
         list[str] | None,
         typer.Option("--include", help="Include pattern(s). Repeatable allowlist; when absent, includes all."),
@@ -844,15 +862,25 @@ def pack(
                 )
         else:
             if resolved_mode is PackMode.HYBRID:
-                if inferred_from_output is not None and inferred_from_output is not PackFormat.JSONL:
-                    raise ValueError("--mode hybrid requires JSONL output (.jsonl)")
-                resolved_fmt = PackFormat.JSONL
+                if inferred_from_output is not None:
+                    if inferred_from_output not in (PackFormat.JSONL, PackFormat.MARKDOWN, PackFormat.PLAIN):
+                        raise ValueError("--mode hybrid supports only markdown, plain, or jsonl output")
+                    resolved_fmt = inferred_from_output
+                else:
+                    resolved_fmt = PackFormat.MARKDOWN
             else:
                 resolved_fmt = inferred_from_output if inferred_from_output is not None else pack_cfg.format
 
         resolved_deps = bool(entry) if deps is None else deps
         resolved_backend = pack_cfg.slice_backend if slice_backend is None else SliceBackend(slice_backend)
 
+        resolved_prefix = pack_cfg.prefix if prefix is None else PrefixStyle(prefix)
+        if resolved_mode is PackMode.HYBRID and resolved_fmt not in (
+            PackFormat.JSONL,
+            PackFormat.MARKDOWN,
+            PackFormat.PLAIN,
+        ):
+            raise ValueError("--mode hybrid supports only markdown, plain, or jsonl output")
         resolved_include = pack_cfg.include if include is None else include
         resolved_ignore = pack_cfg.ignore if ignore is None else ignore
         resolved_ignore_files = (
@@ -902,11 +930,23 @@ def pack(
             [Path(p) for p in pack_cfg.python_roots] if python_root is None else python_root
         )
 
+        selection_report_path: Path | None = None
+        if explain_selection:
+            base = resolved_output if resolved_output is not None else default_output_path(resolved_fmt)
+            base = base.resolve()
+            selection_report_path = (
+                explain_selection_output.resolve()
+                if explain_selection_output is not None
+                else base.with_name(base.name + ".selection.json")
+            )
+
         res = run_pack(
             root=root,
             output=resolved_output,
             fmt=resolved_fmt,
             mode=resolved_mode,
+            prefix_style=resolved_prefix,
+            selection_report_output=selection_report_path,
             include=resolved_include,
             ignore=resolved_ignore,
             ignore_files=resolved_ignore_files,
@@ -941,6 +981,8 @@ def pack(
 
         for a in res.artifacts:
             typer.echo(f"Wrote: {a.path}")
+        if selection_report_path is not None:
+            typer.echo(f"Selection report: {selection_report_path}")
         total_artifact_tokens = sum(a.tokens for a in res.artifacts)
         typer.echo(f"Artifact tokens: {total_artifact_tokens:,} ({resolved_token_encoding})")
         typer.echo(f"Content tokens:  {res.content_tokens:,} ({resolved_token_encoding})")

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/config.py

@@ -14,7 +14,7 @@ from pydantic import BaseModel, Field
 from anatomize.core.policy import SymlinkPolicy
 from anatomize.core.types import ResolutionLevel
 from anatomize.formats import OutputFormat
-from anatomize.pack.formats import ContentEncoding, PackFormat, infer_pack_format_from_output_path
+from anatomize.pack.formats import ContentEncoding, PackFormat, PrefixStyle, infer_pack_format_from_output_path
 from anatomize.pack.mode import PackMode
 from anatomize.pack.slicing import SliceBackend
 from anatomize.pack.summaries import SummaryConfig
@@ -26,6 +26,7 @@ class PackConfig(BaseModel):
     format: PackFormat = PackFormat.MARKDOWN
     mode: PackMode = PackMode.BUNDLE
     output: str | None = None
+    prefix: PrefixStyle = PrefixStyle.STANDARD
     include: list[str] = Field(default_factory=list)
     ignore: list[str] = Field(default_factory=list)
     ignore_files: list[str] = Field(default_factory=list)
@@ -54,6 +55,13 @@ class PackConfig(BaseModel):
     model_config = {"extra": "forbid"}
 
     def model_post_init(self, __context: Any) -> None:
+        if self.mode is PackMode.HYBRID and self.format not in (
+            PackFormat.MARKDOWN,
+            PackFormat.PLAIN,
+            PackFormat.JSONL,
+        ):
+            raise ValueError("pack.mode=hybrid supports only markdown, plain, or jsonl format")
+
         if self.output is None:
             return
         inferred = infer_pack_format_from_output_path(Path(self.output))
@@ -180,6 +188,7 @@ class AnatomizeConfig(BaseModel):
                 "format": self.pack.format.value,
                 "mode": self.pack.mode.value,
                 "output": self.pack.output,
+                "prefix": self.pack.prefix.value,
                 "include": self.pack.include,
                 "ignore": self.pack.ignore,
                 "ignore_files": self.pack.ignore_files,

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/core/exclude.py

@@ -16,10 +16,12 @@ Supported:
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 from fnmatch import fnmatchcase
 from functools import cache
 from pathlib import PurePosixPath
+from typing import TypeAlias
 
 
 @dataclass(frozen=True)
@@ -35,12 +37,23 @@ class ExcludeRule:
     anchored: bool
     directory_only: bool
     has_slash: bool
+    source: str
+
+
+IgnorePattern: TypeAlias = str | tuple[str, str]
 
 
 class Excluder:
-    def __init__(self, patterns: list[str]) -> None:
+    def __init__(self, patterns: Sequence[IgnorePattern]) -> None:
         self._rules: list[ExcludeRule] = []
-        for raw in patterns:
+        for item in patterns:
+            source = "unspecified"
+            raw: str
+            if isinstance(item, tuple):
+                raw, source = item
+            else:
+                raw = item
+
             parsed = parse_ignore_line(raw, allow_negation=True)
             if parsed is None:
                 continue
@@ -67,20 +80,30 @@ class Excluder:
                     anchored=anchored,
                     directory_only=directory_only,
                     has_slash=has_slash,
+                    source=source,
                 )
             )
 
     def is_excluded(self, rel_posix: str, *, is_dir: bool) -> bool:
         """Return True if the given relative path should be excluded."""
+        return self.explain(rel_posix, is_dir=is_dir)[0]
+
+    def rules(self) -> list[ExcludeRule]:
+        return list(self._rules)
+
+    def explain(self, rel_posix: str, *, is_dir: bool) -> tuple[bool, ExcludeRule | None]:
+        """Return (excluded, last_matching_rule_or_None)."""
         rel_posix = rel_posix.strip("/")
         path = PurePosixPath(rel_posix) if rel_posix else PurePosixPath(".")
 
         excluded = False
+        matched: ExcludeRule | None = None
         for rule in self._rules:
             if not self._matches(path, rule, is_dir=is_dir):
                 continue
             excluded = not rule.negated
-        return excluded
+            matched = rule
+        return excluded, matched
 
     def filter_dirnames(self, parent_rel_posix: str, dirnames: list[str]) -> None:
         """Prune excluded directories in-place for os.walk dirnames."""

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/formats/json_fmt.py

@@ -26,7 +26,7 @@ class JsonFormatter:
     Example
     -------
     >>> formatter = JsonFormatter()
-    >>> formatter.write(skeleton, Path(".skeleton"))
+    >>> formatter.write(skeleton, Path(".anatomy"))
     """
 
     def __init__(self, indent: int = 2) -> None:

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/formats/markdown_fmt.py

@@ -23,7 +23,7 @@ class MarkdownFormatter:
     Example
     -------
     >>> formatter = MarkdownFormatter()
-    >>> formatter.write(skeleton, Path(".skeleton"))
+    >>> formatter.write(skeleton, Path(".anatomy"))
     """
 
     def write(self, skeleton: Skeleton, output_dir: Path) -> None:

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/formats/yaml_fmt.py

@@ -27,7 +27,7 @@ class YamlFormatter:
     Example
     -------
     >>> formatter = YamlFormatter()
-    >>> formatter.write(skeleton, Path(".skeleton"))
+    >>> formatter.write(skeleton, Path(".anatomy"))
     """
 
     def __init__(self) -> None:

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/generators/main.py

@@ -69,9 +69,14 @@ class SkeletonGenerator:
             "*.pyc",
             ".git",
             ".venv",
-            ".skeleton",
+            ".anatomy",
+            ".runtime",
             ".mypy_cache",
             ".pytest_cache",
+            ".ruff_cache",
+            "dist",
+            "build",
+            "*.egg-info",
         ]
         self._symlinks = symlinks
         self._workers = workers

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/pack/deps.py

@@ -90,10 +90,12 @@ def dependency_closure(entry_files: list[Path], *, index: PythonModuleIndex) ->
         raise ValueError("At least one --entry is required for dependency closure")
 
     seen: set[Path] = set()
+    parent: dict[Path, Path | None] = {}
     queue: list[PythonModule] = []
     for f in entry_files:
         mod = index.module_for_path(f)
         queue.append(mod)
+        parent.setdefault(mod.path, None)
 
     while queue:
         current = queue.pop()
@@ -104,16 +106,30 @@ def dependency_closure(entry_files: list[Path], *, index: PythonModuleIndex) ->
         for init in index.package_inits_for(current.module):
             if init.path not in seen:
                 queue.append(init)
+                parent.setdefault(init.path, current.path)
 
         for imported in _extract_imported_modules(current, index=index):
             target = index.resolve_module(imported)
             if target is None:
                 top = imported.split(".", 1)[0]
                 if index.is_local_toplevel(top):
-                    raise ValueError(f"Unresolved local import '{imported}' from {current.path}")
+                    chain: list[Path] = [current.path]
+                    p = current.path
+                    while True:
+                        prev = parent.get(p)
+                        if prev is None:
+                            break
+                        p = prev
+                        chain.append(p)
+                    chain = list(reversed(chain))
+                    chain_str = "\n".join(f"  - {c}" for c in chain)
+                    raise ValueError(
+                        f"Unresolved local import '{imported}' from {current.path}\nImport chain:\n{chain_str}"
+                    )
                 continue
             if target.path not in seen:
                 queue.append(target)
+                parent.setdefault(target.path, current.path)
 
     return sorted(seen)
 

{anatomize-0.2.0 → anatomize-0.2.1}/src/anatomize/pack/discovery.py

@@ -20,6 +20,16 @@ class DiscoveredPath:
     is_binary: bool
 
 
+@dataclass(frozen=True)
+class DiscoveryTraceItem:
+    path: str
+    is_dir: bool
+    decision: str  # "included" or "excluded"
+    reason: str | None  # "ignore" | "include" | None
+    matched_pattern: str | None
+    matched_source: str | None
+
+
 def discover_paths(
     root: Path,
     *,
@@ -27,6 +37,7 @@ def discover_paths(
     include_patterns: list[str] | None,
     symlinks: SymlinkPolicy,
     max_file_bytes: int,
+    trace: list[DiscoveryTraceItem] | None = None,
 ) -> list[DiscoveredPath]:
     root = root.resolve()
     if not root.exists() or not root.is_dir():
@@ -55,7 +66,22 @@ def discover_paths(
             except OSError as e:
                 raise ValueError(f"Failed to stat path: {entry}") from e
 
-            if excluder.is_excluded(rel_posix, is_dir=is_dir):
+            excluded, matched = excluder.explain(rel_posix, is_dir=is_dir)
+            if excluded:
+                if trace is not None:
+                    matched_pattern = None
+                    if matched is not None:
+                        matched_pattern = matched.pattern + ("/" if matched.directory_only else "")
+                    trace.append(
+                        DiscoveryTraceItem(
+                            path=rel_posix,
+                            is_dir=is_dir,
+                            decision="excluded",
+                            reason="ignore",
+                            matched_pattern=matched_pattern,
+                            matched_source=matched.source if matched is not None else None,
+                        )
+                    )
                 continue
 
             if include_patterns and not include_matcher.matches_any(rel_posix, is_dir=is_dir):
@@ -64,6 +90,17 @@ def discover_paths(
                 # our simple include matcher cannot prove that cheaply, so we traverse all
                 # non-excluded directories and filter files at the leaf.
                 if not is_dir:
+                    if trace is not None:
+                        trace.append(
+                            DiscoveryTraceItem(
+                                path=rel_posix,
+                                is_dir=False,
+                                decision="excluded",
+                                reason="include",
+                                matched_pattern=None,
+                                matched_source=None,
+                            )
+                        )
                     continue
 
             if is_dir:
@@ -95,6 +132,17 @@ def discover_paths(
                     is_binary=is_binary,
                 )
             )
+            if trace is not None:
+                trace.append(
+                    DiscoveryTraceItem(
+                        path=rel_posix,
+                        is_dir=False,
+                        decision="included",
+                        reason=None,
+                        matched_pattern=None,
+                        matched_source=None,
+                    )
+                )
 
     results.append(
         DiscoveredPath(
@@ -115,7 +163,8 @@ def discover_paths(
 
 def _is_binary_file(path: Path, *, sniff_bytes: int = 8192) -> bool:
     try:
-        data = path.read_bytes()[:sniff_bytes]
+        with path.open("rb") as f:
+            data = f.read(sniff_bytes)
     except OSError:
         return True
     if b"\x00" in data: