ai-saas-guard 0.1.3 → 0.2.0

package/README.md

@@ -41,7 +41,7 @@ It is intentionally evidence-first. Findings include a rule ID, severity, file e
 
 This repository is public on GitHub.
 
-The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. If you need stricter supply-chain pinning in CI, pin the GitHub Action to a reviewed commit SHA instead of a mutable tag.
+The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag for controlled upgrades, or a reviewed commit SHA for stricter supply-chain pinning.
 
 | Area | Status |
 | --- | --- |
@@ -50,8 +50,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Local CLI from source | Available for development |
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
-| Versioned Action tags | `v0.1.3` |
-| npm package | `ai-saas-guard@0.1.3` |
+| Versioned Action tags | `v0.2.0`, `v0` |
+| npm package | `ai-saas-guard@0.2.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -76,6 +76,7 @@ Machine-readable output:
 ```bash
 npx ai-saas-guard@latest scan --root /path/to/your-saas --json
 npx ai-saas-guard@latest scan --root /path/to/your-saas --sarif > ai-saas-guard.sarif
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --markdown > ai-saas-guard-pr.md
 npx ai-saas-guard@latest scan --root /path/to/your-saas --fail-on high
 ```
 
@@ -148,9 +149,11 @@ AI-generated PRs often combine unrelated work:
 - suggested PR split
 - required tests or manual verification
 - explicit git-diff diagnostics when a base ref or shallow checkout prevents PR classification
+- PR-focused markdown for GitHub step summaries or PR comments
 
 ```bash
 node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --json
+node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --markdown
 ```
 
 If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` instead of silently reporting a clean or empty diff. In GitHub Actions, use `actions/checkout` with `fetch-depth: 0` when you need merge-base comparison against `origin/main`.
@@ -160,14 +163,14 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
 | Command | Purpose |
 | --- | --- |
 | `scan` | Broad local launch preflight across secrets, Stripe, Supabase, MCP, API routes, and deploy config |
-| `pr-risk` | Classify the current git diff or a base branch diff for review priority |
+| `pr-risk` | Classify the current git diff or a base branch diff for review priority; supports JSON, SARIF, and PR-focused markdown |
 | `check-supabase` | Inspect migrations and policy files for RLS and ownership risks |
 | `check-stripe` | Inspect webhook handlers and billing lifecycle coverage |
 | `check-mcp` | Inventory MCP configs and classify side effects |
 
 ## GitHub Action
 
-The repo includes a composite Action. Use the latest release tag or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.2.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -185,7 +188,7 @@ jobs:
       - uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0
-      - uses: zr9959/ai-saas-guard@v0.1.3
+      - uses: zr9959/ai-saas-guard@v0
         with:
           command: pr-risk
           root: ${{ github.workspace }}
@@ -196,7 +199,7 @@ jobs:
 For SARIF upload:
 
 ```yaml
-      - uses: zr9959/ai-saas-guard@v0.1.3
+      - uses: zr9959/ai-saas-guard@v0
         with:
           command: scan
           format: sarif
@@ -206,7 +209,22 @@ For SARIF upload:
           sarif_file: ai-saas-guard.sarif
 ```
 
-For maximum reproducibility, replace `v0.1.3` with the full commit SHA from the release notes.
+For PR-readable markdown in the Actions run:
+
+```yaml
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: pr-risk
+          root: ${{ github.workspace }}
+          base: origin/main
+          format: markdown
+          output: ai-saas-guard-pr.md
+      - run: cat ai-saas-guard-pr.md >> "$GITHUB_STEP_SUMMARY"
+```
+
+Use markdown for reviewer-facing PR triage and SARIF for GitHub code scanning alerts. See [docs/github-action.md](docs/github-action.md) for copy-paste workflows and trade-offs.
+
+For maximum reproducibility, replace `v0` with the full commit SHA from the release notes.
 
 ## Ignore File
 
@@ -274,17 +292,16 @@ Open-source core:
 - local CLI
 - deterministic scanner rules
 - vulnerable and safe fixtures
-- JSON and SARIF output
+- JSON, SARIF, and PR-focused markdown output
 - GitHub Action wrapper
 - rule documentation
 
 Near-term priorities:
 
-- PR comment summary mode
 - configurable severity and rule toggles
 - expanded Supabase RLS fixtures
 - Stripe webhook replay cookbook
-- SARIF upload workflow example
+- launch-readiness checklist content
 
 Potential paid layer later:
 

package/action.yml

@@ -12,7 +12,7 @@ inputs:
     required: false
     default: ${{ github.workspace }}
   format:
-    description: "Output format: terminal, json, or sarif."
+    description: "Output format: terminal, json, sarif, or markdown."
     required: false
     default: terminal
   fail-on:
@@ -62,7 +62,7 @@ runs:
         esac
 
         case "${INPUT_FORMAT}" in
