pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/infrastructure/utils/__tests__/utils.spec.js

@@ -0,0 +1,8 @@
+describe('utils', () => {
+    describe('token-manager', () => {
+        it('should export module', () => {
+            const mod = require('../token-manager');
+            expect(mod).toBeDefined();
+        });
+    });
+});

package/scripts/hooks-system/infrastructure/utils/error-utils.js

@@ -0,0 +1,28 @@
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+
+function toErrorDetails(error) {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            stack: error.stack,
+            name: error.name,
+            cause: error.cause
+        };
+    }
+    return {
+        message: toErrorMessage(error),
+        stack: undefined,
+        name: 'UnknownError',
+        cause: undefined
+    };
+}
+
+module.exports = { toErrorMessage, toErrorDetails };

package/scripts/hooks-system/infrastructure/utils/timestamp-helper.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════
+# Timestamp Helper - Consistent ISO 8601 timestamps
+# ═══════════════════════════════════════════════════════════════
+# Usage:
+#   source timestamp-helper.sh
+#   NOW=$(get_current_timestamp)
+#   AGE=$(get_timestamp_age "$EVIDENCE_TS")
+# ═══════════════════════════════════════════════════════════════
+
+# Get current timestamp in ISO 8601 with milliseconds
+# Returns: 2025-11-06T10:45:23.123Z
+get_current_timestamp() {
+  date -u +"%Y-%m-%dT%H:%M:%S.000Z"
+}
+
+# Get current timestamp in epoch seconds
+get_current_epoch() {
+  date +%s
+}
+
+# Convert ISO 8601 timestamp to epoch
+# Args: $1 = ISO 8601 timestamp (with or without milliseconds)
+# Returns: epoch seconds or "0" if invalid
+iso_to_epoch() {
+  local timestamp="$1"
+
+  # Strip milliseconds if present (2025-11-06T10:45:23.123Z → 2025-11-06T10:45:23Z)
+  local clean_ts=$(echo "$timestamp" | sed 's/\.[0-9]*Z$/Z/')
+
+  # Convert to epoch (macOS date command)
+  TZ=UTC date -j -f "%Y-%m-%dT%H:%M:%SZ" "$clean_ts" +%s 2>/dev/null || echo "0"
+}
+
+# Get age of timestamp in seconds
+# Args: $1 = ISO 8601 timestamp
+# Returns: age in seconds or "999999" if invalid
+get_timestamp_age() {
+  local timestamp="$1"
+
+  local ts_epoch=$(iso_to_epoch "$timestamp")
+  local now_epoch=$(get_current_epoch)
+
+  if [[ "$ts_epoch" == "0" ]]; then
+    echo "999999"  # Invalid timestamp = very old
+    return 1
+  fi
+
+  echo $((now_epoch - ts_epoch))
+}
+
+# Check if timestamp is fresh (less than N seconds old)
+# Args: $1 = ISO 8601 timestamp, $2 = max age in seconds (default 180)
+# Returns: 0 if fresh, 1 if stale
+is_timestamp_fresh() {
+  local timestamp="$1"
+  local max_age="${2:-180}"  # Default 3 minutes
+
+  local age=$(get_timestamp_age "$timestamp")
+
+  [[ "$age" -le "$max_age" ]]
+}
+
+# Update .AI_EVIDENCE.json timestamp
+# Args: none (updates in-place)
+update_evidence_timestamp() {
+  local evidence_file="${1:-.AI_EVIDENCE.json}"
+
+  if [[ ! -f "$evidence_file" ]]; then
+    echo "❌ Evidence file not found: $evidence_file"
+    return 1
+  fi
+
+  local new_timestamp=$(get_current_timestamp)
+
+  # Use jq to update timestamp field
+  local temp_file="${evidence_file}.tmp"
+  jq --arg ts "$new_timestamp" '.timestamp = $ts' "$evidence_file" > "$temp_file" && mv "$temp_file" "$evidence_file"
+
+  echo "✅ Evidence timestamp updated: $new_timestamp"
+}
+
+# Format age for human-readable display
+# Args: $1 = age in seconds
+# Returns: "2m 30s" or "1h 15m" or "2d 3h"
+format_age() {
+  local age="$1"
+
+  if [[ $age -lt 60 ]]; then
+    echo "${age}s"
+  elif [[ $age -lt 3600 ]]; then
+    local minutes=$((age / 60))
+    local seconds=$((age % 60))
+    echo "${minutes}m ${seconds}s"
+  elif [[ $age -lt 86400 ]]; then
+    local hours=$((age / 3600))
+    local minutes=$(((age % 3600) / 60))
+    echo "${hours}h ${minutes}m"
+  else
+    local days=$((age / 86400))
+    local hours=$(((age % 86400) / 3600))
+    echo "${days}d ${hours}h"
+  fi
+}
+
+# 🐈 Pumuki approved timestamps 💚

