pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/domain/ports/IGitPort.js

@@ -0,0 +1,114 @@
+/**
+ * IGitPort
+ *
+ * Port interface for Git operations.
+ * Infrastructure adapters must implement this interface.
+ */
+const { NotImplementedError } = require('../errors');
+
+class IGitPort {
+    /**
+     * Get current branch name
+     * @returns {string}
+     */
+    getCurrentBranch() {
+        throw new NotImplementedError('IGitPort.getCurrentBranch() must be implemented');
+    }
+
+    /**
+     * Check if current branch is protected
+     * @returns {boolean}
+     */
+    isProtectedBranch() {
+        throw new NotImplementedError('IGitPort.isProtectedBranch() must be implemented');
+    }
+
+    /**
+     * Get uncommitted changes (git status --porcelain)
+     * @returns {string}
+     */
+    getUncommittedChanges() {
+        throw new NotImplementedError('IGitPort.getUncommittedChanges() must be implemented');
+    }
+
+    /**
+     * Get staged files
+     * @returns {string[]}
+     */
+    getStagedFiles() {
+        throw new NotImplementedError('IGitPort.getStagedFiles() must be implemented');
+    }
+
+    /**
+     * Create a new branch from current HEAD
+     * @param {string} branchName
+     * @returns {boolean}
+     */
+    createBranch(branchName) {
+        throw new NotImplementedError('IGitPort.createBranch() must be implemented');
+    }
+
+    /**
+     * Checkout to a branch
+     * @param {string} branchName
+     * @returns {boolean}
+     */
+    checkout(branchName) {
+        throw new NotImplementedError('IGitPort.checkout() must be implemented');
+    }
+
+    /**
+     * Stage files
+     * @param {string[]} files
+     * @returns {boolean}
+     */
+    stageFiles(files) {
+        throw new NotImplementedError('IGitPort.stageFiles() must be implemented');
+    }
+
+    /**
+     * Commit staged changes
+     * @param {string} message
+     * @returns {boolean}
+     */
+    commit(message) {
+        throw new NotImplementedError('IGitPort.commit() must be implemented');
+    }
+
+    /**
+     * Get recent commits log
+     * @param {number} count
+     * @returns {string[]}
+     */
+    getRecentCommits(count) {
+        throw new NotImplementedError('IGitPort.getRecentCommits() must be implemented');
+    }
+
+    /**
+     * Get git diff output
+     * @param {boolean} cached - Whether to diff cached (staged) files
+     * @returns {string}
+     */
+    getDiff(cached = false) {
+        throw new NotImplementedError('IGitPort.getDiff() must be implemented');
+    }
+
+    /**
+     * Get status output (short format)
+     * @returns {string}
+     */
+    getStatusShort() {
+        throw new NotImplementedError('IGitPort.getStatusShort() must be implemented');
+    }
+
+    /**
+     * Get detailed log with stats
+     * @param {number} count
+     * @returns {string}
+     */
+    getLog(count) {
+        throw new NotImplementedError('IGitPort.getLog() must be implemented');
+    }
+}
+
+module.exports = IGitPort;

package/scripts/hooks-system/domain/ports/IGitQueryPort.js