-          terminal|json|sarif) ;;
+          terminal|json|sarif|markdown) ;;
           *)
             echo "Invalid format input: ${INPUT_FORMAT}" >&2
             exit 2
@@ -83,6 +83,8 @@ runs:
           args+=("--json")
         elif [ "${INPUT_FORMAT}" = "sarif" ]; then
           args+=("--sarif")
+        elif [ "${INPUT_FORMAT}" = "markdown" ]; then
+          args+=("--markdown")
         fi
 
         if [ "${INPUT_FAIL_ON}" != "none" ]; then

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { resolve } from "node:path";
 import { checkMcp, checkStripe, checkSupabase, classifyPrRisk, scanRepository } from "./index.js";
 import { formatJsonReport } from "./report/json.js";
+import { formatMarkdownReport } from "./report/markdown.js";
 import { formatSarifReport } from "./report/sarif.js";
 import { formatTerminalReport } from "./report/terminal.js";
 async function main(argv) {
@@ -57,10 +58,14 @@ function parseArgs(argv) {
             result.format = "sarif";
             continue;
         }
+        if (arg === "--markdown") {
+            result.format = "markdown";
+            continue;
+        }
         if (arg === "--format") {
             const value = argv[index + 1];
-            if (value !== "terminal" && value !== "json" && value !== "sarif") {
-                throw new Error("--format requires terminal, json, or sarif");
+            if (value !== "terminal" && value !== "json" && value !== "sarif" && value !== "markdown") {
+                throw new Error("--format requires terminal, json, sarif, or markdown");
             }
             result.format = value;
             index += 1;
@@ -108,6 +113,8 @@ function formatReport(report, format) {
         return formatJsonReport(report);
     if (format === "sarif")
         return formatSarifReport(report);
+    if (format === "markdown")
+        return formatMarkdownReport(report);
     return `${formatTerminalReport(report)}\n`;
 }
 function shouldFail(report, failOn) {
@@ -138,7 +145,7 @@ Usage:
   ai-saas-guard check-supabase [--root <repo>] [--json|--sarif] [--fail-on <severity>]
   ai-saas-guard check-stripe [--root <repo>] [--json|--sarif] [--fail-on <severity>]
   ai-saas-guard check-mcp [--root <repo>] [--json|--sarif] [--fail-on <severity>]
-  ai-saas-guard pr-risk [--root <repo>] [--base <branch>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard pr-risk [--root <repo>] [--base <branch>] [--json|--sarif|--markdown] [--fail-on <severity>]
 
 Defaults:
   - read-only
@@ -146,6 +153,7 @@ Defaults:
   - no account or login required
   - terminal output by default, JSON with --json
   - SARIF output for GitHub code scanning with --sarif
+  - PR-focused markdown summary with --markdown
 `;
 }
 main(process.argv.slice(2)).then((code) => {

package/dist/report/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { BaseReport } from "../types.js";
+export declare function formatMarkdownReport(report: BaseReport): string;

package/dist/report/markdown.js

@@ -0,0 +1,83 @@
+export function formatMarkdownReport(report) {
+    if (report.command === "pr-risk")
+        return `${formatPrRiskMarkdown(report)}\n`;
+    return `${formatGenericMarkdown(report)}\n`;
+}
+function formatPrRiskMarkdown(report) {
+    const lines = [];
+    lines.push("## ai-saas-guard PR risk summary");
+    lines.push("");
+    lines.push(summaryLine(report));
+    if (report.categories.length > 0) {
+        lines.push("");
+        lines.push(`**Risk categories:** ${report.categories.map((category) => `\`${category}\``).join(", ")}`);
+    }
+    lines.push("");
+    lines.push("### Review first");
+    if (report.topRiskyFiles.length === 0) {
+        lines.push("");
+        lines.push("No changed trust-boundary files were classified by `pr-risk`.");
+    }
+    else {
+        lines.push("");
+        lines.push("| File | Score | Categories | Diff |");
+        lines.push("| --- | ---: | --- | ---: |");
+        for (const file of report.topRiskyFiles.slice(0, 10)) {
+            lines.push(`| \`${escapeMarkdownTableCell(file.path)}\` | ${file.score} | ${file.categories.map((category) => `\`${escapeMarkdownTableCell(category)}\``).join("<br>")} | +${file.added} / -${file.removed} |`);
+        }
+    }
+    lines.push("");
+    lines.push("### Required verification");
+    appendList(lines, report.requiredTests.length > 0 ? report.requiredTests : report.reviewChecklist);
+    lines.push("");
+    lines.push("### Suggested PR split");
+    appendList(lines, report.suggestedSplit.length > 0 ? report.suggestedSplit : ["No split suggestion from the current diff."]);
+    lines.push("");
+    lines.push("### Findings");
+    appendFindings(lines, report.findings);
+    return lines.join("\n");
+}
+function formatGenericMarkdown(report) {
+    const lines = [];
+    lines.push(`## ai-saas-guard ${report.command}`);
+    lines.push("");
+    lines.push(summaryLine(report));
+    lines.push("");
+    lines.push("### Findings");
+    appendFindings(lines, report.findings);
+    return lines.join("\n");
+}
+function summaryLine(report) {
+    return `**Findings:** ${report.summary.total} total | critical ${report.summary.critical} | high ${report.summary.high} | medium ${report.summary.medium} | low ${report.summary.low} | info ${report.summary.info}`;
+}
+function appendList(lines, items) {
+    for (const item of items) {
+        lines.push(`- ${item}`);
+    }
+}
+function appendFindings(lines, findings) {
+    if (findings.length === 0) {
+        lines.push("");
+        lines.push("No heuristic launch-readiness risks found by this command.");
+        return;
+    }
+    for (const [index, finding] of findings.entries()) {
+        lines.push("");
+        lines.push(`${index + 1}. **[${finding.severity.toUpperCase()}] ${finding.title}**`);
+        lines.push(`   - Rule: \`${finding.ruleId}\``);
+        lines.push(`   - Evidence: ${formatEvidence(finding.evidence[0])}`);
+        lines.push(`   - Why: ${finding.why}`);
+        lines.push(`   - Verify: ${finding.suggestedVerification}`);
+        lines.push(`   - Fix direction: ${finding.suggestedFix}`);
+    }
+}
+function formatEvidence(evidence) {
+    if (!evidence)
+        return "`none`";
+    const location = evidence.line ? `${evidence.file}:${evidence.line}` : evidence.file;
+    const detail = evidence.snippet ?? evidence.match;
+    return detail ? `\`${location}\` - ${detail}` : `\`${location}\``;
+}
+function escapeMarkdownTableCell(value) {
+    return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}

package/docs/github-action.md

@@ -0,0 +1,69 @@
+# GitHub Action Usage
+
+`ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
+
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.2.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+
+## PR Summary
+
+Use markdown when reviewers need a short, evidence-first summary of risky files, required verification, and suggested PR split.
+
+```yaml
+name: ai-saas-guard-pr-summary
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pr-summary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: pr-risk
+          root: ${{ github.workspace }}
+          base: origin/main
+          format: markdown
+          output: ai-saas-guard-pr.md
+      - run: cat ai-saas-guard-pr.md >> "$GITHUB_STEP_SUMMARY"
+```
+
+Use markdown for PR review triage. It is intentionally short enough for a GitHub step summary or a PR comment created by your own workflow. It does not require a hosted service.
+
+## SARIF Upload
+
+Use SARIF when you want findings to appear in GitHub code scanning alerts.
+
+```yaml
+name: ai-saas-guard-sarif
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  code-scanning:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: scan
+          root: ${{ github.workspace }}
+          format: sarif
+          output: ai-saas-guard.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ai-saas-guard.sarif
+```
+
+Use SARIF for tracking alerts over time. Use markdown for reviewer guidance on a specific PR. Many teams should run both: markdown for quick review order, SARIF for code scanning visibility.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.1.3`
+- Current version: `0.2.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.1.3`
+- GitHub Release: `v0.2.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.1.3`.
+1. Create and review a release tag such as `v0.2.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -46,6 +46,7 @@ Implemented surfaces:
 - Next/Vercel deploy and runtime footguns
 - PR diff risk triage for auth, billing, RLS, env, tests removed, and large mixed diffs
 - PR diff diagnostics when a base ref or shallow checkout prevents comparison
+- PR-focused markdown summary output for GitHub step summaries or PR comments
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
@@ -98,13 +99,9 @@ GitHub Project:
 Current issue set:
 
 - #1 Add launch-readiness checklist content
-- #2 Add GitHub Action release packaging
 - #3 Add configurable rule severity and rule toggles
-- #4 Add PR comment summary mode
 - #5 Write Stripe webhook replay cookbook
-- #6 Add SARIF upload workflow example
 - #7 Expand Supabase RLS fixtures and ownership patterns
-- #8 Publish ai-saas-guard to npm
 
 CI:
 
@@ -116,7 +113,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.1.3`
+- Current release line: `v0.2.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.
@@ -143,13 +140,11 @@ Not allowed:
 
 Recommended order:
 
-1. Add PR comment summary mode.
-2. Add configurable severity and rule toggles.
-3. Expand Supabase RLS fixtures and ownership patterns.
-4. Write Stripe webhook replay cookbook.
-5. Add SARIF upload workflow example.
-6. Improve false-positive suppression and rule stability labels.
-7. Add a GitHub App design note for the potential hosted layer.
+1. Add configurable severity and rule toggles.
+2. Expand Supabase RLS fixtures and ownership patterns.
+3. Write Stripe webhook replay cookbook.
+4. Improve false-positive suppression and rule stability labels.
+5. Add a GitHub App design note for the potential hosted layer.
 
 For every feature, keep the scanner evidence-first:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",