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.