@@ -0,0 +1,93 @@
+/**
+ * IGitQueryPort
+ *
+ * Port interface for Git read-only operations (Queries).
+ */
+const { NotImplementedError } = require('../errors');
+
+class IGitQueryPort {
+    /**
+     * Get current branch name
+     * @returns {string}
+     */
+    getCurrentBranch() {
+        throw new NotImplementedError('IGitQueryPort.getCurrentBranch() must be implemented');
+    }
+
+    /**
+     * Check if current branch is protected
+     * @returns {boolean}
+     */
+    isProtectedBranch() {
+        throw new NotImplementedError('IGitQueryPort.isProtectedBranch() must be implemented');
+    }
+
+    /**
+     * Get uncommitted changes (git status --porcelain)
+     * @returns {string}
+     */
+    getUncommittedChanges() {
+        throw new NotImplementedError('IGitQueryPort.getUncommittedChanges() must be implemented');
+    }
+
+    /**
+     * Get staged files
+     * @returns {string[]}
+     */
+    getStagedFiles() {
+        throw new NotImplementedError('IGitQueryPort.getStagedFiles() must be implemented');
+    }
+
+    /**
+     * has uncommitted changes boolean
+     * @returns {boolean}
+     */
+    hasUncommittedChanges() {
+        throw new NotImplementedError('IGitQueryPort.hasUncommittedChanges() must be implemented');
+    }
+
+    /**
+     * has staged changes boolean
+     * @returns {boolean}
+     */
+    hasStagedChanges() {
+        throw new NotImplementedError('IGitQueryPort.hasStagedChanges() must be implemented');
+    }
+
+    /**
+     * Get recent commits log
+     * @param {number} count
+     * @returns {string[]}
+     */
+    getRecentCommits(count) {
+        throw new NotImplementedError('IGitQueryPort.getRecentCommits() must be implemented');
+    }
+
+    /**
+     * Get git diff output
+     * @param {boolean} cached - Whether to diff cached (staged) files
+     * @returns {string}
+     */
+    getDiff(cached) {
+        throw new NotImplementedError('IGitQueryPort.getDiff() must be implemented');
+    }
+
+    /**
+     * Get status output (short format)
+     * @returns {string}
+     */
+    getStatusShort() {
+        throw new NotImplementedError('IGitQueryPort.getStatusShort() must be implemented');
+    }
+
+    /**
+     * Get detailed log with stats
+     * @param {number} count
+     * @returns {string}
+     */
+    getLog(count) {
+        throw new NotImplementedError('IGitQueryPort.getLog() must be implemented');
+    }
+}
+
+module.exports = IGitQueryPort;

package/scripts/hooks-system/domain/ports/INotificationPort.js

@@ -0,0 +1,35 @@
+/**
+ * INotificationPort
+ *
+ * Port interface for notification delivery.
+ * Infrastructure adapters must implement this interface.
+ *
+ * @interface
+ */
+const { NotImplementedError } = require('../errors');
+
+class INotificationPort {
+    /**
+     * Send a notification to the user
+     * @param {Object} notification
+     * @param {string} notification.title - Notification title
+     * @param {string} notification.message - Notification message
+     * @param {string} notification.level - Level: 'info' | 'warn' | 'error'
+     * @param {string} [notification.type] - Type for cooldown/deduplication
+     * @param {string} [notification.sound] - Sound name (macOS)
+     * @returns {Promise<boolean>} true if sent successfully
+     */
+    async send(notification) {
+        throw new NotImplementedError('INotificationPort.send() must be implemented');
+    }
+
+    /**
+     * Check if notifications are enabled
+     * @returns {boolean}
+     */
+    isEnabled() {
+        throw new NotImplementedError('INotificationPort.isEnabled() must be implemented');
+    }
+}
+
+module.exports = INotificationPort;

package/scripts/hooks-system/domain/ports/__tests__/ports.spec.js

@@ -0,0 +1,36 @@
+describe('domain/ports', () => {
+  describe('IAstPort', () => {
+    it('should export interface', () => {
+      const mod = require('../IAstPort');
+      expect(mod).toBeDefined();
+    });
+  });
+
+  describe('IEvidencePort', () => {
+    it('should export interface', () => {
+      const mod = require('../IEvidencePort');
+      expect(mod).toBeDefined();
+    });
+  });
+
+  describe('IGitPort', () => {
+    it('should export interface', () => {
+      const mod = require('../IGitPort');
+      expect(mod).toBeDefined();
+    });
+  });
+
+  describe('INotificationPort', () => {
+    it('should export interface', () => {
+      const mod = require('../INotificationPort');
+      expect(mod).toBeDefined();
+    });
+  });
+
+  describe('index', () => {
+    it('should export all ports', () => {
+      const ports = require('../index');
+      expect(ports).toBeDefined();
+    });
+  });
+});

package/scripts/hooks-system/domain/ports/index.js

@@ -0,0 +1,14 @@
+/**
+ * Domain Ports - Interfaces for infrastructure adapters
+ */
+const INotificationPort = require('./INotificationPort');
+const IGitPort = require('./IGitPort');
+const IAstPort = require('./IAstPort');
+const IEvidencePort = require('./IEvidencePort');
+
+module.exports = {
+    INotificationPort,
+    IGitPort,
+    IAstPort,
+    IEvidencePort
+};

package/scripts/hooks-system/domain/repositories/ICursorTokenRepository.js

