chati-dev 3.2.5 → 3.3.0

package/src/decision/analyzer.js

@@ -139,6 +139,154 @@ export function getTransitiveDependents(graph, entityPath) {
   return result;
 }
 
+/**
+ * Score a decision option based on multiple criteria using TF-IDF-inspired
+ * keyword relevance scoring.
+ *
+ * @param {{ name: string, description?: string, keywords?: string[] }} option
+ * @param {{ requirements?: string[], constraints?: string[], existingEntities?: string[] }} context
+ * @returns {{ score: number, alignment: number, complexity: number, reuse: number, breakdown: object }}
+ */
+export function scoreDecision(option, context = {}) {
+  if (!option || !option.name) {
+    return { score: 0, alignment: 0, complexity: 0, reuse: 0, breakdown: {} };
+  }
+
+  const requirements = context.requirements || [];
+  const constraints = context.constraints || [];
+  const existingEntities = context.existingEntities || [];
+
+  // 1. Alignment score — how well does option match requirements?
+  const optionText = `${option.name} ${option.description || ''} ${(option.keywords || []).join(' ')}`.toLowerCase();
+  const alignment = computeRelevance(optionText, requirements);
+
+  // 2. Complexity score (inverse — lower complexity = higher score)
+  const complexitySignals = ['microservice', 'distributed', 'multi-tenant', 'real-time', 'concurrent', 'migration'];
+  let complexityCount = 0;
+  for (const signal of complexitySignals) {
+    if (optionText.includes(signal)) {
+      complexityCount++;
+    }
+  }
+  const complexity = Math.max(0, 1 - complexityCount * 0.15);
+
+  // 3. Reuse score — overlap with existing entities (decision priority: REUSE > ADAPT > CREATE)
+  let reuse = 0;
+  if (existingEntities.length > 0) {
+    const optionWords = new Set(optionText.split(/\s+/));
+    let matchCount = 0;
+    for (const entity of existingEntities) {
+      const entityWords = entity.toLowerCase().split(/[\s/.-]+/);
+      for (const word of entityWords) {
+        if (word.length > 3 && optionWords.has(word)) {
+          matchCount++;
+          break;
+        }
+      }
+    }
+    reuse = existingEntities.length > 0 ? matchCount / existingEntities.length : 0;
+  }
+
+  // 4. Constraint satisfaction
+  let constraintScore = 1;
+  if (constraints.length > 0) {
+    let satisfied = 0;
+    for (const constraint of constraints) {
+      const constraintWords = constraint.toLowerCase().split(/\s+/);
+      const hasMatch = constraintWords.some(w => w.length > 3 && optionText.includes(w));
+      if (hasMatch) satisfied++;
+    }
+    constraintScore = constraints.length > 0 ? satisfied / constraints.length : 1;
+  }
+
+  // Weighted final score
+  const score = Math.round(
+    (alignment * 0.4 + complexity * 0.2 + reuse * 0.25 + constraintScore * 0.15) * 100
+  ) / 100;
+
+  return {
+    score,
+    alignment: Math.round(alignment * 100) / 100,
+    complexity: Math.round(complexity * 100) / 100,
+    reuse: Math.round(reuse * 100) / 100,
+    breakdown: {
+      alignment: { weight: 0.4, raw: alignment },
+      complexity: { weight: 0.2, raw: complexity },
+      reuse: { weight: 0.25, raw: reuse },
+      constraints: { weight: 0.15, raw: constraintScore },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// TF-IDF Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute TF-IDF-inspired relevance between text and a set of documents.
+ *
+ * @param {string} text - Source text
+ * @param {string[]} documents - Reference documents (requirements, etc.)
+ * @returns {number} Relevance score (0-1)
+ */
+function computeRelevance(text, documents) {
+  if (!text || documents.length === 0) return 0;
+
+  const textWords = tokenize(text);
+  if (textWords.length === 0) return 0;
+
+  // Build document frequency map
+  const docCount = documents.length;
+  const df = new Map();
+
+  for (const doc of documents) {
+    const words = new Set(tokenize(doc.toLowerCase()));
+    for (const word of words) {
+      df.set(word, (df.get(word) || 0) + 1);
+    }
+  }
+
+  // Calculate TF-IDF score for each text word
+  const textWordSet = new Set(textWords);
+  let totalScore = 0;
+
+  for (const word of textWordSet) {
+    const termFreq = textWords.filter(w => w === word).length / textWords.length;
+    const docFreq = df.get(word) || 0;
+
+    if (docFreq > 0) {
+      // IDF = log(N / df) — boost rare terms
+      const idf = Math.log((docCount + 1) / (docFreq + 1)) + 1;
+      totalScore += termFreq * idf;
+    }
+  }
+
+  // Normalize to 0-1 range
+  const maxPossible = Math.log(docCount + 1) + 1;
+  return maxPossible > 0 ? Math.min(totalScore / maxPossible, 1) : 0;
+}
+
+/**
+ * Tokenize text into meaningful words (skip stopwords and short tokens).
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+  const stopwords = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+    'of', 'with', 'by', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+    'should', 'may', 'might', 'shall', 'can', 'this', 'that', 'these',
+    'those', 'it', 'its', 'not', 'no', 'from', 'as', 'into', 'all',
+  ]);
+
+  return text
+    .toLowerCase()
+    .split(/[\s,.;:!?()[\]{}"'`/\\-]+/)
+    .filter(w => w.length > 2 && !stopwords.has(w));
+}
+
 /**
  * Flatten entity registry into array of entities.
  * @private

package/src/decision/registry-healer.js

@@ -10,6 +10,20 @@ import { join, isAbsolute } from 'path';
 import yaml from 'js-yaml';
 import { detectNewEntities, detectRemovedEntities, generateEntityMeta } from './registry-updater.js';
 
+/**
+ * Load and parse the entity registry YAML once.
+ * @param {string} projectDir
+ * @returns {{ registry: object|null, registryPath: string }}
+ */
+function loadRegistry(projectDir) {
+  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  if (!existsSync(registryPath)) {
+    return { registry: null, registryPath };
+  }
+  const registry = yaml.load(readFileSync(registryPath, 'utf8'));
+  return { registry, registryPath };
+}
+
 /**
  * Run all healing rules and return diagnosis.
  * @param {string} projectDir
@@ -22,6 +36,9 @@ export function healRegistry(projectDir, options = {}) {
   const issues = [];
   const fixes = [];
 
+  // Load registry once for rules 3-6
+  const { registry } = loadRegistry(projectDir);
+
   // Rule 1: Missing entities
   const missingIssues = detectMissingEntities(projectDir);
   issues.push(...missingIssues);
@@ -50,7 +67,7 @@ export function healRegistry(projectDir, options = {}) {
   }
 
   // Rule 3: Stale metadata
-  const staleIssues = detectStaleMetadata(projectDir);
+  const staleIssues = detectStaleMetadata(projectDir, registry);
   issues.push(...staleIssues);
   if (autoFix) {
     staleIssues.forEach(issue => {
@@ -64,7 +81,7 @@ export function healRegistry(projectDir, options = {}) {
   }
 
   // Rule 4: Duplicates
-  const duplicateIssues = detectDuplicates(projectDir);
+  const duplicateIssues = detectDuplicates(projectDir, registry);
   issues.push(...duplicateIssues);
   if (autoFix) {
     duplicateIssues.forEach(issue => {
@@ -78,7 +95,7 @@ export function healRegistry(projectDir, options = {}) {
   }
 
   // Rule 5: Invalid paths
-  const invalidPathIssues = detectInvalidPaths(projectDir);
+  const invalidPathIssues = detectInvalidPaths(projectDir, registry);
   issues.push(...invalidPathIssues);
   if (autoFix) {
     invalidPathIssues.forEach(issue => {
@@ -92,7 +109,7 @@ export function healRegistry(projectDir, options = {}) {
   }
 
   // Rule 6: Count mismatch
-  const countIssues = detectCountMismatch(projectDir);
+  const countIssues = detectCountMismatch(projectDir, registry);
   issues.push(...countIssues);
   if (autoFix) {
     countIssues.forEach(issue => {
@@ -158,15 +175,15 @@ export function detectOrphanedEntries(projectDir) {
 /**
  * Rule 3: Stale metadata (file modified after registry entry).
  * @param {string} projectDir
+ * @param {object} [preloaded] - Pre-loaded registry object (avoids redundant file read)
  * @returns {object[]} Issues found
  */
-export function detectStaleMetadata(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
-  if (!existsSync(registryPath)) {
+export function detectStaleMetadata(projectDir, preloaded) {
+  const registry = preloaded || loadRegistry(projectDir).registry;
+  if (!registry) {
     return [];
   }
 
-  const registry = yaml.load(readFileSync(registryPath, 'utf8'));
   const lastUpdated = registry.metadata?.last_updated
     ? new Date(registry.metadata.last_updated)
     : new Date(0);
@@ -202,15 +219,15 @@ export function detectStaleMetadata(projectDir) {
 /**
  * Rule 4: Duplicate entries (same path appears twice).
  * @param {string} projectDir
+ * @param {object} [preloaded] - Pre-loaded registry object (avoids redundant file read)
  * @returns {object[]} Issues found
  */
-export function detectDuplicates(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
-  if (!existsSync(registryPath)) {
+export function detectDuplicates(projectDir, preloaded) {
+  const registry = preloaded || loadRegistry(projectDir).registry;
+  if (!registry) {
     return [];
   }
 
-  const registry = yaml.load(readFileSync(registryPath, 'utf8'));
   const pathCounts = new Map();
   const issues = [];
 
@@ -242,15 +259,15 @@ export function detectDuplicates(projectDir) {
 /**
  * Rule 5: Invalid paths (malformed or absolute paths).
  * @param {string} projectDir
+ * @param {object} [preloaded] - Pre-loaded registry object (avoids redundant file read)
  * @returns {object[]} Issues found
  */
-export function detectInvalidPaths(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
-  if (!existsSync(registryPath)) {
+export function detectInvalidPaths(projectDir, preloaded) {
+  const registry = preloaded || loadRegistry(projectDir).registry;
+  if (!registry) {
     return [];
   }
 
-  const registry = yaml.load(readFileSync(registryPath, 'utf8'));
   const issues = [];
 
   Object.values(registry.entities || {}).forEach(entities => {
@@ -291,15 +308,15 @@ export function detectInvalidPaths(projectDir) {
 /**
  * Rule 6: Entity count mismatch (metadata.entity_count != actual).
  * @param {string} projectDir
+ * @param {object} [preloaded] - Pre-loaded registry object (avoids redundant file read)
  * @returns {object[]} Issues found
  */
-export function detectCountMismatch(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
-  if (!existsSync(registryPath)) {
+export function detectCountMismatch(projectDir, preloaded) {
+  const registry = preloaded || loadRegistry(projectDir).registry;
+  if (!registry) {
     return [];
   }
 
-  const registry = yaml.load(readFileSync(registryPath, 'utf8'));
   let actualCount = 0;
 
   Object.values(registry.entities || {}).forEach(entities => {
@@ -346,7 +363,7 @@ export function applyFixes(projectDir, fixes) {
   const backupPath = join(backupDir, `entity-registry-${timestamp}.yaml`);
   copyFileSync(registryPath, backupPath);
 
-  // Load registry
+  // Load registry (fresh read for modification — applyFixes is the write path)
   const registry = yaml.load(readFileSync(registryPath, 'utf8'));
 
   let applied = 0;

package/src/extensions/loader.js

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Extension loader for chati.dev.
+ *
+ * Discovers and loads project-level extensions from
+ * `chati.dev/extensions/*.js`, validates them, and registers
+ * them in the extension registry.
+ *
+ * Constitution Article XIV — Framework Registry Governance.
+ */
+
+import { existsSync, readdirSync } from 'fs';
+import { join, extname, basename } from 'path';
+import { registerExtension, EXTENSION_POINTS } from './registry.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Directory relative to project root where extensions are stored. */
+const EXTENSIONS_DIR = 'chati.dev/extensions';
+
+/** Required fields in an extension module's default export. */
+const REQUIRED_FIELDS = ['name', 'point', 'handler'];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an extension object has the required shape.
+ *
+ * @param {object} ext - Extension object to validate
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateExtension(ext) {
+  const errors = [];
+
+  if (!ext || typeof ext !== 'object') {
+    errors.push('Extension must be a non-null object');
+    return { valid: false, errors };
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (ext[field] === undefined || ext[field] === null) {
+      errors.push(`Missing required field: "${field}"`);
+    }
+  }
+
+  if (ext.name !== undefined && typeof ext.name !== 'string') {
+    errors.push('name must be a string');
+  }
+
+  if (ext.point !== undefined) {
+    const validPoints = Object.values(EXTENSION_POINTS);
+    if (!validPoints.includes(ext.point)) {
+      errors.push(`Invalid extension point: "${ext.point}". Valid: ${validPoints.join(', ')}`);
+    }
+  }
+
+  if (ext.handler !== undefined && typeof ext.handler !== 'function') {
+    errors.push('handler must be a function');
+  }
+
+  if (ext.priority !== undefined && typeof ext.priority !== 'number') {
+    errors.push('priority must be a number');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Discover extension files in the project extensions directory.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {{ files: string[], dir: string }}
+ */
+export function discoverExtensions(projectDir) {
+  if (!projectDir) {
+    return { files: [], dir: '' };
+  }
+
+  const extDir = join(projectDir, EXTENSIONS_DIR);
+
+  if (!existsSync(extDir)) {
+    return { files: [], dir: extDir };
+  }
+
+  try {
+    const entries = readdirSync(extDir);
+    const jsFiles = entries
+      .filter(f => extname(f) === '.js')
+      .map(f => join(extDir, f));
+
+    return { files: jsFiles, dir: extDir };
+  } catch {
+    return { files: [], dir: extDir };
+  }
+}
+
+/**
+ * Load and register all extensions from a project directory.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {Promise<{ loaded: number, failed: number, errors: Array<{ file: string, error: string }> }>}
+ */
+export async function loadProjectExtensions(projectDir) {
+  const { files } = discoverExtensions(projectDir);
+  let loaded = 0;
+  let failed = 0;
+  const errors = [];
+
+  for (const filePath of files) {
+    try {
+      const mod = await import(filePath);
+      const ext = mod.default || mod;
+
+      const validation = validateExtension(ext);
+      if (!validation.valid) {
+        failed++;
+        errors.push({
+          file: basename(filePath),
+          error: validation.errors.join('; '),
+        });
+        continue;
+      }
+
+      const result = registerExtension(ext.point, ext.handler, {
+        name: ext.name,
+        priority: ext.priority || 0,
+      });
+
+      if (result.registered) {
+        loaded++;
+      } else {
+        failed++;
+        errors.push({
+          file: basename(filePath),
+          error: result.error || 'Registration failed',
+        });
+      }
+    } catch (err) {
+      failed++;
+      errors.push({
+        file: basename(filePath),
+        error: err.message,
+      });
+    }
+  }
+
+  return { loaded, failed, errors };
+}

package/src/extensions/registry.js

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Extension point registry for chati.dev.
+ *
+ * Provides a mechanism for registering, retrieving, and
+ * executing extension handlers at defined extension points.
+ *
+ * Constitution Article XIV — Framework Registry Governance.
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Available extension points in the pipeline lifecycle. */
+export const EXTENSION_POINTS = {
+  PRE_AGENT: 'pre_agent',
+  POST_AGENT: 'post_agent',
+  PRE_BUILD: 'pre_build',
+  POST_BUILD: 'post_build',
+  HEALTH_CHECK: 'health_check',
+  CUSTOM_GATE: 'custom_gate',
+};
+
+// ---------------------------------------------------------------------------
+// Internal State
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, Array<{ handler: Function, name: string, priority: number }>>} */
+const _registry = new Map();
+
+// Initialize registry with empty arrays for each point
+for (const point of Object.values(EXTENSION_POINTS)) {
+  _registry.set(point, []);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register an extension handler at a specific point.
+ *
+ * @param {string} point - Extension point (from EXTENSION_POINTS)
+ * @param {Function} handler - Handler function
+ * @param {{ name?: string, priority?: number }} [options={}]
+ * @returns {{ registered: boolean, error?: string }}
+ */
+export function registerExtension(point, handler, options = {}) {
+  if (!Object.values(EXTENSION_POINTS).includes(point)) {
+    return { registered: false, error: `Unknown extension point: ${point}` };
+  }
+
+  if (typeof handler !== 'function') {
+    return { registered: false, error: 'Handler must be a function' };
+  }
+
+  const name = options.name || handler.name || 'anonymous';
+  const priority = options.priority || 0;
+
+  const extensions = _registry.get(point);
+  extensions.push({ handler, name, priority });
+
+  // Sort by priority (higher first)
+  extensions.sort((a, b) => b.priority - a.priority);
+
+  return { registered: true };
+}
+
+/**
+ * Get all extensions registered at a point.
+ *
+ * @param {string} point - Extension point
+ * @returns {Array<{ handler: Function, name: string, priority: number }>}
+ */
+export function getExtensions(point) {
+  return _registry.get(point) || [];
+}
+
+/**
+ * Execute all extensions at a point with given context.
+ *
+ * @param {string} point - Extension point
+ * @param {object} context - Context passed to each handler
+ * @returns {Promise<{ results: Array<{ name: string, result: any, error?: string }>, executed: number }>}
+ */
+export async function executeExtensions(point, context = {}) {
+  const extensions = getExtensions(point);
+  const results = [];
+
+  for (const ext of extensions) {
+    try {
+      const result = await ext.handler(context);
+      results.push({ name: ext.name, result });
+    } catch (err) {
+      results.push({ name: ext.name, result: null, error: err.message });
+    }
+  }
+
+  return { results, executed: extensions.length };
+}
+
+/**
+ * Clear all extensions (or extensions at a specific point).
+ *
+ * @param {string} [point] - Optional point to clear (clears all if omitted)
+ */
+export function clearExtensions(point) {
+  if (point) {
+    if (_registry.has(point)) {
+      _registry.set(point, []);
+    }
+  } else {
+    for (const key of _registry.keys()) {
+      _registry.set(key, []);
+    }
+  }
+}
+
+/**
+ * Get count of registered extensions.
+ *
+ * @returns {{ total: number, byPoint: Record<string, number> }}
+ */
+export function getExtensionStats() {
+  const byPoint = {};
+  let total = 0;
+
+  for (const [point, extensions] of _registry.entries()) {
+    byPoint[point] = extensions.length;
+    total += extensions.length;
+  }
+
+  return { total, byPoint };
+}

package/src/gates/circuit-breaker.js

@@ -10,6 +10,8 @@
  *   HALF_OPEN — After reset timeout, allows a single test request
  */
 
+import { track as telemetryTrack } from '../telemetry/collector.js';
+
 export const CIRCUIT_STATES = {
   CLOSED: 'CLOSED',
   OPEN: 'OPEN',
@@ -61,6 +63,31 @@ export class CircuitBreaker {
     }
   }
 
+  /**
+   * Execute an async function through the circuit breaker.
+   * @param {Function} fn - Async function to execute
+   * @returns {Promise<*>} Result from fn
+   */
+  async executeAsync(fn) {
+    if (this._state === CIRCUIT_STATES.OPEN) {
+      const elapsed = Date.now() - (this._lastFailure || 0);
+      if (elapsed >= this.resetTimeout) {
+        this._state = CIRCUIT_STATES.HALF_OPEN;
+      } else {
+        throw new Error('Circuit breaker is OPEN. Request rejected.');
+      }
+    }
+
+    try {
+      const result = await fn();
+      this._onSuccess();
+      return result;
+    } catch (error) {
+      this._onFailure();
+      throw error;
+    }
+  }
+
   /** @private */
   _onSuccess() {
     this._successes++;
@@ -83,6 +110,11 @@ export class CircuitBreaker {
       this._state = CIRCUIT_STATES.OPEN;
     } else if (this._failures >= this.failureThreshold) {
       this._state = CIRCUIT_STATES.OPEN;
+      telemetryTrack('circuit_breaker_triggered', {
+        trigger: 'failure_threshold',
+        agent: 'unknown',
+        provider: 'unknown',
+      });
     }
   }
 

package/src/gates/g3-implementation.js

@@ -6,7 +6,7 @@
  * source files, lint passes, and no security issues are flagged.
  */
 
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { GateBase } from './gate-base.js';
 import { loadSession } from '../orchestrator/session-manager.js';
@@ -75,10 +75,23 @@ export class ImplementationGate extends GateBase {
       });
     }
 
-    // Check for lint results file
+    // Check for lint results file — parse content for real findings
     const lintResultPath = join(projectDir, '.lint-result');
     if (existsSync(lintResultPath)) {
-      evidence.lintPasses = true; // Presence of file assumed to mean lint was run
+      try {
+        const content = readFileSync(lintResultPath, 'utf-8');
+        const hasErrors = /error|failed|failure|\d+\s+error/i.test(content);
+        const hasPassIndicator = /pass|clean|ok|no\s*(errors|issues|warnings)|0\s+errors|success/i.test(content);
+        if (hasErrors && !hasPassIndicator) {
+          evidence.lintPasses = false;
+        } else if (hasPassIndicator) {
+          evidence.lintPasses = true;
+        } else {
+          evidence.lintPasses = null; // Ambiguous — file exists but no clear verdict
+        }
+      } catch {
+        evidence.lintPasses = null;
+      }
     }
 
     // Check for security scan results
@@ -88,7 +101,20 @@ export class ImplementationGate extends GateBase {
     ];
     for (const secPath of securityPaths) {
       if (existsSync(secPath)) {
-        evidence.securityClean = true;
+        try {
+          const content = readFileSync(secPath, 'utf-8');
+          const hasBlockers = /blocker|critical|high\s*severity|vulnerability found|failed/i.test(content);
+          const hasPassIndicator = /pass|clean|no\s*(issues|vulnerabilities|findings)|score:\s*(9[5-9]|100)/i.test(content);
+          if (hasBlockers) {
+            evidence.securityClean = false;
+          } else if (hasPassIndicator) {
+            evidence.securityClean = true;
+          } else {
+            evidence.securityClean = null;
+          }
+        } catch {
+          evidence.securityClean = null;
+        }
         break;
       }
     }