ai-saas-guard 0.2.0 → 0.3.0

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.2.0`, `v0` |
-| npm package | `ai-saas-guard@0.2.0` |
+| Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
+| Versioned Action tags | `v0.3.0`, `v0` |
+| npm package | `ai-saas-guard@0.3.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -77,6 +78,7 @@ Machine-readable output:
 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 --config <file> --json
 npx ai-saas-guard@latest scan --root /path/to/your-saas --fail-on high
 ```
 
@@ -168,9 +170,28 @@ If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` inste
 | `check-stripe` | Inspect webhook handlers and billing lifecycle coverage |
 | `check-mcp` | Inventory MCP configs and classify side effects |
 
+## Project Configuration
+
+Add `.ai-saas-guard.json` at the repository root to tune findings without changing scanner code. The CLI auto-loads this file from `--root` when it exists. Use `--config <file>` to point to a different JSON file.
+
+```json
+{
+  "failOn": "high",
+  "rules": {
+    "stripe.webhook.missing-signature": "off",
+    "stripe.webhook.missing-idempotency": "critical",
+    "deploy.env.example-missing": "info"
+  }
+}
+```
+
+`rules` is keyed by published rule ID from [docs/rules.md](docs/rules.md). Set a rule to `off` to remove matching findings from terminal, JSON, SARIF, and markdown output. Set a rule to `critical`, `high`, `medium`, `low`, or `info` to override severity before summaries and `--fail-on` are evaluated.
+
+`failOn` sets the default CI failure threshold for the project. A CLI `--fail-on` value takes precedence, so local runs can still use `--fail-on none` or a stricter threshold.
+
 ## GitHub Action
 
-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:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.3.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -194,6 +215,7 @@ jobs:
           root: ${{ github.workspace }}
           base: origin/main
           fail-on: high
