findfmt 0.1.0__py3-none-any.whl

findfmt/__init__.py

@@ -0,0 +1,22 @@
+"""findfmt: A .gitignore-aware file discovery and classification suite."""
+
+from __future__ import annotations
+
+from findfmt.classifier import classify_file, get_known_tags
+from findfmt.cli import get_version, main
+from findfmt.models import FileInfo, TraversalConfig
+from findfmt.traversal import find_files, traverse_directory
+
+__version__ = get_version()
+
+__all__ = [
+    "FileInfo",
+    "TraversalConfig",
+    "__version__",
+    "classify_file",
+    "find_files",
+    "get_known_tags",
+    "get_version",
+    "main",
+    "traverse_directory",
+]

findfmt/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for python -m findfmt."""
+
+from __future__ import annotations
+
+import sys
+
+from findfmt.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

findfmt/classifier.py

@@ -0,0 +1,258 @@
+"""File classification and content analysis engine."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+from typing import TYPE_CHECKING
+
+import identify.identify as identify_engine
+
+from findfmt.models import FileInfo
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def get_known_tags() -> frozenset[str]:
+    """Retrieve all known format and type tags recognized by the engine.
+
+    Returns:
+        frozenset of all recognized string tags.
+    """
+    return frozenset(identify_engine.ALL_TAGS)
+
+
+def extract_shebang(path: Path) -> str | None:
+    """Extract the shebang interpreter from the top of an executable file.
+
+    Args:
+        path: Path to the target file.
+
+    Returns:
+        The raw shebang line string if present and readable, or None.
+    """
+    try:
+        if not path.is_file():
+            return None
+
+        with path.open("rb") as f:
+            first_line = f.readline(512)
+            if first_line.startswith(b"#!"):
+                return first_line.decode("utf-8", errors="replace").strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    return None
+
+
+def _resolve_relative(path: Path, root_path: Path | None) -> Path:
+    """Compute relative path from root_path if provided.
+
+    Args:
+        path: Target file path.
+        root_path: Optional root directory path.
+
+    Returns:
+        Relative path if root_path is given and matches, otherwise original path.
+    """
+    if root_path is None:
+        return path
+
+    try:
+        return path.resolve().relative_to(root_path.resolve())
+    except (ValueError, OSError):
+        return path
+
+
+def _identify_tags(
+    path: Path,
+    str_path: str,
+    *,
+    exists: bool,
+    is_regular_or_symlink: bool = True,
+) -> set[str]:
+    """Extract identify tags with fallback handling.
+
+    Args:
+        path: Target file path.
+        str_path: String representation of path.
+        exists: Flag indicating whether path exists on disk.
+        is_regular_or_symlink: Flag indicating whether path is regular file or symlink.
+
+    Returns:
+        Set of tag strings identified for the file.
+    """
+    try:
+        if exists and is_regular_or_symlink:
+            return set(identify_engine.tags_from_path(str_path))
+
+        return set(identify_engine.tags_from_filename(path.name))
+    except (ValueError, OSError):
+        return set(identify_engine.tags_from_filename(path.name))
+
+
+def _shebang_info(
+    path: Path,
+    str_path: str,
+    *,
+    is_file: bool,
+    is_symlink: bool,
+) -> tuple[str | None, set[str]]:
+    """Extract shebang and interpreter tags if applicable.
+
+    Args:
+        path: Target file path.
+        str_path: String representation of path.
+        is_file: Flag indicating whether path is a regular file.
+        is_symlink: Flag indicating whether path is a symbolic link.
+
+    Returns:
+        Tuple containing shebang string (or None) and set of tags.
+    """
+    if not (is_file and not is_symlink):
+        return None, set()
+
+    shebang = extract_shebang(path)
+    tags: set[str] = set()
+    if shebang:
+        parts = identify_engine.parse_shebang_from_file(str_path)
+        for part in parts:
+            tags.update(identify_engine.tags_from_interpreter(part))
+
+    return shebang, tags
+
+
+def _mime_info(str_path: str) -> tuple[str | None, set[str]]:
+    """Extract MIME type and MIME-derived tags.
+
+    Args:
+        str_path: String representation of the file path.
+
+    Returns:
+        Tuple containing MIME type string (or None) and set of MIME tags.
+    """
+    mime_type, _ = mimetypes.guess_type(str_path)
+    tags: set[str] = set()
+    if mime_type:
+        tags.add(f"mime:{mime_type}")
+        category = mime_type.split("/", 1)[0]
+        tags.add(category)
+
+    return mime_type, tags
+
+
+def _check_executable(path: Path, *, exists: bool, shebang: str | None = None) -> bool:
+    """Determine whether a file is executable across POSIX and Windows platforms.
+
+    Args:
+        path: File path to check.
+        exists: Flag indicating whether path exists on disk.
+        shebang: Optional shebang line string if detected.
+
+    Returns:
+        True if the file is considered executable on the host platform.
+    """
+    if not exists:
+        return False
+
+    if os.name == "nt":
+        pathext = os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC").split(";")
+        has_pathext = any(path.name.upper().endswith(ext.upper()) for ext in pathext if ext)
+        return has_pathext or bool(shebang)
+
+    return os.access(path, os.X_OK)
+
+
+def _inspect_metadata(path: Path) -> tuple[bool, bool, bool, int]:
+    """Inspect filesystem metadata safely.
+
+    Args:
+        path: File path to inspect.
+
+    Returns:
+        Tuple of (is_symlink, exists, is_file, size_bytes).
+    """
+    try:
+        is_symlink = path.is_symlink()
+    except OSError:
+        is_symlink = False
+
+    try:
+        stat_result = path.lstat() if is_symlink else path.stat()
+        size_bytes = stat_result.st_size
+    except OSError:
+        size_bytes = 0
+
+    try:
+        exists = path.exists()
+    except OSError:
+        exists = False
+
+    try:
+        is_file = path.is_file() if exists else False
+    except OSError:
+        is_file = False
+
+    return is_symlink, exists, is_file, size_bytes
+
+
+def _adjust_nt_tags(tags: set[str], *, is_executable: bool) -> None:
+    """Adjust executable tags on Windows platform.
+
+    Args:
+        tags: Set of tags to modify in place.
+        is_executable: Flag indicating whether path is executable.
+    """
+    if os.name != "nt":
+        return
+
+    if is_executable:
+        tags.discard("non-executable")
+        tags.add("executable")
+    else:
+        tags.discard("executable")
+        tags.add("non-executable")
+
+
+def classify_file(path: Path, root_path: Path | None = None) -> FileInfo:
+    """Classify a given file path by inspection of name, content, and metadata.
+
+    Args:
+        path: The path of the file to classify.
+        root_path: Optional root directory used to compute relative_path.
+
+    Returns:
+        FileInfo containing metadata, identified tags, shebang, and MIME info.
+    """
+    str_path = str(path)
+    is_symlink, exists, is_file, size_bytes = _inspect_metadata(path)
+
+    tags = _identify_tags(
+        path,
+        str_path,
+        exists=exists,
+        is_regular_or_symlink=is_file or is_symlink,
+    )
+    shebang, shebang_tags = _shebang_info(path, str_path, is_file=is_file, is_symlink=is_symlink)
+    tags.update(shebang_tags)
+
+    is_executable = _check_executable(path, exists=exists, shebang=shebang)
+    _adjust_nt_tags(tags, is_executable=is_executable)
+
+    mime_type, mime_tags = _mime_info(str_path)
+    tags.update(mime_tags)
+
+    relative_path = _resolve_relative(path, root_path)
+    resolved_path = path.resolve() if exists else path
+
+    return FileInfo(
+        path=resolved_path,
+        relative_path=relative_path,
+        tags=frozenset(tags),
+        shebang=shebang,
+        mime_type=mime_type,
+        is_executable=is_executable,
+        is_symlink=is_symlink,
+        size_bytes=size_bytes,
+    )

