@paths.design/caws-cli 10.1.0 → 11.0.0

package/dist/sidecars/spec-drift.js

@@ -1,151 +0,0 @@
-/**
- * @fileoverview Spec Drift Analysis Sidecar
- * Compares implementation evidence (files_touched, AC results, gate results)
- * against spec scope and acceptance criteria.
- * @author @darianrosebrook
- */
-
-const _minimatch = require('minimatch');
-const minimatch = typeof _minimatch === 'function'
-  ? _minimatch
-  : (_minimatch.minimatch || (() => { throw new Error('minimatch export not found — expected v3 default or v5+ named export'); }));
-const { createSidecarOutput, createNoStateOutput } = require('./schema');
-const { getRecurrence } = require('../gates/feedback');
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Check whether a file path is within the spec's declared scope.
- * A file is in scope if it matches at least one scope.in pattern
- * and does not match any scope.out pattern.
- * @param {string} file
- * @param {string[]} scopeIn
- * @param {string[]} scopeOut
- * @returns {boolean}
- */
-function isInScope(file, scopeIn, scopeOut) {
-  if (scopeIn.length === 0) return true; // No scope.in means everything is allowed
-  const matchesIn = scopeIn.some(pattern => minimatch(file, pattern));
-  if (!matchesIn) return false;
-  const matchesOut = scopeOut.some(pattern => minimatch(file, pattern));
-  return !matchesOut;
-}
-
-/**
- * Build a set of file paths that are referenced by any acceptance criterion.
- * This is a rough heuristic: ACs that have results with file references, or
- * whose descriptions mention paths present in files_touched.
- * @param {object[]} acResults - state.acceptance_criteria.results
- * @param {string[]} filesTouched
- * @returns {Set<string>}
- */
-function filesWithACCoverage(acResults, filesTouched) {
-  const covered = new Set();
-  if (!acResults || !filesTouched) return covered;
-
-  for (const result of acResults) {
-    // If a result references files explicitly, mark them covered
-    if (result.files) {
-      result.files.forEach(f => covered.add(f));
-    }
-    // Heuristic: any file_touched whose basename appears in the AC description
-    // is considered loosely covered
-    if (result.description) {
-      for (const file of filesTouched) {
-        const basename = file.split('/').pop();
-        if (result.description.includes(basename)) {
-          covered.add(file);
-        }
-      }
-    }
-  }
-  return covered;
-}
-
-/**
- * Gather gate corroboration: how many scope_boundary failures exist in history.
- * @param {object|null} state
- * @returns {{ scope_failures: number, last_failure: string|null }}
- */
-function getGateCorroboration(state) {
-  const recurrence = getRecurrence('scope_boundary', state);
-  if (!recurrence) return { scope_failures: 0, last_failure: null };
-  return { scope_failures: recurrence.count, last_failure: recurrence.lastSeen };
-}
-
-// ---------------------------------------------------------------------------
-// Main analysis
-// ---------------------------------------------------------------------------
-
-/**
- * Analyze spec drift by comparing implementation evidence against spec intent.
- * Pure function -- no side effects, no writes.
- * @param {object|null} state - Working state (from loadState)
- * @param {object} spec - Resolved spec object
- * @returns {object} Sidecar output envelope
- */
-function analyzeSpecDrift(state, spec) {
-  if (!state) {
-    return createNoStateOutput('drift', spec.id);
-  }
-
-  const scopeIn = (spec.scope && spec.scope.in) || [];
-  const scopeOut = (spec.scope && spec.scope.out) || [];
-  const filesTouched = state.files_touched || [];
-  const acceptance = spec.acceptance || [];
-  const acResults = (state.acceptance_criteria && state.acceptance_criteria.results) || [];
-
-  // 1. Scope analysis -- find files outside declared scope
-  const outOfScopeFiles = filesTouched.filter(f => !isInScope(f, scopeIn, scopeOut));
-
-  // 2. Acceptance criteria cross-reference
-  const acResultMap = new Map();
-  for (const r of acResults) {
-    acResultMap.set(r.id, r);
-  }
-
-  const failingCriteria = [];
-  const missingEvidence = [];
-
-  for (const ac of acceptance) {
-    const result = acResultMap.get(ac.id);
-    if (!result || result.status === 'UNCHECKED') {
-      missingEvidence.push({ id: ac.id, description: ac.description || ac.text || '' });
-    } else if (result.status === 'FAIL') {
-      failingCriteria.push({ id: ac.id, description: ac.description || ac.text || '' });
-    }
-  }
-
-  // 3. Scope creep -- files with no AC coverage
-  const covered = filesWithACCoverage(acResults, filesTouched);
-  const scopeCreepFiles = filesTouched.filter(f => !covered.has(f));
-
-  // 4. Gate corroboration
-  const gateCorroboration = getGateCorroboration(state);
-
-  // 5. Drift detection
-  const driftDetected = outOfScopeFiles.length > 0 ||
-    failingCriteria.length > 0 ||
-    missingEvidence.length > 0;
-
-  // 6. Summary
-  const parts = [];
-  if (outOfScopeFiles.length > 0) parts.push(`${outOfScopeFiles.length} file(s) outside scope`);
-  if (failingCriteria.length > 0) parts.push(`${failingCriteria.length} AC failing`);
-  if (missingEvidence.length > 0) parts.push(`${missingEvidence.length} AC unchecked`);
-  const summary = parts.length > 0 ? parts.join(', ') : 'No drift detected';
-
-  return createSidecarOutput('drift', spec.id, {
-    drift_detected: driftDetected,
-    out_of_scope_files: outOfScopeFiles,
-    failing_criteria: failingCriteria,
-    missing_evidence: missingEvidence,
-    scope_creep_files: scopeCreepFiles,
-    gate_corroboration: gateCorroboration,
-    summary,
-  });
-}
-
-module.exports = { analyzeSpecDrift };

