pyossmtool 0.0.1__py3-none-any.whl

pyossmtool/bundle/catalog/tools/pydeps.yaml

@@ -0,0 +1,10 @@
+id: pydeps
+name: pydeps
+description: Python module dependency analysis and cycle detection.
+install:
+  method: pip
+  package: pydeps>=3.0
+binary: pydeps
+documentation_url: https://github.com/thebjorn/pydeps
+files:
+- '**/*.py'

pyossmtool/bundle/catalog/tools/pytest.yaml

@@ -0,0 +1,12 @@
+id: pytest
+name: pytest
+description: Python test runner with optional coverage via pytest-cov plugin.
+install:
+  method: pip
+  package: pytest>=8.0 pytest-cov>=6.0
+binary: pytest
+documentation_url: https://docs.pytest.org/
+ignore:
+  kind: flag_pairs
+  flag: --ignore
+files: []

pyossmtool/bundle/catalog/tools/radon.yaml

@@ -0,0 +1,10 @@
+id: radon
+name: Radon
+description: Code metrics for cyclomatic complexity and maintainability index.
+install:
+  method: pip
+  package: radon>=6.0.0
+binary: radon
+documentation_url: https://radon.readthedocs.io/
+files:
+- '**/*.py'

pyossmtool/bundle/catalog/tools/ruff.yaml

@@ -0,0 +1,26 @@
+id: ruff
+name: Ruff
+description: Fast Python linter and formatter.
+install:
+  method: pip
+  package: ruff>=0.15.0
+binary: ruff
+documentation_url: https://docs.astral.sh/ruff/
+config:
+  flag: --config
+  bundled: ruff.toml
+  repo_files:
+  - ruff.toml
+  pyproject:
+  - tool
+  - ruff
+ignore:
+  kind: config_overlay
+  format: toml
+  file: ruff.toml
+  flag: --config
+  key: extend-exclude
+  extend_from: base_or_pyproject
+  extend_key: extend
+files:
+- '**/*.py'

pyossmtool/bundle/catalog/tools/script.yaml

@@ -0,0 +1,8 @@
+id: script
+name: Shell Script Gate
+description: Project-local bash gate script (install skipped; uses system bash).
+install:
+  method: skip
+binary: bash
+documentation_url: https://github.com/dayhatt/pyossmtool#script-gates
+files: []

pyossmtool/bundle/catalog/tools/semgrep.yaml

@@ -0,0 +1,21 @@
+id: semgrep
+name: Semgrep
+description: Static analysis for security and code quality patterns.
+install:
+  method: pip
+  package: semgrep>=1.79.0
+binary: semgrep
+documentation_url: https://semgrep.dev/
+config:
+  flag: --config
+  bundled_path: defaults/semgrep/python-quality.yml
+  pass_flag: false
+  repo_dirs:
+  - .semgrep
+  - .tools/semgrep
+ignore:
+  kind: flag_pairs
+  flag: --exclude
+  post_subcommand: true
+files:
+- '**/*.py'

pyossmtool/bundle/catalog/tools/shellcheck.yaml

@@ -0,0 +1,10 @@
+id: shellcheck
+name: ShellCheck
+description: Static analysis for shell scripts.
+install:
+  method: system
+  package: shellcheck
+binary: shellcheck
+documentation_url: https://www.shellcheck.net/
+files:
+- '**/*.{sh,bash,ksh,zsh}'

pyossmtool/bundle/catalog/tools/shfmt.yaml

@@ -0,0 +1,13 @@
+id: shfmt
+name: shfmt
+description: Shell script formatter (via shfmt-py).
+install:
+  method: pip
+  package: shfmt-py>=4.0.0
+binary: shfmt
+documentation_url: https://github.com/mvdan/sh
+config:
+  repo_files:
+  - .editorconfig
+files:
+- '**/*.{sh,bash,ksh,zsh}'

pyossmtool/bundle/catalog/tools/sourcery.yaml

@@ -0,0 +1,10 @@
+id: sourcery
+name: Sourcery
+description: Automated Python code review and refactoring suggestions.
+install:
+  method: pip
+  package: sourcery>=1.0.0
+binary: sourcery
+documentation_url: https://sourcery.ai/
+files:
+- '**/*.py'

pyossmtool/bundle/catalog/tools/ty.yaml

