pyossmtool 0.0.1__py3-none-any.whl

pyossmtool/bundle/defaults/gates/module-private-vars.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Module private-vars gate — no leading-underscore module-level names.
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$(pyossmtool gates lib-path)"
+
+gate_init "module-private-vars"
+
+BASE_BRANCH="${GATE_BASE_BRANCH:-main}"
+ALLOWLIST="${GATE_ALLOWLIST_FILE:-}"
+IFS=' ' read -r -a SCAN_ROOTS <<<"${GATE_SCAN_ROOTS:-src/}"
+
+ASSIGN_PATTERN='^_[^_][A-Za-z0-9_]*[[:space:]]*[:=]'
+DEF_PATTERN='^(async[[:space:]]+)?def[[:space:]]+_[^_][A-Za-z0-9_]*[[:space:]]*[\(:]'
+CLASS_PATTERN='^class[[:space:]]+_[^_][A-Za-z0-9_]*[[:space:]]*[\(:]'
+
+is_allowlisted() {
+	local rel="$1"
+	[[ -n ${ALLOWLIST} && -f ${ALLOWLIST} ]] || return 1
+	grep -v '^[[:space:]]*#' "${ALLOWLIST}" | grep -v '^[[:space:]]*$' | grep -Fxq "${rel}"
+}
+
+is_strict_file() {
+	local rel="$1"
+	local strict
+	for strict in "${STRICT_FILES[@]-}"; do
+		[[ ${rel} == "${strict}" ]] && return 0
+	done
+	return 1
+}
+
+report_matches() {
+	local rel="$1"
+	local label="$2"
+	local matches="$3"
+	if [[ -n ${matches} ]]; then
+		while IFS= read -r line; do
+			[[ -n ${line} ]] || continue
+			line_no="${line%%:*}"
+			gate_fail "private-${label}" "${rel}:${line}" "${rel}" "${line_no}"
+		done <<<"${matches}"
+	fi
+}
+
+STRICT_FILES=()
+if git rev-parse --verify "${BASE_BRANCH}" >/dev/null 2>&1; then
+	MERGE_BASE="$(git merge-base HEAD "${BASE_BRANCH}")"
+	new_file_globs=()
+	for scan_root in "${SCAN_ROOTS[@]}"; do
+		new_file_globs+=("${scan_root}" "${scan_root}/**")
+	done
+	mapfile -t STRICT_FILES < <(git diff --name-only --diff-filter=A "${MERGE_BASE}...HEAD" -- "${new_file_globs[@]}" | grep '\.py$' || true)
+fi
+
+for scan_dir in "${SCAN_ROOTS[@]}"; do
+	[[ -d ${scan_dir} ]] || continue
+	while IFS= read -r -d '' file; do
+		rel="${file#./}"
+		if gate_path_ignored "${rel}"; then
+			continue
+		fi
+		if is_allowlisted "${rel}"; then
+			continue
+		fi
+		assign_matches="$(grep -nE "${ASSIGN_PATTERN}" "${file}" || true)"
+		report_matches "${rel}" "assignment" "${assign_matches}"
+		if is_strict_file "${rel}"; then
+			def_matches="$(grep -nE "${DEF_PATTERN}" "${file}" || true)"
+			class_matches="$(grep -nE "${CLASS_PATTERN}" "${file}" || true)"
+			report_matches "${rel}" "function" "${def_matches}"
+			report_matches "${rel}" "class" "${class_matches}"
+		fi
+	done < <(find "${scan_dir}" -name '*.py' -print0)
+done
+
+gate_finish

