ai-saas-guard 0.1.2 → 0.1.3

package/README.md

@@ -50,8 +50,9 @@ 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.2` |
-| npm package | `ai-saas-guard@0.1.2` |
+| Versioned Action tags | `v0.1.3` |
+| npm package | `ai-saas-guard@0.1.3` |
+| npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
 
@@ -146,11 +147,14 @@ AI-generated PRs often combine unrelated work:
 - review-first checklist
 - suggested PR split
 - required tests or manual verification
+- explicit git-diff diagnostics when a base ref or shallow checkout prevents PR classification
 
 ```bash
 node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --json
 ```
 
+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`.
+
 ## Commands
 
 | Command | Purpose |
@@ -181,7 +185,7 @@ jobs:
       - uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0
-      - uses: zr9959/ai-saas-guard@v0.1.2
+      - uses: zr9959/ai-saas-guard@v0.1.3
         with:
           command: pr-risk
           root: ${{ github.workspace }}
@@ -192,7 +196,7 @@ jobs:
 For SARIF upload:
 
 ```yaml
-      - uses: zr9959/ai-saas-guard@v0.1.2
+      - uses: zr9959/ai-saas-guard@v0.1.3
         with:
           command: scan
           format: sarif
@@ -202,7 +206,7 @@ For SARIF upload:
           sarif_file: ai-saas-guard.sarif
 ```
 
-For maximum reproducibility, replace `v0.1.2` with the full commit SHA from the release notes.
+For maximum reproducibility, replace `v0.1.3` with the full commit SHA from the release notes.
 
 ## Ignore File
 
@@ -276,7 +280,6 @@ Open-source core:
 
 Near-term priorities:
 
-- npm trusted publishing and provenance
 - PR comment summary mode
 - configurable severity and rule toggles
 - expanded Supabase RLS fixtures
@@ -301,4 +304,4 @@ Please read [SECURITY.md](SECURITY.md) before reporting vulnerabilities. Do not
 
 ## npm Publishing
 