package/dist/sidecars/waiver-draft.js

@@ -1,176 +0,0 @@
-/**
- * @fileoverview Waiver Drafting Assistance Sidecar
- * Generates pre-filled waiver templates from gate failure context.
- * Reduces boilerplate for the human reviewer.
- * @author @darianrosebrook
- */
-
-const yaml = require('js-yaml');
-const { getRecurrence, GATE_CATEGORIES } = require('../gates/feedback');
-const { createSidecarOutput, createNoStateOutput } = require('./schema');
-
-// ---------------------------------------------------------------------------
-// Category → reason mapping
-// ---------------------------------------------------------------------------
-
-const CATEGORY_REASON_MAP = {
-  scope: 'third_party_constraint',
-  policy: 'infrastructure_limitation',
-  quality: 'experimental_feature',
-  architectural: 'legacy_integration',
-};
-
-// ---------------------------------------------------------------------------
-// Impact level from recurrence count
-// ---------------------------------------------------------------------------
-
-function impactFromRecurrence(count) {
-  if (count <= 1) return 'low';
-  if (count <= 3) return 'medium';
-  return 'high';
-}
-
-// ---------------------------------------------------------------------------
-// Template generation
-// ---------------------------------------------------------------------------
-
-/**
- * Pad a description to meet the 50-char minimum.
- * @param {string} desc
- * @returns {string}
- */
-function padDescription(desc) {
-  if (desc.length >= 50) return desc;
-  return desc + ' '.repeat(1) + 'This waiver allows temporary bypass while the issue is addressed.';
-}
-
-/**
- * Clamp a string to max length.
- * @param {string} str
- * @param {number} max
- * @returns {string}
- */
-function clamp(str, max) {
-  if (str.length <= max) return str;
-  return str.slice(0, max - 3) + '...';
-}
-
-/**
- * Build a waiver template for one failing gate.
- * @param {object} gate - Gate result object
- * @param {object} spec - Spec object
- * @param {object} state - Working state (for recurrence)
- * @returns {object} Draft object with gate, category, recurrence, template, yaml
- */
-function buildDraft(gate, spec, state) {
-  const gateName = gate.name;
-  const category = GATE_CATEGORIES[gateName] || 'quality';
-  const reason = CATEGORY_REASON_MAP[category] || 'other';
-
-  const recurrenceInfo = getRecurrence(gateName, state);
-  const recurrenceCount = recurrenceInfo ? recurrenceInfo.count : 0;
-  const impact = impactFromRecurrence(recurrenceCount);
-
-  const now = new Date();
-  const expiresAt = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
-
-  // Build description from gate messages
-  const specTitle = spec?.title || spec?.id || 'unknown';
-  let rawTitle = `Waive ${gateName} for ${specTitle}`;
-  // Clamp title to 10-200 chars, pad if too short
-  if (rawTitle.length < 10) {
-    rawTitle = rawTitle + ' — temporary bypass';
-  }
-  const title = clamp(rawTitle, 200);
-
-  // Build description from messages
-  const messageText = gate.messages && gate.messages.length > 0
-    ? gate.messages.join('. ')
-    : `Gate ${gateName} is failing`;
-  let description = `Gate ${gateName} is blocking: ${messageText}. This waiver allows temporary bypass while ${gateName} is addressed.`;
-  description = padDescription(description);
-  description = clamp(description, 1000);
-
-  const template = {
-    id: 'WV-XXXX',
-    title,
-    reason,
-    description,
-    gates: [gateName],
-    risk_assessment: {
-      impact_level: impact,
-      mitigation_plan: '[REQUIRED: Describe how you will address the underlying issue within the waiver period]',
-      review_required: impact === 'high' || impact === 'critical',
-    },
-    expires_at: expiresAt.toISOString(),
-    approved_by: '[REQUIRED]',
-    created_at: now.toISOString(),
-    metadata: { environment: 'development' },
-  };
-
-  const yamlStr = yaml.dump(template, { lineWidth: 120, noRefs: true });
-
-  return {
-    gate: gateName,
-    category,
-    recurrence: recurrenceCount,
-    template,
-    yaml: yamlStr,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Main entry point
-// ---------------------------------------------------------------------------
-
-/**
- * Generate waiver draft templates from gate failures.
- * @param {object|null} state - Working state
- * @param {object} [spec] - Spec object
- * @param {object} [options={}] - Options
- * @param {string} [options.gateName] - Filter to a specific gate
- * @returns {object} Sidecar envelope
- */
-function draftWaiver(state, spec, options = {}) {
-  const specId = spec?.id || 'unknown';
-
-  if (!state) {
-    return createNoStateOutput('waiver-draft', specId);
-  }
-
-  if (!state.gates || !state.gates.results) {
-    return createSidecarOutput('waiver-draft', specId, {
-      drafts: [],
-      instructions: '',
-      summary: 'No gate results available',
-    });
-  }
-
-  // Find failing gates
-  let failingGates = state.gates.results.filter(g => g.status === 'fail');
-
-  if (options.gateName) {
-    failingGates = failingGates.filter(g => g.name === options.gateName);
-  }
-
-  if (failingGates.length === 0) {
-    return createSidecarOutput('waiver-draft', specId, {
-      drafts: [],
-      instructions: '',
-      summary: 'No failing gates found',
-    });
-  }
-
-  const drafts = failingGates.map(gate => buildDraft(gate, spec, state));
-
-  const gateNames = drafts.map(d => d.gate).join(', ');
-  const summary = `${drafts.length} waiver draft${drafts.length !== 1 ? 's' : ''} generated for ${gateNames}`;
-
-  return createSidecarOutput('waiver-draft', specId, {
-    drafts,
-    instructions: 'Review and fill [REQUIRED] fields, then run: caws waivers create --file <path>',
-    summary,
-  });
-}
-
-module.exports = { draftWaiver };