findfmt/cli.py

@@ -0,0 +1,262 @@
+"""Command-line interface for findfmt."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import Counter
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from findfmt.classifier import get_known_tags
+from findfmt.models import TraversalConfig
+from findfmt.traversal import find_files
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from findfmt.models import FileInfo
+
+
+def get_version() -> str:
+    """Retrieve package version or fallback string.
+
+    Returns:
+        Version string.
+    """
+    try:
+        return version("findfmt")
+    except PackageNotFoundError:
+        return "0.1.0.dev0"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct command-line argument parser.
+
+    Returns:
+        Configured ArgumentParser instance.
+    """
+    parser = argparse.ArgumentParser(
+        prog="findfmt",
+        description=(
+            "A .gitignore-aware file discovery and classification suite that locates "
+            "files by content format, shebang, and MIME tag."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        default=["."],
+        help="One or more directory or file paths to inspect (default: current directory).",
+    )
+
+    parser.add_argument(
+        "-t",
+        "--type",
+        "--tag",
+        dest="tags",
+        action="append",
+        help="Tag or comma-separated tags to match (e.g. 'python', 'yaml,json', 'executable').",
+    )
+
+    parser.add_argument(
+        "-e",
+        "--exclude",
+        "--exclude-tag",
+        dest="exclude_tags",
+        action="append",
+        help="Tag or comma-separated tags to exclude.",
+    )
+
+    parser.add_argument(
+        "--all-tags",
+        action="store_true",
+        help="Require matching files to have ALL specified tags rather than ANY tag.",
+    )
+
+    parser.add_argument(
+        "--shebang",
+        dest="shebang",
+        help="Filter files whose shebang contains this interpreter or pattern.",
+    )
+
+    parser.add_argument(
+        "--no-ignore",
+        action="store_true",
+        help="Do not respect .gitignore rules during traversal.",
+    )
+
+    parser.add_argument(
+        "--hidden",
+        action="store_true",
+        help="Include hidden files and directories.",
+    )
+
+    parser.add_argument(
+        "-L",
+        "--follow-symlinks",
+        action="store_true",
+        help="Follow symbolic links during traversal.",
+    )
+
+    parser.add_argument(
+        "--absolute",
+        action="store_true",
+        help="Output absolute paths rather than paths relative to the traversal root.",
+    )
+
+    parser.add_argument(
+        "-0",
+        "--print0",
+        action="store_true",
+        help=r"Delimit path outputs with a NUL (\0) character instead of a newline.",
+    )
+
+    parser.add_argument(
+        "-l",
+        "--list-tags",
+        action="store_true",
+        help="Display identified tags alongside each matched path.",
+    )
+
+    parser.add_argument(
+        "-s",
+        "--summary",
+        action="store_true",
+        help="Print summary match statistics to stderr.",
+    )
+
+    parser.add_argument(
+        "--known-tags",
+        action="store_true",
+        help="List all known classification tags supported by the engine and exit.",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {get_version()}",
+    )
+
+    return parser
+
+
+def parse_tag_arguments(tag_args: Sequence[str] | None) -> frozenset[str]:
+    """Parse repeatable or comma-delimited tag arguments into a normalized frozenset.
+
+    Args:
+        tag_args: Raw arguments provided to tag filter flags.
+
+    Returns:
+        frozenset of lowercase tag strings.
+    """
+    if not tag_args:
+        return frozenset[str]()
+
+    result: set[str] = set()
+    for arg in tag_args:
+        for tag in arg.split(","):
+            cleaned = tag.strip().lower()
+            if cleaned:
+                result.add(cleaned)
+
+    return frozenset(result)
+
+
+def _format_match(file_info: FileInfo, *, absolute: bool, show_tags: bool, delimiter: str) -> str:
+    """Format matching file information for stdout output.
+
+    Args:
+        file_info: Classified file information.
+        absolute: Whether to format using absolute path.
+        show_tags: Whether to append comma-separated tags.
+        delimiter: End of line delimiter string.
+
+    Returns:
+        Formatted string for output.
+    """
+    path_str = str(file_info.path if absolute else file_info.relative_path)
+    if show_tags:
+        tags_repr = ", ".join(sorted(file_info.tags))
+        return f"{path_str} [{tags_repr}]{delimiter}"
+
+    return f"{path_str}{delimiter}"
+
+
+def _write_summary(match_count: int, tag_counter: Counter[str]) -> None:
+    """Write execution summary to stderr.
+
+    Args:
+        match_count: Total number of files matched.
+        tag_counter: Frequency counter of tags matched.
+    """
+    sys.stderr.write(f"\n--- findfmt summary ---\nMatched files: {match_count}\n")
+    if tag_counter:
+        sys.stderr.write("Top tags:\n")
+        for tag, count in tag_counter.most_common(10):
+            sys.stderr.write(f"  {tag}: {count}\n")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main CLI entrypoint.
+
+    Args:
+        argv: Optional command-line arguments (defaults to sys.argv[1:]).
+
+    Returns:
+        Integer exit code (0 for success, 1 on error).
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.known_tags:
+        for tag in sorted(get_known_tags()):
+            sys.stdout.write(f"{tag}\n")
+
+        return 0
+
+    root_paths = tuple(Path(p) for p in args.paths)
+    config = TraversalConfig(
+        root_paths=root_paths,
+        include_tags=parse_tag_arguments(args.tags),
+        exclude_tags=parse_tag_arguments(args.exclude_tags),
+        all_tags=args.all_tags,
+        shebang_filter=args.shebang,
+        respect_gitignore=not args.no_ignore,
+        include_hidden=args.hidden,
+        follow_symlinks=args.follow_symlinks,
+        relative_paths=not args.absolute,
+        null_delimited=args.print0,
+        show_tags=args.list_tags,
+        show_summary=args.summary,
+    )
+
+    tag_counter: Counter[str] = Counter()
+    match_count = 0
+    delimiter = "\0" if config.null_delimited else "\n"
+
+    for file_info in find_files(config):
+        match_count += 1
+        if config.show_summary:
+            tag_counter.update(file_info.tags)
+
+        formatted = _format_match(
+            file_info,
+            absolute=args.absolute,
+            show_tags=config.show_tags,
+            delimiter=delimiter,
+        )
+        sys.stdout.write(formatted)
+
+    if config.show_summary:
+        _write_summary(match_count, tag_counter)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

findfmt/models.py

@@ -0,0 +1,64 @@
+"""Core data models and configurations for findfmt."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class FileInfo:
+    """Represents file metadata, classification tags, and content attributes.
+
+    Attributes:
+        path: Absolute path to the file.
+        relative_path: Path relative to the traversal root.
+        tags: Set of tags assigned by the classifier (e.g., 'python', 'text').
+        shebang: Extracted shebang line if present, otherwise None.
+        mime_type: Detected MIME type if available, otherwise None.
+        is_executable: Whether the file has executable permissions.
+        is_symlink: Whether the path is a symbolic link.
+        size_bytes: File size in bytes.
+    """
+
+    path: Path
+    relative_path: Path
+    tags: frozenset[str] = field(default_factory=frozenset)
+    shebang: str | None = None
+    mime_type: str | None = None
+    is_executable: bool = False
+    is_symlink: bool = False
+    size_bytes: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class TraversalConfig:
+    r"""Configuration options for repository traversal and format filtering.
+
+    Attributes:
+        root_paths: Roots from which to begin file discovery.
+        include_tags: Tags that files must have to be included.
+        exclude_tags: Tags that disqualify a file from inclusion.
+        all_tags: If True, file must match all include_tags; if False, any tag.
+        shebang_filter: Substring or interpreter name required in shebang.
+        respect_gitignore: Whether to ignore paths matched by gitignore rules.
+        include_hidden: Whether to inspect hidden files and directories.
+        follow_symlinks: Whether to resolve and traverse symbolic links.
+        relative_paths: Whether to output relative paths rather than absolute.
+        null_delimited: Whether to delimit output paths with NUL bytes (\0).
+        show_tags: Whether to print identified tags alongside file paths.
+        show_summary: Whether to output summary statistics of matches.
+    """
+
+    root_paths: tuple[Path, ...] = field(default_factory=lambda: (Path(),))
+    include_tags: frozenset[str] = field(default_factory=frozenset)
+    exclude_tags: frozenset[str] = field(default_factory=frozenset)
+    all_tags: bool = False
+    shebang_filter: str | None = None
+    respect_gitignore: bool = True
+    include_hidden: bool = False
+    follow_symlinks: bool = False
+    relative_paths: bool = True
+    null_delimited: bool = False
+    show_tags: bool = False
+    show_summary: bool = False

findfmt/traversal.py

@@ -0,0 +1,297 @@
+"""Git-conscious directory traversal and filtering engine."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pathspec
+
+from findfmt.classifier import classify_file
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from findfmt.models import FileInfo, TraversalConfig
+
+PathSpecType = pathspec.PathSpec[Any]
+
+
+def load_gitignore_spec(directory: Path) -> PathSpecType | None:
+    """Load gitignore patterns from a directory if a .gitignore file exists.
+
+    Args:
+        directory: Directory to check for .gitignore.
+
+    Returns:
+        PathSpec instance if rules exist, or None.
+    """
+    gitignore_file = directory / ".gitignore"
+    if gitignore_file.is_file():
+        try:
+            with gitignore_file.open("r", encoding="utf-8", errors="replace") as f:
+                lines = [line.strip() for line in f if line.strip() and not line.startswith("#")]
+                if lines:
+                    return pathspec.PathSpec.from_lines("gitignore", lines)
+        except OSError:
+            return None
+
+    return None
+
+
+def load_git_exclude_spec(root: Path) -> PathSpecType | None:
+    """Load exclude patterns from .git/info/exclude if present.
+
+    Args:
+        root: Git repository root directory.
+
+    Returns:
+        PathSpec instance if exclude patterns exist, or None.
+    """
+    exclude_file = root / ".git" / "info" / "exclude"
+    if exclude_file.is_file():
+        try:
+            with exclude_file.open("r", encoding="utf-8", errors="replace") as f:
+                lines = [line.strip() for line in f if line.strip() and not line.startswith("#")]
+                if lines:
+                    return pathspec.PathSpec.from_lines("gitignore", lines)
+        except OSError:
+            return None
+
+    return None
+
+
+def should_skip_dir(dir_name: str, *, include_hidden: bool) -> bool:
+    """Determine if a directory should be skipped during descent.
+
+    Args:
+        dir_name: Basename of directory.
+        include_hidden: Whether hidden directories are included.
+
+    Returns:
+        True if the directory should be skipped, False otherwise.
+    """
+    if dir_name == ".git":
+        return True
+
+    return bool(not include_hidden and dir_name.startswith("."))
+
+
+def matches_filter(file_info: FileInfo, config: TraversalConfig) -> bool:
+    """Determine whether a classified file satisfies traversal filter criteria.
+
+    Args:
+        file_info: The classified FileInfo object.
+        config: The active TraversalConfig filter settings.
+
+    Returns:
+        True if the file satisfies all filters, False otherwise.
+    """
+    tags = file_info.tags
+
+    # Check exclude tags first
+    if config.exclude_tags and (tags & config.exclude_tags):
+        return False
+
+    # Check include tags
+    if config.include_tags:
+        if config.all_tags and not config.include_tags.issubset(tags):
+            return False
+
+        if not config.all_tags and not (tags & config.include_tags):
+            return False
+
+    # Check shebang filter
+    if config.shebang_filter:
+        return bool(file_info.shebang and config.shebang_filter in file_info.shebang)
+
+    return True
+
+
+def _load_active_specs(
+    root: Path,
+    active_specs: tuple[tuple[Path, PathSpecType], ...],
+    *,
+    respect_gitignore: bool,
+) -> tuple[tuple[Path, PathSpecType], ...]:
+    """Assemble active gitignore specifications for a given directory."""
+    if not respect_gitignore:
+        return ()
+
+    current_specs = list(active_specs)
+    if not active_specs:
+        git_exclude = load_git_exclude_spec(root)
+        if git_exclude:
+            current_specs.append((root, git_exclude))
+
+    local_spec = load_gitignore_spec(root)
+    if local_spec:
+        current_specs.append((root, local_spec))
+
+    return tuple(current_specs)
+
+
+def _is_path_ignored(
+    entry_path: Path,
+    *,
+    is_dir: bool,
+    specs: tuple[tuple[Path, PathSpecType], ...],
+) -> bool:
+    """Check if an entry matches any active gitignore rule."""
+    for base_dir, spec in specs:
+        if not entry_path.is_relative_to(base_dir):
+            continue
+
+        rel = entry_path.relative_to(base_dir)
+        rel_str = str(rel) + ("/" if is_dir else "")
+        if spec.match_file(rel_str):
+            return True
+
+    return False
+
+
+def _scan_directory_entries(
+    root: Path,
+    config: TraversalConfig,
+    specs: tuple[tuple[Path, PathSpecType], ...],
+) -> tuple[list[Path], list[Path]]:
+    """Scan and partition directory entries into subdirectories and files."""
+    try:
+        entries = sorted(os.scandir(root), key=lambda e: e.name)
+    except OSError:
+        return [], []
+
+    subdirs: list[Path] = []
+    files: list[Path] = []
+
+    for entry in entries:
+        if not config.include_hidden and entry.name.startswith("."):
+            continue
+
+        entry_path = Path(entry.path)
+        is_dir = entry.is_dir(follow_symlinks=config.follow_symlinks)
+
+        if config.respect_gitignore and _is_path_ignored(entry_path, is_dir=is_dir, specs=specs):
+            continue
+
+        if is_dir:
+            if not should_skip_dir(entry.name, include_hidden=config.include_hidden):
+                subdirs.append(entry_path)
+        elif entry.is_file(follow_symlinks=config.follow_symlinks):
+            files.append(entry_path)
+
+    return subdirs, files
+
+
+def _should_skip_symlink_dir(
+    subdir: Path,
+    *,
+    follow_symlinks: bool,
+    visited: set[Path] | None,
+) -> bool:
+    """Determine whether a candidate directory should be skipped to break symlink loops.
+
+    Args:
+        subdir: Directory path candidate.
+        follow_symlinks: Traversal configuration flag for following symlinks.
+        visited: Set of canonical directory paths already visited.
+
+    Returns:
+        True if the directory should be skipped, False otherwise.
+    """
+    if not (follow_symlinks and visited is not None):
+        return False
+
+    try:
+        resolved = subdir.resolve()
+    except OSError:
+        return True
+
+    if resolved in visited:
+        return True
+
+    visited.add(resolved)
+    return False
+
+
+def traverse_directory(
+    root: Path,
+    config: TraversalConfig,
+    active_specs: tuple[tuple[Path, PathSpecType], ...] = (),
+    base_root: Path | None = None,
+    visited_dirs: set[Path] | None = None,
+) -> Iterator[FileInfo]:
+    """Recursively traverse a directory hierarchy honoring .gitignore and filters.
+
+    Args:
+        root: The current directory to traverse.
+        config: Traversal configuration options.
+        active_specs: Inherited parent gitignore specs with their base paths.
+        base_root: The top-level root directory used for relative paths.
+        visited_dirs: Tracked set of canonical directory paths visited to break cycles.
+
+    Yields:
+        FileInfo objects for matching files in deterministic sorted order.
+    """
+    effective_base = base_root if base_root is not None else root
+    active_visited = visited_dirs
+    if config.follow_symlinks and active_visited is None:
+        active_visited = set()
+        with contextlib.suppress(OSError):
+            active_visited.add(root.resolve())
+
+    specs = _load_active_specs(
+        root,
+        active_specs,
+        respect_gitignore=config.respect_gitignore,
+    )
+    subdirs, files = _scan_directory_entries(root, config, specs)
+
+    for file_path in files:
+        info = classify_file(file_path, root_path=effective_base)
+        if matches_filter(info, config):
+            yield info
+
+    for subdir in subdirs:
+        if _should_skip_symlink_dir(
+            subdir,
+            follow_symlinks=config.follow_symlinks,
+            visited=active_visited,
+        ):
+            continue
+
+        yield from traverse_directory(
+            subdir,
+            config,
+            specs,
+            base_root=effective_base,
+            visited_dirs=active_visited,
+        )
+
+
+def find_files(config: TraversalConfig) -> Iterator[FileInfo]:
+    """Discover and classify files across all configured root paths.
+
+    Args:
+        config: Traversal and filtering configuration.
+
+    Yields:
+        FileInfo objects matching the criteria.
+    """
+    for root in sorted(config.root_paths):
+        resolved_root = root.resolve()
+        if not resolved_root.exists():
+            continue
+
+        if resolved_root.is_file():
+            info = classify_file(resolved_root, root_path=resolved_root.parent)
+            if matches_filter(info, config):
+                yield info
+        else:
+            yield from traverse_directory(
+                resolved_root,
+                config,
+                base_root=resolved_root,
+            )

findfmt-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.5
+Name: findfmt
+Version: 0.1.0
+Summary: A.gitignore-aware file discovery and classification suite that locates files by content format, shebang, and MIME tag for automated linting, formatting, and CI pipelines.
+Project-URL: Changelog, https://github.com/bdperkin/findfmt/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://bdperkin.github.io/findfmt
+Project-URL: Homepage, https://github.com/bdperkin/findfmt
+Project-URL: Issues, https://github.com/bdperkin/findfmt/issues
+Project-URL: Repository, https://github.com/bdperkin/findfmt
+Author-email: Brandon Perkins <bdperkin@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: classification,discovery,find,format,gitignore,identify,linting,mime,shebang
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: identify>=2.6
+Requires-Dist: pathspec>=0.12
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" alt="findfmt Logo" width="600" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/bdperkin/findfmt/actions/workflows/ci.yml"><img src="https://github.com/bdperkin/findfmt/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a>
+  <a href="https://github.com/bdperkin/findfmt/actions/workflows/codeql.yml"><img src="https://github.com/bdperkin/findfmt/actions/workflows/codeql.yml/badge.svg" alt="CodeQL Analysis" /></a>
+  <a href="https://github.com/bdperkin/findfmt/actions/workflows/docs.yml"><img src="https://github.com/bdperkin/findfmt/actions/workflows/docs.yml/badge.svg" alt="Documentation Status" /></a>
+  <a href="https://results.pre-commit.ci/latest/github/bdperkin/findfmt/main"><img src="https://results.pre-commit.ci/badge/github/bdperkin/findfmt/main.svg" alt="pre-commit.ci status" /></a>
+  <a href="https://codecov.io/gh/bdperkin/findfmt"><img src="https://codecov.io/gh/bdperkin/findfmt/branch/main/graph/badge.svg" alt="Coverage" /></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/findfmt/"><img src="https://img.shields.io/pypi/v/findfmt.svg?logo=pypi&logoColor=white" alt="PyPI Version" /></a>
+  <a href="https://pypi.org/project/findfmt/"><img src="https://img.shields.io/pypi/pyversions/findfmt.svg?logo=python&logoColor=white" alt="Python Versions" /></a>
+  <a href="https://pypi.org/project/findfmt/"><img src="https://img.shields.io/pypi/wheel/findfmt.svg" alt="PyPI Wheel" /></a>
+  <a href="https://github.com/bdperkin/findfmt/pkgs/container/findfmt"><img src="https://img.shields.io/badge/GHCR-container-blue?logo=docker&logoColor=white" alt="GHCR Container" /></a>
+  <a href="https://github.com/bdperkin/findfmt/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv" /></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" /></a>
+  <a href="https://github.com/astral-sh/ty"><img src="https://img.shields.io/badge/type--checked-ty-blueviolet" alt="Type-checked: ty" /></a>
+  <a href="https://interrogate.readthedocs.io/"><img src="https://img.shields.io/badge/interrogate-100%25-brightgreen" alt="Docstring Coverage: 100%" /></a>
+  <a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg" alt="Conventional Commits" /></a>
+  <a href="ACCESSIBILITY.md"><img src="https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-blue" alt="Accessibility WCAG 2.1 AA" /></a>
+</p>
+
+______________________________________________________________________
+
+> **A `.gitignore`-aware file discovery and classification suite that locates files by content
+> format, shebang, and MIME tag for automated linting, formatting, and CI pipelines.**
+
+## 1. Why findfmt?
+
+Unlike traditional `find` or globbing tools that rely strictly on file extensions, `findfmt`:
+
+- **Understands file content**: Identifies format by content, shebang (`#!/usr/bin/env python3`),
+  and MIME types using the `identify` engine.
+- **Respects Git**: Traverses trees hierarchically while pruning `.gitignore` and
+  `.git/info/exclude` paths early before descending into large directories (e.g. `node_modules/`,
+  `.venv/`).
+- **Deterministic**: Always returns clean, relative, deterministically sorted paths optimized for
+  subshells, xargs, and automation.
+
+______________________________________________________________________
+
+## 2. Installation
+
+### 2.1. With `uv` (Recommended)
+
+Run directly with `uvx`:
+
+```bash
+uvx findfmt --help
+```
+
+Install globally:
+
+```bash
+uv tool install findfmt
+```
+
+Or add to your project:
+
+```bash
+uv add findfmt
+```
+
+### 2.2. With `pip`
+
+```bash
+pip install findfmt
+```
+
+### 2.3. With Docker / Container
+
+```bash
+docker pull ghcr.io/bdperkin/findfmt:latest
+docker run --rm -v "$(pwd)":/workspace -w /workspace ghcr.io/bdperkin/findfmt:latest -t python
+```
+
+______________________________________________________________________
+
+## 3. Usage
+
+### 3.1. Locate Files by Tag / Format
+
+```bash
+# Locate all Python files
+findfmt -t python
+
+# Locate all YAML and JSON files
+findfmt -t yaml,json
+
+# Locate shell scripts
+findfmt -t shell
+```
+
+### 3.2. Shebang Filtering
+
+```bash
+# Locate files with bash shebang
+findfmt --shebang bash
+
+# Locate scripts executing with python
+findfmt --shebang python
+```
+
+### 3.3. Pipe Safely to Linters and Tools
+
+Use `-0` for NUL-delimited output with `xargs -0`:
+
+```bash
+# Format discovered Python files
+findfmt -t python -0 | xargs -0 ruff format
+
+# Lint shell scripts with shellcheck
+findfmt -t shell -0 | xargs -r -0 shellcheck
+```
+
+### 3.4. Inspect Tags & Summaries
+
+```bash
+# Print matched files and their classification tags
+findfmt -l -t python
+
+# Print summary statistics to stderr
+findfmt -s
+```
+
+______________________________________________________________________
+
+## 4. CLI Options
+
+| Flag                           | Description                                        |
+| ------------------------------ | -------------------------------------------------- |
+| `-t, --tag, --type`            | Match files containing specified tag(s)            |
+| `-e, --exclude, --exclude-tag` | Exclude files containing specified tag(s)          |
+| `--all-tags`                   | Require match against all include tags (AND logic) |
+| `--shebang`                    | Match shebang interpreter name or pattern          |
+| `--no-ignore`                  | Do not prune paths matching `.gitignore`           |
+| `--hidden`                     | Inspect hidden files and directories               |
+| `-0, --print0`                 | NUL-delimited output for `xargs -0`                |
+| `-l, --list-tags`              | Print tags alongside file paths                    |
+| `-s, --summary`                | Print match frequencies to stderr                  |
+| `--absolute`                   | Output absolute rather than relative paths         |
+| `--known-tags`                 | List all supported classification tags             |
+| `-v, --version`                | Display version and exit                           |
+
+______________________________________________________________________
+
+## 5. Development & Testing
+
+This project enforces 100% test coverage and strict type checking:
+
+```bash
+# Clone the repository
+git clone https://github.com/bdperkin/findfmt.git
+cd findfmt
+
+# Install dependencies with uv
+uv sync --all-groups
+
+# Run tests and verify 100% coverage
+uv run pytest
+
+# Run linting and typing
+uv run ruff check
+uv run ty check
+
+# Run full verification suite
+uv run python tools/verify_quality.py
+```
+
+______________________________________________________________________
+
+## 6. Governance & Community
+
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
+- [Support Information](SUPPORT.md)
+- [Accessibility Statement](ACCESSIBILITY.md)
+
+## 7. License
+
+[MIT License](LICENSE) © 2026 Brandon Perkins.

findfmt-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+findfmt/__init__.py,sha256=XEJBW3qrJKLsExfWyvx3M5tIRKfyBECf8UA4Uw24Vbk,549
+findfmt/__main__.py,sha256=Y38nYVtAEYxkPM-8pJSmIiIL1maIJEPnsl8-ZXsdCek,188
+findfmt/classifier.py,sha256=KCkYwjcHOG9-IhWTIApZ_zjPLX_lLrOSOaMdKpY8pG0,7089
+findfmt/cli.py,sha256=A3T_JkiDzUrAq0mpXw6Yp6aUB-LKiulnqrYAOpbvQ0c,6964
+findfmt/models.py,sha256=3903OEMGOY9w39TSYZWbsJItcnO7WTy_20wwoQwjHvE,2585
+findfmt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+findfmt/traversal.py,sha256=EjYA7-pEJIclK24MBik4AyBc4F2PdaBj1Q3K76TQHoE,8681
+findfmt-0.1.0.dist-info/METADATA,sha256=icoW7gl_O3t19evOKUXmJxynfPrTInmUYI8o1sqiVHM,8745
+findfmt-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+findfmt-0.1.0.dist-info/entry_points.txt,sha256=1mZdpaiLuEes0P-UzwIy7yvg0YChbQiFUpBQodfKZmE,45
+findfmt-0.1.0.dist-info/licenses/LICENSE,sha256=3U-6gkW73x_v0Qc79rs2mQfYVYQAawO7tHREHDkO3UA,1072
+findfmt-0.1.0.dist-info/RECORD,,

findfmt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

findfmt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+findfmt = findfmt.cli:main

findfmt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Perkins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.