-The package is published as [`ai-saas-guard`](https://www.npmjs.com/package/ai-saas-guard). See [docs/npm-publishing.md](docs/npm-publishing.md) for the GitHub Actions provenance workflow, the first-publish token history, and the trusted-publisher follow-up.
+The package is published as [`ai-saas-guard`](https://www.npmjs.com/package/ai-saas-guard). See [docs/npm-publishing.md](docs/npm-publishing.md) for the GitHub Actions Trusted Publisher workflow, provenance notes, and first-publish token history.

package/dist/rules/catalog.js

@@ -195,6 +195,13 @@ export const RULE_CATALOG = {
         why: "AI-generated PRs often bury trust-boundary changes inside larger diffs.",
         stability: "default"
     },
+    "pr-risk.diff-unavailable": {
+        ruleId: "pr-risk.diff-unavailable",
+        severity: "info",
+        title: "Git diff could not be read",
+        why: "PR classification can be misleading when the requested base ref or Git history is unavailable.",
+        stability: "default"
+    },
     "pr-risk.no-diff": {
         ruleId: "pr-risk.no-diff",
         severity: "info",

package/dist/scanners/gitDiff.js

@@ -14,10 +14,13 @@ const categoryWeights = {
     "large AI-generated/refactor-like diff": 18
 };
 export async function classifyPrRisk(options) {
-    const diffText = options.diffText ?? (await readGitDiff(options.rootDir, options.base));
+    const diffResult = options.diffText === undefined
+        ? await readGitDiff(options.rootDir, options.base)
+        : { diffText: options.diffText, diagnostics: [] };
+    const { diffText } = diffResult;
     const files = parseDiffFiles(diffText);
     const categories = new Set();
-    const findings = [];
+    const findings = [...diffResult.diagnostics];
     for (const file of files) {
         for (const category of file.categories) {
             categories.add(category);
@@ -44,7 +47,7 @@ export async function classifyPrRisk(options) {
             suggestedFix: "Split unrelated UI/refactor work away from trust-boundary changes and add focused tests before merge."
         }));
     }
-    if (diffText.trim().length === 0) {
+    if (diffText.trim().length === 0 && diffResult.diagnostics.length === 0) {
         findings.push(finding({
             ruleId: "pr-risk.no-diff",
             title: "No git diff found",
@@ -68,13 +71,17 @@ async function readGitDiff(rootDir, base) {
     if (base) {
         try {
             const { stdout } = await execFileAsync("git", ["diff", `${base}...HEAD`], { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
-            return stdout;
+            return { diffText: stdout, diagnostics: [] };
         }
-        catch {
-            return "";
+        catch (error) {
+            return {
+                diffText: "",
+                diagnostics: [buildGitDiffFailureFinding(rootDir, ["git", "diff", `${base}...HEAD`], error, base)]
+            };
         }
     }
     const parts = [];
+    const failures = [];
     for (const args of [
         ["diff", "--cached"],
         ["diff"]
@@ -83,11 +90,62 @@ async function readGitDiff(rootDir, base) {
             const { stdout } = await execFileAsync("git", args, { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
             parts.push(stdout);
         }
-        catch {
-            continue;
+        catch (error) {
+            failures.push({ args: ["git", ...args], error });
         }
     }
-    return parts.join("\n");
+    if (parts.length === 0 && failures.length > 0) {
+        return {
+            diffText: "",
+            diagnostics: [buildGitDiffFailureFinding(rootDir, failures[0].args, failures[0].error)]
+        };
+    }
+    return { diffText: parts.join("\n"), diagnostics: [] };
+}
+function buildGitDiffFailureFinding(rootDir, command, error, base) {
+    const errorText = redactRootPath(getGitErrorText(error), rootDir);
+    const lowerError = errorText.toLowerCase();
+    let suggestedVerification = "Run `git status` and confirm the target path is inside a Git repository.";
+    let suggestedFix = "Run `pr-risk` from a Git checkout, or pass explicit diff text through the API.";
+    if (base) {
+        suggestedVerification = `Run \`${buildFetchCommand(base)}\`, then \`git rev-parse --verify ${base}\` to confirm the base ref exists locally.`;
+        suggestedFix = "Fetch the branch or pass an existing local base ref, for example `--base origin/main`.";
+    }
+    if (base && (lowerError.includes("no merge base") || lowerError.includes("shallow"))) {
+        suggestedVerification = "Run `git rev-parse --is-shallow-repository` and confirm CI checks out full history before `pr-risk`.";
+        suggestedFix = "Use `fetch-depth: 0` in `actions/checkout`, or run `git fetch --unshallow` before invoking `pr-risk`.";
+    }
+    return finding({
+        ruleId: "pr-risk.diff-unavailable",
+        title: base ? `Could not read git diff for base ${base}` : "Could not read git diff",
+        severity: "info",
+        evidence: [
+            {
+                file: ".",
+                match: command.join(" "),
+                snippet: errorText.slice(0, 500)
+            }
+        ],
+        why: "PR risk classification needs a readable git diff, but the git command failed for the target repository.",
+        suggestedVerification,
+        suggestedFix
+    });
+}
+function buildFetchCommand(base) {
+    const remoteRef = /^([^/\s]+)\/(.+)$/.exec(base);
+    if (remoteRef)
+        return `git fetch ${remoteRef[1]} ${remoteRef[2]}`;
+    return `git fetch origin ${base}`;
+}
+function redactRootPath(text, rootDir) {
+    return rootDir ? text.replaceAll(rootDir, ".") : text;
+}
+function getGitErrorText(error) {
+    const candidate = error;
+    return [candidate.stderr, candidate.stdout, candidate.message]
+        .filter((value) => Boolean(value?.trim()))
+        .join("\n")
+        .trim() || "git diff exited with a non-zero status.";
 }
 function parseDiffFiles(diffText) {
     const files = [];

package/docs/npm-publishing.md

@@ -5,27 +5,25 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.1.2`
+- Current version: `0.1.3`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.1.2`
+- GitHub Release: `v0.1.3`
 - 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
 
 ## Preferred Path
 
-Use GitHub Actions with npm provenance:
+Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.1.2`.
-2. Run the `Publish npm` workflow manually with `ref` set to that tag.
-3. Configure npm Trusted Publisher for future releases:
-   - Provider: GitHub Actions
-   - Organization or user: `zr9959`
-   - Repository: `ai-saas-guard`
-   - Workflow filename: `npm-publish.yml`
-   - Allowed action: `npm publish`
-4. Once trusted publishing is verified, remove or rotate any long-lived npm publish token.
+1. Create and review a release tag such as `v0.1.3`.
+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.
+5. Keep npm package publishing access set to require 2FA and disallow traditional tokens. Trusted publishers continue to work because they use OIDC instead of npm auth tokens.
 
-The first npm publish used a temporary granular access token because npm requires a 2FA-bypass token until trusted publishing is configured. The workflow sets `id-token: write`, uses Node 24, and runs `npm publish --provenance --access public`, so it is ready for npm Trusted Publisher OIDC publishing.
+The first npm publish used a temporary granular access token because npm requires a 2FA-bypass token until trusted publishing is configured. That temporary automation token and the GitHub `NPM_TOKEN` secret were removed after the Trusted Publisher migration.
 
 ## Release Gate
 

package/docs/project-handoff.md

@@ -45,9 +45,11 @@ Implemented surfaces:
 - MCP config side-effect and secret-bearing risk inventory
 - 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
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
+- npm publishing through GitHub Actions Trusted Publisher/OIDC
 
 Existing commands:
 
@@ -111,6 +113,14 @@ CI:
 - Uses `permissions: contents: read`
 - Latest verified run after setup succeeded
 
+Publishing:
+
+- npm package: `ai-saas-guard`
+- Current release line: `v0.1.3`
+- 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.
+
 ## Repository Boundaries
 
 Allowed in this public repository:
@@ -133,14 +143,13 @@ Not allowed:
 
 Recommended order:
 
-1. Prepare npm publishing plan with trusted publishing/provenance.
-2. Add GitHub Action release packaging and example workflow.
-3. Add PR comment summary mode.
-4. Add configurable severity and rule toggles.
-5. Expand Supabase RLS fixtures and ownership patterns.
-6. Write Stripe webhook replay cookbook.
-7. Add SARIF upload workflow example.
-8. Improve false-positive suppression and rule stability labels.
+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.
 
 For every feature, keep the scanner evidence-first:
 

package/docs/rules.md

@@ -61,6 +61,7 @@ Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so S
 | Rule ID | Severity | Why it exists |
 | --- | --- | --- |
 | `pr-risk.sensitive-surface` | medium/high | Highlights files reviewers should inspect before cosmetic or refactor files. |
+| `pr-risk.diff-unavailable` | info | Explains when the requested base ref or Git history prevents PR diff classification. |
 | `pr-risk.no-diff` | info | Explains that PR classification needs a diff. |
 
 ## Adding Rules

package/package.json

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