package/scripts/hooks-system/infrastructure/utils/token-manager.js

@@ -0,0 +1,121 @@
+
+const fs = require('fs');
+const path = require('path');
+
+class TokenManager {
+  constructor() {
+    this.limit = 1000000;
+    this.warningThresholds = [
+      { percent: 75, level: 'INFO' },
+      { percent: 85, level: 'WARNING' },
+      { percent: 95, level: 'CRITICAL' }
+    ];
+
+    this.historyPath = '.audit_tmp/token-usage.jsonl';
+    this.ensureHistoryFile();
+  }
+
+  ensureHistoryFile() {
+    const dir = path.dirname(this.historyPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Estimate tokens used in current operation
+   * @param {Array} violations - Violations array
+   * @param {Object} report - Generated report
+   * @returns {Object} Token usage estimate
+   */
+  estimate(violations, report) {
+    const baseTokens = 50000;
+    const violationTokens = violations.length * 100;
+    const reportTokens = JSON.stringify(report).length / 4;
+
+    const estimated = baseTokens + violationTokens + reportTokens;
+
+    return {
+      estimated,
+      percentUsed: (estimated / this.limit) * 100,
+      remaining: this.limit - estimated
+    };
+  }
+
+  /**
+   * Check if warning should be issued
+   */
+  checkWarnings(usage) {
+    const percent = usage.percentUsed;
+
+    for (const threshold of this.warningThresholds.reverse()) {
+      if (percent >= threshold.percent) {
+        return {
+          shouldWarn: true,
+          level: threshold.level,
+          message: this.generateWarningMessage(threshold.level, usage)
+        };
+      }
+    }
+
+    return { shouldWarn: false };
+  }
+
+  generateWarningMessage(level, usage) {
+    const messages = {
+      INFO: `ℹ️  Token usage at ${Math.round(usage.percentUsed)}% (${usage.estimated.toLocaleString()} / ${this.limit.toLocaleString()})`,
+      WARNING: `⚠️  HIGH token usage: ${Math.round(usage.percentUsed)}% - Consider wrapping up session soon`,
+      CRITICAL: `🚨 CRITICAL token usage: ${Math.round(usage.percentUsed)}% - Session will end soon! Save context to .AI_EVIDENCE.json`
+    };
+
+    return messages[level] || messages.INFO;
+  }
+
+  /**
+   * Record token usage
+   */
+  record(usage) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      estimated: usage.estimated,
+      percentUsed: usage.percentUsed,
+      remaining: usage.remaining
+    };
+
+    fs.appendFileSync(this.historyPath, JSON.stringify(entry) + '\n');
+  }
+
+  /**
+   * Get usage trend
+   */
+  getTrend() {
+    if (!fs.existsSync(this.historyPath)) {
+      return { trend: 'NO_DATA' };
+    }
+
+    const lines = fs.readFileSync(this.historyPath, 'utf8')
+      .split('\n')
+      .filter(l => l.trim());
+
+    if (lines.length < 2) {
+      return { trend: 'INSUFFICIENT_DATA' };
+    }
+
+    const history = lines.map(l => JSON.parse(l));
+    const latest = history[history.length - 1];
+    const first = history[0];
+
+    const totalIncrease = latest.estimated - first.estimated;
+    const avgPerEntry = totalIncrease / history.length;
+
+    return {
+      trend: totalIncrease > 500000 ? 'HIGH_CONSUMPTION' : 'NORMAL',
+      totalUsed: latest.estimated,
+      averagePerOperation: Math.round(avgPerEntry),
+      entriesInSession: history.length,
+      projectedToLimit: Math.round((this.limit - latest.estimated) / avgPerEntry)
+    };
+  }
+}
+
+module.exports = { TokenManager };

package/scripts/hooks-system/infrastructure/validators/__tests__/detect-commit-language.spec.js