@@ -0,0 +1,13 @@
+const { NotImplementedError } = require('../../domain/errors');
+
+class ICursorTokenRepository {
+    async getUsageFromApi() {
+        throw new NotImplementedError('getUsageFromApi must be implemented');
+    }
+
+    async getUsageFromFile() {
+        throw new NotImplementedError('getUsageFromFile must be implemented');
+    }
+}
+
+module.exports = ICursorTokenRepository;

package/scripts/hooks-system/domain/repositories/IFindingsRepository.js

@@ -0,0 +1,30 @@
+
+const { NotImplementedError } = require('../errors');
+
+class IFindingsRepository {
+  async save(findings) {
+    throw new NotImplementedError('IFindingsRepository.save() must be implemented');
+  }
+
+  async load() {
+    throw new NotImplementedError('IFindingsRepository.load() must be implemented');
+  }
+
+  async clear() {
+    throw new NotImplementedError('IFindingsRepository.clear() must be implemented');
+  }
+
+  async exists() {
+    throw new NotImplementedError('IFindingsRepository.exists() must be implemented');
+  }
+
+  async saveAuditResult(auditResult) {
+    throw new NotImplementedError('IFindingsRepository.saveAuditResult() must be implemented');
+  }
+
+  async loadAuditResult() {
+    throw new NotImplementedError('IFindingsRepository.loadAuditResult() must be implemented');
+  }
+}
+
+module.exports = IFindingsRepository;

package/scripts/hooks-system/domain/repositories/__tests__/IFindingsRepository.spec.js

@@ -0,0 +1,18 @@
+describe('IFindingsRepository', () => {
+  it('should export interface/class', () => {
+    const IFindingsRepository = require('../IFindingsRepository');
+    expect(IFindingsRepository).toBeDefined();
+  });
+
+  it('should be instantiable', () => {
+    const IFindingsRepository = require('../IFindingsRepository');
+    const instance = new IFindingsRepository();
+    expect(instance).toBeDefined();
+  });
+
+  it('should have save method', () => {
+    const IFindingsRepository = require('../IFindingsRepository');
+    const instance = new IFindingsRepository();
+    expect(typeof instance.save).toBe('function');
+  });
+});

package/scripts/hooks-system/domain/rules/CommitBlockingRules.js