@@ -0,0 +1,20 @@
+id: ty
+name: ty
+description: Astral static type checker for Python.
+install:
+  method: pip
+  package: ty>=0.0.50
+binary: ty
+documentation_url: https://docs.astral.sh/ty/
+config:
+  flag: --config-file
+  bundled: ty.toml
+  pyproject:
+    - tool
+    - ty
+ignore:
+  kind: flag_pairs
+  flag: --exclude
+  post_subcommand: true
+files:
+  - "**/*.py"

pyossmtool/bundle/catalog/tools/vulture.yaml

@@ -0,0 +1,13 @@
+id: vulture
+name: Vulture
+description: Find dead Python code with high confidence.
+install:
+  method: pip
+  package: vulture>=2.14
+binary: vulture
+documentation_url: https://github.com/jendrikseipp/vulture
+ignore:
+  kind: prefix
+  prefix: --exclude=
+files:
+- '**/*.py'

pyossmtool/bundle/catalog/tools/yamlfmt.yaml

@@ -0,0 +1,24 @@
+id: yamlfmt
+name: yamlfmt
+description: YAML formatter and linter from Google.
+install:
+  method: system
+  package: yamlfmt
+binary: yamlfmt
+documentation_url: https://github.com/google/yamlfmt
+config:
+  flag: -conf
+  bundled: yamlfmt.yaml
+  repo_files:
+  - .yamlfmt.yaml
+  - .yamlfmt.yml
+  - yamlfmt.yaml
+ignore:
+  kind: config_overlay
+  format: yaml
+  file: yamlfmt.yaml
+  flag: -conf
+  key: exclude
+  key_style: list
+files:
+- '**/*.{yml,yaml}'

pyossmtool/bundle/catalog/tools/yamllint.yaml

@@ -0,0 +1,24 @@
+id: yamllint
+name: yamllint
+description: YAML syntax and style linter.
+install:
+  method: pip
+  package: yamllint>=1.38.0
+binary: yamllint
+documentation_url: https://yamllint.readthedocs.io/
+config:
+  flag: -c
+  bundled: yamllint.yaml
+  repo_files:
+  - .yamllint
+  - .yamllint.yaml
+  - .yamllint.yml
+ignore:
+  kind: config_overlay
+  format: yaml
+  file: yamllint.yaml
+  flag: -c
+  key: ignore
+  key_style: block
+files:
+- '**/*.{yml,yaml}'

pyossmtool/bundle/defaults/allowlists/acronyms.yaml

@@ -0,0 +1,10 @@
+AI:
+  expansion: Artificial intelligence
+API:
+  expansion: Application programming interface
+CI:
+  expansion: Continuous integration
+CLI:
+  expansion: Command-line interface
+README:
+  expansion: Read me (project overview document)

pyossmtool/bundle/defaults/allowlists/folder-breadth.txt

@@ -0,0 +1 @@
+# Directory paths exempt from folder breadth limits (repo-relative).

pyossmtool/bundle/defaults/allowlists/module-private-vars.txt

@@ -0,0 +1 @@
+# One repo-relative file path per line (whole-file exemption).

pyossmtool/bundle/defaults/allowlists/module-size.txt

@@ -0,0 +1 @@
+# One repo-relative path per line (optional). Lines starting with # are ignored.

pyossmtool/bundle/defaults/configs/bandit.yaml

@@ -0,0 +1,5 @@
+# Bandit defaults for quality-tool orchestrators (subprocess is expected).
+skips:
+  - B404
+  - B603
+  - B607

pyossmtool/bundle/defaults/configs/gates/acronym-allowlist.yaml

@@ -0,0 +1,4 @@
+scan_roots:
+  - docs/
+  - AGENTS.md
+allowlist_file: .pyossmtool/allowlists/acronyms.yaml

pyossmtool/bundle/defaults/configs/gates/folder-breadth.yaml

@@ -0,0 +1,12 @@
+max_allowed: 12
+scan_roots:
+  - src/
+  - docs/
+  - tests/
+extensions:
+  - .py
+  - .md
+  - .yaml
+  - .sh
+strict: true
+allowlist_file: .pyossmtool/allowlists/folder-breadth.txt

pyossmtool/bundle/defaults/configs/gates/module-private-vars.yaml