+          config: .ai-saas-guard.json
 ```
 
 For SARIF upload:
@@ -298,10 +320,10 @@ Open-source core:
 
 Near-term priorities:
 
-- configurable severity and rule toggles
 - expanded Supabase RLS fixtures
 - Stripe webhook replay cookbook
 - launch-readiness checklist content
+- false-positive suppression and rule stability labels
 
 Potential paid layer later:
 

package/action.yml

@@ -23,6 +23,10 @@ inputs:
     description: Base ref for pr-risk.
     required: false
     default: ""
+  config:
+    description: Optional ai-saas-guard JSON config path.
+    required: false
+    default: ""
   output:
     description: Optional path to write output while also keeping the command exit code.
     required: false
@@ -49,6 +53,7 @@ runs:
         INPUT_FORMAT: ${{ inputs.format }}
         INPUT_FAIL_ON: ${{ inputs.fail-on }}
         INPUT_BASE: ${{ inputs.base }}
+        INPUT_CONFIG: ${{ inputs.config }}
         INPUT_OUTPUT: ${{ inputs.output }}
       run: |
         set -o pipefail
@@ -95,6 +100,10 @@ runs:
           args+=("--base" "${INPUT_BASE}")
         fi
 
+        if [ -n "${INPUT_CONFIG}" ]; then
+          args+=("--config" "${INPUT_CONFIG}")
+        fi
+
         if [ -n "${INPUT_OUTPUT}" ]; then
           node "${GITHUB_ACTION_PATH}/dist/cli.js" "${args[@]}" | tee -- "${INPUT_OUTPUT}"
         else

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
+import { applyGuardConfig, loadGuardConfig } from "./config.js";
 import { checkMcp, checkStripe, checkSupabase, classifyPrRisk, scanRepository } from "./index.js";
 import { formatJsonReport } from "./report/json.js";
 import { formatMarkdownReport } from "./report/markdown.js";
@@ -11,6 +12,7 @@ async function main(argv) {
         process.stdout.write(helpText());
         return 0;
     }
+    const config = await loadGuardConfig(args.rootDir, args.configPath);
     let report;
     switch (args.command) {
         case "scan":
@@ -32,9 +34,11 @@ async function main(argv) {
             process.stderr.write(`Unknown command: ${String(args.command)}\n\n${helpText()}`);
             return 2;
     }
+    report = applyGuardConfig(report, config);
     process.stdout.write(formatReport(report, args.format));
-    if (shouldFail(report, args.failOn)) {
-        process.stderr.write(`Failing because findings met --fail-on ${args.failOn}\n`);
+    const failOn = args.failOn ?? config.failOn;
+    if (shouldFail(report, failOn)) {
+        process.stderr.write(`Failing because findings met --fail-on ${failOn}\n`);
         return 1;
     }
     return 0;
@@ -87,6 +91,14 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (arg === "--config") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--config requires a path");
+            result.configPath = resolve(value);
+            index += 1;
+            continue;
+        }
         if (arg === "--base") {
             const value = argv[index + 1];
             if (!value)
@@ -141,11 +153,11 @@ function helpText() {
 Repo-local launch-readiness scanner for AI-built SaaS apps.
 
 Usage:
-  ai-saas-guard scan [--root <repo>] [--json|--sarif] [--fail-on <severity>]
-  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|--markdown] [--fail-on <severity>]
+  ai-saas-guard scan [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard check-supabase [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard check-stripe [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard check-mcp [--root <repo>] [--config <file>] [--json|--sarif] [--fail-on <severity>]
+  ai-saas-guard pr-risk [--root <repo>] [--config <file>] [--base <branch>] [--json|--sarif|--markdown] [--fail-on <severity>]
 
 Defaults:
   - read-only
@@ -154,6 +166,7 @@ Defaults:
   - terminal output by default, JSON with --json
   - SARIF output for GitHub code scanning with --sarif
   - PR-focused markdown summary with --markdown
+  - project config auto-loaded from .ai-saas-guard.json when present
 `;
 }
 main(process.argv.slice(2)).then((code) => {

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import type { BaseReport, Severity } from "./types.js";
+export declare const defaultConfigFileName = ".ai-saas-guard.json";
+export type RuleConfigValue = "off" | Severity;
+export interface GuardConfig {
+    sourcePath?: string;
+    failOn?: Severity | "none";
+    rules: Record<string, RuleConfigValue>;
+}
+export declare function loadGuardConfig(rootDir: string, explicitPath?: string): Promise<GuardConfig>;
+export declare function applyGuardConfig<T extends BaseReport>(report: T, config: GuardConfig): T;

package/dist/config.js

@@ -0,0 +1,89 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { summarizeFindings, sortFindings } from "./report/findings.js";
+import { getRuleMetadata } from "./rules/catalog.js";
+export const defaultConfigFileName = ".ai-saas-guard.json";
+export async function loadGuardConfig(rootDir, explicitPath) {
+    const sourcePath = explicitPath ? resolve(explicitPath) : resolve(rootDir, defaultConfigFileName);
+    let content;
+    try {
+        content = await readFile(sourcePath, "utf8");
+    }
+    catch (error) {
+        if (!explicitPath && isNotFoundError(error))
+            return { rules: {} };
+        throw new Error(`Could not read config file ${sourcePath}: ${errorMessage(error)}`);
+    }
+    return parseGuardConfig(content, sourcePath);
+}
+export function applyGuardConfig(report, config) {
+    const configuredRuleIds = Object.keys(config.rules);
+    if (configuredRuleIds.length === 0)
+        return report;
+    const findings = sortFindings(report.findings.flatMap((finding) => {
+        const ruleConfig = config.rules[finding.ruleId];
+        if (!ruleConfig)
+            return [finding];
+        if (ruleConfig === "off")
+            return [];
+        return [{ ...finding, severity: ruleConfig }];
+    }));
+    return {
+        ...report,
+        findings,
+        summary: summarizeFindings(findings)
+    };
+}
+function parseGuardConfig(content, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in config file ${sourcePath}: ${errorMessage(error)}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error(`Invalid config file ${sourcePath}: expected a JSON object`);
+    }
+    const failOn = parsed.failOn;
+    if (failOn !== undefined && !isFailOnValue(failOn)) {
+        throw new Error("Invalid config failOn: expected critical, high, medium, low, info, or none");
+    }
+    const rawRules = parsed.rules ?? {};
+    if (!isPlainObject(rawRules)) {
+        throw new Error("Invalid config rules: expected an object keyed by rule ID");
+    }
+    const rules = {};
+    for (const [ruleId, value] of Object.entries(rawRules)) {
+        if (!getRuleMetadata(ruleId)) {
+            throw new Error(`Unknown rule ID in config: ${ruleId}`);
+        }
+        if (!isRuleConfigValue(value)) {
+            throw new Error(`Invalid config for rule ${ruleId}: expected off, critical, high, medium, low, or info`);
+        }
+        rules[ruleId] = value;
+    }
+    return {
+        sourcePath,
+        failOn,
+        rules
+    };
+}
+function isRuleConfigValue(value) {
+    return value === "off" || isSeverity(value);
+}
+function isFailOnValue(value) {
+    return value === "none" || isSeverity(value);
+}
+function isSeverity(value) {
+    return value === "critical" || value === "high" || value === "medium" || value === "low" || value === "info";
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNotFoundError(error) {
+    return isPlainObject(error) && error.code === "ENOENT";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -3,8 +3,10 @@ export { checkStripe } from "./commands/checkStripe.js";
 export { checkSupabase } from "./commands/checkSupabase.js";
 export { checkMcp } from "./commands/checkMcp.js";
 export { classifyPrRisk } from "./commands/prRisk.js";
+export { applyGuardConfig, defaultConfigFileName, loadGuardConfig } from "./config.js";
 export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";
 export type { BaseReport, CommandName, Evidence, Finding, McpReport, McpServerInventory, PrRiskFile, PrRiskReport, ScanOptions, StripeReport, SupabaseReport } from "./types.js";
 export type { ScanContext, ScanInput } from "./context.js";
+export type { GuardConfig, RuleConfigValue } from "./config.js";
 export type { RuleMetadata, RuleStability } from "./rules/catalog.js";

package/dist/index.js

@@ -3,5 +3,6 @@ export { checkStripe } from "./commands/checkStripe.js";
 export { checkSupabase } from "./commands/checkSupabase.js";
 export { checkMcp } from "./commands/checkMcp.js";
 export { classifyPrRisk } from "./commands/prRisk.js";
+export { applyGuardConfig, defaultConfigFileName, loadGuardConfig } from "./config.js";
 export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `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.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.3.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 
@@ -29,6 +29,7 @@ jobs:
           command: pr-risk
           root: ${{ github.workspace }}
           base: origin/main
+          config: .ai-saas-guard.json
           format: markdown
           output: ai-saas-guard-pr.md
       - run: cat ai-saas-guard-pr.md >> "$GITHUB_STEP_SUMMARY"
@@ -36,6 +37,21 @@ jobs:
 
 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.
 
+## Project Config
+
+The Action auto-loads `.ai-saas-guard.json` from `root` when the file exists. Use the `config` input when the policy file lives somewhere else or when you want the workflow to be explicit:
+
+```yaml
+      - uses: zr9959/ai-saas-guard@v0
+        with:
+          command: scan
+          root: ${{ github.workspace }}
+          config: .ai-saas-guard.json
+          fail-on: none
+```
+
+Project config can disable noisy rules, override severity by rule ID, and set a default `failOn` threshold. A workflow `fail-on` input overrides the config threshold for that run.
+
 ## SARIF Upload
 
 Use SARIF when you want findings to appear in GitHub code scanning alerts.

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.2.0`
+- Current version: `0.3.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.2.0`
+- GitHub Release: `v0.3.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.2.0`.
+1. Create and review a release tag such as `v0.3.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

@@ -47,6 +47,7 @@ Implemented surfaces:
 - 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
+- project-local `.ai-saas-guard.json` config for rule toggles, severity overrides, and default fail thresholds
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
@@ -99,7 +100,6 @@ GitHub Project:
 Current issue set:
 
 - #1 Add launch-readiness checklist content
-- #3 Add configurable rule severity and rule toggles
 - #5 Write Stripe webhook replay cookbook
 - #7 Expand Supabase RLS fixtures and ownership patterns
 
@@ -113,7 +113,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.2.0`
+- Current release line: `v0.3.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.
@@ -140,9 +140,9 @@ Not allowed:
 
 Recommended order:
 
-1. Add configurable severity and rule toggles.
-2. Expand Supabase RLS fixtures and ownership patterns.
-3. Write Stripe webhook replay cookbook.
+1. Expand Supabase RLS fixtures and ownership patterns.
+2. Write Stripe webhook replay cookbook.
+3. Add launch-readiness checklist content.
 4. Improve false-positive suppression and rule stability labels.
 5. Add a GitHub App design note for the potential hosted layer.
 

package/package.json

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