@@ -0,0 +1,142 @@
+
+class CommitBlockingRules {
+  constructor() {
+    this.DEFAULT_BLOCKING_SEVERITIES = ['critical', 'high'];
+    this.STRICT_BLOCKING_SEVERITIES = ['critical', 'high', 'medium', 'low'];
+  }
+
+  shouldBlockCommit(auditResult, strictMode = false, blockOnlyCriticalHigh = false) {
+    if (!auditResult.hasViolations()) {
+      return {
+        shouldBlock: false,
+        reason: 'No violations found',
+      };
+    }
+
+    if (blockOnlyCriticalHigh) {
+      return this.blockOnCriticalHigh(auditResult);
+    }
+
+    if (strictMode) {
+      return this.blockOnAnyViolation(auditResult);
+    }
+
+    return this.blockOnBlockingLevels(auditResult);
+  }
+
+  shouldBlockByStagedFiles(stagedFindings, strictMode = false) {
+    if (stagedFindings.length === 0) {
+      return {
+        shouldBlock: false,
+        reason: 'No violations in staged files',
+      };
+    }
+
+    const blockingFindings = stagedFindings.filter(f => f.isBlockingLevel());
+
+    if (strictMode) {
+      return {
+        shouldBlock: stagedFindings.length > 0,
+        reason: `Found ${stagedFindings.length} violation(s) in staged files (strict mode)`,
+        violations: stagedFindings.length,
+      };
+    }
+
+    if (blockingFindings.length > 0) {
+      const bySeverity = {
+        critical: blockingFindings.filter(f => f.isCritical()).length,
+        high: blockingFindings.filter(f => f.isHigh()).length,
+      };
+
+      return {
+        shouldBlock: true,
+        reason: `Found ${blockingFindings.length} blocking violation(s) in staged files`,
+        violations: bySeverity,
+      };
+    }
+
+    return {
+      shouldBlock: false,
+      reason: 'No blocking violations in staged files',
+      technicalDebt: stagedFindings.length,
+    };
+  }
+
+  blockOnAnyViolation(auditResult) {
+    const bySeverity = auditResult.getViolationsBySeverity();
+
+    return {
+      shouldBlock: true,
+      reason: 'Strict mode: Any violation blocks commit',
+      violations: bySeverity,
+      total: auditResult.getTotalViolations(),
+    };
+  }
+
+  blockOnCriticalHigh(auditResult) {
+    const bySeverity = auditResult.getViolationsBySeverity();
+    const blockingCount = bySeverity.critical + bySeverity.high;
+
+    if (blockingCount > 0) {
+      return {
+        shouldBlock: true,
+        reason: `Found ${blockingCount} CRITICAL/HIGH violation(s)`,
+        violations: {
+          critical: bySeverity.critical,
+          high: bySeverity.high,
+        },
+      };
+    }
+
+    return {
+      shouldBlock: false,
+      reason: 'No CRITICAL/HIGH violations',
+      technicalDebt: bySeverity.medium + bySeverity.low,
+    };
+  }
+
+  blockOnBlockingLevels(auditResult) {
+    if (auditResult.hasBlockingViolations()) {
+      const bySeverity = auditResult.getViolationsBySeverity();
+
+      return {
+        shouldBlock: true,
+        reason: `Found blocking violations (CRITICAL: ${bySeverity.critical}, HIGH: ${bySeverity.high})`,
+        violations: {
+          critical: bySeverity.critical,
+          high: bySeverity.high,
+        },
+      };
+    }
+
+    return {
+      shouldBlock: false,
+      reason: 'No blocking violations found',
+      technicalDebt: auditResult.getTotalViolations(),
+    };
+  }
+
+  calculateTechnicalDebtThreshold(auditResult, maxDebtHours = 100) {
+    const totalDebtHours = auditResult.getTechnicalDebtHours();
+
+    return {
+      currentDebt: totalDebtHours,
+      maxAllowed: maxDebtHours,
+      exceedsThreshold: totalDebtHours > maxDebtHours,
+      message: `Technical debt: ${totalDebtHours}h / ${maxDebtHours}h max`,
+    };
+  }
+
+  getMaintainabilityGate(auditResult, minScore = 60) {
+    const score = auditResult.getMaintainabilityIndex();
+
+    return {
+      score,
+      minScore,
+      passes: score >= minScore,
+      message: `Maintainability Index: ${score.toFixed(1)}/100 (min ${minScore})`,
+    };
+  }
+}
+
+module.exports = CommitBlockingRules;

package/scripts/hooks-system/domain/rules/__tests__/CommitBlockingRules.spec.js

@@ -0,0 +1,18 @@
+describe('CommitBlockingRules', () => {
+  it('should export class', () => {
+    const CommitBlockingRules = require('../CommitBlockingRules');
+    expect(CommitBlockingRules).toBeDefined();
+  });
+
+  it('should be instantiable', () => {
+    const CommitBlockingRules = require('../CommitBlockingRules');
+    const instance = new CommitBlockingRules();
+    expect(instance).toBeDefined();
+  });
+
+  it('should have shouldBlockCommit method', () => {
+    const CommitBlockingRules = require('../CommitBlockingRules');
+    const instance = new CommitBlockingRules();
+    expect(typeof instance.shouldBlockCommit).toBe('function');
+  });
+});

package/scripts/hooks-system/domain/services/AuditAnalyzer.js

