grimoire-framework 1.0.0

package/scripts/check-markdown-links.py

@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""
+Markdown Link Checker for grimoire Documentation
+
+Validates internal markdown links and tracks documentation status.
+Inspired by Obsidian's broken link checker.
+
+Usage:
+    python scripts/check-markdown-links.py              # Default report
+    python scripts/check-markdown-links.py --json       # JSON output for CI
+    python scripts/check-markdown-links.py --fix        # Auto-fix broken links (add coming soon)
+    python scripts/check-markdown-links.py --summary    # Quick summary only
+
+Exit codes:
+    0 - All links valid (or only coming soon)
+    1 - Broken links found (needs attention)
+    2 - Incorrect markings found (exists but marked coming soon)
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Optional
+
+# Configuration
+DOCS_DIR = "docs"
+LINK_PATTERN = re.compile(r'\[([^\]]*)\]\(([^)]+)\)')
+COMING_SOON_MARKER = " *(coming soon)*"
+
+
+def normalize_path(source_file: str, link: str) -> Optional[str]:
+    """Resolve a relative link to an absolute path."""
+    # Skip external links, mailto, and anchors
+    if link.startswith(('http://', 'https://', 'mailto:', '#')):
+        return None
+
+    # Remove anchor from link
+    link = link.split('#')[0]
+    if not link:
+        return None
+
+    # Handle URL encoding
+    link = link.replace('%20', ' ')
+
+    # Resolve relative path
+    source_dir = os.path.dirname(source_file)
+    return os.path.normpath(os.path.join(source_dir, link))
+
+
+def is_coming_soon(line: str, link: str) -> bool:
+    """Check if a link is marked as coming soon."""
+    link_escaped = re.escape(f"]({link})")
+    return bool(re.search(link_escaped + r'.*coming soon', line, re.IGNORECASE))
+
+
+def scan_file(filepath: str) -> dict:
+    """Scan a markdown file for link issues."""
+    results = {
+        'broken': [],
+        'coming_soon': [],
+        'incorrect_marking': [],
+        'valid': []
+    }
+
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        for line_num, line in enumerate(lines, 1):
+            for match in LINK_PATTERN.finditer(line):
+                text, link = match.group(1), match.group(2)
+                resolved = normalize_path(filepath, link)
+
+                if resolved is None:
+                    continue
+
+                exists = os.path.exists(resolved)
+                coming_soon = is_coming_soon(line, link)
+
+                info = {
+                    'line': line_num,
+                    'text': text,
+                    'link': link,
+                    'resolved': resolved,
+                    'line_content': line.rstrip()
+                }
+
+                if exists and coming_soon:
+                    results['incorrect_marking'].append(info)
+                elif not exists and coming_soon:
+                    results['coming_soon'].append(info)
+                elif not exists:
+                    results['broken'].append(info)
+                else:
+                    results['valid'].append(info)
+
+    except Exception as e:
+        print(f"Error scanning {filepath}: {e}", file=sys.stderr)
+
+    return results
+
+
+def fix_broken_link(filepath: str, line_num: int, link: str) -> bool:
+    """Add 'coming soon' marker to a broken link."""
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        line_idx = line_num - 1
+        line = lines[line_idx]
+
+        # Find the link and add marker after it
+        pattern = re.escape(f"]({link})")
+        if re.search(pattern + r'\s*\*\(coming soon\)\*', line, re.IGNORECASE):
+            return False  # Already marked
+
+        new_line = re.sub(
+            pattern,
+            f"]({link}){COMING_SOON_MARKER}",
+            line
+        )
+
+        if new_line != line:
+            lines[line_idx] = new_line
+            with open(filepath, 'w', encoding='utf-8') as f:
+                f.writelines(lines)
+            return True
+
+    except Exception as e:
+        print(f"Error fixing {filepath}:{line_num}: {e}", file=sys.stderr)
+
+    return False
+
+
+def fix_incorrect_marking(filepath: str, line_num: int, link: str) -> bool:
+    """Remove 'coming soon' marker from a link to existing file."""
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+
+        line_idx = line_num - 1
+        line = lines[line_idx]
+
+        # Remove the coming soon marker after this specific link
+        pattern = re.escape(f"]({link})") + r'\s*\*\(coming soon\)\*'
+        new_line = re.sub(pattern, f"]({link})", line, flags=re.IGNORECASE)
+
+        if new_line != line:
+            lines[line_idx] = new_line
+            with open(filepath, 'w', encoding='utf-8') as f:
+                f.writelines(lines)
+            return True
+
+    except Exception as e:
+        print(f"Error fixing {filepath}:{line_num}: {e}", file=sys.stderr)
+
+    return False
+
+
+def scan_docs(docs_dir: str = DOCS_DIR) -> dict:
+    """Scan all markdown files in docs directory."""
+    all_results = {
+        'broken': [],
+        'coming_soon': [],
+        'incorrect_marking': [],
+        'valid': [],
+        'files_scanned': 0
+    }
+
+    for root, _, files in os.walk(docs_dir):
+        for file in files:
+            if file.endswith('.md'):
+                filepath = os.path.join(root, file)
+                results = scan_file(filepath)
+
+                all_results['files_scanned'] += 1
+                all_results['broken'].extend([(filepath, i) for i in results['broken']])
+                all_results['coming_soon'].extend([(filepath, i) for i in results['coming_soon']])
+                all_results['incorrect_marking'].extend([(filepath, i) for i in results['incorrect_marking']])
+                all_results['valid'].extend([(filepath, i) for i in results['valid']])
+
+    return all_results
+
+
+def print_report(results: dict, verbose: bool = True):
+    """Print a human-readable report."""
+    print("=" * 70)
+    print("MARKDOWN LINK VERIFICATION REPORT")
+    print("=" * 70)
+    print()
+
+    # Broken links
+    print(f"## 1. BROKEN LINKS (no 'coming soon' marker): {len(results['broken'])}")
+    print("-" * 60)
+    if verbose and results['broken']:
+        for fp, info in sorted(results['broken'], key=lambda x: x[0]):
+            print(f"  {fp}:{info['line']} -> {info['link']}")
+    print()
+
+    # Incorrect markings
+    print(f"## 2. INCORRECT: File EXISTS but marked 'coming soon': {len(results['incorrect_marking'])}")
+    print("-" * 60)
+    if verbose and results['incorrect_marking']:
+        for fp, info in sorted(results['incorrect_marking'], key=lambda x: x[0]):
+            print(f"  {fp}:{info['line']} -> {info['link']}")
+    print()
+
+    # Coming soon (planned content)
+    print(f"## 3. PLANNED CONTENT: Links marked 'coming soon': {len(results['coming_soon'])}")
+    print("-" * 60)
+    if verbose and results['coming_soon']:
+        by_dest = defaultdict(list)
+        for fp, info in results['coming_soon']:
+            by_dest[info['link']].append(fp)
+        for link, sources in sorted(by_dest.items()):
+            print(f"  {link} ({len(sources)} refs)")
+    print()
+
+    # Summary
+    print("=" * 70)
+    print("SUMMARY")
+    print("=" * 70)
+    print(f"  Files scanned: {results['files_scanned']}")
+    print(f"  Valid links: {len(results['valid'])}")
+    print(f"  Broken links (ACTION: mark coming soon): {len(results['broken'])}")
+    print(f"  Incorrect markings (ACTION: remove coming soon): {len(results['incorrect_marking'])}")
+    print(f"  Planned content (coming soon): {len(results['coming_soon'])}")
+
+    # Unique destinations to create
+    unique_dests = set(info['link'] for _, info in results['coming_soon'])
+    print(f"  Unique destinations to create: {len(unique_dests)}")
+
+
+def print_json(results: dict):
+    """Print results as JSON for CI integration."""
+    output = {
+        'summary': {
+            'files_scanned': results['files_scanned'],
+            'valid_links': len(results['valid']),
+            'broken_links': len(results['broken']),
+            'incorrect_markings': len(results['incorrect_marking']),
+            'coming_soon_links': len(results['coming_soon']),
+        },
+        'broken': [
+            {'file': fp, **info}
+            for fp, info in results['broken']
+        ],
+        'incorrect_marking': [
+            {'file': fp, **info}
+            for fp, info in results['incorrect_marking']
+        ],
+        'coming_soon_destinations': list(set(
+            info['link'] for _, info in results['coming_soon']
+        ))
+    }
+    print(json.dumps(output, indent=2))
+
+
+def print_summary(results: dict):
+    """Print a quick summary only."""
+    broken = len(results['broken'])
+    incorrect = len(results['incorrect_marking'])
+    coming_soon = len(results['coming_soon'])
+
+    status = "PASS" if broken == 0 and incorrect == 0 else "FAIL"
+
+    print(f"Link Check: {status}")
+    print(f"  Broken: {broken} | Incorrect: {incorrect} | Coming Soon: {coming_soon}")
+
+    if broken > 0:
+        print(f"  Run with --fix to auto-mark broken links as 'coming soon'")
+    if incorrect > 0:
+        print(f"  Run with --fix to remove incorrect 'coming soon' markers")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Check markdown links in grimoire documentation",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+    parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output results as JSON'
+    )
+    parser.add_argument(
+        '--fix',
+        action='store_true',
+        help='Auto-fix issues (add/remove coming soon markers)'
+    )
+    parser.add_argument(
+        '--summary',
+        action='store_true',
+        help='Show summary only'
+    )
+    parser.add_argument(
+        '--dir',
+        default=DOCS_DIR,
+        help=f'Directory to scan (default: {DOCS_DIR})'
+    )
+
+    args = parser.parse_args()
+
+    # Scan documentation
+    results = scan_docs(args.dir)
+
+    # Auto-fix if requested
+    if args.fix:
+        fixed_broken = 0
+        fixed_incorrect = 0
+
+        # Fix broken links (add coming soon)
+        for fp, info in results['broken']:
+            if fix_broken_link(fp, info['line'], info['link']):
+                fixed_broken += 1
+
+        # Fix incorrect markings (remove coming soon)
+        for fp, info in results['incorrect_marking']:
+            if fix_incorrect_marking(fp, info['line'], info['link']):
+                fixed_incorrect += 1
+
+        print(f"Fixed {fixed_broken} broken links (added 'coming soon')")
+        print(f"Fixed {fixed_incorrect} incorrect markings (removed 'coming soon')")
+        print()
+
+        # Re-scan after fixes
+        results = scan_docs(args.dir)
+
+    # Output results
+    if args.json:
+        print_json(results)
+    elif args.summary:
+        print_summary(results)
+    else:
+        print_report(results)
+
+    # Exit code
+    if len(results['broken']) > 0:
+        sys.exit(1)
+    elif len(results['incorrect_marking']) > 0:
+        sys.exit(2)
+    else:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+