@@ -0,0 +1,16 @@
+describe('detect-commit-language', () => {
+  it('should exist as a file', () => {
+    const fs = require('fs');
+    const path = require('path');
+    expect(fs.existsSync(path.join(__dirname, '../detect-commit-language.js'))).toBe(true);
+  });
+
+  it('should be valid JavaScript', () => {
+    expect(() => require.resolve('../detect-commit-language.js')).not.toThrow();
+  });
+
+  it('should export a function or object', () => {
+    const mod = require('../detect-commit-language.js');
+    expect(mod).toBeDefined();
+  });
+});

package/scripts/hooks-system/infrastructure/validators/__tests__/enforce-english-literals.spec.js

@@ -0,0 +1,67 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+describe('enforce-english-literals validator', () => {
+    let repoRoot;
+    const originalEnv = { ...process.env };
+
+    beforeEach(() => {
+        repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'language-guard-'));
+        process.env.HOOK_GUARD_REPO_ROOT = repoRoot;
+        fs.mkdirSync(path.join(repoRoot, 'scripts/hooks-system/config'), { recursive: true });
+    });
+
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    });
+
+    it('detects banned characters and words inside staged files', () => {
+        const config = {
+            extensions: ['ts'],
+            bannedCharacters: ['á'],
+            bannedWords: ['gracias']
+        };
+        fs.writeFileSync(
+            path.join(repoRoot, 'scripts/hooks-system/config/language-guard.json'),
+            JSON.stringify(config)
+        );
+
+        const filePath = path.join(repoRoot, 'src/example.ts');
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(
+            filePath,
+            'const mensaje = "gracias por tu colaboraci\u00f3n";\nconst titulo = "Planificaci\u00f3n \u00e1gil";\n'
+        );
+
+        jest.resetModules();
+        const validator = require('../enforce-english-literals');
+
+        const violations = validator.analyzeFile('src/example.ts', config);
+        expect(violations).toEqual(
+            expect.arrayContaining([
+                expect.objectContaining({ reason: 'banned_word' }),
+                expect.objectContaining({ reason: 'banned_character' })
+            ])
+        );
+    });
+
+    it('ignores files outside configured extensions', () => {
+        const config = {
+            extensions: ['ts'],
+            bannedCharacters: ['á'],
+            bannedWords: ['gracias']
+        };
+        fs.writeFileSync(
+            path.join(repoRoot, 'scripts/hooks-system/config/language-guard.json'),
+            JSON.stringify(config)
+        );
+
+        jest.resetModules();
+        const validator = require('../enforce-english-literals');
+
+        const shouldSkip = validator.shouldInspect('README.md', config.extensions);
+        expect(shouldSkip).toBe(false);
+    });
+});

