pyossmtool 0.0.2__tar.gz → 0.0.4__tar.gz

pyossmtool-0.0.4/PKG-INFO

@@ -0,0 +1,260 @@
+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

pyossmtool-0.0.4/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.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

{pyossmtool-0.0.2 → pyossmtool-0.0.4}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "pyossmtool"
-version = "0.0.2"
+version = "0.0.4"
 description = "Quality-gate orchestrator for AI-assisted development"
 readme = "README.md"
-requires-python = ">=3.11,<3.14"
+requires-python = ">=3.11,<3.15"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [
@@ -26,6 +26,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
 dependencies = [
@@ -83,7 +84,10 @@ line-length = 120
 target-version = "py311"
 
 [tool.ruff.lint]
-select = ["B", "E", "F", "I", "UP"]
+select = ["B", "C90", "E", "F", "I", "UP"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
 
 [tool.ty]
 # Repo-owned config; wins over bundled defaults when configs.mode=auto

{pyossmtool-0.0.2 → pyossmtool-0.0.4}/src/pyossmtool/__init__.py

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

pyossmtool-0.0.4/src/pyossmtool/bundle/defaults/configs/ruff.toml

@@ -0,0 +1,11 @@
+line-length = 120
+target-version = "py311"
+
+[lint]
+select = ["E", "F", "I", "UP", "B", "C90"]
+
+[lint.mccabe]
+max-complexity = 10
+
+[format]
+quote-style = "double"

{pyossmtool-0.0.2 → pyossmtool-0.0.4}/src/pyossmtool/cli.py

@@ -89,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
@@ -102,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"),
@@ -114,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"),
@@ -147,7 +165,7 @@ def _execute(
 
     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:

{pyossmtool-0.0.2 → pyossmtool-0.0.4}/src/pyossmtool/installer.py

@@ -76,6 +76,12 @@ class Installer:
             return False
 
     def _managed_python(self) -> str:
+        """Prefer a stable CPython for managed tool installs.
+
+        pyossmtool itself supports 3.11–3.14. Some third-party CLI tools still lag
+        on brand-new interpreters, so when the host is 3.14+, prefer 3.13/3.12/3.11
+        if available for the managed venv.
+        """
         if sys.version_info < (3, 14):
             return sys.executable
         for candidate in ("python3.13", "python3.12", "python3.11"):
@@ -85,16 +91,6 @@ class Installer:
         return sys.executable
 
     def _ensure_managed_venv(self) -> None:
-        python_bin = self.managed_venv / "bin" / "python"
-        if python_bin.exists():
-            version = subprocess.run(
-                [str(python_bin), "--version"],
-                capture_output=True,
-                text=True,
-                check=True,
-            ).stdout
-            if "3.14" in version:
-                shutil.rmtree(self.managed_venv)
         if (self.managed_venv / "bin" / "python").exists():
             return
         self.managed_venv.parent.mkdir(parents=True, exist_ok=True)