opsscript-gate 0.6.2__tar.gz → 0.7.0__tar.gz

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/.github/workflow-templates/opsscript-gate.yml

@@ -25,7 +25,7 @@ jobs:
           persist-credentials: false
 
       - name: Run OpsScript Gate
-        uses: Mresyzz/opsscript-gate@v0.6.2
+        uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           shell: auto
           network: none

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- Added SARIF 2.1.0 output for location-aware GitHub Code Scanning integration.
+
+## [0.7.0] - 2026-10-01
+
+### Added
+- Added `opsscript-gate doctor` to diagnose Python and Docker prerequisites before a local run.
+
+### Changed
+- Expanded package and Marketplace keywords for shell installers, ShellCheck users, portability, and BusyBox.
+- Clarified the Action description around shell installer runtime compatibility.
+
 ## [0.6.2] - 2026-10-01
 
 ### Changed

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/CITATION.cff

@@ -5,8 +5,8 @@ type: software
 authors:
   - family-names: Mresyzz
     given-names: Mresy
-version: 0.6.2
-date-released: 2026-09-30
+version: 0.7.0
+date-released: 2026-10-01
 repository-code: https://github.com/Mresyzz/opsscript-gate
 url: https://github.com/Mresyzz/opsscript-gate
 license: MIT

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.6.2
+Version: 0.7.0
 Summary: Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge
 Project-URL: Homepage, https://mresyzz.github.io/InstallReady/
 Project-URL: Demo, https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate
@@ -11,7 +11,7 @@ Project-URL: Documentation, https://github.com/Mresyzz/opsscript-gate/tree/main/
 Author: Mresyzz
 License: MIT
 License-File: LICENSE
-Keywords: alpine,bootstrap,ci,compatibility,cross-distro,debian,devops,docker,github-actions,installer,linux,posix,shell,shellcheck-alternative,testing,ubuntu
+Keywords: alpine,bootstrap,busybox,ci,compatibility,cross-distro,debian,devops,docker,github-actions,installer,installer-testing,linux,posix,shell,shell-portability,shellcheck,shellcheck-alternative,testing,ubuntu
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
@@ -48,15 +48,15 @@ Description-Content-Type: text/markdown
 It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 If your repository contains an installer, bootstrap script, or shell entrypoint, the fastest path is to