package/scripts/hooks-system/infrastructure/validators/detect-commit-language.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+
+const COMMON_ENGLISH_WORDS = new Set([
+    'the', 'be', 'to', 'of', 'and', 'a', 'in', 'that', 'have', 'i',
+    'it', 'for', 'not', 'on', 'with', 'he', 'as', 'you', 'do', 'at',
+    'this', 'but', 'his', 'by', 'from', 'they', 'we', 'say', 'her', 'she',
+    'or', 'an', 'will', 'my', 'one', 'all', 'would', 'there', 'their',
+    'fix', 'add', 'update', 'remove', 'change', 'refactor', 'feat', 'chore',
+    'docs', 'test', 'style', 'perf', 'ci', 'build', 'revert', 'merge',
+    'correct', 'improve', 'enhance', 'implement', 'create', 'delete',
+    'use', 'using', 'dependencies', 'dependency', 'component', 'service',
+    'function', 'method', 'class', 'interface', 'type', 'error', 'bug',
+    'issue', 'problem', 'solution', 'should', 'must', 'can', 'will'
+]);
+
+const NON_ENGLISH_CHAR_PATTERNS = [
+    /[áéíóúñüÁÉÍÓÚÑÜ¿¡]/u,
+    /[àèìòùÀÈÌÒÙçÇ]/u,
+    /[äëïöüÄËÏÖÜß]/u,
+    /[åæøÅÆØ]/u,
+    /[čćđšžČĆĐŠŽ]/u,
+    /[αβγδεζηθικλμνξοπρστυφχψωΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩ]/u,
+    /[абвгдеёжзийклмнопрстуфхцчшщъыьэюяАБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯ]/u,
+    /[あいうえおかきくけこさしすせそたちつてとなにぬねのはひふへほまみむめもやゆよらりるれろわをん]/u,
+    /[的了一是在不人有我他这为之大来以个中上]/u,
+    /[àáạảãâầấậẩẫăằắặẳẵèéẹẻẽêềếệểễìíịỉĩòóọỏõôồốộổỗơờớợởỡùúụủũưừứựửữỳýỵỷỹđĐ]/u
+];
+
+function hasNonEnglishCharacters(text) {
+    return NON_ENGLISH_CHAR_PATTERNS.some(pattern => pattern.test(text));
+}
+
+function analyzeWords(text) {
+    const lowerText = text.toLowerCase();
+    const words = lowerText.split(/[\s:]+/).filter(w => w.length > 1);
+
+    let englishWordCount = 0;
+    let nonEnglishWordCount = 0;
+    let wordsWithNonASCII = [];
+
+    for (const word of words) {
+        const hasNonASCII = NON_ENGLISH_CHAR_PATTERNS.some(pattern => pattern.test(word));
+
+        if (hasNonASCII) {
+            nonEnglishWordCount++;
+            wordsWithNonASCII.push(word);
+        } else if (COMMON_ENGLISH_WORDS.has(word)) {
+            englishWordCount++;
+        } else if (/^[a-z]+$/.test(word)) {
+            englishWordCount++;
+        }
+    }
+
+    return {
+        englishWordCount,
+        nonEnglishWordCount,
+        totalWords: words.length,
+        wordsWithNonASCII
+    };
+}
+
+function detectLanguage(text) {
+    if (!text || text.trim().length === 0) {
+        return 'en';
+    }
+
+    const hasNonASCII = hasNonEnglishCharacters(text);
+
+    if (!hasNonASCII) {
+        return 'en';
+    }
+
+    const analysis = analyzeWords(text);
+
+    if (analysis.totalWords === 0) {
+        return 'en';
+    }
+
+    if (analysis.nonEnglishWordCount === 0) {
+        return 'en';
+    }
+
+    const englishRatio = analysis.englishWordCount / analysis.totalWords;
+    const nonEnglishRatio = analysis.nonEnglishWordCount / analysis.totalWords;
+
+    if (nonEnglishRatio >= 0.4) {
+        return 'non-english';
+    }
+
+    if (nonEnglishRatio > 0 && englishRatio < 0.6) {
+        return 'non-english';
+    }
+
+    if (englishRatio >= 0.7) {
+        return 'en';
+    }
+
+    return 'non-english';
+}
+
+function main() {
+    const msgFile = process.argv[2];
+
+    if (!msgFile || !fs.existsSync(msgFile)) {
+        process.exit(0);
+    }
+
+    const message = fs.readFileSync(msgFile, 'utf8').trim();
+
+    if (!message) {
+        process.exit(0);
+    }
+
+    const detectedLang = detectLanguage(message);
+
+    if (detectedLang !== 'en') {
+        console.error('❌ Commit message must be in English');
+        console.error('');
+        console.error('Current message:');
+        console.error(`  ${message}`);
+        console.error('');
+        console.error('⚠️  Detected non-English language');
+        console.error('');
+        console.error('💡 Example:');
+        console.error('  fix: correct useEffect dependencies in MetricsChart to use mode from useTheme');
+        console.error('');
+        process.exit(1);
+    }
+
+    process.exit(0);
+}
+
+if (require.main === module) {
+    try {
+        main();
+    } catch (error) {
+        console.error('❌ Error detecting commit message language:', error.message);
+        process.exit(1);
+    }
+}
+
+module.exports = { detectLanguage, hasNonEnglishCharacters, analyzeWords };