@@ -0,0 +1,103 @@
+const { ValidationError } = require('../errors');
+
+class AuditAnalyzer {
+    constructor(scorer) {
+        this.scorer = scorer;
+    }
+
+    getViolationsBySeverity(findings) {
+        return {
+            critical: findings.filter(f => f.isCritical()).length,
+            high: findings.filter(f => f.isHigh()).length,
+            medium: findings.filter(f => f.isMedium()).length,
+            low: findings.filter(f => f.isLow()).length,
+            info: findings.filter(f => f.isInfo()).length,
+        };
+    }
+
+    getViolationsByPlatform(findings) {
+        const platformMap = {};
+        findings.forEach(finding => {
+            const platform = finding.platform;
+            if (!platformMap[platform]) {
+                platformMap[platform] = {
+                    total: 0,
+                    critical: 0,
+                    high: 0,
+                    medium: 0,
+                    low: 0,
+                    info: 0,
+                };
+            }
+            platformMap[platform].total++;
+            platformMap[platform][finding.severity.toString()]++;
+        });
+        return platformMap;
+    }
+
+    getViolationsByRuleId(findings) {
+        const ruleMap = {};
+        findings.forEach(finding => {
+            const ruleId = finding.ruleId;
+            if (!ruleMap[ruleId]) {
+                ruleMap[ruleId] = [];
+            }
+            ruleMap[ruleId].push(finding);
+        });
+        return ruleMap;
+    }
+
+    getTopViolatedRules(findings, limit = 10) {
+        const ruleMap = this.getViolationsByRuleId(findings);
+        return Object.entries(ruleMap)
+            .map(([ruleId, ruleFindings]) => ({
+                ruleId,
+                count: ruleFindings.length,
+                severity: ruleFindings[0].severity.toString(),
+                examples: ruleFindings.slice(0, 3),
+            }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, limit);
+    }
+
+    getTopViolatedFiles(findings, limit = 10) {
+        const fileMap = {};
+        findings.forEach(finding => {
+            if (!fileMap[finding.filePath]) {
+                fileMap[finding.filePath] = {
+                    filePath: finding.filePath,
+                    violations: [],
+                };
+            }
+            fileMap[finding.filePath].violations.push(finding);
+        });
+
+        return Object.values(fileMap)
+            .map(file => ({
+                filePath: file.filePath,
+                count: file.violations.length,
+                bySeverity: {
+                    critical: file.violations.filter(f => f.isCritical()).length,
+                    high: file.violations.filter(f => f.isHigh()).length,
+                    medium: file.violations.filter(f => f.isMedium()).length,
+                    low: file.violations.filter(f => f.isLow()).length,
+                },
+            }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, limit);
+    }
+
+    filterByPlatform(findings, platform) {
+        return findings.filter(f => f.belongsToPlatform(platform));
+    }
+
+    filterBySeverity(findings, severity) {
+        return findings.filter(f => f.severity.toString() === severity.toLowerCase());
+    }
+
+    filterByFile(findings, filePath) {
+        return findings.filter(f => f.filePath === filePath);
+    }
+}
+
+module.exports = AuditAnalyzer;

package/scripts/hooks-system/domain/services/AuditFilter.js

@@ -0,0 +1,26 @@
+const AuditResult = require('../entities/AuditResult');
+
+class AuditFilter {
+    filterByPlatform(findings, platform) {
+        return findings.filter(f => f.belongsToPlatform(platform));
+    }
+
+    filterBySeverity(findings, severity) {
+        return findings.filter(f => f.severity.toString() === severity.toLowerCase());
+    }
+
+    filterByFile(findings, filePath) {
+        return findings.filter(f => f.filePath === filePath);
+    }
+
+    createFilteredResult(originalResult, filterFn, filterArg) {
+        const filteredFindings = filterFn(originalResult.findings, filterArg);
+        const newResult = new AuditResult(filteredFindings);
+        // Preserve metadata except totals which are recalculated
+        newResult.metadata = { ...originalResult.metadata };
+        // Recalculate specific metadata if needed? No, totals are calculated on fly or in constructor.
+        return newResult;
+    }
+}
+
+module.exports = AuditFilter;

package/scripts/hooks-system/domain/services/AuditResultSerializer.js

@@ -0,0 +1,35 @@
+const Finding = require('../entities/Finding');
+
+class AuditResultSerializer {
+    toJSON(auditResult) {
+        return {
+            timestamp: auditResult.timestamp.toISOString(),
+            summary: {
+                totalViolations: auditResult.getTotalViolations(),
+                bySeverity: auditResult.getViolationsBySeverity(),
+                byPlatform: auditResult.getViolationsByPlatform(),
+                technicalDebtHours: auditResult.getTechnicalDebtHours(),
+                maintainabilityIndex: auditResult.getMaintainabilityIndex(),
+            },
+            metadata: auditResult.metadata,
+            findings: auditResult.findings.map(f => f.toJSON()),
+        };
+    }
+
+    fromJSON(json) {
+        const findings = json.findings.map(f => Finding.fromJSON(f));
+        const AuditResult = require('../entities/AuditResult');
+        const result = new AuditResult(findings);
+
+        if (json.timestamp) {
+            result.timestamp = new Date(json.timestamp);
+        }
+        if (json.metadata) {
+            result.metadata = json.metadata;
+        }
+
+        return result;
+    }
+}
+
+module.exports = AuditResultSerializer;