decision-guardian 1.1.0

package/dist/main.js

@@ -0,0 +1,290 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const github = __importStar(require("@actions/github"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const parser_1 = require("./core/parser");
+const matcher_1 = require("./core/matcher");
+const metrics_1 = require("./core/metrics");
+const logger_1 = require("./core/logger");
+const health_1 = require("./core/health");
+const actions_logger_1 = require("./adapters/github/actions-logger");
+const github_provider_1 = require("./adapters/github/github-provider");
+const health_2 = require("./adapters/github/health");
+const zod_1 = require("zod");
+const sender_1 = require("./telemetry/sender");
+const version_1 = require("./version");
+// Create the logger for the entire action lifetime
+const logger = new actions_logger_1.ActionsLogger();
+/**
+ * Main entry point for the GitHub Action
+ */
+async function run() {
+    const startTime = Date.now();
+    const errors = [];
+    let config;
+    try {
+        // 1. Load configuration
+        config = loadConfig();
+        // 2. Health checks
+        const decisionFileOk = await (0, health_1.checkDecisionFileExists)(config.decisionFile);
+        const tokenOk = await (0, health_2.validateToken)(config.token, logger);
+        if (!decisionFileOk || !tokenOk) {
+            logger.setFailed('System health check failed');
+            return;
+        }
+        logger.info(`Decision file: ${config.decisionFile}`);
+        // 3. Parse decisions
+        logger.startGroup('Parsing decisions...');
+        const parser = new parser_1.DecisionParser();
+        // Check if path is a directory and handle accordingly
+        const isDir = fs.existsSync(config.decisionFile) && fs.statSync(config.decisionFile).isDirectory();
+        const parseResult = isDir
+            ? await parser.parseDirectory(config.decisionFile)
+            : await parser.parseFile(config.decisionFile);
+        if (parseResult.warnings.length > 0) {
+            parseResult.warnings.forEach((warn) => {
+                logger.warning(warn);
+            });
+        }
+        if (parseResult.errors.length > 0) {
+            logger.warning(`Found ${parseResult.errors.length} parse errors`);
+            parseResult.errors.forEach((err) => {
+                logger.warning(`Line ${err.line}: ${err.message}`);
+            });
+            if (config.failOnError) {
+                logger.setFailed(`Decision file has ${parseResult.errors.length} parse errors`);
+                return;
+            }
+        }
+        const hasRules = parseResult.decisions.some((d) => d.rules);
+        logger.info(`Loaded ${parseResult.decisions.length} decisions (${hasRules ? 'with advanced rules' : 'file-based only'})`);
+        logger.endGroup();
+        // 4. Create SCM provider and fetch diffs
+        logger.startGroup('Fetching file diffs...');
+        const provider = new github_provider_1.GitHubProvider(config.token, logger);
+        const changedFiles = await provider.getChangedFiles();
+        const useStreaming = changedFiles.length > 1000;
+        // Create FileMatcher once for all code paths
+        const matcher = new matcher_1.FileMatcher(parseResult.decisions, logger);
+        let matches = [];
+        let processedFileCount = 0;
+        if (useStreaming) {
+            logger.info(`Large PR detected (${changedFiles.length} files), using streaming mode`);
+            logger.endGroup();
+            logger.startGroup('Processing with streaming...');
+            matches = await processWithStreaming(parseResult.decisions, provider);
+            processedFileCount = changedFiles.length;
+            logger.endGroup();
+        }
+        else {
+            const fileDiffs = await provider.getFileDiffs();
+            processedFileCount = fileDiffs.length;
+            metrics_1.metrics.addFilesProcessed(fileDiffs.length);
+            logger.info(`PR modifies ${fileDiffs.length} files`);
+            if (fileDiffs.length === 0) {
+                logger.info('No file diffs found - PR is clear!');
+                logger.setOutput('matches_found', '0');
+                logger.setOutput('critical_count', '0');
+                (0, logger_1.logStructured)(logger, 'info', 'Decision Guardian completed successfully (no files)', {
+                    duration_ms: Date.now() - startTime,
+                });
+                metrics_1.metrics.setDuration(Date.now() - startTime);
+                reportMetrics(config);
+                return;
+            }
+            logger.endGroup();
+            // 5. Match files to decisions
+            logger.startGroup('Matching decisions...');
+            try {
+                matches = await matcher.findMatchesWithDiffs(fileDiffs);
+            }
+            catch (error) {
+                logger.warning(`Advanced matching failed, falling back to simple mode: ${error}`);
+                const fileNames = fileDiffs.map((f) => f.filename);
+                matches = await matcher.findMatches(fileNames);
+            }
+        }
+        const grouped = matcher.groupBySeverity(matches);
+        metrics_1.metrics.addMatchesFound(matches.length);
+        metrics_1.metrics.addCriticalMatches(grouped.critical.length);
+        metrics_1.metrics.addWarningMatches(grouped.warning.length);
+        metrics_1.metrics.addInfoMatches(grouped.info.length);
+        logger.info(`Found ${matches.length} matches:`);
+        logger.info(`  - Critical: ${grouped.critical.length}`);
+        logger.info(`  - Warning: ${grouped.warning.length}`);
+        logger.info(`  - Info: ${grouped.info.length}`);
+        logger.endGroup();
+        // 6. Post comment if matches found
+        if (matches.length > 0) {
+            logger.startGroup('Posting PR comment...');
+            await provider.postComment(matches);
+            logger.endGroup();
+            logger.setOutput('matches_found', String(matches.length));
+            logger.setOutput('critical_count', String(grouped.critical.length));
+            // 7. Fail check if critical decisions violated
+            if (config.failOnCritical && grouped.critical.length > 0) {
+                const failureMessage = `PR modifies ${grouped.critical.length} files protected by critical decisions`;
+                (0, logger_1.logStructured)(logger, 'error', 'Decision Guardian failed checks', {
+                    match_count: matches.length,
+                    critical_count: grouped.critical.length,
+                    duration_ms: Date.now() - startTime,
+                });
+                logger.setFailed(failureMessage);
+                metrics_1.metrics.setDuration(Date.now() - startTime);
+                reportMetrics(config);
+                return;
+            }
+        }
+        else {
+            logger.info('No decision matches found - PR is clear!');
+            logger.setOutput('matches_found', '0');
+            logger.setOutput('critical_count', '0');
+            if (provider.postAllClear) {
+                logger.startGroup('Updating status to All Clear...');
+                try {
+                    await provider.postAllClear();
+                }
+                catch (error) {
+                    logger.warning(`Failed to post all-clear status: ${error}`);
+                }
+                logger.endGroup();
+            }
+        }
+        const duration = Date.now() - startTime;
+        (0, logger_1.logStructured)(logger, 'info', 'Decision Guardian completed successfully', {
+            pr_number: github.context.payload.pull_request?.number,
+            file_count: processedFileCount,
+            decision_count: parseResult.decisions.length,
+            match_count: matches.length,
+            duration_ms: duration,
+        });
+        metrics_1.metrics.setDuration(duration);
+        reportMetrics(config);
+        logger.info('✅ Decision Guardian completed successfully');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const stack = error instanceof Error ? error.stack : undefined;
+        errors.push(message);
+        (0, logger_1.logStructured)(logger, 'error', 'Decision Guardian failed', {
+            duration_ms: Date.now() - startTime,
+            errors,
+        });
+        logger.setFailed(`Action failed: ${message}`);
+        if (stack) {
+            logger.debug(stack);
+        }
+        metrics_1.metrics.setDuration(Date.now() - startTime);
+        // Send telemetry only if config was loaded successfully
+        if (config) {
+            reportMetrics(config);
+        }
+    }
+}
+const ConfigSchema = zod_1.z.object({
+    decisionFile: zod_1.z
+        .string()
+        .regex(/^[a-zA-Z0-9._/-]+$/, 'Invalid characters in decision file path')
+        .refine((val) => !val.includes('..'), 'Path traversal not allowed'),
+    failOnCritical: zod_1.z.boolean(),
+    failOnError: zod_1.z.boolean(),
+    token: zod_1.z.string().min(1, 'Token cannot be empty'),
+});
+/**
+ * Load action configuration from inputs
+ */
+function loadConfig() {
+    const rawConfig = {
+        decisionFile: logger.getInput('decision_file') || '.decispher/decisions.md',
+        failOnCritical: logger.getBooleanInput('fail_on_critical'),
+        failOnError: logger.getBooleanInput('fail_on_error'),
+        token: logger.getInput('token', true),
+    };
+    const result = ConfigSchema.safeParse(rawConfig);
+    if (!result.success) {
+        const errorMessage = result.error.issues
+            .map((e) => `${e.path.join('.')}: ${e.message}`)
+            .join(', ');
+        throw new Error(`Invalid configuration: ${errorMessage}`);
+    }
+    if (path.isAbsolute(result.data.decisionFile)) {
+        throw new Error('decision_file must be a relative path');
+    }
+    const config = result.data;
+    logger.debug(`Configuration loaded: ${JSON.stringify({
+        ...config,
+        token: '***',
+    })}`);
+    return config;
+}
+/**
+ * Report metrics using the decoupled snapshot approach
+ */
+function reportMetrics(_config) {
+    const snapshot = metrics_1.metrics.getSnapshot();
+    logger.info('=== Performance Metrics ===');
+    logger.info(`API Calls: ${snapshot.api_calls}`);
+    logger.info(`API Errors: ${snapshot.api_errors}`);
+    logger.info(`Rate Limit Hits: ${snapshot.rate_limit_hits}`);
+    logger.info(`Files Processed: ${snapshot.files_processed}`);
+    logger.info(`Decisions Evaluated: ${snapshot.decisions_evaluated}`);
+    logger.info(`Matches Found: ${snapshot.matches_found}`);
+    logger.info(`Duration: ${snapshot.duration_ms}ms`);
+    logger.setOutput('metrics', JSON.stringify(snapshot));
+    // Send telemetry (controlled by DG_TELEMETRY env variable)
+    (0, sender_1.sendTelemetry)('action', snapshot, version_1.VERSION).catch(() => { });
+}
+/**
+ * Process large PRs using streaming
+ */
+async function processWithStreaming(decisions, provider) {
+    const matcher = new matcher_1.FileMatcher(decisions, logger);
+    const allMatches = [];
+    let processedCount = 0;
+    if (!provider.streamFileDiffs) {
+        throw new Error('Provider does not support streaming');
+    }
+    for await (const batch of provider.streamFileDiffs()) {
+        const batchMatches = await matcher.findMatchesWithDiffs(batch);
+        allMatches.push(...batchMatches);
+        processedCount += batch.length;
+        logger.info(`Processed ${processedCount} files, found ${allMatches.length} matches so far`);
+    }
+    return allMatches;
+}
+// Run the action
+run();

package/dist/telemetry/payload.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPayload = buildPayload;
+function buildPayload(source, snapshot, version) {
+    return {
+        event: 'run_complete',
+        version,
+        source,
+        timestamp: new Date().toISOString(),
+        metrics: {
+            files_processed: snapshot.files_processed,
+            decisions_evaluated: snapshot.decisions_evaluated,
+            matches_found: snapshot.matches_found,
+            critical_matches: snapshot.critical_matches,
+            warning_matches: snapshot.warning_matches,
+            info_matches: snapshot.info_matches,
+            duration_ms: snapshot.duration_ms,
+        },
+        environment: {
+            node_version: process.version,
+            os_platform: process.platform,
+            ci: !!process.env.CI,
+        },
+    };
+}

package/dist/telemetry/privacy.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePrivacy = validatePrivacy;
+const BLOCKED_FIELDS = new Set([
+    'repo_name',
+    'org_name',
+    'file_names',
+    'file_paths',
+    'pr_title',
+    'pr_body',
+    'decision_content',
+    'user_names',
+    'github_token',
+    'commit_message',
+    'branch_name',
+    'author',
+    'email',
+]);
+function validatePrivacy(payload) {
+    const violations = findBlockedKeys(payload);
+    if (violations.length > 0) {
+        throw new Error(`Telemetry privacy violation: blocked fields found: ${violations.join(', ')}`);
+    }
+}
+function findBlockedKeys(obj, prefix = '') {
+    const violations = [];
+    for (const key of Object.keys(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (BLOCKED_FIELDS.has(key.toLowerCase())) {
+            violations.push(fullKey);
+        }
+        if (obj[key] && typeof obj[key] === 'object' && !Array.isArray(obj[key])) {
+            violations.push(...findBlockedKeys(obj[key], fullKey));
+        }
+    }
+    return violations;
+}

package/dist/telemetry/sender.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendTelemetry = sendTelemetry;
+const payload_1 = require("./payload");
+const privacy_1 = require("./privacy");
+const DEFAULT_ENDPOINT = 'https://decision-guardian-telemetry.decision-guardian-telemetry.workers.dev/collect';
+const TIMEOUT_MS = 5000;
+function isOptedIn(_source) {
+    // Unified telemetry control for both GitHub Actions and CLI via DG_TELEMETRY env
+    // Opt-out model: telemetry is enabled by default
+    // Users must explicitly set DG_TELEMETRY to '0' or 'false' to disable
+    if (process.env.DG_TELEMETRY === '0' || process.env.DG_TELEMETRY === 'false') {
+        return false;
+    }
+    // Enabled by default if not set, or if set to '1' or 'true'
+    return true;
+}
+function getEndpoint() {
+    return process.env.DG_TELEMETRY_URL || DEFAULT_ENDPOINT;
+}
+async function sendTelemetry(source, snapshot, version) {
+    if (!isOptedIn(source))
+        return;
+    try {
+        const payload = (0, payload_1.buildPayload)(source, snapshot, version);
+        (0, privacy_1.validatePrivacy)(payload);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        await fetch(getEndpoint(), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+    }
+    catch {
+        // Silently fail — never break the tool
+    }
+}

package/dist/version.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/**
+ * Version information for Decision Guardian
+ */
+exports.VERSION = '1.1.0';

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "decision-guardian",
+  "version": "1.1.0",
+  "description": "Surface architectural decision context on Pull Requests",
+  "main": "dist/index.js",
+  "bin": {
+    "decision-guardian": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "bundle": "ncc build src/main.ts -o dist --license licenses.txt",
+    "build:cli": "ncc build src/cli/index.ts -o dist/cli --license licenses.txt",
+    "test": "jest",
+    "test:e2e": "npx ts-node scripts/e2e-test.ts",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts",
+    "all": "npm run format && npm run lint && npm run test && npm run build && npm run bundle"
+  },
+  "keywords": [
+    "actions",
+    "github",
+    "documentation",
+    "architecture",
+    "decisions"
+  ],
+  "author": "Decispher",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DecispherHQ/decision-guardian.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@actions/core": "^1.10.1",
+    "@actions/github": "^6.0.0",
+    "minimatch": "^9.0.3",
+    "parse-diff": "^0.11.1",
+    "safe-regex": "^2.1.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.0.0",
+    "@types/safe-regex": "^1.1.6",
+    "@typescript-eslint/eslint-plugin": "^6.18.0",
+    "@typescript-eslint/parser": "^6.18.0",
+    "@vercel/ncc": "^0.38.1",
+    "dotenv": "^17.2.3",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.1",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  }
+}

package/templates/advanced-rules.md

@@ -0,0 +1,94 @@
+<!-- DECISION-ADV-001 -->
+## Decision: Config File Validation
+**Status**: Active
+**Date**: 2024-06-01
+**Severity**: Critical
+**Files**:
+- `config/**/*.json`
+- `config/**/*.yml`
+
+**Rules**:
+```json
+{
+  "match": "any",
+  "conditions": [
+    {
+      "files": ["config/**/*.json"],
+      "content": {
+        "mode": "json_path",
+        "paths": ["database.host", "database.port", "database.password"]
+      }
+    },
+    {
+      "files": ["config/**/*.yml"],
+      "content": {
+        "mode": "regex",
+        "pattern": "(password|secret|api_key)\\s*[:=]",
+        "flags": "i"
+      }
+    }
+  ]
+}
+```
+
+### Context
+All config changes affecting database credentials must be reviewed.
+
+---
+
+<!-- DECISION-ADV-002 -->
+## Decision: License Header Enforcement
+**Status**: Active
+**Date**: 2024-06-15
+**Severity**: Warning
+**Files**:
+- `src/**/*.ts`
+
+**Rules**:
+```json
+{
+  "match": "all",
+  "conditions": [
+    {
+      "files": ["src/**/*.ts"],
+      "content": {
+        "mode": "line_range",
+        "start": 1,
+        "end": 5
+      }
+    }
+  ]
+}
+```
+
+### Context
+Source files must contain license headers in the first 5 lines.
+
+---
+
+<!-- DECISION-ADV-003 -->
+## Decision: Deprecated API Detection
+**Status**: Active
+**Date**: 2024-07-01
+**Severity**: Info
+**Files**:
+- `src/**/*.ts`
+
+**Rules**:
+```json
+{
+  "match": "any",
+  "conditions": [
+    {
+      "files": ["src/**/*.ts"],
+      "content": {
+        "mode": "string",
+        "patterns": ["@deprecated", "TODO: remove"]
+      }
+    }
+  ]
+}
+```
+
+### Context
+Track usage of deprecated APIs and items marked for removal.

package/templates/api.md

@@ -0,0 +1,70 @@
+<!-- DECISION-API-001 -->
+## Decision: API Versioning
+**Status**: Active
+**Date**: 2024-05-01
+**Severity**: Critical
+**Files**:
+- `src/api/v1/**/*`
+- `src/routes/v1/**/*`
+
+### Context
+V1 API endpoints are frozen. New features go to V2. Modifying V1 routes breaks existing integrations.
+
+---
+
+<!-- DECISION-API-002 -->
+## Decision: Rate Limiting Required
+**Status**: Active
+**Date**: 2024-05-15
+**Severity**: Warning
+**Files**:
+- `src/api/**/*.ts`
+- `src/routes/**/*.ts`
+
+**Rules**:
+```json
+{
+  "match": "any",
+  "conditions": [
+    {
+      "files": ["src/api/**/*.ts", "src/routes/**/*.ts"],
+      "content": {
+        "mode": "string",
+        "patterns": ["router.get(", "router.post(", "app.get(", "app.post("]
+      }
+    }
+  ]
+}
+```
+
+### Context
+All public endpoints must include rate limiting. New endpoints require load testing results.
+
+---
+
+<!-- DECISION-API-003 -->
+## Decision: Response Schema Validation
+**Status**: Active
+**Date**: 2024-06-01
+**Severity**: Info
+**Files**:
+- `src/api/**/*.ts`
+
+**Rules**:
+```json
+{
+  "match": "any",
+  "conditions": [
+    {
+      "files": ["src/api/**/*.ts"],
+      "content": {
+        "mode": "string",
+        "patterns": ["res.json(", "res.send(", "response.json("]
+      }
+    }
+  ]
+}
+```
+
+### Context
+API responses should use validated schemas. Check that response DTOs are defined.

package/templates/basic.md

@@ -0,0 +1,38 @@
+<!-- DECISION-001 -->
+## Decision: Database Connection Pool
+**Status**: Active
+**Date**: 2024-01-15
+**Severity**: Critical
+**Files**:
+- `src/db/pool.ts`
+- `config/database.yml`
+
+### Context
+Connection pool size must stay at 20 to prevent exhaustion.
+
+---
+
+<!-- DECISION-002 -->
+## Decision: API Rate Limiting
+**Status**: Active
+**Date**: 2024-02-01
+**Severity**: Warning
+**Files**:
+- `src/api/**/*.ts`
+
+### Context
+All new API endpoints must implement the standard rate limiter middleware.
+
+---
+
+<!-- DECISION-003 -->
+## Decision: Authentication Module
+**Status**: Active
+**Date**: 2024-03-10
+**Severity**: Critical
+**Files**:
+- `src/auth/**/*`
+- `config/auth.json`
+
+### Context
+Auth module changes require security team review.