agentsys 5.0.3 → 5.1.0

package/plugins/debate/lib/collectors/documentation.js

@@ -0,0 +1,219 @@
+/**
+ * Documentation Collector
+ *
+ * Analyzes documentation files: README, PLAN, CHANGELOG, etc.
+ * Extracted from drift-detect/collectors.js for shared use.
+ *
+ * @module lib/collectors/documentation
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_OPTIONS = {
+  depth: 'thorough',
+  cwd: process.cwd()
+};
+
+/**
+ * Validate file path to prevent path traversal
+ * @param {string} filePath - Path to validate
+ * @param {string} basePath - Base directory
+ * @returns {boolean} True if path is safe
+ */
+function isPathSafe(filePath, basePath) {
+  const resolved = path.resolve(basePath, filePath);
+  return resolved.startsWith(path.resolve(basePath));
+}
+
+/**
+ * Safe file read with path validation
+ * @param {string} filePath - Path to read
+ * @param {string} basePath - Base directory for validation
+ * @returns {string|null} File contents or null
+ */
+function safeReadFile(filePath, basePath) {
+  const fullPath = path.resolve(basePath, filePath);
+  if (!isPathSafe(filePath, basePath)) {
+    return null;
+  }
+  try {
+    return fs.readFileSync(fullPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Analyze a single markdown file
+ */
+function analyzeMarkdownFile(content, filePath) {
+  const sectionMatches = content.match(/^##\s+(.+)$/gm) || [];
+  const sections = sectionMatches.slice(0, 10).map(s => s.replace(/^##\s+/, ''));
+  const sectionLower = sections.map(s => s.toLowerCase()).join(' ');
+
+  return {
+    path: filePath,
+    sectionCount: sectionMatches.length,
+    sections,
+    hasInstallation: /install|setup|getting.started/i.test(sectionLower),
+    hasUsage: /usage|how.to|example/i.test(sectionLower),
+    hasApi: /api|reference|methods/i.test(sectionLower),
+    hasTesting: /test|spec|coverage/i.test(sectionLower),
+    codeBlocks: Math.floor((content.match(/```/g) || []).length / 2),
+    wordCount: content.split(/\s+/).length
+  };
+}
+
+/**
+ * Extract checkboxes from content
+ */
+function extractCheckboxes(result, content) {
+  const checked = (content.match(/^[-*]\s+\[x\]/gim) || []).length;
+  const unchecked = (content.match(/^[-*]\s+\[\s\]/gim) || []).length;
+
+  result.checkboxes.checked += checked;
+  result.checkboxes.unchecked += unchecked;
+  result.checkboxes.total += checked + unchecked;
+}
+
+/**
+ * Extract documented features
+ */
+function extractFeatures(result, content) {
+  const featurePattern = /^[-*]\s+\*{0,2}(.+?)\*{0,2}(?:\s*[-–]\s*(.+))?$/gm;
+  let match;
+
+  while ((match = featurePattern.exec(content)) !== null && result.features.length < 20) {
+    const feature = match[1].trim();
+    if (feature.length > 5 && feature.length < 80) {
+      result.features.push(feature);
+    }
+  }
+
+  result.features = [...new Set(result.features)].slice(0, 20);
+}
+
+/**
+ * Extract planned items from content
+ */
+function extractPlans(result, content) {
+  const planPatterns = [
+    /(?:TODO|FIXME|PLAN):\s*(.+)/gi,
+    /^##\s+(?:Roadmap|Future|Planned|Coming Soon)/gim
+  ];
+
+  for (const pattern of planPatterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null && result.plans.length < 15) {
+      const plan = (match[1] || match[0]).slice(0, 100);
+      result.plans.push(plan);
+    }
+  }
+}
+
+/**
+ * Identify documentation gaps
+ */
+function identifyDocGaps(result) {
+  const readme = result.files['README.md'];
+
+  if (!readme) {
+    result.gaps.push({ type: 'missing', file: 'README.md', severity: 'high' });
+  } else {
+    if (!readme.hasInstallation) {
+      result.gaps.push({ type: 'missing-section', file: 'README.md', section: 'Installation', severity: 'medium' });
+    }
+    if (!readme.hasUsage) {
+      result.gaps.push({ type: 'missing-section', file: 'README.md', section: 'Usage', severity: 'medium' });
+    }
+  }
+
+  if (!result.files['CHANGELOG.md']) {
+    result.gaps.push({ type: 'missing', file: 'CHANGELOG.md', severity: 'low' });
+  }
+}
+
+/**
+ * Analyze documentation files
+ * @param {Object} options - Collection options
+ * @returns {Object} Documentation analysis
+ */
+function analyzeDocumentation(options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const basePath = opts.cwd;
+
+  const result = {
+    summary: { fileCount: 0, totalWords: 0 },
+    files: {},
+    features: [],
+    plans: [],
+    checkboxes: { total: 0, checked: 0, unchecked: 0 },
+    gaps: []
+  };
+
+  const docFiles = [
+    'README.md',
+    'PLAN.md',
+    'CLAUDE.md',
+    'AGENTS.md',
+    'CONTRIBUTING.md',
+    'CHANGELOG.md',
+    'docs/README.md',
+    'docs/PLAN.md'
+  ];
+
+  for (const file of docFiles) {
+    const content = safeReadFile(file, basePath);
+    if (content) {
+      const analysis = analyzeMarkdownFile(content, file);
+      result.files[file] = analysis;
+      result.summary.totalWords += analysis.wordCount;
+      extractCheckboxes(result, content);
+      extractFeatures(result, content);
+      extractPlans(result, content);
+    }
+  }
+
+  // Find additional markdown files if depth is thorough
+  if (opts.depth === 'thorough') {
+    const docsDir = path.join(basePath, 'docs');
+    if (fs.existsSync(docsDir)) {
+      try {
+        const additionalFiles = fs.readdirSync(docsDir)
+          .filter(f => f.endsWith('.md') && !docFiles.includes(`docs/${f}`));
+
+        for (const file of additionalFiles.slice(0, 5)) {
+          const filePath = `docs/${file}`;
+          const content = safeReadFile(filePath, basePath);
+          if (content) {
+            const analysis = analyzeMarkdownFile(content, filePath);
+            result.files[filePath] = analysis;
+            result.summary.totalWords += analysis.wordCount;
+          }
+        }
+      } catch {
+        // Ignore directory read errors
+      }
+    }
+  }
+
+  result.summary.fileCount = Object.keys(result.files).length;
+  identifyDocGaps(result);
+
+  return result;
+}
+
+module.exports = {
+  DEFAULT_OPTIONS,
+  analyzeDocumentation,
+  analyzeMarkdownFile,
+  safeReadFile,
+  isPathSafe,
+  extractCheckboxes,
+  extractFeatures,
+  extractPlans,
+  identifyDocGaps
+};

package/plugins/debate/lib/collectors/github.js

@@ -0,0 +1,330 @@
+/**
+ * GitHub Data Collector
+ *
+ * Collects GitHub state: issues, PRs, milestones.
+ * Extracted from drift-detect/collectors.js for shared use.
+ *
+ * @module lib/collectors/github
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+const DEFAULT_OPTIONS = {
+  issueLimit: 100,
+  prLimit: 50,
+  milestoneLimit: 100,
+  timeout: 10000,
+  cwd: process.cwd()
+};
+
+/**
+ * Execute gh CLI command safely
+ * @param {string[]} args - Command arguments
+ * @param {Object} options - Execution options
+ * @returns {Object|null} Parsed JSON result or null
+ */
+function execGh(args, options = {}) {
+  const result = execGhWithResult(args, options);
+  return result.ok ? result.data : null;
+}
+
+function execGhWithResult(args, options = {}) {
+  try {
+    const output = execFileSync('gh', args, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: options.timeout || DEFAULT_OPTIONS.timeout,
+      cwd: options.cwd || DEFAULT_OPTIONS.cwd
+    });
+
+    try {
+      return { ok: true, data: JSON.parse(output) };
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          type: 'parse',
+          message: `Failed to parse gh output as JSON: ${error.message}`,
+          raw: output.slice(0, 500)
+        }
+      };
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        type: error.killed ? 'timeout' : 'process',
+        message: error.message,
+        exitCode: error.status ?? null,
+        stderr: error.stderr ? String(error.stderr).trim() : ''
+      }
+    };
+  }
+}
+
+/**
+ * Check if gh CLI is available and authenticated
+ * @returns {boolean} True if gh is ready
+ */
+function isGhAvailable() {
+  try {
+    execFileSync('gh', ['auth', 'status'], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 5000
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Summarize an issue for analysis
+ * @param {Object} item - Issue object
+ * @returns {Object} Summarized item
+ */
+function summarizeIssue(item) {
+  return {
+    number: item.number,
+    title: item.title,
+    labels: (item.labels || []).map(l => l.name || l),
+    milestone: item.milestone?.title || item.milestone || null,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    snippet: item.body ? item.body.slice(0, 200).replace(/\n/g, ' ').trim() + (item.body.length > 200 ? '...' : '') : ''
+  };
+}
+
+/**
+ * Summarize a PR for analysis
+ * @param {Object} item - PR object
+ * @returns {Object} Summarized item
+ */
+function summarizePR(item) {
+  return {
+    number: item.number,
+    title: item.title,
+    labels: (item.labels || []).map(l => l.name || l),
+    isDraft: item.isDraft,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    files: item.files || [],
+    snippet: item.body ? item.body.slice(0, 150).replace(/\n/g, ' ').trim() + (item.body.length > 150 ? '...' : '') : ''
+  };
+}
+
+/**
+ * Categorize issues by labels
+ */
+function categorizeIssues(result, issues) {
+  const labelMap = {
+    bug: 'bugs',
+    'type: bug': 'bugs',
+    feature: 'features',
+    'type: feature': 'features',
+    enhancement: 'enhancements',
+    security: 'security',
+    'type: security': 'security'
+  };
+
+  const labelPatterns = Object.entries(labelMap).map(([pattern, category]) => ({
+    regex: new RegExp(`(^|[^a-z])${pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z]|$)`, 'i'),
+    category
+  }));
+
+  for (const issue of issues) {
+    const labels = (issue.labels || []).map(l => (l.name || l).toLowerCase());
+    let categorized = false;
+    const ref = { number: issue.number, title: issue.title };
+
+    for (const { regex, category } of labelPatterns) {
+      if (labels.some(l => regex.test(l))) {
+        result.categorized[category].push(ref);
+        categorized = true;
+        break;
+      }
+    }
+
+    if (!categorized) {
+      result.categorized.other.push(ref);
+    }
+  }
+}
+
+/**
+ * Find stale items
+ */
+function findStaleItems(result, items, staleDays) {
+  const staleDate = new Date();
+  staleDate.setDate(staleDate.getDate() - staleDays);
+
+  for (const item of items) {
+    const updated = new Date(item.updatedAt);
+    if (updated < staleDate) {
+      result.stale.push({
+        number: item.number,
+        title: item.title,
+        lastUpdated: item.updatedAt,
+        daysStale: Math.floor((Date.now() - updated) / (1000 * 60 * 60 * 24))
+      });
+    }
+  }
+}
+
+/**
+ * Extract common themes from issue titles
+ */
+function extractThemes(result, issues) {
+  const words = {};
+  const stopWords = new Set(['the', 'a', 'an', 'is', 'are', 'to', 'for', 'in', 'on', 'at', 'with', 'and', 'or', 'of']);
+
+  for (const issue of issues) {
+    const titleWords = (issue.title || '').toLowerCase().split(/\s+/);
+    for (const word of titleWords) {
+      if (word.length > 3 && !stopWords.has(word)) {
+        words[word] = (words[word] || 0) + 1;
+      }
+    }
+  }
+
+  result.themes = Object.entries(words)
+    .filter(([, count]) => count > 1)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([word, count]) => ({ word, count }));
+}
+
+/**
+ * Find overdue milestones
+ */
+function findOverdueMilestones(result) {
+  const now = new Date();
+  result.overdueMilestones = result.milestones.filter(m => {
+    if (!m.due_on || m.state === 'closed') return false;
+    return new Date(m.due_on) < now;
+  });
+}
+
+/**
+ * Scan GitHub state: issues, PRs, milestones
+ * @param {Object} options - Collection options
+ * @returns {Object} GitHub state data
+ */
+function scanGitHubState(options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+
+  const result = {
+    available: false,
+    partial: false,
+    errors: [],
+    summary: { issueCount: 0, prCount: 0, milestoneCount: 0 },
+    issues: [],
+    prs: [],
+    milestones: [],
+    overdueMilestones: [],
+    pagination: {
+      issues: { requestedLimit: opts.issueLimit, fetchedCount: 0, hasMore: false },
+      prs: { requestedLimit: opts.prLimit, fetchedCount: 0, hasMore: false },
+      milestones: { requestedLimit: opts.milestoneLimit, fetchedCount: 0, hasMore: false }
+    },
+    categorized: { bugs: [], features: [], security: [], enhancements: [], other: [] },
+    stale: [],
+    themes: []
+  };
+
+  if (!isGhAvailable()) {
+    result.error = 'gh CLI not available or not authenticated';
+    return result;
+  }
+
+  result.available = true;
+
+  // Fetch open issues
+  const issuesResult = execGhWithResult([
+    'issue', 'list',
+    '--state', 'open',
+    '--json', 'number,title,labels,milestone,createdAt,updatedAt,body',
+    '--limit', String(opts.issueLimit)
+  ], opts);
+
+  if (issuesResult.ok && Array.isArray(issuesResult.data)) {
+    const issues = issuesResult.data;
+    result.issues = issues.map(summarizeIssue);
+    result.summary.issueCount = issues.length;
+    result.pagination.issues.fetchedCount = issues.length;
+    result.pagination.issues.hasMore = opts.issueLimit > 0 && issues.length >= opts.issueLimit;
+    categorizeIssues(result, issues);
+    findStaleItems(result, issues, 90);
+    extractThemes(result, issues);
+  } else if (!issuesResult.ok) {
+    result.errors.push({ source: 'issues', ...issuesResult.error });
+  }
+
+  // Fetch open PRs with files changed
+  const prsResult = execGhWithResult([
+    'pr', 'list',
+    '--state', 'open',
+    '--json', 'number,title,labels,isDraft,createdAt,updatedAt,body,files',
+    '--limit', String(opts.prLimit)
+  ], opts);
+
+  if (prsResult.ok && Array.isArray(prsResult.data)) {
+    const prs = prsResult.data;
+    result.prs = prs.map(summarizePR);
+    result.summary.prCount = prs.length;
+    result.pagination.prs.fetchedCount = prs.length;
+    result.pagination.prs.hasMore = opts.prLimit > 0 && prs.length >= opts.prLimit;
+  } else if (!prsResult.ok) {
+    result.errors.push({ source: 'prs', ...prsResult.error });
+  }
+
+  // Fetch milestones
+  const milestonesResult = execGhWithResult([
+    'api', 'repos/{owner}/{repo}/milestones',
+    '--paginate',
+    '--slurp'
+  ], opts);
+
+  if (milestonesResult.ok && Array.isArray(milestonesResult.data)) {
+    const pages = milestonesResult.data;
+    const allMilestones = pages.flatMap(page => Array.isArray(page) ? page : []);
+    const mappedMilestones = allMilestones.map((milestone) => ({
+      title: milestone.title,
+      state: milestone.state,
+      due_on: milestone.due_on,
+      open_issues: milestone.open_issues,
+      closed_issues: milestone.closed_issues
+    }));
+
+    result.pagination.milestones.fetchedCount = mappedMilestones.length;
+    result.pagination.milestones.hasMore = opts.milestoneLimit > 0 && mappedMilestones.length > opts.milestoneLimit;
+    result.milestones = mappedMilestones.slice(0, opts.milestoneLimit);
+    result.summary.milestoneCount = result.milestones.length;
+    findOverdueMilestones(result);
+  } else if (!milestonesResult.ok) {
+    result.errors.push({ source: 'milestones', ...milestonesResult.error });
+  }
+
+  result.partial = result.errors.length > 0;
+  if (result.partial && !result.error) {
+    result.error = 'Partial GitHub data collected';
+  }
+
+  return result;
+}
+
+module.exports = {
+  DEFAULT_OPTIONS,
+  scanGitHubState,
+  isGhAvailable,
+  execGh,
+  summarizeIssue,
+  summarizePR,
+  categorizeIssues,
+  findStaleItems,
+  extractThemes,
+  findOverdueMilestones
+};

package/plugins/debate/lib/collectors/index.js

@@ -0,0 +1,126 @@
+/**
+ * Shared Data Collectors
+ *
+ * Composable data collection infrastructure for drift-detect, deslop, sync-docs.
+ * Follows the "JS collectors + single LLM call" pattern for token efficiency.
+ *
+ * @module lib/collectors
+ */
+
+'use strict';
+
+const github = require('./github');
+const documentation = require('./documentation');
+const codebase = require('./codebase');
+const docsPatterns = require('./docs-patterns');
+
+const DEFAULT_OPTIONS = {
+  collectors: ['github', 'docs', 'code'],
+  depth: 'thorough',
+  cwd: process.cwd()
+};
+
+/**
+ * Collect data from specified collectors
+ *
+ * @param {Object} options - Collection options
+ * @param {string[]} options.collectors - Which collectors to run: 'github', 'docs', 'code', 'docs-patterns'
+ * @param {string} options.depth - 'quick' or 'thorough'
+ * @param {string} options.cwd - Working directory
+ * @param {string[]} options.changedFiles - For docs-patterns collector
+ * @returns {Object} Collected data
+ *
+ * @example
+ * // Drift-detect uses all three
+ * const data = collect({ collectors: ['github', 'docs', 'code'] });
+ *
+ * // Deslop uses codebase only
+ * const data = collect({ collectors: ['code'] });
+ *
+ * // Sync-docs uses docs + docs-patterns
+ * const data = collect({ collectors: ['docs', 'docs-patterns'], changedFiles });
+ */
+function collect(options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const collectors = Array.isArray(opts.collectors) ? opts.collectors : DEFAULT_OPTIONS.collectors;
+
+  const data = {
+    timestamp: new Date().toISOString(),
+    options: opts,
+    github: null,
+    docs: null,
+    code: null,
+    docsPatterns: null
+  };
+
+  // Collect from each enabled collector
+  if (collectors.includes('github')) {
+    data.github = github.scanGitHubState(opts);
+  }
+
+  if (collectors.includes('docs')) {
+    data.docs = documentation.analyzeDocumentation(opts);
+  }
+
+  if (collectors.includes('code')) {
+    data.code = codebase.scanCodebase(opts);
+  }
+
+  if (collectors.includes('docs-patterns')) {
+    data.docsPatterns = docsPatterns.collect(opts);
+  }
+
+  return data;
+}
+
+/**
+ * Collect all data (backward compat with drift-detect)
+ *
+ * Supports both new 'collectors' option and legacy 'sources' option
+ */
+function collectAllData(options = {}) {
+  // Map legacy 'sources' option to 'collectors'
+  let collectors = ['github', 'docs', 'code'];
+  if (options.sources) {
+    collectors = options.sources;
+  } else if (options.collectors) {
+    collectors = options.collectors;
+  }
+
+  return collect({
+    ...options,
+    collectors
+  });
+}
+
+module.exports = {
+  // Main entry point
+  collect,
+  collectAllData,
+
+  // Individual collectors
+  github,
+  documentation,
+  codebase,
+  docsPatterns,
+
+  // Re-export commonly used functions for convenience
+  scanGitHubState: github.scanGitHubState,
+  isGhAvailable: github.isGhAvailable,
+  analyzeDocumentation: documentation.analyzeDocumentation,
+  scanCodebase: codebase.scanCodebase,
+  findRelatedDocs: docsPatterns.findRelatedDocs,
+  analyzeDocIssues: docsPatterns.analyzeDocIssues,
+  checkChangelog: docsPatterns.checkChangelog,
+
+  // New: repo-map integration exports
+  ensureRepoMap: docsPatterns.ensureRepoMap,
+  ensureRepoMapSync: docsPatterns.ensureRepoMapSync,
+  getExportsFromRepoMap: docsPatterns.getExportsFromRepoMap,
+  findUndocumentedExports: docsPatterns.findUndocumentedExports,
+  isInternalExport: docsPatterns.isInternalExport,
+  isEntryPoint: docsPatterns.isEntryPoint,
+
+  // Constants
+  DEFAULT_OPTIONS
+};

package/plugins/debate/lib/config/index.js

@@ -0,0 +1,14 @@
+/**
+ * Configuration Module
+ *
+ * Placeholder for future configuration management.
+ * This module exists to satisfy lib/index.js imports.
+ *
+ * @module config
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+module.exports = {
+  // Configuration will be added as needed
+};