pyossmtool/bundle/defaults/gates/module-size.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Module size gate — portfolio and new-file line caps.
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$(pyossmtool gates lib-path)"
+
+gate_init "module-size"
+
+PORTFOLIO_MAX="${GATE_PORTFOLIO_MAX_LINES:-1000}"
+NEW_FILE_MAX="${GATE_NEW_FILE_MAX_LINES:-500}"
+BASE_BRANCH="${GATE_BASE_BRANCH:-main}"
+ALLOWLIST="${GATE_ALLOWLIST_FILE:-}"
+IFS=' ' read -r -a SCAN_ROOTS <<<"${GATE_SCAN_ROOTS:-src/}"
+
+count_non_blank_lines() {
+	local file="$1"
+	grep -cve '^[[:space:]]*$' "${file}" || true
+}
+
+is_allowlisted() {
+	local rel="$1"
+	[[ -n ${ALLOWLIST} && -f ${ALLOWLIST} ]] || return 1
+	grep -v '^[[:space:]]*#' "${ALLOWLIST}" | grep -v '^[[:space:]]*$' | grep -Fxq "${rel}"
+}
+
+for scan_root in "${SCAN_ROOTS[@]}"; do
+	[[ -d ${scan_root} ]] || continue
+	while IFS= read -r -d '' file; do
+		rel="${file#./}"
+		if gate_path_ignored "${rel}"; then
+			continue
+		fi
+		loc="$(count_non_blank_lines "${file}")"
+		if ((loc > PORTFOLIO_MAX)) && ! is_allowlisted "${rel}"; then
+			gate_fail "module-size" "${rel} has ${loc} lines (portfolio cap ${PORTFOLIO_MAX})" "${rel}" "1"
+		fi
+	done < <(find "${scan_root}" -name '*.py' -print0)
+done
+
+if git rev-parse --verify "${BASE_BRANCH}" >/dev/null 2>&1; then
+	MERGE_BASE="$(git merge-base HEAD "${BASE_BRANCH}")"
+	new_file_globs=()
+	for scan_root in "${SCAN_ROOTS[@]}"; do
+		new_file_globs+=("${scan_root}" "${scan_root}/**")
+	done
+	mapfile -t new_files < <(git diff --name-only --diff-filter=A "${MERGE_BASE}...HEAD" -- "${new_file_globs[@]}" | grep '\.py$' || true)
+	for rel in "${new_files[@]}"; do
+		[[ -f ${rel} ]] || continue
+		if gate_path_ignored "${rel}"; then
+			continue
+		fi
+		loc="$(count_non_blank_lines "${rel}")"
+		if ((loc > NEW_FILE_MAX)) && ! is_allowlisted "${rel}"; then
+			gate_fail "module-size" "${rel} has ${loc} lines (new-file cap ${NEW_FILE_MAX})" "${rel}" "1"
+		fi
+	done
+fi
+
+gate_finish

pyossmtool/bundle/defaults/semgrep/python-quality.yml

@@ -0,0 +1,19 @@
+rules:
+  - id: no-eval
+    patterns:
+      - pattern: eval(...)
+    message: Avoid eval() — use safer alternatives.
+    languages: [python]
+    severity: ERROR
+  - id: no-exec
+    patterns:
+      - pattern: exec(...)
+    message: Avoid exec() — use safer alternatives.
+    languages: [python]
+    severity: ERROR
+  - id: no-hardcoded-temp-password
+    patterns:
+      - pattern: password = "..."
+    message: Possible hardcoded password.
+    languages: [python]
+    severity: WARNING

pyossmtool/bundle/suites/demo.yaml

@@ -0,0 +1,11 @@
+id: demo
+name: Demo Suite
+description: Internal demo suite for sample_files fixtures (development only).
+env: auto
+target: sample_files/
+checks:
+  - id: ruff.lint
+  - id: ruff.format
+  - id: ty.check
+  - id: shellcheck
+  - id: bandit.scan

pyossmtool/bundle/suites/extended.yaml

@@ -0,0 +1,34 @@
+id: extended
+name: Extended Quality Suite
+description: Standard suite plus slow or optional checks (mutation testing, sourcery
+  review).
+env: auto
+target: .
+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

pyossmtool/bundle/suites/format.yaml

@@ -0,0 +1,10 @@
+id: format
+name: Format Apply
+description: Apply formatters across Python, shell, Markdown, and YAML.
+env: auto
+target: .
+checks:
+  - id: ruff.format.apply
+  - id: shfmt.apply
+  - id: mdformat.apply
+  - id: yamlfmt.apply

pyossmtool/bundle/suites/formatting.yaml

@@ -0,0 +1,10 @@
+id: formatting
+name: Formatting
+description: All format-only checks across Python, shell, Markdown, and YAML.
+env: auto
+target: .
+checks:
+- id: ruff.format
+- id: shfmt.format
+- id: mdformat.format
+- id: yamlfmt.format