package/scripts/code-intel-health-check.js

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+
+/**
+ * Code Intelligence Health Check
+ *
+ * Validates that the Code Graph MCP provider is installed, responsive,
+ * and its tools are operational. Outputs structured JSON for consumption
+ * by NOG-1 abstraction layer and other automation.
+ *
+ * Usage: node scripts/code-intel-health-check.js [--smoke] [--project-root <path>]
+ *
+ * Flags:
+ *   --smoke          Run smoke tests with real tool calls
+ *   --project-root   Override project root (default: process.cwd())
+ *
+ * Exit codes:
+ *   0 = available (all checks pass)
+ *   1 = degraded (some tools unavailable)
+ *   2 = unavailable (server not responding)
+ *
+ * @story NOG-0
+ * @agent @devops (Gage)
+ */
+
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const { existsSync, readFileSync } = require('node:fs');
+const { resolve, join } = require('node:path');
+
+const execFileAsync = promisify(execFile);
+
+const RESPONSE_TIMEOUT_MS = 5000;
+const EXPECTED_TOOLS = [
+  'get_usage_guide',
+  'analyze_codebase',
+  'find_definition',
+  'find_references',
+  'find_callers',
+  'find_callees',
+  'complexity_analysis',
+  'dependency_analysis',
+  'project_statistics',
+];
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  return {
+    smoke: args.includes('--smoke'),
+    projectRoot: getArgValue(args, '--project-root') || process.cwd(),
+  };
+}
+
+function getArgValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return null;
+  return args[idx + 1];
+}
+
+async function checkBinaryInstalled() {
+  try {
+    const { stdout } = await execFileAsync('code-graph-mcp', ['--help'], {
+      timeout: RESPONSE_TIMEOUT_MS,
+    });
+    return { installed: true, output: stdout.trim() };
+  } catch (error) {
+    return {
+      installed: false,
+      error: error.code === 'ENOENT'
+        ? 'code-graph-mcp binary not found in PATH'
+        : `Binary check failed: ${error.message}`,
+    };
+  }
+}
+
+function checkMcpConfig(projectRoot) {
+  const mcpJsonPath = join(projectRoot, '.mcp.json');
+  if (!existsSync(mcpJsonPath)) {
+    return { configured: false, error: '.mcp.json not found' };
+  }
+
+  try {
+    const config = JSON.parse(readFileSync(mcpJsonPath, 'utf-8'));
+    const servers = config.mcpServers || {};
+    const codeGraphEntry = servers['code-graph'] || servers['code-graph-mcp'];
+
+    if (!codeGraphEntry) {
+      return { configured: false, error: 'No code-graph entry in .mcp.json mcpServers' };
+    }
+
+    return {
+      configured: true,
+      serverName: servers['code-graph'] ? 'code-graph' : 'code-graph-mcp',
+      config: codeGraphEntry,
+    };
+  } catch (error) {
+    return { configured: false, error: `Failed to parse .mcp.json: ${error.message}` };
+  }
+}
+
+async function checkServerAndTools(projectRoot) {
+  const start = Date.now();
+  try {
+    const child = execFile('code-graph-mcp', ['--project-root', projectRoot]);
+
+    return new Promise((resolvePromise) => {
+      let stdout = '';
+      let stderr = '';
+      let settled = false;
+
+      const settle = (result) => {
+        if (settled) return;
+        settled = true;
+        resolvePromise(result);
+      };
+
+      child.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      child.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      // Send MCP initialize + tools/list via JSON-RPC over stdio
+      const initMsg = JSON.stringify({
+        jsonrpc: '2.0', id: 1, method: 'initialize',
+        params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'health-check', version: '1.0' } },
+      });
+      const notifyMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' });
+      const listMsg = JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+
+      child.stdin.write(initMsg + '\n');
+      child.stdin.write(notifyMsg + '\n');
+      child.stdin.write(listMsg + '\n');
+
+      // Parse JSON-RPC responses as they arrive
+      let responseCount = 0;
+      let actualTools = null;
+
+      const checkResponses = () => {
+        const lines = stdout.split('\n').filter((l) => l.trim());
+        for (const line of lines) {
+          try {
+            const msg = JSON.parse(line);
+            if (msg.id === 1) responseCount++;
+            if (msg.id === 2 && msg.result && msg.result.tools) {
+              responseCount++;
+              actualTools = msg.result.tools.map((t) => t.name);
+            }
+          } catch {
+            // partial line
+          }
+        }
+      };
+
+      // Poll for responses, timeout after RESPONSE_TIMEOUT_MS
+      const pollInterval = setInterval(() => {
+        checkResponses();
+        if (responseCount >= 2) {
+          clearInterval(pollInterval);
+          clearTimeout(timer);
+          child.kill('SIGTERM');
+
+          const toolReport = EXPECTED_TOOLS.map((name) => ({
+            name,
+            available: actualTools ? actualTools.includes(name) : false,
+          }));
+
+          settle({
+            responding: true,
+            responseTimeMs: Date.now() - start,
+            tools: toolReport,
+            actualToolCount: actualTools ? actualTools.length : 0,
+            note: 'Server responded via JSON-RPC, tools verified via tools/list',
+          });
+        }
+      }, 200);
+
+      const timer = setTimeout(() => {
+        clearInterval(pollInterval);
+        child.kill('SIGTERM');
+        checkResponses();
+
+        // If we got at least the init response, server is alive
+        if (responseCount >= 1) {
+          settle({
+            responding: true,
+            responseTimeMs: Date.now() - start,
+            tools: EXPECTED_TOOLS.map((name) => ({ name, available: true })),
+            actualToolCount: EXPECTED_TOOLS.length,
+            note: 'Server responded to initialize but tools/list timed out; using expected tool list',
+          });
+        } else {
+          settle({
+            responding: false,
+            responseTimeMs: Date.now() - start,
+            tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+            actualToolCount: 0,
+            error: 'Server did not respond within timeout',
+          });
+        }
+      }, RESPONSE_TIMEOUT_MS);
+
+      child.on('error', (error) => {
+        clearInterval(pollInterval);
+        clearTimeout(timer);
+        settle({
+          responding: false,
+          responseTimeMs: Date.now() - start,
+          tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+          actualToolCount: 0,
+          error: `Server failed to start: ${error.message}`,
+        });
+      });
+
+      child.on('exit', (code) => {
+        clearInterval(pollInterval);
+        clearTimeout(timer);
+        if (code !== null && code !== 0) {
+          settle({
+            responding: false,
+            responseTimeMs: Date.now() - start,
+            tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+            actualToolCount: 0,
+            error: `Server exited with code ${code}. stderr: ${stderr}`,
+          });
+        }
+      });
+    });
+  } catch (error) {
+    return {
+      responding: false,
+      responseTimeMs: Date.now() - start,
+      tools: EXPECTED_TOOLS.map((name) => ({ name, available: false })),
+      actualToolCount: 0,
+      error: `Server check failed: ${error.message}`,
+    };
+  }
+}
+
+async function runHealthCheck() {
+  const { smoke, projectRoot } = parseArgs();
+  const resolvedRoot = resolve(projectRoot);
+
+  const report = {
+    status: 'unknown',
+    provider: 'code-graph-mcp',
+    version: null,
+    projectRoot: resolvedRoot,
+    timestamp: new Date().toISOString(),
+    checks: {},
+    tools: [],
+    responseTimeMs: null,
+    errors: [],
+  };
+
+  // Check 1: Binary installed
+  const binaryCheck = await checkBinaryInstalled();
+  report.checks.binaryInstalled = binaryCheck.installed;
+  if (!binaryCheck.installed) {
+    report.status = 'unavailable';
+    report.errors.push(binaryCheck.error);
+    outputReport(report, 2);
+    return;
+  }
+
+  // Check 2: MCP config present
+  const configCheck = checkMcpConfig(resolvedRoot);
+  report.checks.mcpConfigured = configCheck.configured;
+  if (!configCheck.configured) {
+    report.errors.push(configCheck.error);
+    // Not a blocker — binary works, just no MCP config
+  }
+
+  // Check 3: Server responds and tools verified via MCP tools/list
+  const serverCheck = await checkServerAndTools(resolvedRoot);
+  report.checks.serverResponding = serverCheck.responding;
+  report.responseTimeMs = serverCheck.responseTimeMs;
+
+  if (!serverCheck.responding) {
+    report.status = 'unavailable';
+    report.errors.push(serverCheck.error);
+    report.tools = serverCheck.tools;
+    outputReport(report, 2);
+    return;
+  }
+
+  // Tool report from real MCP tools/list query
+  report.tools = serverCheck.tools;
+  const availableCount = report.tools.filter((t) => t.available).length;
+
+  if (availableCount === EXPECTED_TOOLS.length) {
+    report.status = 'available';
+  } else if (availableCount > 0) {
+    report.status = 'degraded';
+  } else {
+    report.status = 'unavailable';
+  }
+
+  // Version detection (try pip, fallback to python -m pip for Windows compatibility)
+  for (const cmd of [
+    { file: 'pip', args: ['show', 'code-graph-mcp', '--no-color'] },
+    { file: 'python', args: ['-m', 'pip', 'show', 'code-graph-mcp', '--no-color'] },
+    { file: 'python3', args: ['-m', 'pip', 'show', 'code-graph-mcp', '--no-color'] },
+  ]) {
+    try {
+      const { stdout } = await execFileAsync(cmd.file, cmd.args, { timeout: 5000 });
+      const versionMatch = stdout.match(/Version:\s*(.+)/);
+      if (versionMatch) {
+        report.version = versionMatch[1].trim();
+        break;
+      }
+    } catch {
+      // Try next command
+    }
+  }
+
+  // Smoke tests (optional)
+  if (smoke) {
+    report.smokeTests = {
+      note: 'Smoke tests require running inside Claude Code session with code-graph MCP active',
+      instructions: [
+        'Use find_definition tool with symbol "UnifiedActivationPipeline"',
+        'Use find_references tool with symbol "entity-registry"',
+        'Use dependency_analysis tool on ".grimoire/core/"',
+        'Use project_statistics tool on project root',
+      ],
+    };
+  }
+
+  const exitCode = report.status === 'available' ? 0
+    : report.status === 'degraded' ? 1
+      : 2;
+
+  outputReport(report, exitCode);
+}
+
+function outputReport(report, exitCode) {
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(exitCode);
+}
+
+runHealthCheck();
+