@agile-vibe-coding/avc 0.2.3 → 0.3.1

package/cli/api-reference-tool.js

@@ -0,0 +1,368 @@
+/**
+ * api-reference-tool.js
+ *
+ * Provides an OpenAI-compatible tool definition and handler that fetches
+ * real API reference documentation from the internet.  Designed to be used
+ * with local LLMs that support tool/function calling so that context writers
+ * can look up accurate payload formats, field names, and auth mechanisms
+ * instead of hallucinating them.
+ */
+
+// ---------------------------------------------------------------------------
+// Known API documentation sources
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps service names to documentation URLs.
+ * Each entry can have:
+ *   - `openapi`  — OpenAPI/Swagger spec URL (JSON or YAML)
+ *   - `docs`     — Human-readable docs index URL
+ *   - `topics`   — Map of topic keywords → specific doc URLs
+ */
+// No hardcoded URLs — all API references fetched dynamically via Context7.
+// This avoids stale/broken URLs and ensures consistent, up-to-date documentation.
+const SERVICE_REGISTRY = {};
+
+// Aliases: normalize common service name variants
+const SERVICE_ALIASES = {
+  // Twilio variants
+  'twilio-whatsapp': 'twilio',
+  'twilio-sms': 'twilio',
+  // Meta/WhatsApp variants (model uses many forms)
+  'meta': 'whatsapp',
+  'meta-cloud-api': 'whatsapp',
+  'meta cloud api': 'whatsapp',
+  'whatsapp-cloud': 'whatsapp',
+  'whatsapp-business': 'whatsapp',
+  'whatsapp cloud api': 'whatsapp',
+  'whatsapp business api': 'whatsapp',
+  // Express variants
+  'express.js': 'express',
+  'expressjs': 'express',
+  // AWS variants
+  's3': 'aws-s3',
+  'amazon-s3': 'aws-s3',
+  // React ecosystem
+  'react-query': 'tanstack-query',
+  'tanstack query': 'tanstack-query',
+  '@tanstack/react-query': 'tanstack-query',
+};
+
+// ---------------------------------------------------------------------------
+// Dynamic discovery via Context7 (Upstash)
+// ---------------------------------------------------------------------------
+
+const CONTEXT7_BASE = 'https://context7.com/api/v2';
+
+/**
+ * Fetch topic-specific documentation from Context7.
+ * Two-step: resolve library ID → fetch docs.
+ * Works without API key; optional CONTEXT7_API_KEY env var for higher rate limits.
+ * @returns {{ libraryId: string, text: string } | null}
+ */
+async function fetchFromContext7(serviceName, topic) {
+  const headers = {};
+  const apiKey = process.env.CONTEXT7_API_KEY;
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+
+  // Step 1: Resolve library ID
+  const searchUrl = `${CONTEXT7_BASE}/libs/search?query=${encodeURIComponent(serviceName)}`;
+  const searchResult = await fetchWithLimit(searchUrl, 10_000, headers);
+  if (!searchResult.ok) return null;
+
+  let libraryId;
+  try {
+    const data = JSON.parse(searchResult.body);
+    const libs = data.libraries || data;
+    if (!Array.isArray(libs) || libs.length === 0) return null;
+    // Pick highest trust match — require trust >= 5 to avoid fuzzy noise
+    // (Context7 never returns empty results; garbage queries get fuzzy matches)
+    const best = libs.sort((a, b) => (b.trust || 0) - (a.trust || 0))[0];
+    if ((best.trust || 0) < 5) return null;
+    libraryId = best.id; // format: "owner/repo" e.g. "stripe/stripe-node"
+  } catch { return null; }
+
+  // Step 2: Fetch topic-specific documentation
+  const contextUrl = `${CONTEXT7_BASE}/context?libraryId=${encodeURIComponent(libraryId)}&query=${encodeURIComponent(topic)}&type=txt&tokenLimit=5000`;
+  const contextResult = await fetchWithLimit(contextUrl, 12_000, headers);
+  if (!contextResult.ok) return null;
+
+  const text = contextResult.body?.trim();
+  if (!text || text.length < 50) return null;
+
+  return { libraryId, text };
+}
+
+// ---------------------------------------------------------------------------
+// Tool definition (OpenAI function-calling format)
+// ---------------------------------------------------------------------------
+
+export const API_REFERENCE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'fetch_api_reference',
+    description:
+      'Fetch API reference documentation for any external service or API. ' +
+      'Supports thousands of libraries and APIs — documentation is discovered automatically. ' +
+      'Use this when you need accurate payload formats, field names, authentication mechanisms, ' +
+      'endpoint signatures, or webhook specifications.',
+    parameters: {
+      type: 'object',
+      properties: {
+        service: {
+          type: 'string',
+          description:
+            'Service or API name (e.g. "twilio", "stripe", "prisma", "shopify", "express", "supabase")',
+        },
+        topic: {
+          type: 'string',
+          description:
+            'Specific topic to look up (e.g. "webhook-payload", "authentication", "send-message", "signature-verification", "rate-limit")',
+        },
+      },
+      required: ['service', 'topic'],
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Fetch helper with timeout and size limit
+// ---------------------------------------------------------------------------
+
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 512_000; // 500 KB — enough for most doc pages
+
+async function fetchWithLimit(url, timeoutMs = FETCH_TIMEOUT_MS, extraHeaders = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(url, {
+      signal: controller.signal,
+      headers: { 'Accept': 'text/html, application/json, text/plain, */*', ...extraHeaders },
+    });
+    if (!resp.ok) {
+      return { ok: false, error: `HTTP ${resp.status} ${resp.statusText}` };
+    }
+    const contentType = resp.headers.get('content-type') || '';
+    const buffer = await resp.arrayBuffer();
+    const body = new TextDecoder().decode(buffer.slice(0, MAX_BODY_BYTES));
+    return { ok: true, body, contentType, truncated: buffer.byteLength > MAX_BODY_BYTES };
+  } catch (err) {
+    return { ok: false, error: err.name === 'AbortError' ? 'Request timed out' : err.message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Content extractors
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract relevant text from an HTML page — strips tags, scripts, styles,
+ * and collapses whitespace.  Returns a readable text summary.
+ */
+function extractTextFromHTML(html, maxChars = 8000) {
+  let text = html;
+  // Remove script, style, nav, footer, header blocks
+  text = text.replace(/<(script|style|nav|footer|header|aside|svg)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ');
+  // Remove HTML comments
+  text = text.replace(/<!--[\s\S]*?-->/g, ' ');
+  // Convert common block elements to newlines
+  text = text.replace(/<\/(p|div|h[1-6]|li|tr|br|hr)\s*>/gi, '\n');
+  text = text.replace(/<(br|hr)\s*\/?>/gi, '\n');
+  // Strip remaining tags
+  text = text.replace(/<[^>]+>/g, ' ');
+  // Decode basic HTML entities
+  text = text.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ');
+  // Collapse whitespace
+  text = text.replace(/[ \t]+/g, ' ').replace(/\n[ \t]+/g, '\n').replace(/\n{3,}/g, '\n\n');
+  return text.trim().slice(0, maxChars);
+}
+
+/**
+ * Extract a relevant section from an OpenAPI spec JSON for a given topic.
+ */
+function extractFromOpenAPI(specJson, topic) {
+  const topicLower = topic.toLowerCase();
+  const lines = [];
+  const paths = specJson.paths || {};
+
+  // Find paths matching the topic keywords
+  const keywords = topicLower.split(/[-_\s]+/);
+  const matchingPaths = Object.entries(paths).filter(([pathStr]) => {
+    const pathLower = pathStr.toLowerCase();
+    return keywords.some(kw => kw.length >= 3 && pathLower.includes(kw));
+  });
+
+  // Limit to first 5 matching paths
+  for (const [pathStr, methods] of matchingPaths.slice(0, 5)) {
+    lines.push(`\n### ${pathStr}`);
+    for (const [method, spec] of Object.entries(methods)) {
+      if (typeof spec !== 'object' || !spec) continue;
+      lines.push(`**${method.toUpperCase()}** — ${spec.summary || spec.description || ''}`);
+      // Request body schema
+      const reqBody = spec.requestBody?.content;
+      if (reqBody) {
+        for (const [contentType, media] of Object.entries(reqBody)) {
+          lines.push(`- Content-Type: ${contentType}`);
+          if (media.schema?.properties) {
+            const props = Object.entries(media.schema.properties).slice(0, 15);
+            for (const [prop, propSpec] of props) {
+              const req = (media.schema.required || []).includes(prop) ? ' (required)' : '';
+              lines.push(`  - ${prop}: ${propSpec.type || 'any'}${req} — ${propSpec.description || ''}`);
+            }
+          }
+        }
+      }
+      // Response schema summary
+      const responses = spec.responses || {};
+      const successResp = responses['200'] || responses['201'] || responses['204'];
+      if (successResp) {
+        lines.push(`- Success: ${successResp.description || 'OK'}`);
+      }
+    }
+  }
+
+  if (lines.length === 0) {
+    // Fallback: show info section
+    const info = specJson.info || {};
+    return `API: ${info.title || 'Unknown'} (v${info.version || '?'})\n` +
+      `${info.description || ''}\n\n` +
+      `No paths matching topic "${topic}" found. Available paths (first 20):\n` +
+      Object.keys(paths).slice(0, 20).map(p => `- ${p}`).join('\n');
+  }
+
+  const info = specJson.info || {};
+  return `API: ${info.title || 'Unknown'} (v${info.version || '?'})\n` +
+    `Topic: ${topic}\n` +
+    lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Tool handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle a fetch_api_reference tool call.
+ * @param {{ service: string, topic: string }} args - Tool call arguments
+ * @returns {Promise<string>} The fetched API reference text
+ */
+export async function handleFetchApiReference({ service, topic }) {
+  const serviceLower = (service || '').toLowerCase().trim();
+  const topicLower = (topic || '').toLowerCase().trim();
+
+  // Resolve aliases
+  const resolvedService = SERVICE_ALIASES[serviceLower] || serviceLower;
+  const registry = SERVICE_REGISTRY[resolvedService];
+
+  // Tier 0: Curated registry (fastest, best quality for known services)
+  if (registry) {
+    // 1. Try topic-specific URL first
+    const topicUrl = findTopicUrl(registry.topics, topicLower);
+    if (topicUrl) {
+      console.log(`[DEBUG] API reference tool: fetching ${resolvedService}/${topicLower} from ${topicUrl}`);
+      const result = await fetchWithLimit(topicUrl);
+      if (result.ok) {
+        const text = extractTextFromHTML(result.body);
+        if (text.length > 100) {
+          return `## ${resolvedService} — ${topic}\nSource: ${topicUrl}\n\n${text}`;
+        }
+      } else {
+        console.log(`[DEBUG] API reference fetch failed: ${result.error}`);
+      }
+    }
+
+    // 2. Try OpenAPI spec for structured data
+    if (registry.openapi) {
+      console.log(`[DEBUG] API reference tool: fetching OpenAPI spec for ${resolvedService}`);
+      const specResult = await fetchWithLimit(registry.openapi, 20_000);
+      if (specResult.ok) {
+        try {
+          const spec = JSON.parse(specResult.body);
+          const extracted = extractFromOpenAPI(spec, topicLower);
+          if (extracted) {
+            return `## ${resolvedService} — ${topic} (from OpenAPI spec)\n\n${extracted}`;
+          }
+        } catch {
+          // Not valid JSON or truncated — fall through
+        }
+      }
+    }
+
+    // 3. Fall back to general docs page
+    if (registry.docs) {
+      console.log(`[DEBUG] API reference tool: falling back to general docs for ${resolvedService}`);
+      const docsResult = await fetchWithLimit(registry.docs);
+      if (docsResult.ok) {
+        const text = extractTextFromHTML(docsResult.body, 4000);
+        return `## ${resolvedService} — general documentation\nSource: ${registry.docs}\n\n${text}\n\n` +
+          `Note: Could not find specific docs for topic "${topic}". Above is the general API docs page.`;
+      }
+    }
+  }
+
+  // Tier 1: Dynamic discovery via Context7
+  console.log(`[DEBUG] API reference: "${service}" not in registry, trying Context7`);
+  const ctx7 = await fetchFromContext7(serviceLower, topicLower);
+  if (ctx7) {
+    return `## ${service} — ${topic} (via Context7: ${ctx7.libraryId})\n\n${ctx7.text}`;
+  }
+
+  return `Could not find API documentation for "${service}/${topic}". ` +
+    `The service may not have indexed documentation available. ` +
+    `Use your training knowledge as a fallback.`;
+}
+
+/**
+ * Find the best matching topic URL from the topics map.
+ */
+function findTopicUrl(topics, topicLower) {
+  if (!topics) return null;
+
+  // Exact match
+  if (topics[topicLower]) return topics[topicLower];
+
+  // Partial match — find topic key that shares keywords with the query
+  const queryWords = topicLower.split(/[-_\s]+/);
+  let bestMatch = null;
+  let bestOverlap = 0;
+
+  for (const [key, url] of Object.entries(topics)) {
+    const keyWords = key.split(/[-_\s]+/);
+    const overlap = queryWords.filter(w => keyWords.includes(w)).length;
+    if (overlap > bestOverlap) {
+      bestOverlap = overlap;
+      bestMatch = url;
+    }
+  }
+
+  return bestOverlap > 0 ? bestMatch : null;
+}
+
+// ---------------------------------------------------------------------------
+// Exports for provider integration
+// ---------------------------------------------------------------------------
+
+/**
+ * All tools available for context generation.
+ * Providers can pass this array in the `tools` parameter of chat completions.
+ */
+export const CONTEXT_GENERATION_TOOLS = [API_REFERENCE_TOOL];
+
+/**
+ * Dispatch a tool call by name.
+ * @param {string} name - Tool function name
+ * @param {Object} args - Tool call arguments (parsed JSON)
+ * @returns {Promise<string>} Tool result text
+ */
+export async function dispatchToolCall(name, args) {
+  if (name === 'fetch_api_reference') {
+    return handleFetchApiReference(args);
+  }
+  return `Unknown tool: ${name}`;
+}
+
+// Exported for unit testing
+export { findTopicUrl, extractFromOpenAPI, extractTextFromHTML, fetchFromContext7 };

package/cli/checks/catalog.json

@@ -0,0 +1,76 @@
+{
+  "version": "1.0.0",
+  "description": "Micro-check catalog for AVC validation system",
+  "tiers": {
+    "1": "Independent micro-checks — one YES/NO question per LLM call",
+    "2": "Cross-reference checks — validate consistency across perspectives",
+    "3": "Programmatic pattern detection — pure JS, no LLM"
+  },
+  "perspectives": [
+    "solution-architect",
+    "security",
+    "developer",
+    "devops",
+    "cloud",
+    "backend",
+    "database",
+    "api",
+    "frontend",
+    "ui",
+    "ux",
+    "mobile",
+    "data",
+    "qa",
+    "test-architect"
+  ],
+  "scopes": ["epic", "story"],
+  "checkCounts": {
+    "epic": {
+      "tier1": 157,
+      "tier2": 15,
+      "byPerspective": {
+        "solution-architect": 16,
+        "security": 15,
+        "developer": 16,
+        "devops": 14,
+        "cloud": 10,
+        "backend": 10,
+        "database": 9,
+        "api": 9,
+        "frontend": 13,
+        "ui": 8,
+        "ux": 7,
+        "mobile": 8,
+        "data": 8,
+        "qa": 7,
+        "test-architect": 7
+      }
+    },
+    "story": {
+      "tier1": 185,
+      "tier2": 13,
+      "byPerspective": {
+        "solution-architect": 19,
+        "security": 16,
+        "developer": 14,
+        "devops": 8,
+        "cloud": 8,
+        "backend": 8,
+        "database": 8,
+        "api": 15,
+        "frontend": 14,
+        "ui": 8,
+        "ux": 8,
+        "mobile": 8,
+        "data": 17,
+        "qa": 17,
+        "test-architect": 17
+      }
+    },
+    "total": {
+      "tier1": 342,
+      "tier2": 28,
+      "all": 370
+    }
+  }
+}

package/cli/checks/code/quality.json

@@ -0,0 +1,26 @@
+[
+  {
+    "id": "qual-01",
+    "severity": "major",
+    "question": "Are ALL functions 25 lines or fewer (excluding JSDoc comments and blank lines)?",
+    "evidenceGuide": "Count executable lines per function body. List any function exceeding 25 lines with its actual line count. Orchestration methods up to 50 lines are acceptable if each line is a single function call."
+  },
+  {
+    "id": "qual-02",
+    "severity": "major",
+    "question": "Are business logic functions pure (no file I/O, no network calls, no database access, no console output)?",
+    "evidenceGuide": "Check non-boundary functions for side-effect calls: fs.*, fetch, database queries, console.*. Side effects must be isolated in clearly named boundary functions (e.g., readFromDatabase, writeToFile, sendApiRequest)."
+  },
+  {
+    "id": "qual-03",
+    "severity": "minor",
+    "question": "Do function names use domain vocabulary from the documentation chain rather than generic programming terms?",
+    "evidenceGuide": "Compare function names against domain nouns and verbs found in the task's context.md and doc.md. Flag generic names like processData, handleRequest, doWork, updateDB. Prefer domain terms like bookAppointment, validateSlotAvailability, sendReminderMessage."
+  },
+  {
+    "id": "qual-04",
+    "severity": "minor",
+    "question": "Is each source file named after its primary exported function using kebab-case with the hierarchy prefix?",
+    "evidenceGuide": "Compare file names to their primary export. Expected pattern: e0001-s0002-t0003-function-name.js for export e0001_s0002_t0003_functionName."
+  }
+]

package/cli/checks/code/testing.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "test-01",
+    "severity": "critical",
+    "question": "Do all test describe blocks reference acceptance criterion IDs in the format taskId#ACn (e.g., context-0001-0002-0003#AC1)?",
+    "evidenceGuide": "Check every describe() string in test files for an AC ID reference. The format must include the full task ID and AC number. List any describe blocks without a valid reference."
+  },
+  {
+    "id": "test-02",
+    "severity": "major",
+    "question": "Is there no orphan code — does every function (exported or helper) have a @satisfies tag or belong to a module whose primary export has one?",
+    "evidenceGuide": "List any functions that cannot be traced to an acceptance criterion through either a direct @satisfies tag or membership in a file whose primary export has one."
+  }
+]

package/cli/checks/code/traceability.json

@@ -0,0 +1,26 @@
+[
+  {
+    "id": "trace-01",
+    "severity": "critical",
+    "question": "Do ALL exported functions and classes have the correct hierarchy prefix e{X}_s{Y}_t{Z}_ matching the task ID?",
+    "evidenceGuide": "Check every export statement. The prefix must match the task's position in the hierarchy: e{epicNum}_s{storyNum}_t{taskNum}_. List any exports missing or using wrong prefix."
+  },
+  {
+    "id": "trace-02",
+    "severity": "critical",
+    "question": "Does every generated file have a provenance header with @file, @story, @task, @agent, and @generated JSDoc tags?",
+    "evidenceGuide": "Check the first JSDoc comment block at the top of each file for all five required tags. List any files missing tags."
+  },
+  {
+    "id": "trace-03",
+    "severity": "critical",
+    "question": "Does every exported function have a JSDoc comment with a @satisfies tag referencing a specific acceptance criterion (e.g., context-XXXX-XXXX-XXXX#AC1)?",
+    "evidenceGuide": "Check the JSDoc block above each exported function for a @satisfies tag with a valid AC reference. List any exports without it."
+  },
+  {
+    "id": "trace-04",
+    "severity": "major",
+    "question": "Is every acceptance criterion from the task's work.json covered by at least one exported function (@satisfies) AND at least one test (describe block)?",
+    "evidenceGuide": "Cross-reference the acceptance criteria array from work.json against @satisfies tags in source files and describe() strings in test files. List any uncovered ACs."
+  }
+]