-copy the [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml). It only runs when
-shell files change, uses offline containers by default, and uploads a report that can be attached to a PR.
-No account, API key, or service signup is required.
+open the [InstallReady scanner](https://mresyzz.github.io/InstallReady/), enter `owner/repository`, and
+choose **Add workflow on GitHub**. It generates a reviewable workflow without an account, API key, or
+service signup. You can also copy the maintained [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml).
 
 Try the browser scanner: [InstallReady](https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate) checks this repository without executing code or requiring a login.
 
 ---
 
-## Current release: v0.6.2
+## Current release: v0.7.0
 
 The current release includes a project config file, a dry-run plan, presets, exclusions,
 saved reports, and changed-script selection for pull requests. The project controls
@@ -64,6 +64,7 @@ were introduced in v0.5.0; projects on v0.4.1 and earlier do not include them.
 
 ```bash
 opsscript-gate init
+opsscript-gate doctor
 opsscript-gate run --dry-run
 opsscript-gate run --format json --output reports/compatibility.json
 ```
@@ -71,6 +72,7 @@ opsscript-gate run --format json --output reports/compatibility.json
 `init` creates `.opsscript-gate.json` and a GitHub Actions workflow without replacing
 existing files. Review its exclusions (`tests/*`, `examples/*`) and offline network
 default before running. No Docker is required for `init` or `--dry-run`.
+Use `opsscript-gate doctor` to check Python and Docker before a real run.
 
 Useful for standalone installers, container entrypoints and release scripts that
 must work on both GNU/Linux and Alpine/BusyBox. Each script runs independently;
@@ -84,8 +86,9 @@ See [configuration and migration](docs/configuration.md) and
 
 Add this workflow to `.github/workflows/shell-compat.yml`:
 
-You can also select **OpsScript Gate shell compatibility** from GitHub's workflow templates, or copy the
-maintained [starter workflow](.github/workflow-templates/opsscript-gate.yml).
+The repository includes a maintained [workflow template](.github/workflow-templates/opsscript-gate.yml).
+For a one-click setup in another public repository, use the InstallReady scanner above; it opens GitHub's
+workflow editor with the generated file ready to review.
 
 You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
 and change the `script-path`, or use the minimal workflow below.
@@ -99,7 +102,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+        with:
+          persist-credentials: false
+      - uses: Mresyzz/opsscript-gate@v0.7.0
 ```
 
 This zero-configuration form discovers shell scripts in the repository. Use
@@ -110,7 +115,7 @@ repository has a single installer. For self-hosted model installers, see the
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+      - uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -140,8 +145,9 @@ unrelated scripts:
 ```yaml
       - uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+      - uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal
@@ -218,6 +224,28 @@ The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 </details>
 ```
 
+### SARIF for Code Scanning
+
+Use `sarif` when the result should appear in GitHub Code Scanning or another
+SARIF-compatible viewer. Upload it explicitly with the official upload action:
+
+```yaml
+- uses: Mresyzz/opsscript-gate@v0.7.0
+  with:
+    script-path: scripts/install.sh
+    format: sarif
+    output: reports/opsscript-gate.sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with:
+    sarif_file: reports/opsscript-gate.sarif
+```
+
+Each runtime failure becomes a location-aware result with the distribution,
+exit code, command, and diagnostic line. A passing matrix produces a valid SARIF
+file with no findings.
+
 ---
 
 ## Example: runtime behavior that static analysis misses
@@ -353,6 +381,12 @@ Customize the matrix at any time via `--matrix` or Action input `matrix`.
 
 ## CLI reference
 
+Check local prerequisites before starting containers:
+
+```text
+opsscript-gate doctor [--format table|json]
+```
+
 ```text
 usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
                           [--format {table,markdown,json}]
@@ -368,7 +402,7 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | `-j, --jobs` | Integer | `min(2, size)` | Number of concurrent container jobs |
 | `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images |
 | `--timeout` | Integer | `60` | Hard timeout per container in seconds |
-| `--format` | Choice | `table` | Output format: `table`, `markdown`, or `json` |
+| `--format` | Choice | `table` | Output format: `table`, `markdown`, `json`, or `sarif` |
 | `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
 | `--pids-limit`| Integer | `128` | Maximum number of processes per container |
@@ -405,14 +439,6 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## Downstream example
-
-[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
-
-See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
-
----
-
 ## 🧪 Development & Testing
 
 ```bash

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/README.md

@@ -18,15 +18,15 @@
 It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 If your repository contains an installer, bootstrap script, or shell entrypoint, the fastest path is to
-copy the [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml). It only runs when
-shell files change, uses offline containers by default, and uploads a report that can be attached to a PR.
-No account, API key, or service signup is required.
+open the [InstallReady scanner](https://mresyzz.github.io/InstallReady/), enter `owner/repository`, and
+choose **Add workflow on GitHub**. It generates a reviewable workflow without an account, API key, or
+service signup. You can also copy the maintained [zero-configuration workflow](.github/workflow-templates/opsscript-gate.yml).
 
 Try the browser scanner: [InstallReady](https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate) checks this repository without executing code or requiring a login.
 
 ---
 
-## Current release: v0.6.2
+## Current release: v0.7.0
 
 The current release includes a project config file, a dry-run plan, presets, exclusions,
 saved reports, and changed-script selection for pull requests. The project controls
@@ -34,6 +34,7 @@ were introduced in v0.5.0; projects on v0.4.1 and earlier do not include them.
 
 ```bash
 opsscript-gate init
+opsscript-gate doctor
 opsscript-gate run --dry-run
 opsscript-gate run --format json --output reports/compatibility.json
 ```
@@ -41,6 +42,7 @@ opsscript-gate run --format json --output reports/compatibility.json
 `init` creates `.opsscript-gate.json` and a GitHub Actions workflow without replacing
 existing files. Review its exclusions (`tests/*`, `examples/*`) and offline network
 default before running. No Docker is required for `init` or `--dry-run`.
+Use `opsscript-gate doctor` to check Python and Docker before a real run.
 
 Useful for standalone installers, container entrypoints and release scripts that
 must work on both GNU/Linux and Alpine/BusyBox. Each script runs independently;
@@ -54,8 +56,9 @@ See [configuration and migration](docs/configuration.md) and
 
 Add this workflow to `.github/workflows/shell-compat.yml`:
 
-You can also select **OpsScript Gate shell compatibility** from GitHub's workflow templates, or copy the
-maintained [starter workflow](.github/workflow-templates/opsscript-gate.yml).
+The repository includes a maintained [workflow template](.github/workflow-templates/opsscript-gate.yml).
+For a one-click setup in another public repository, use the InstallReady scanner above; it opens GitHub's
+workflow editor with the generated file ready to review.
 
 You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
 and change the `script-path`, or use the minimal workflow below.
@@ -69,7 +72,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+        with:
+          persist-credentials: false
+      - uses: Mresyzz/opsscript-gate@v0.7.0
 ```
 
 This zero-configuration form discovers shell scripts in the repository. Use
@@ -80,7 +85,7 @@ repository has a single installer. For self-hosted model installers, see the
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+      - uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -110,8 +115,9 @@ unrelated scripts:
 ```yaml
       - uses: actions/checkout@v7
         with:
+          persist-credentials: false
           fetch-depth: 0
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+      - uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal
@@ -188,6 +194,28 @@ The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 </details>
 ```
 
+### SARIF for Code Scanning
+
+Use `sarif` when the result should appear in GitHub Code Scanning or another
+SARIF-compatible viewer. Upload it explicitly with the official upload action:
+
+```yaml
+- uses: Mresyzz/opsscript-gate@v0.7.0
+  with:
+    script-path: scripts/install.sh
+    format: sarif
+    output: reports/opsscript-gate.sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with:
+    sarif_file: reports/opsscript-gate.sarif
+```
+
+Each runtime failure becomes a location-aware result with the distribution,
+exit code, command, and diagnostic line. A passing matrix produces a valid SARIF
+file with no findings.
+
 ---
 
 ## Example: runtime behavior that static analysis misses
@@ -323,6 +351,12 @@ Customize the matrix at any time via `--matrix` or Action input `matrix`.
 
 ## CLI reference
 
+Check local prerequisites before starting containers:
+
+```text
+opsscript-gate doctor [--format table|json]
+```
+
 ```text
 usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
                           [--format {table,markdown,json}]
@@ -338,7 +372,7 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | `-j, --jobs` | Integer | `min(2, size)` | Number of concurrent container jobs |
 | `--matrix` | String | `debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20` | Comma-separated list of Docker images |
 | `--timeout` | Integer | `60` | Hard timeout per container in seconds |
-| `--format` | Choice | `table` | Output format: `table`, `markdown`, or `json` |
+| `--format` | Choice | `table` | Output format: `table`, `markdown`, `json`, or `sarif` |
 | `--shell` | Choice | `posix` | Execution mode: `posix` (default), `shebang`, or `auto` |
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
 | `--pids-limit`| Integer | `128` | Maximum number of processes per container |
@@ -375,14 +409,6 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## Downstream example
-
-[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
-
-See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
-
----
-
 ## 🧪 Development & Testing
 
 ```bash

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/README.zh-CN.md

@@ -10,9 +10,9 @@ Bash 依赖、包管理器假设和交互式阻塞。它与 ShellCheck 互补。
 
 也可以直接打开 [InstallReady 在线扫描器](https://mresyzz.github.io/InstallReady/?repo=Mresyzz%2Fopsscript-gate)，无需登录即可检查公开仓库。
 
-## 当前版本 v0.6.2
+## 当前版本 v0.7.0
 
-v0.6.2 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
+v0.7.0 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
 
 ```bash
 pip install -e .
@@ -23,13 +23,19 @@ opsscript-gate run examples/basic/clean_setup.sh --dry-run
 
 ```bash
 opsscript-gate init
+opsscript-gate doctor
 opsscript-gate run --dry-run
 opsscript-gate run --format json --output reports/compatibility.json
 ```
 
-`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.6.2`。
+`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.7.0`。
 预览不需要 Docker；真实运行需要 Python 3.10+
 和可访问的 Linux Docker 引擎。
+`opsscript-gate doctor` 可以在真实运行前检查 Python 和 Docker。
+
+需要接入 GitHub Code Scanning 时，将 `--format sarif --output reports/opsscript-gate.sarif`
+传给运行命令，再用 `github/codeql-action/upload-sarif@v3` 上传报告。每个失败发行版
+都会保留脚本路径、诊断行号、命令和退出码；全部通过时仍会生成合法的空 SARIF 报告。
 
 生成的配置默认排除 `tests/*`、`examples/*`，使用 Debian + Alpine，尊重
 脚本 shebang，并关闭网络。请根据实际脚本审核配置；需要下载文件时启用
@@ -47,13 +53,16 @@ opsscript-gate run --format json --output reports/compatibility.json
 返回码 `0` 表示全部通过，`1` 表示检查失败或发生错误。`--dry-run` 成功只表示
 执行计划生成成功。容器不是不可信代码的安全沙箱。
 
+需要排查本地环境时运行 `opsscript-gate doctor --format json`；它会检查 Python、
+Docker daemon 和可选的项目配置。
+
 在 Pull Request 中只检查本次修改的脚本，可以先获取完整 Git 历史，再传入目标分支提交：
 
 ```yaml
 - uses: actions/checkout@v7
   with:
     fetch-depth: 0
-- uses: Mresyzz/opsscript-gate@v0.6.2
+- uses: Mresyzz/opsscript-gate@v0.7.0
   with:
     changed-since: ${{ github.event.pull_request.base.sha }}
     preset: minimal

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/action.yml

@@ -1,5 +1,5 @@
 name: 'OpsScript Gate'
-description: 'Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge'
+description: 'Run Linux shell installers across Debian, Ubuntu, and Alpine; a ShellCheck companion for runtime compatibility in CI.'
 author: 'Mresyzz'
 branding:
   icon: 'shield'
@@ -23,7 +23,7 @@ inputs:
     required: false
     default: ''
   format:
-    description: 'Output report format: table, markdown, or json'
+    description: 'Output report format: table, markdown, json, or sarif'
     required: false
     default: ''
   shell:

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/docs/configuration.md

@@ -7,11 +7,15 @@ have these commands.
 
 ```bash
 opsscript-gate init
+opsscript-gate doctor
 opsscript-gate run --dry-run
 ```
 
 `init` refuses to overwrite either `.opsscript-gate.json` or
-`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.6.2 tag.
+`.github/workflows/opsscript-gate.yml`. The generated workflow uses the v0.7.0 tag.
+
+`doctor` checks Python and Docker connectivity without executing repository scripts.
+Use `opsscript-gate doctor --format json` when collecting a support report.
 
 The generated config uses the two-image `minimal` preset, honors recognized shell
 shebangs, disables networking, and excludes `tests/*` and `examples/*`. Review these
@@ -95,7 +99,7 @@ For pull requests, set `changed-since` to the base commit and fetch full Git his
 - uses: actions/checkout@v7
   with:
     fetch-depth: 0
-- uses: Mresyzz/opsscript-gate@v0.6.2
+- uses: Mresyzz/opsscript-gate@v0.7.0
   with:
     changed-since: ${{ github.event.pull_request.base.sha }}
     preset: minimal
@@ -105,7 +109,7 @@ The Action passes when no changed shell scripts are selected. This keeps unrelat
 documentation or application changes from starting container jobs.
 
 ```yaml
-- uses: Mresyzz/opsscript-gate@v0.6.2
+- uses: Mresyzz/opsscript-gate@v0.7.0
   with:
     config: .opsscript-gate.json
     format: json

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/docs/gpt-oss.md

@@ -33,7 +33,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+      - uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           changed-since: ${{ github.event.pull_request.base.sha }}
           preset: minimal

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/examples/github-actions/README.md

@@ -2,4 +2,4 @@
 
 This example shows a GitHub Actions workflow for checking a shell script on pull requests.
 
-Copy `workflow.yml` into your repository at `.github/workflows/script-gate.yml` and point `script-path` to the script you want to validate. The example uses the current v0.6.2 Action release.
+Copy `workflow.yml` into your repository at `.github/workflows/script-gate.yml` and point `script-path` to the script you want to validate. The example uses the current v0.7.0 Action release.

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/examples/github-actions/workflow.yml

@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
 
       - name: Run OpsScript Gate
-        uses: Mresyzz/opsscript-gate@v0.6.2
+        uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           script-path: 'scripts/deploy.sh'
           shell: auto

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opsscript-gate"
-version = "0.6.2"
+version = "0.7.0"
 description = "Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge"
 readme = "README.md"
 license = { text = "MIT" }
@@ -29,6 +29,10 @@ keywords = [
     "ubuntu",
     "alpine",
     "shellcheck-alternative",
+    "shellcheck",
+    "shell-portability",
+    "installer-testing",
+    "busybox",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/src/opsscript_gate/__init__.py

@@ -1,4 +1,4 @@
 """OpsScript Gate: Lightweight cross-distro compatibility pre-check for Linux ops scripts."""
 
-__version__ = "0.6.2"
+__version__ = "0.7.0"
 __all__ = ["__version__"]

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/src/opsscript_gate/cli.py

@@ -15,8 +15,10 @@ from opsscript_gate.reporter import (
     emit_github_annotations,
     format_github_summary,
     format_json,
+    format_multi_sarif,
     format_multi_github_summary,
     format_multi_terminal_table,
+    format_sarif,
     format_terminal_table,
     write_github_step_summary,
 )
@@ -24,6 +26,7 @@ from opsscript_gate.runner import (
     DEFAULT_MATRIX,
     DEFAULT_TIMEOUT,
     DockerDaemonError,
+    get_docker_client,
     run_matrix,
 )
 
@@ -43,6 +46,16 @@ def build_parser() -> argparse.ArgumentParser:
 
     subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
     subparsers.add_parser("init", help="Create project configuration and GitHub workflow")
+    doctor_parser = subparsers.add_parser(
+        "doctor",
+        help="Check the local environment before running containers",
+    )
+    doctor_parser.add_argument(
+        "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Output format: 'table' (default) or 'json'",
+    )
 
     # 'run' subcommand
     run_parser = subparsers.add_parser(
@@ -80,9 +93,9 @@ def build_parser() -> argparse.ArgumentParser:
     )
     run_parser.add_argument(
         "--format",
-        choices=["table", "markdown", "json"],
+        choices=["table", "markdown", "json", "sarif"],
         default="table",
-        help="Output report format: 'table' (default ASCII), 'markdown', or 'json'",
+        help="Output report format: 'table' (default ASCII), 'markdown', 'json', or 'sarif'",
     )
     run_parser.add_argument(
         "--shell",
@@ -149,6 +162,38 @@ def main(argv: list[str] | None = None) -> int:
             sys.stderr.write(f"Error: {err}\n")
             return 1
 
+    if args.command == "doctor":
+        checks = [
+            {
+                "name": "python",
+                "ok": sys.version_info >= (3, 10),
+                "detail": f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            }
+        ]
+        try:
+            get_docker_client()
+            checks.append({"name": "docker", "ok": True, "detail": "Docker daemon is reachable"})
+        except DockerDaemonError as err:
+            checks.append({"name": "docker", "ok": False, "detail": str(err)})
+
+        config_path = Path(".opsscript-gate.json")
+        checks.append({
+            "name": "project",
+            "ok": True,
+            "detail": f"Found {config_path}" if config_path.is_file() else "No project config (optional)",
+        })
+        passed = all(check["ok"] for check in checks)
+        if args.format == "json":
+            print(json.dumps({"status": "PASS" if passed else "FAIL", "checks": checks}, indent=2))
+        else:
+            print("OpsScript Gate doctor")
+            for check in checks:
+                marker = "PASS" if check["ok"] else "FAIL"
+                print(f"[{marker}] {check['name']}: {check['detail']}")
+            if not passed:
+                print("Run `opsscript-gate init` after fixing the failed check, then preview with `opsscript-gate run --dry-run`.")
+        return 0 if passed else 1
+
     if args.command == "run":
         try:
             config = load_config(args.config)
@@ -258,6 +303,8 @@ def main(argv: list[str] | None = None) -> int:
             # Format report output
             if args.format == "json":
                 output = format_json(report)
+            elif args.format == "sarif":
+                output = format_sarif(report, script_path=script_path)
             elif args.format == "markdown":
                 output = format_github_summary(report, script_path=script_path)
             else:
@@ -310,6 +357,8 @@ def main(argv: list[str] | None = None) -> int:
 
         if args.format == "json":
             output = format_json(multi_report)
+        elif args.format == "sarif":
+            output = format_multi_sarif(multi_report)
         elif args.format == "markdown":
             output = format_multi_github_summary(multi_report)
         else:

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/src/opsscript_gate/config.py

@@ -63,7 +63,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: Mresyzz/opsscript-gate@v0.6.2
+      - uses: Mresyzz/opsscript-gate@v0.7.0
         with:
           config: .opsscript-gate.json
 """,

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/src/opsscript_gate/reporter.py

@@ -3,6 +3,7 @@ import json
 import os
 import re
 import sys
+from opsscript_gate import __version__
 from opsscript_gate.models import DistroStatus, MultiScriptReport, RunReport, SingleResult
 
 # Structure-altering Markdown characters in regular prose:
@@ -463,6 +464,125 @@ def format_json(report: RunReport | MultiScriptReport) -> str:
     return json.dumps(report.to_dict(), indent=2, ensure_ascii=False)
 
 
+_SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+_SARIF_RULES = {
+    DistroStatus.FAIL: ("OSG001", "Runtime compatibility failure"),
+    DistroStatus.TIMED_OUT: ("OSG002", "Runtime compatibility check timed out"),
+    DistroStatus.ERROR: ("OSG003", "Runtime compatibility check error"),
+}
+
+
+def _sarif_path(script_path: str) -> str:
+    """Return a repository-relative SARIF artifact path."""
+    clean = (script_path or "script.sh").replace("\\", "/")
+    while clean.startswith("./"):
+        clean = clean[2:]
+    return clean or "script.sh"
+
+
+def _sarif_message(result: SingleResult) -> str:
+    parts = [f"[{result.distro}] {result.status.value}"]
+    if result.diagnostic:
+        parts.append(result.diagnostic.message)
+        if result.diagnostic.hint:
+            parts.append(result.diagnostic.hint)
+    elif result.error_message:
+        parts.append(result.error_message)
+    elif result.exit_code is not None:
+        parts.append(f"Execution exited with code {result.exit_code}.")
+    return " — ".join(parts)
+
+
+def _sarif_result(result: SingleResult, script_path: str) -> dict[str, object] | None:
+    if result.status == DistroStatus.PASS:
+        return None
+
+    rule_id, rule_name = _SARIF_RULES[result.status]
+    physical_location: dict[str, object] = {
+        "artifactLocation": {
+            "uri": _sarif_path(script_path),
+        },
+    }
+    if result.diagnostic and result.diagnostic.line and result.diagnostic.line > 0:
+        physical_location["region"] = {"startLine": result.diagnostic.line}
+
+    properties: dict[str, object] = {
+        "distribution": result.distro,
+        "status": result.status.value,
+        "durationSeconds": round(result.duration, 3),
+    }
+    if result.exit_code is not None:
+        properties["exitCode"] = result.exit_code
+    if result.diagnostic and result.diagnostic.command:
+        properties["command"] = result.diagnostic.command
+
+    return {
+        "ruleId": rule_id,
+        "level": "error",
+        "message": {"text": _sarif_message(result)},
+        "locations": [{"physicalLocation": physical_location}],
+        "properties": properties,
+        "help": {
+            "text": rule_name,
+            "uri": "https://github.com/Mresyzz/opsscript-gate#ci-output",
+        },
+    }
+
+
+def _sarif_run(results: list[dict[str, object]]) -> dict[str, object]:
+    return {
+        "tool": {
+            "driver": {
+                "name": "OpsScript Gate",
+                "version": __version__,
+                "informationUri": "https://github.com/Mresyzz/opsscript-gate",
+                "rules": [
+                    {
+                        "id": rule_id,
+                        "name": rule_name,
+                        "shortDescription": {"text": rule_name},
+                        "helpUri": "https://github.com/Mresyzz/opsscript-gate#ci-output",
+                    }
+                    for rule_id, rule_name in _SARIF_RULES.values()
+                ],
+            },
+        },
+        "results": results,
+    }
+
+
+def format_sarif(report: RunReport, script_path: str = "") -> str:
+    """Format runtime failures as SARIF 2.1.0 for GitHub Code Scanning."""
+    results = [
+        item
+        for result in report.results
+        if (item := _sarif_result(result, script_path)) is not None
+    ]
+    payload = {
+        "$schema": _SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [_sarif_run(results)],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def format_multi_sarif(report: MultiScriptReport) -> str:
+    """Format multi-script runtime failures as one SARIF 2.1.0 run."""
+    results: list[dict[str, object]] = []
+    for script_path, script_report in report.reports.items():
+        results.extend(
+            item
+            for result in script_report.results
+            if (item := _sarif_result(result, script_path)) is not None
+        )
+    payload = {
+        "$schema": _SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [_sarif_run(results)],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
 def write_github_step_summary(
     report_or_content: RunReport | MultiScriptReport | str,
     script_path: str = "",

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/tests/test_action_contract.py

@@ -14,6 +14,7 @@ def test_action_metadata_is_valid_and_inputs_are_wired():
                  "--network", "--matrix", "--jobs", "--config", "--preset",
                  "--max-scripts", "--output", "--exclude"):
         assert flag in run_text
+    assert "json, or sarif" in text
     assert "--changed-since" in run_text
 
 

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/tests/test_onboarding.py

@@ -8,6 +8,7 @@ from opsscript_gate.cli import main
 from opsscript_gate.config import CONFIG_NAME, init_project, load_config
 from opsscript_gate.discovery import discover_changed_scripts, discover_scripts, is_shell_script
 from opsscript_gate.models import RunReport, SingleResult, DistroStatus
+from opsscript_gate.runner import DockerDaemonError
 
 
 @pytest.fixture
@@ -35,6 +36,27 @@ def test_init_preview_and_no_overwrite(project, capsys):
     assert Path(CONFIG_NAME).read_bytes() == original
 
 
+def test_doctor_reports_local_prerequisites(project, capsys):
+    with patch("opsscript_gate.cli.get_docker_client"):
+        assert main(["doctor"]) == 0
+    output = capsys.readouterr().out
+    assert "OpsScript Gate doctor" in output
+    assert "[PASS] python" in output
+    assert "[PASS] docker" in output
+    assert "No project config (optional)" in output
+
+
+def test_doctor_json_reports_docker_failure(project, capsys):
+    with patch(
+        "opsscript_gate.cli.get_docker_client",
+        side_effect=DockerDaemonError("Docker is not running"),
+    ):
+        assert main(["doctor", "--format", "json"]) == 1
+    report = json.loads(capsys.readouterr().out)
+    assert report["status"] == "FAIL"
+    assert next(check for check in report["checks"] if check["name"] == "docker")["ok"] is False
+
+
 def test_init_existing_workflow_leaves_config_absent(project):
     workflow = project / ".github/workflows/opsscript-gate.yml"
     workflow.parent.mkdir(parents=True)

{opsscript_gate-0.6.2 → opsscript_gate-0.7.0}/tests/test_runner.py

@@ -19,8 +19,10 @@ from opsscript_gate.reporter import (
     format_github_annotations,
     format_github_summary,
     format_json,
+    format_multi_sarif,
     format_multi_github_summary,
     format_multi_terminal_table,
+    format_sarif,
     format_terminal_table,
     write_github_step_summary,
 )
@@ -300,6 +302,54 @@ def test_reporter_json():
     assert data["results"][0]["status"] == "PASS"
 
 
+def test_reporter_sarif_contains_failure_location_and_metadata():
+    result = SingleResult(
+        "alpine:3.20",
+        DistroStatus.FAIL,
+        127,
+        0.42,
+        diagnostic=FailureDiagnostic(
+            kind="missing_command",
+            message="apt-get: command not found",
+            command="apt-get",
+            line=4,
+            distro="alpine:3.20",
+            hint="Use apk instead of apt-get.",
+        ),
+    )
+    report = RunReport([SingleResult("debian:12-slim", DistroStatus.PASS, 0, 0.2), result])
+
+    payload = json.loads(format_sarif(report, script_path="./scripts/install.sh"))
+    assert payload["$schema"].endswith("sarif-2.1.0.json")
+    assert payload["version"] == "2.1.0"
+    finding = payload["runs"][0]["results"][0]
+    assert finding["ruleId"] == "OSG001"
+    assert finding["level"] == "error"
+    assert finding["locations"][0]["physicalLocation"]["artifactLocation"]["uri"] == "scripts/install.sh"
+    assert finding["locations"][0]["physicalLocation"]["region"]["startLine"] == 4
+    assert finding["properties"]["distribution"] == "alpine:3.20"
+    assert finding["properties"]["command"] == "apt-get"
+
+
+def test_reporter_multi_sarif_keeps_script_paths():
+    report = MultiScriptReport(
+        reports={
+            "install.sh": RunReport([SingleResult("alpine:3.20", DistroStatus.FAIL, 1, 0.1)]),
+            "scripts/setup.sh": RunReport([SingleResult("debian:12-slim", DistroStatus.TIMED_OUT, None, 5.0)]),
+        },
+        total_duration=5.1,
+    )
+
+    payload = json.loads(format_multi_sarif(report))
+    results = payload["runs"][0]["results"]
+    assert len(results) == 2
+    paths = {
+        result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
+        for result in results
+    }
+    assert paths == {"install.sh", "scripts/setup.sh"}
+
+
 def test_write_github_step_summary(tmp_path):
     summary_file = tmp_path / "step_summary.md"
     r1 = SingleResult("debian:12-slim", DistroStatus.PASS, 0, 1.0)