pyossmtool/bundle/suites/policy.yaml

@@ -0,0 +1,11 @@
+id: policy
+name: Policy Gates
+description: Structural policy checks (module size, private vars, folder breadth,
+  acronyms).
+env: auto
+target: .
+checks:
+- id: gate.module-size
+- id: gate.module-private-vars
+- id: gate.folder-breadth
+- id: gate.acronym-allowlist

pyossmtool/bundle/suites/python-quality.yaml

@@ -0,0 +1,9 @@
+id: python-quality
+name: Python Quality
+description: Core Python lint, format, and type checks.
+env: auto
+target: .
+checks:
+- id: ruff.format
+- id: ruff.lint
+- id: ty.check

pyossmtool/bundle/suites/reslab-parity.yaml

@@ -0,0 +1,41 @@
+id: reslab-parity
+name: ResLab Parity Reference
+description: "Alias for the standard suite \u2014 full reslab-equivalent CLI tool\
+  \ coverage."
+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: shfmt.format
+- id: shellcheck
+- 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: 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

pyossmtool/bundle/suites/standard.yaml

@@ -0,0 +1,45 @@
+id: standard
+name: Standard Quality Suite
+description: Full portable quality gate set for new Python projects (matches reslab
+  tool coverage).
+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: gate.module-size
+- id: gate.module-private-vars
+- id: gate.folder-breadth
+- id: gate.acronym-allowlist

pyossmtool/cli.py

@@ -0,0 +1,233 @@
+"""pyossmtool command-line interface."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from pyossmtool.gates import lib_path, scaffold_gate
+from pyossmtool.installer import Installer
+from pyossmtool.models import CheckMode, FailureReport
+from pyossmtool.registry import Registry
+from pyossmtool.runner import Runner
+
+app = typer.Typer(help="Quality-gate orchestrator for AI-assisted development")
+list_app = typer.Typer(help="List catalog entries")
+gate_app = typer.Typer(help="Shell script gate framework")
+gates_app = typer.Typer(help="Gate library utilities")
+app.add_typer(list_app, name="list")
+app.add_typer(gate_app, name="gate")
+app.add_typer(gates_app, name="gates")
+
+
+def _project_root() -> Path:
+    return Path.cwd()
+
+
+def _registry() -> Registry:
+    return Registry(project_root=_project_root())
+
+
+@list_app.command("tools")
+def list_tools() -> None:
+    registry = _registry()
+    for tool in registry.tools.values():
+        typer.echo(f"{tool.id}\t{tool.name}\t({tool.install.method.value})")
+
+
+@list_app.command("checks")
+def list_checks() -> None:
+    registry = _registry()
+    for check in registry.checks.values():
+        origin = "project" if check.tool == "script" else "bundled"
+        typer.echo(f"{check.id}\t{check.tool}\t{check.name}\t{check.mode.value}\t({origin})")
+
+
+@list_app.command("suites")
+def list_suites() -> None:
+    registry = _registry()
+    for suite in registry.suites.values():
+        typer.echo(f"{suite.id}\t{suite.name}")
+
+
+@gates_app.command("lib-path")
+def gates_lib_path() -> None:
+    """Print absolute path to defaults/gates/lib.sh for sourcing in scripts."""
+    typer.echo(str(lib_path()))
+
+
+@gate_app.command("init")
+def gate_init(
+    name: str = typer.Argument(..., help="Gate name (e.g. module-size)"),
+    description: str = typer.Option("Project script gate", "--description", "-d"),
+) -> None:
+    """Scaffold a script gate under .pyossmtool/gates/ and register it in the catalog."""
+    project_root = _project_root()
+    try:
+        script_path, catalog_path = scaffold_gate(project_root, name, description)
+    except FileExistsError as exc:
+        typer.echo(f"SETUP {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+    typer.echo(f"Created gate script: {script_path.relative_to(project_root)}")
+    typer.echo(f"Created catalog check: {catalog_path.relative_to(project_root)}")
+    typer.echo("")
+    typer.echo("Add the check to pyossmtool.yaml:")
+    typer.echo(f"  - id: {catalog_path.stem}")
+    typer.echo("")
+    typer.echo("Run it:")
+    typer.echo(f"  pyossmtool check --check {catalog_path.stem} --target .")
+
+
+@app.command("schema")
+def export_schema() -> None:
+    typer.echo(json.dumps(FailureReport.model_json_schema(), indent=2))
+
+
+@app.command("install")
+def install(
+    suite: str = typer.Option("demo", "--suite", help="Suite whose tool dependencies to install"),
+) -> None:
+    registry = _registry()
+    installer = Installer(registry, _project_root())
+    try:
+        installer.install_suite(suite)
+    except Exception as exc:
+        typer.echo(f"SETUP {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+
+@app.command("check")
+def check_cmd(
+    suite: str | None = typer.Option(None, "--suite", help="Suite id to run"),
+    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"),
+    verbose: bool = typer.Option(False, "--verbose", help="Print commands and keep raw artifacts on success"),
+) -> None:
+    """Report-only quality checks (no file writes from formatters)."""
+    raise typer.Exit(code=_execute(CheckMode.CHECK, suite, check, target, fail_fast, verbose))
+
+
+@app.command("format")
+def format_cmd(
+    suite: str | None = typer.Option("format", "--suite", help="Suite id to run"),
+    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"),
+    verbose: bool = typer.Option(False, "--verbose", help="Print commands and keep raw artifacts on success"),
+) -> None:
+    """Apply formatters / autofix checks that write to the tree."""
+    raise typer.Exit(code=_execute(CheckMode.FORMAT, suite, check, target, fail_fast, verbose))
+
+
+def _execute(
+    mode: CheckMode,
+    suite: str | None,
+    check: str | None,
+    target: str | None,
+    fail_fast: bool,
+    verbose: bool,
+) -> int:
+    registry = _registry()
+    project_root = _project_root()
+    project_config = registry.load_project_config(project_root)
+    runner = Runner(registry, project_root, verbose=verbose)
+
+    if check:
+        return _run_single_check(runner, check, target, suite, project_config, mode)
+
+    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)
+        return 2
+
+    try:
+        suite_result = runner.run_suite(
+            suite_id,
+            project_config=project_config,
+            fail_fast=fail_fast,
+            mode=mode,
+        )
+    except KeyError as exc:
+        typer.echo(f"SETUP {exc}", err=True)
+        return 2
+    return _emit_suite_result(suite_result)
+
+
+def _run_single_check(
+    runner: Runner,
+    check: str,
+    target: str | None,
+    suite: str | None,
+    project_config,
+    mode: CheckMode,
+) -> int:
+    if not target:
+        typer.echo("SETUP --target is required with --check", err=True)
+        return 2
+    check_def = runner.registry.get_check(check)
+    if check_def.mode != mode:
+        typer.echo(
+            f"SETUP check '{check}' has mode={check_def.mode.value}; use pyossmtool {check_def.mode.value}",
+            err=True,
+        )
+        return 2
+    result = runner.run_check(
+        check,
+        target=target,
+        suite_id=suite or (project_config.suite if project_config else None),
+        project_config=project_config,
+    )
+    return _exit_for_check_result(result)
+
+
+def _exit_for_check_result(result) -> 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)
+    return 1
+
+
+def _emit_suite_result(suite_result) -> int:
+    if suite_result.passed:
+        return 0
+    for result in suite_result.results:
+        _emit_failed_check(result)
+    return 1
+
+
+def _emit_failed_check(result) -> None:
+    if result.passed:
+        return
+    if result.error:
+        typer.echo(f"SETUP {result.check_id}: {result.error}", err=True)
+        return
+    if result.report_path:
+        typer.echo(f"FAIL {result.check_id} -> {result.report_path}", err=True)
+
+
+def main() -> None:
+    app()
+
+
+_TYPER_COMMANDS = (
+    list_tools,
+    list_checks,
+    list_suites,
+    gates_lib_path,
+    gate_init,
+    export_schema,
+    install,
+    check_cmd,
+    format_cmd,
+)
+
+
+if __name__ == "__main__":
+    main()

pyossmtool/config_resolver.py

@@ -0,0 +1,117 @@
+"""Resolve tool configuration: repo-native > pyossmtool.yaml paths > bundled defaults."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pyossmtool.models import (
+    ConfigMode,
+    ConfigSpec,
+    ProjectConfig,
+    ToolConfigSpec,
+    ToolDef,
+)
+from pyossmtool.registry import BUNDLE_ROOT
+
+DEFAULTS_DIR = BUNDLE_ROOT / "defaults" / "configs"
+
+
+class ConfigResolver:
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = project_root.resolve()
+        self.defaults_dir = DEFAULTS_DIR
+
+    def extra_argv(self, tool: ToolDef, project_config: ProjectConfig | None) -> list[str]:
+        config_path = self._selected_config_path(tool, project_config)
+        if config_path is None:
+            return []
+        return self._config_argv(tool, config_path)
+
+    def resolve_config_path(self, tool: ToolDef, project_config: ProjectConfig | None) -> Path | None:
+        path = self._selected_config_path(tool, project_config)
+        return path.resolve() if path and path.exists() else None
+
+    def _selected_config_path(self, tool: ToolDef, project_config: ProjectConfig | None) -> Path | None:
+        spec = project_config.configs if project_config else ConfigSpec()
+        if spec.mode == ConfigMode.PATHS:
+            return self._paths_mode_config(tool.id, spec)
+        if tool.config is None:
+            return None
+        if spec.mode == ConfigMode.BUNDLED:
+            return self._bundled_mode_config(tool.config)
+        return self._auto_mode_config(tool.config)
+
+    def _paths_mode_config(self, tool_id: str, spec: ConfigSpec) -> Path | None:
+        path = spec.paths.get(tool_id)
+        return (self.project_root / path).resolve() if path else None
+
+    def _bundled_mode_config(self, config: ToolConfigSpec) -> Path | None:
+        bundled = self._bundled_path(config)
+        return bundled.resolve() if bundled and bundled.exists() else None
+
+    def _auto_mode_config(self, config: ToolConfigSpec) -> Path | None:
+        if config.use_pyproject_as_path and self._pyproject_has_table(*config.pyproject):
+            return self.project_root / "pyproject.toml"
+        if self._repo_has_config(config):
+            return None
+        return self._bundled_mode_config(config)
+
+    def _config_argv(self, tool: ToolDef, config_path: Path) -> list[str]:
+        if not config_path.exists() or tool.config is None:
+            return []
+        if not tool.config.should_pass_flag() or not tool.config.flag:
+            return []
+        return [tool.config.flag, str(config_path)]
+
+    def _repo_has_config(self, config: ToolConfigSpec) -> bool:
+        if self._repo_has_files(config):
+            return True
+        if self._repo_has_dirs(config):
+            return True
+        return bool(config.pyproject) and self._pyproject_has_table(*config.pyproject)
+
+    def _repo_has_files(self, config: ToolConfigSpec) -> bool:
+        return any((self.project_root / name).exists() for name in config.repo_files)
+
+    def _repo_has_dirs(self, config: ToolConfigSpec) -> bool:
+        return any(self._nonempty_dir(name) for name in config.repo_dirs)
+
+    def _nonempty_dir(self, rel: str) -> bool:
+        candidate = self.project_root / rel
+        return candidate.is_dir() and any(candidate.iterdir())
+
+    def _bundled_path(self, config: ToolConfigSpec) -> Path | None:
+        if config.bundled_path:
+            path = BUNDLE_ROOT / config.bundled_path
+            return path if path.exists() else None
+        if config.bundled:
+            path = self.defaults_dir / config.bundled
+            return path if path.exists() else None
+        return None
+
+    def _pyproject_has_table(self, *keys: str) -> bool:
+        if not keys:
+            return False
+        data = self._load_pyproject()
+        if data is None:
+            return False
+        return _dict_has_path(data, keys)
+
+    def _load_pyproject(self) -> dict | None:
+        pyproject = self.project_root / "pyproject.toml"
+        if not pyproject.exists():
+            return None
+        try:
+            return tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        except tomllib.TOMLDecodeError:
+            return None
+
+
+def _dict_has_path(data: dict, keys: tuple[str, ...]) -> bool:
+    node: object = data
+    for key in keys:
+        if not isinstance(node, dict) or key not in node:
+            return False
+        node = node[key]
+    return True