package/scripts/hooks-system/infrastructure/validators/enforce-english-literals.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const REPO_ROOT = process.env.HOOK_GUARD_REPO_ROOT || process.cwd();
+const CONFIG_PATH = path.join(REPO_ROOT, 'scripts', 'hooks-system', 'config', 'language-guard.json');
+const DEFAULT_IGNORED_SEGMENTS = [
+    `${path.sep}node_modules${path.sep}`,
+    `${path.sep}dist${path.sep}`,
+    `${path.sep}coverage${path.sep}`,
+    `${path.sep}.git${path.sep}`,
+    `${path.sep}.next${path.sep}`
+];
+
+function decodeUnicode(value) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    try {
+        return JSON.parse(`"${value}"`);
+    } catch (error) {
+        if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+            console.debug(`[enforce-english-literals] Failed to decode Unicode value "${value}": ${error.message}`);
+        }
+        return value;
+    }
+}
+
+function loadConfig(configPath = CONFIG_PATH) {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    return {
+        extensions: Array.isArray(config.extensions) ? config.extensions : [],
+        bannedCharacters: Array.isArray(config.bannedCharacters)
+            ? config.bannedCharacters.map(decodeUnicode)
+            : [],
+        bannedWords: Array.isArray(config.bannedWords)
+            ? config.bannedWords.map(decodeUnicode)
+            : [],
+        allowPatterns: Array.isArray(config.allowPatterns)
+            ? config.allowPatterns.map(pattern => new RegExp(pattern))
+            : []
+    };
+}
+
+function escapeForCharClass(character) {
+    return character.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+
+function shouldInspect(relativePath, extensions, ignoredSegments = DEFAULT_IGNORED_SEGMENTS) {
+    if (!relativePath) {
+        return false;
+    }
+    for (const segment of ignoredSegments) {
+        if (relativePath.includes(segment)) {
+            return false;
+        }
+    }
+    const normalized = relativePath.toLowerCase();
+    return extensions.some(extension => normalized.endsWith(`.${extension.toLowerCase()}`));
+}
+
+function analyzeFile(relativePath, config) {
+    const absolutePath = path.join(REPO_ROOT, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+        return [];
+    }
+
+    const bannedCharacters = config.bannedCharacters || [];
+    const bannedWords = (config.bannedWords || []).map(entry => entry.toLowerCase());
+    const violations = [];
+
+    const source = fs.readFileSync(absolutePath, 'utf8');
+    const lines = source.split(/\r?\n/);
+
+    let charPattern = null;
+    if (bannedCharacters.length > 0) {
+        const patternBody = bannedCharacters.map(escapeForCharClass).join('');
+        if (patternBody.length > 0) {
+            charPattern = new RegExp(`[${patternBody}]`, 'u');
+        }
+    }
+
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const lowerLine = line.toLowerCase();
+
+        if (charPattern && charPattern.test(line)) {
+            violations.push({
+                file: relativePath,
+                line: index + 1,
+                reason: 'banned_character',
+                snippet: line.trim()
+            });
+            continue;
+        }
+
+        for (const word of bannedWords) {
+            if (!word) continue;
+            const wordPattern = new RegExp(`\\b${word}\\b`, 'i');
+            if (wordPattern.test(lowerLine)) {
+                violations.push({
+                    file: relativePath,
+                    line: index + 1,
+                    reason: 'banned_word',
+                    snippet: line.trim(),
+                    metadata: { word }
+                });
+                break;
+            }
+        }
+    }
+
+    return violations;
+}
+
+function collectStagedFiles() {
+    try {
+        const raw = execSync('git diff --cached --name-only --diff-filter=ACMR', {
+            cwd: REPO_ROOT,
+            encoding: 'utf8'
+        });
+        return raw.split('\n').map(entry => entry.trim()).filter(Boolean);
+    } catch (error) {
+        if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+            console.debug(`[enforce-english-literals] Failed to collect staged files: ${error.message}`);
+        }
+        return [];
+    }
+}
+
+function isAllowed(relativePath, allowPatterns = []) {
+    for (const pattern of allowPatterns) {
+        if (pattern.test(relativePath)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function evaluate({ files, config }) {
+    const violations = [];
+    for (const relativePath of files) {
+        if (!shouldInspect(relativePath, config.extensions)) {
+            continue;
+        }
+        if (isAllowed(relativePath, config.allowPatterns)) {
+            continue;
+        }
+        const result = analyzeFile(relativePath, config);
+        if (result.length > 0) {
+            violations.push(...result);
+        }
+    }
+    return violations;
+}
+
+function formatViolation(violation) {
+    const location = `${violation.file}:${violation.line}`;
+    if (violation.reason === 'banned_word' && violation.metadata && violation.metadata.word) {
+        return `  • ${location} contains banned word "${violation.metadata.word}": ${violation.snippet}`;
+    }
+    return `  • ${location} contains banned characters: ${violation.snippet}`;
+}
+
+function run() {
+    const config = loadConfig();
+    const files = collectStagedFiles();
+    if (files.length === 0) {
+        process.exit(0);
+    }
+
+    const violations = evaluate({ files, config });
+    if (violations.length === 0) {
+        process.exit(0);
+    }
+
+    const uniqueMessages = violations.map(formatViolation);
+    uniqueMessages.forEach(message => console.error(message));
+    console.error('\nEnsure every string literal and test description is written in English.');
+    process.exit(1);
+}
+
+if (require.main === module) {
+    try {
+        run();
+    } catch (error) {
+        console.error('❌ Error executing enforce-english-literals:', error.message);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    loadConfig,
+    shouldInspect,
+    analyzeFile,
+    evaluate,
+    run
+};