pyossmtool 0.0.1__tar.gz → 0.0.3__tar.gz

pyossmtool-0.0.3/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: pyossmtool
+Version: 0.0.3
+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: Topic :: Software Development :: Quality Assurance
+Requires-Python: <3.14,>=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.13.
+
+## 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

pyossmtool-0.0.3/README.md

@@ -0,0 +1,230 @@
+# 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.13.
+
+## 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

{pyossmtool-0.0.1 → pyossmtool-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyossmtool"
-version = "0.0.1"
+version = "0.0.3"
 description = "Quality-gate orchestrator for AI-assisted development"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{pyossmtool-0.0.1 → pyossmtool-0.0.3}/src/pyossmtool/__init__.py

@@ -1,3 +1,3 @@
 """pyossmtool — quality-gate orchestrator for AI-assisted development."""
 
-__version__ = "0.0.1"
+__version__ = "0.0.3"

pyossmtool-0.0.3/src/pyossmtool/bundle/suites/all.yaml

@@ -0,0 +1,51 @@
+id: all
+name: All Checks
+description: Full catalog — every bundled check (check-mode and format-apply). Use
+  pyossmtool check for report-only checks and pyossmtool format for apply checks.
+env: auto
+target: .
+ignore-profile:
+  - .gitignore
+  - .cursorignore
+ignore-paths:
+  - .pyossmtool/
+  - venv/
+  - .venv/
+  - reports/
+  - sample_files/
+checks:
+  - id: ruff.format
+  - id: ruff.lint
+  - id: ruff.unused
+  - id: ty.check
+  - id: bandit.scan
+  - id: gitleaks.secrets
+  - id: semgrep.scan
+  - id: deadcode.scan
+  - id: vulture.scan
+  - id: pydeps.cycles
+  - id: radon.cc
+  - id: radon.mi
+  - id: jscpd.duplication
+  - id: shfmt.format
+  - id: shellcheck
+  - id: mdformat.format
+  - id: markdownlint.check
+  - id: yamlfmt.format
+  - id: yamllint.check
+  - id: codespell.spelling
+  - id: pytest.test
+    target: tests/
+  - id: pytest.coverage
+    target: tests/
+  - id: hadolint.dockerfile
+  - id: mutmut.run
+  - id: sourcery.review
+  - id: gate.module-size
+  - id: gate.module-private-vars
+  - id: gate.folder-breadth
+  - id: gate.acronym-allowlist
+  - id: ruff.format.apply
+  - id: shfmt.apply
+  - id: mdformat.apply
+  - id: yamlfmt.apply

{pyossmtool-0.0.1 → pyossmtool-0.0.3}/src/pyossmtool/cli.py

@@ -7,9 +7,10 @@ from pathlib import Path
 
 import typer
 
+from pyossmtool.error_formatters import ErrorFormatter, format_report_file, resolve_error_formatter
 from pyossmtool.gates import lib_path, scaffold_gate
 from pyossmtool.installer import Installer
-from pyossmtool.models import CheckMode, FailureReport
+from pyossmtool.models import CheckMode, FailureReport, ProjectConfig
 from pyossmtool.registry import Registry
 from pyossmtool.runner import Runner
 
@@ -88,12 +89,22 @@ def export_schema() -> None:
 
 @app.command("install")
 def install(
-    suite: str = typer.Option("demo", "--suite", help="Suite whose tool dependencies to install"),
+    suite: str | None = typer.Option(
+        None,
+        "--suite",
+        help="Suite whose tools to install (default: suite from pyossmtool.yaml)",
+    ),
 ) -> None:
     registry = _registry()
-    installer = Installer(registry, _project_root())
+    project_root = _project_root()
+    project_config = registry.load_project_config(project_root)
+    suite_id = suite or (project_config.suite if project_config else None)
+    if not suite_id:
+        typer.echo("SETUP provide --suite or set suite: in pyossmtool.yaml", err=True)
+        raise typer.Exit(code=2)
+    installer = Installer(registry, project_root)
     try:
-        installer.install_suite(suite)
+        installer.install_suite(suite_id)
     except Exception as exc:
         typer.echo(f"SETUP {exc}", err=True)
         raise typer.Exit(code=2) from exc
@@ -101,7 +112,11 @@ def install(
 
 @app.command("check")
 def check_cmd(
-    suite: str | None = typer.Option(None, "--suite", help="Suite id to run"),
+    suite: str | None = typer.Option(
+        None,
+        "--suite",
+        help="Suite id to run (default: suite from pyossmtool.yaml)",
+    ),
     check: str | None = typer.Option(None, "--check", help="Single check id to run"),
     target: str | None = typer.Option(None, "--target", help="Target path for single check"),
     fail_fast: bool = typer.Option(False, "--fail-fast", help="Stop at first failure"),
@@ -113,7 +128,11 @@ def check_cmd(
 
 @app.command("format")
 def format_cmd(
-    suite: str | None = typer.Option("format", "--suite", help="Suite id to run"),
+    suite: str | None = typer.Option(
+        None,
+        "--suite",
+        help="Suite id to run (default: suite from pyossmtool.yaml)",
+    ),
     check: str | None = typer.Option(None, "--check", help="Single check id to run"),
     target: str | None = typer.Option(None, "--target", help="Target path for single check"),
     fail_fast: bool = typer.Option(False, "--fail-fast", help="Stop at first failure"),
@@ -134,14 +153,19 @@ def _execute(
     registry = _registry()
     project_root = _project_root()
     project_config = registry.load_project_config(project_root)
+    try:
+        formatter = resolve_error_formatter(project_config)
+    except (KeyError, ValueError, RuntimeError) as exc:
+        typer.echo(f"SETUP {exc}", err=True)
+        return 2
     runner = Runner(registry, project_root, verbose=verbose)
 
     if check:
-        return _run_single_check(runner, check, target, suite, project_config, mode)
+        return _run_single_check(runner, check, target, suite, project_config, mode, formatter)
 
     suite_id = suite or (project_config.suite if project_config else None)
     if not suite_id:
-        typer.echo("SETUP provide --suite or create pyossmtool.yaml", err=True)
+        typer.echo("SETUP provide --suite or set suite: in pyossmtool.yaml", err=True)
         return 2
 
     try:
@@ -154,7 +178,7 @@ def _execute(
     except KeyError as exc:
         typer.echo(f"SETUP {exc}", err=True)
         return 2
-    return _emit_suite_result(suite_result)
+    return _emit_suite_result(suite_result, formatter)
 
 
 def _run_single_check(
@@ -162,8 +186,9 @@ def _run_single_check(
     check: str,
     target: str | None,
     suite: str | None,
-    project_config,
+    project_config: ProjectConfig | None,
     mode: CheckMode,
+    formatter: ErrorFormatter,
 ) -> int:
     if not target:
         typer.echo("SETUP --target is required with --check", err=True)
@@ -181,35 +206,42 @@ def _run_single_check(
         suite_id=suite or (project_config.suite if project_config else None),
         project_config=project_config,
     )
-    return _exit_for_check_result(result)
+    return _exit_for_check_result(result, formatter)
 
 
-def _exit_for_check_result(result) -> int:
+def _exit_for_check_result(result, formatter: ErrorFormatter) -> int:
     if result.error:
         typer.echo(f"SETUP {result.error}", err=True)
         return 2
     if result.passed:
         return 0
-    typer.echo(f"FAIL {result.check_id} -> {result.report_path}", err=True)
+    _emit_failed_check(result, formatter)
     return 1
 
 
-def _emit_suite_result(suite_result) -> int:
+def _emit_suite_result(suite_result, formatter: ErrorFormatter) -> int:
     if suite_result.passed:
         return 0
     for result in suite_result.results:
-        _emit_failed_check(result)
+        _emit_failed_check(result, formatter)
     return 1
 
 
-def _emit_failed_check(result) -> None:
+def _emit_failed_check(result, formatter: ErrorFormatter) -> None:
     if result.passed:
         return
     if result.error:
         typer.echo(f"SETUP {result.check_id}: {result.error}", err=True)
         return
-    if result.report_path:
+    if not result.report_path:
+        return
+    try:
+        text = format_report_file(result.report_path, formatter)
+    except (OSError, ValueError, RuntimeError) as exc:
+        typer.echo(f"SETUP failed to format report for {result.check_id}: {exc}", err=True)
         typer.echo(f"FAIL {result.check_id} -> {result.report_path}", err=True)
+        return
+    typer.echo(text, err=True)
 
 
 def main() -> None: