Metadata-Version: 2.4
Name: pyossmtool
Version: 0.0.4
Summary: Quality-gate orchestrator for AI-assisted development
Author-email: Vishal Kumar Mishra <vishal.k.mishra2@gmail.com>
License-Expression: MIT
Project-URL: Changelog, https://github.com/inquilabee/pyossmtool/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/inquilabee/pyossmtool
Project-URL: Issues, https://github.com/inquilabee/pyossmtool/issues
Project-URL: Repository, https://github.com/inquilabee/pyossmtool
Keywords: quality,lint,format,pre-commit,python,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pathspec>=0.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Dynamic: license-file

# pyossmtool

Quality gates for Python repos that developers can run locally, in CI, or hand to an AI agent without inventing a new workflow each time.

`pyossmtool` gives you one project config, a bundled catalog of checks, quiet success, and structured failure reports. It is inspired by Trunk and pre-commit, but keeps the surface area small:

```bash
pyossmtool install
pyossmtool format
pyossmtool check
```

## Install

```bash
pip install pyossmtool
# or
uv add --dev pyossmtool
```

Requires Python 3.11–3.14.

## 60-Second Setup

Create `pyossmtool.yaml`:

```yaml
suite: all
env: auto
target: .
error-format: compact
configs:
  mode: auto
```

Then run:

```bash
pyossmtool install   # install tools needed by suite:
pyossmtool format    # apply formatter/autofix checks
pyossmtool check     # report-only quality checks
```

The `suite:` value is the project default. You do not need to repeat `--suite all`; the CLI reads it from `pyossmtool.yaml`.

Success is silent and exits `0`. Failures exit `1`, write a JSON report under `reports/failures/`, and print the same report through your configured `error-format`.

## Mental Model

- **Suite**: a named checklist, such as `python-quality`, `standard`, or `all`.
- **Check**: one rule runner inside a suite, such as `ruff.lint` or `ty.check`.
- **`check`**: report-only. It should not rewrite your files.
- **`format`**: applies write/fix checks, such as formatters.
- **`install`**: installs the tools needed by the selected suite.

Most teams pick a suite once in `pyossmtool.yaml` and run the same three commands everywhere.

## Config That Matters

```yaml
suite: python-quality   # default checklist for install/check/format
env: auto               # auto | managed | project
target: .               # scan root; defaults to .
error-format: compact   # json | log | text | compact | github

configs:
  mode: auto            # repo configs first, bundled fallback
```

Use `--suite` only when you want a one-off override:

```bash
pyossmtool check --suite extended
pyossmtool install --suite standard
```

Copy [`pyossmtool.yaml.example`](pyossmtool.yaml.example) for an annotated config with ignores, custom checks, gates, and custom error formatters.

## Suites

Suites are bundled starting points. They choose which checks run; tools still discover their own files and `.gitignore` is always respected.

| Suite | Use it for |
| --- | --- |
| `all` | Run every bundled check |
| `python-quality` | Core Python lint, format-check, and type checks |
| `formatting` | Report-only formatting drift |
| `format` | Formatter/autofix checks that write files |
| `standard` | Broader portable quality baseline |
| `extended` | Slower optional checks on top of standard |
| `policy` | Bundled script gates |
| `demo` | Internal/sample fixture suite |

Examples:

```yaml
# Local Python repo
suite: python-quality
error-format: text
```

```yaml
# CI baseline with GitHub annotations
suite: standard
error-format: github
```

```yaml
# Max coverage while developing pyossmtool itself
suite: all
error-format: compact
```

## Error Output

On failure, pyossmtool always writes the canonical JSON report to disk:

```text
reports/failures/ruff.lint-20260716T163000Z/report.json
```

`error-format` only controls what is printed to stderr.

| Format | Example output |
| --- | --- |
| `json` | Pretty JSON report, including `report_path` |
| `log` | `2026-07-16T12:00:00+00:00 [error] ruff.lint/E501 src/app.py:42: Line too long` |
| `text` | `- [error] E501: Line too long (src/app.py:42)` |
| `compact` | `src/app.py:42: error: E501 Line too long` |
| `github` | `::error file=src/app.py,title=ruff.lint/E501,line=42::Line too long` |

Default is `json` when `error-format` is omitted.

Custom formatters live in `pyossmtool.yaml`:

```yaml
suite: all
error-format: short
error-formatters:
  short:
    kind: finding_line
    template: "{severity}\t{rule_id}\t{file}:{line}\t{message}"
  jq-summary:
    kind: jq
    program: >
      .findings[] | "[\(.severity)] \(.rule_id) \(.message)"
```

`finding_line` placeholders: `severity`, `rule_id`, `message`, `file`, `line`, `check_id`, `report_path`.

`jq` formatters require `jq` on `PATH`.

## Daily Commands

```bash
pyossmtool install
pyossmtool format
pyossmtool check
```

Inspect what is available:

```bash
pyossmtool list suites
pyossmtool list tools
pyossmtool list checks
```

Run a single check:

```bash
pyossmtool check --check ruff.lint --target .
```

Export the failure report schema:

```bash
pyossmtool schema > failure-report.schema.json
```

## Project-Local Gates

Use gates when a repo needs a policy that is not covered by the bundled catalog.

```bash
pyossmtool gate init module-size --description "Cap module line counts"
```

That creates a shell gate under `.pyossmtool/gates/` and a catalog entry under `.pyossmtool/catalog/checks/`. Enable it from `pyossmtool.yaml`:

```yaml
checks:
  - id: gate.module-size
```

## CI

Minimal GitHub Actions job:

```yaml
name: quality

on:
  pull_request:
  push:
    branches: [main]

jobs:
  pyossmtool:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
      - run: uvx pyossmtool install
      - run: uvx pyossmtool check
```

For GitHub PR annotations, set:

```yaml
error-format: github
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, adding tools/checks, and release notes.

## License

MIT