@@ -0,0 +1,4 @@
+scan_roots:
+  - src/
+base_branch: main
+allowlist_file: .pyossmtool/allowlists/module-private-vars.txt

pyossmtool/bundle/defaults/configs/gates/module-size.yaml

@@ -0,0 +1,6 @@
+scan_roots:
+  - src/
+portfolio_max_lines: 1000
+new_file_max_lines: 500
+base_branch: main
+allowlist_file: .pyossmtool/allowlists/module-size.txt

pyossmtool/bundle/defaults/configs/markdownlint.json

@@ -0,0 +1,8 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false,
+  "MD040": false,
+  "MD060": false
+}

pyossmtool/bundle/defaults/configs/ruff.toml

@@ -0,0 +1,8 @@
+line-length = 100
+target-version = "py311"
+
+[lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[format]
+quote-style = "double"

pyossmtool/bundle/defaults/configs/ty.toml

@@ -0,0 +1,5 @@
+[environment]
+python-version = "3.11"
+
+[rules]
+all = "error"

pyossmtool/bundle/defaults/configs/yamlfmt.yaml

@@ -0,0 +1,4 @@
+formatter:
+  type: basic
+  indent: 2
+  include_document_start: false

pyossmtool/bundle/defaults/configs/yamllint.yaml

@@ -0,0 +1,12 @@
+extends: default
+
+rules:
+  line-length:
+    max: 120
+    level: warning
+  document-start: disable
+  truthy:
+    allowed-values: ["true", "false", "on", "off"]
+    check-keys: false
+  brackets:
+    forbid: false

pyossmtool/bundle/defaults/gates/README.md

@@ -0,0 +1,150 @@
+# Script gates
+
+Shell-based policy checks integrated with pyossmtool failure reports.
+
+## Bundled policy gates
+
+| Check | Script | Config |
+| -------------------------- | --------------------------------------- | ------------------------------------------------- |
+| `gate.module-size` | `defaults/gates/module-size.sh` | `defaults/configs/gates/module-size.yaml` |
+| `gate.module-private-vars` | `defaults/gates/module-private-vars.sh` | `defaults/configs/gates/module-private-vars.yaml` |
+| `gate.folder-breadth` | `defaults/gates/folder-breadth.sh` | `defaults/configs/gates/folder-breadth.yaml` |
+| `gate.acronym-allowlist` | `defaults/gates/acronym-allowlist.sh` | `defaults/configs/gates/acronym-allowlist.yaml` |
+
+Run via suite `policy` or as part of `standard`.
+
+### Configure per repo
+
+Each gate check declares where config lives (see `config:` on `catalog/checks/gate.*.yaml`):
+
+```yaml
+config:
+  bundled: gates/module-size.yaml
+  project_file: .pyossmtool/configs/gates/gate.module-size.yaml
+  allowlist_bundled: module-size.txt
+```
+
+Resolution order: `configs.mode: paths` override → `project_file` if present → `bundled` under `defaults/configs/`.
+
+Override bundled defaults by adding the project file:
+
+```yaml
+# .pyossmtool/configs/gates/gate.module-size.yaml
+scan_roots:
+  - src/myapp
+  - scripts
+portfolio_max_lines: 800
+new_file_max_lines: 400
+base_branch: main
+allowlist_file: .pyossmtool/allowlists/module-size.txt
+```
+
+Or set explicit paths in `pyossmtool.yaml`:
+
+```yaml
+configs:
+  mode: paths
+  paths:
+    gate.module-size: .pyossmtool/configs/gates/gate.module-size.yaml
+```
+
+Config keys are exported to gate scripts as `GATE_<KEY>` environment variables (lists become space-separated).
+
+## Quick start (custom gate)
+
+```bash
+pyossmtool gate init module-size --description "Cap Python module line counts"
+# edit .pyossmtool/gates/module-size.sh
+# add to pyossmtool.yaml checks: - id: gate.module-size
+pyossmtool run --check gate.module-size --target src/
+```
+
+## Layout
+
+```text
+.pyossmtool/
+  gates/                 # your bash scripts
+    module-size.sh
+  catalog/
+    checks/              # gate.<name>.yaml registrations
+      gate.module-size.yaml
+  reports/               # structured JSON written by lib.sh (gitignore this)
+    gate.module-size.json
+```
+
+Project catalog entries **override** bundled checks with the same id.
+
+## Gate script contract
+
+1. Source `defaults/gates/lib.sh` via `pyossmtool gates lib-path`
+1. Call `gate_init "<name>"`
+1. Use `gate_fail` / `gate_warn` for findings
+1. Call `gate_finish` (exits 0 on pass, 1 on fail)
+
+### Environment (set by runner)
+
+| Variable | Meaning |
+| --------------------------- | ------------------------------------------------------------ |
+| `PYOSSMTOOL_ROOT` | Repository root |
+| `PYOSSMTOOL_TARGET` | Resolved scan target for this check |
+| `PYOSSMTOOL_CHECK_ID` | Catalog check id |
+| `PYOSSMTOOL_REPORT` | Path to write structured JSON findings |
+| `PYOSSMTOOL_IGNORE_PROFILES` | Newline-separated ignore profile files (`.gitignore` syntax) |
+| `PYOSSMTOOL_IGNORE_PATHS` | Newline-separated repo-relative paths/globs to skip |
+
+Use `gate_path_ignored "<repo-relative-path>"` in bash gates to skip ignored files.
+
+### Structured output
+
+`gate_fail` / `gate_warn` append to `PYOSSMTOOL_REPORT`:
+
+```json
+{
+  "findings": [
+    {
+      "rule_id": "module-size",
+      "severity": "error",
+      "message": "src/foo.py has 1200 lines (cap 1000)",
+      "location": { "file": "src/foo.py", "line": 1 }
+    }
+  ]
+}
+```
+
+On failure, pyossmtool normalizes this into `FailureReport` v1 under `reports/failures/`.
+
+### Legacy scripts (no lib)
+
+Existing bash gates that print `FAIL ...` lines still work when registered with `parser: script_text`.
+
+## Catalog entry
+
+```yaml
+id: gate.module-size
+tool: script
+name: Module Size Gate
+description: Enforce per-file line limits.
+script: .pyossmtool/gates/module-size.sh
+parser: gate_json
+output_file: .pyossmtool/reports/gate.module-size.json
+argv: []
+success:
+  exit_codes: [0]
+```
+
+Optional `argv` entries are passed after the script path; use `{target}` and `{cov}` placeholders.
+
+## Wrapping existing reslab gates
+
+Keep `bin/gates/module-size-check.sh` as-is and register it:
+
+```yaml
+id: gate.module-size
+tool: script
+name: Module Size Gate
+script: bin/gates/module-size-check.sh
+parser: script_text
+argv: []
+```
+
+Use `parser: gate_json` after migrating the script to call `gate_fail` / `gate_finish`.

pyossmtool/bundle/defaults/gates/acronym-allowlist.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Documented-acronym gate for contributor-facing prose.
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$(pyossmtool gates lib-path)"
+
+gate_init "acronym-allowlist"
+
+CONFIG="${PYOSSMTOOL_GATE_CONFIG:?PYOSSMTOOL_GATE_CONFIG is required}"
+ROOT="${PYOSSMTOOL_ROOT:?PYOSSMTOOL_ROOT is required}"
+REPORT="${PYOSSMTOOL_REPORT:?PYOSSMTOOL_REPORT is required}"
+
+"${PYOSSMTOOL_PYTHON:?PYOSSMTOOL_PYTHON is required}" -m pyossmtool.policy.acronym_allowlist --root "${ROOT}" --config "${CONFIG}" --report "${REPORT}"
+exit $?

pyossmtool/bundle/defaults/gates/folder-breadth.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Folder breadth gate — caps direct sibling file counts per directory.
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$(pyossmtool gates lib-path)"
+
+gate_init "folder-breadth"
+
+CONFIG="${PYOSSMTOOL_GATE_CONFIG:?PYOSSMTOOL_GATE_CONFIG is required}"
+ROOT="${PYOSSMTOOL_ROOT:?PYOSSMTOOL_ROOT is required}"
+REPORT="${PYOSSMTOOL_REPORT:?PYOSSMTOOL_REPORT is required}"
+
+ARGS=(--root "${ROOT}" --config "${CONFIG}" --report "${REPORT}")
+if [[ ${GATE_STRICT:-1} == "1" ]]; then
+	ARGS+=(--strict)
+else
+	ARGS+=(--advisory)
+fi
+
+"${PYOSSMTOOL_PYTHON:?PYOSSMTOOL_PYTHON is required}" -m pyossmtool.policy.folder_breadth "${ARGS[@]}"
+exit $?

pyossmtool/bundle/defaults/gates/lib.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# pyossmtool script-gate helper library.
+# Source from project gates: source "$(pyossmtool gates lib-path)"
+set -euo pipefail
+
+gate_init() {
+	GATE_NAME="${1:-script-gate}"
+	GATE_FINDING_COUNT=0
+	if [[ -z "${PYOSSMTOOL_REPORT:-}" ]]; then
+		echo "gate_init: PYOSSMTOOL_REPORT is not set (pyossmtool runner should set this)" >&2
+		exit 2
+	fi
+	mkdir -p "$(dirname "${PYOSSMTOOL_REPORT}")"
+	printf '%s\n' '{"findings":[]}' >"${PYOSSMTOOL_REPORT}"
+}
+
+_gate_append_finding() {
+	local rule_id="$1"
+	local severity="$2"
+	local message="$3"
+	local file="${4:-}"
+	local line="${5:-}"
+	python3 - "${PYOSSMTOOL_REPORT}" "${rule_id}" "${severity}" "${message}" "${file}" "${line}" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+report_path, rule_id, severity, message, file, line = sys.argv[1:7]
+payload = json.loads(Path(report_path).read_text(encoding="utf-8"))
+finding = {
+    "rule_id": rule_id,
+    "severity": severity,
+    "message": message,
+}
+if file:
+    location = {"file": file}
+    if line:
+        try:
+            location["line"] = int(line)
+        except ValueError:
+            pass
+    finding["location"] = location
+payload.setdefault("findings", []).append(finding)
+Path(report_path).write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+PY
+	GATE_FINDING_COUNT=$((GATE_FINDING_COUNT + 1))
+}
+
+gate_fail() {
+	local rule_id="${1:-gate}"
+	local message="${2:-gate failed}"
+	local file="${3:-}"
+	local line="${4:-}"
+	_gate_append_finding "${rule_id}" "error" "${message}" "${file}" "${line}"
+	echo "FAIL ${rule_id}: ${message}" >&2
+}
+
+gate_warn() {
+	local rule_id="${1:-gate}"
+	local message="${2:-gate warning}"
+	local file="${3:-}"
+	local line="${4:-}"
+	_gate_append_finding "${rule_id}" "warning" "${message}" "${file}" "${line}"
+	echo "WARN ${rule_id}: ${message}" >&2
+}
+
+gate_path_ignored() {
+	local rel_path="${1#./}"
+	"${PYOSSMTOOL_PYTHON:-python3}" - "${rel_path}" <<'PY'
+import fnmatch
+import os
+import sys
+from pathlib import Path
+
+try:
+    import pathspec
+except ImportError:
+    pathspec = None
+
+rel = sys.argv[1].replace("\\", "/").lstrip("./")
+patterns: list[str] = [
+    p.strip() for p in os.environ.get("PYOSSMTOOL_IGNORE_PATHS", "").splitlines() if p.strip()
+]
+for profile in os.environ.get("PYOSSMTOOL_IGNORE_PROFILES", "").splitlines():
+    path = Path(profile.strip())
+    if not path.is_file():
+        continue
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#") and not stripped.startswith("!"):
+            patterns.append(stripped)
+
+if not patterns:
+    raise SystemExit(1)
+
+if pathspec is not None:
+    matcher = pathspec.PathSpec.from_lines("gitignore", patterns)
+    raise SystemExit(0 if matcher.match_file(rel) else 1)
+
+for pattern in patterns:
+    normalized = pattern.rstrip("/")
+    if rel == normalized or rel.startswith(f"{normalized}/"):
+        raise SystemExit(0)
+    if "*" in pattern and fnmatch.fnmatch(rel, pattern):
+        raise SystemExit(0)
+raise SystemExit(1)
+PY
+}
+
+gate_finish() {
+	if ((GATE_FINDING_COUNT > 0)); then
+		echo "gate '${GATE_NAME}' failed with ${GATE_FINDING_COUNT} finding(s)" >&2
+		exit 1
+	fi
+	exit 0
+}