Metadata-Version: 2.4
Name: fast-gate-py
Version: 0.1.0
Summary: Deterministic pre-flight fact generator that satisfies Fact-Forcing Gate hooks on the first attempt
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: repodigest-py>=0.1.0

# fast-gate

Deterministic pre-flight facts for Fact-Forcing Gate (GateGuard-style) hooks.

Hooks like GateGuard reject a `Write` or `Update` unless the agent first states: who calls the file, that nothing
already serves the same purpose, the schema of any data it touches, and the user's instruction verbatim. `fast-gate`
computes the first three from the workspace and formats all four, so the agent does not have to research or reformat
them by hand.

## Install

```bash
uv pip install -e .        # or: pip install -e .
```

The package is published as `fast-gate-py`; the command is `fast-gate`. Python 3.10+.

## Use

```bash
# print the four-point block for a file you are about to write
fast-gate inspect src/app/export.py --instruction "Add a CSV exporter to app" --root .

# exit 0 if the target is safe to write, 1 (with reasons on stderr) otherwise
fast-gate check src/app/export.py
```

Relative targets are resolved from the current directory; `--root` (default `.`) is the workspace to scan.

Example output:

```markdown
## Pre-flight facts for `src/app/export.py` (create new file)

### 1. Callers / importers

- No existing file imports or references the target.
- Planned caller / entry point: `src/app/cli.py` (console script `app = app.cli:main`) is expected to import or dispatch to it

### 2. Non-duplication

- Searched 14 file(s) under the workspace root (skipped: .git, .venv, venv, __pycache__, ...).
- No file has the same name, the same stem, or a similar name; nothing existing serves this purpose.

### 3. Data schemas

- N/A: the target does not exist yet and the instruction names no data file; ...

### 4. Verbatim user instruction

> Add a CSV exporter to app
```

## What it checks

| Fact | How |
| --- | --- |
| Callers / importers | AST scan of every `.py` file for imports of the target (absolute, relative, aliased, `from pkg import module`), with line numbers. Non-code targets are matched by string literals. New files get a planned entry point from `[project.scripts]`, the package `__init__`, or pytest collection. |
| Non-duplication | Same name, same stem, or a similar name (difflib ratio >= 0.8) anywhere in the tree, ignoring `.git`, `.venv`, `venv`, `__pycache__`, caches, and build output. |
| Data schemas | CSV, JSON, JSONL, SQLite, and YAML are read; Parquet needs `pyarrow`, and YAML values need `PyYAML` (otherwise keys only). Output is field names, type names, date-format names, and a synthetic example row. Values are never printed, and SQLite is opened read-only without reading rows. |
| Verbatim instruction | Passed through `--instruction`, quoted line for line. |

Workspace text (paths, field names, source lines) is stripped of backticks and control characters before it is put in the block, so a hostile CSV header cannot forge a heading.

## Claude Code integration

- `skills/fast-gate.md`: the skill. Copy it to `~/.claude/skills/fast-gate/SKILL.md` (or a project's `.claude/skills/`) to have Claude run `fast-gate inspect` before guarded writes.
- `.claude/commands/fast-gate.md`: the `/fast-gate <target_file>` slash command for this repo.

Some hooks deny the first attempt on every new file no matter what was presented, then accept an identical retry.
`fast-gate` cannot change that behavior; it makes the facts correct and complete so the retry is a single call.

## Development

```bash
./venv/bin/pytest tests/ -v
ruff check .
```
