thanh-kit 2.5.0 → 2.5.2

package/templates/scripts/test_ck_help.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+Smoke/integration tests for canonical ck-help script.
+Run: python3 .claude/scripts/test_ck_help.py
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent
+    / "skills"
+    / "ck-help"
+    / "scripts"
+    / "ck-help.py"
+)
+
+passed = 0
+failed = 0
+failures = []
+
+
+def run_ck_help(args: str) -> Tuple[str, int]:
+    cmd = [sys.executable, str(SCRIPT_PATH)] + (args.split() if args else [])
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.stdout + result.stderr, result.returncode
+
+
+def count_output_markers(output: str) -> int:
+    return len([line for line in output.splitlines() if line.startswith("@CK_OUTPUT_TYPE:")])
+
+
+def test(
+    name: str,
+    args: str,
+    expect_contains: Optional[List[str]] = None,
+    expect_type: Optional[str] = None,
+    expect_marker_count: Optional[int] = 1,
+):
+    global passed, failed, failures
+    output, code = run_ck_help(args)
+    errors = []
+
+    if code != 0:
+        errors.append(f"Exit code {code} != 0")
+
+    if expect_type:
+        marker = f"@CK_OUTPUT_TYPE:{expect_type}"
+        if marker not in output:
+            errors.append(f"Missing marker: {marker}")
+
+    if expect_marker_count is not None:
+        marker_count = count_output_markers(output)
+        if marker_count != expect_marker_count:
+            errors.append(f"Expected {expect_marker_count} output marker(s), got {marker_count}")
+
+    if expect_contains:
+        lower_output = output.lower()
+        for text in expect_contains:
+            if text.lower() not in lower_output:
+                errors.append(f"Missing text: {text}")
+
+    if errors:
+        failed += 1
+        failures.append((name, args, errors, output[:500]))
+        print(f"❌ {name}")
+        for err in errors:
+            print(f"   - {err}")
+    else:
+        passed += 1
+        print(f"✅ {name}")
+
+
+def main():
+    print("=" * 60)
+    print("ck-help canonical test suite")
+    print("=" * 60)
+
+    test(
+        "overview renders",
+        "",
+        expect_type="category-guide",
+        expect_contains=["claudekit skills", "quick start", "/code-review"],
+    )
+
+    test(
+        "category query routes correctly",
+        "fix",
+        expect_type="category-guide",
+        expect_contains=["fixing issues", "/fix --parallel"],
+    )
+
+    test(
+        "multi-word task routes to recommendation",
+        "test my login",
+        expect_type="task-recommendations",
+        expect_contains=["recommended for", "/test"],
+    )
+
+    test(
+        "subcommand space syntax resolves to command details",
+        "plan archive",
+        expect_type="command-details",
+        expect_contains=["/plan archive", "usage"],
+    )
+
+    test(
+        "legacy colon syntax alias resolves to command details",
+        "plan:validate",
+        expect_type="command-details",
+        expect_contains=["/plan validate", "usage"],
+    )
+
+    test(
+        "unknown skill query falls back to search",
+        "unknown:thing",
+        expect_type="search-results",
+        expect_contains=["no skills found"],
+    )
+
+    print("=" * 60)
+    print(f"RESULT: {passed} passed, {failed} failed")
+    print("=" * 60)
+
+    if failed:
+        print("Failures:")
+        for name, args, errors, preview in failures:
+            print(f"- {name} ({args})")
+            for err in errors:
+                print(f"  - {err}")
+            print(f"  preview: {preview!r}")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/scripts/test_ck_help_integration.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Integration tests for canonical ck-help query routing."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT = (
+    Path(__file__).resolve().parent.parent
+    / "skills"
+    / "ck-help"
+    / "scripts"
+    / "ck-help.py"
+)
+
+
+def run_ck_help(query: str) -> str:
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT)] + query.split(),
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout
+
+
+def marker(output: str) -> str:
+    for line in output.splitlines():
+        if line.startswith("@CK_OUTPUT_TYPE:"):
+            return line.replace("@CK_OUTPUT_TYPE:", "", 1).strip()
+    return ""
+
+
+def assert_route(query: str, expected_marker: str, expected_snippets: list[str]) -> bool:
+    output = run_ck_help(query)
+    ok = marker(output) == expected_marker
+    for snippet in expected_snippets:
+        ok = ok and (snippet.lower() in output.lower())
+    return ok
+
+
+TESTS = [
+    ("fix login bug", "task-recommendations", ["/fix"]),
+    ("docs update", "command-details", ["/docs update"]),
+    ("plan:validate", "command-details", ["/plan validate"]),
+    ("watzup", "category-guide", ["wrap-up"]),
+]
+
+
+def main() -> int:
+    passed = 0
+    failed = 0
+
+    print("=" * 60)
+    print("ck-help integration tests")
+    print("=" * 60)
+
+    for query, expected_type, snippets in TESTS:
+        ok = assert_route(query, expected_type, snippets)
+        print(f"{'✅' if ok else '❌'} {query!r} -> {expected_type}")
+        if ok:
+            passed += 1
+        else:
+            failed += 1
+
+    print("=" * 60)
+    print(f"RESULT: {passed} passed, {failed} failed")
+    print("=" * 60)
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/scripts/validate-docs.cjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+/**
+ * Validate documentation accuracy against codebase.
+ * Detects potential hallucinations: invented APIs, broken links, missing env vars.
+ *
+ * Usage:
+ *   node .claude/scripts/validate-docs.cjs [docs-dir] [--src dir1,dir2]
+ *
+ * Checks:
+ *   1. Code references - verify `functionName()` and `ClassName` exist
+ *   2. Internal links - verify markdown links point to existing files
+ *   3. Config keys - verify ENV_VAR exist in .env.example
+ *
+ * Exit: Always 0 (non-blocking, warn-only mode)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Patterns
+const CODE_REF_PATTERN = /`([A-Za-z_][A-Za-z0-9_]*(?:\(\))?)`/g;
+const LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/g;
+const ENV_PATTERN = /`([A-Z][A-Z0-9_]{2,})`|\$([A-Z][A-Z0-9_]{2,})/g;
+
+// Common code terms to ignore (not actual code refs)
+const IGNORE_CODE_REFS = new Set([
+  'true', 'false', 'null', 'undefined', 'string', 'number', 'boolean',
+  'object', 'array', 'function', 'async', 'await', 'const', 'let', 'var',
+  'if', 'else', 'for', 'while', 'return', 'import', 'export', 'default',
+  'npm', 'npx', 'node', 'yarn', 'pnpm', 'git', 'bash', 'sh', 'zsh',
+  'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',
+  'JSON', 'XML', 'HTML', 'CSS', 'SQL', 'API', 'URL', 'URI', 'HTTP', 'HTTPS',
+  'OK', 'ERROR', 'WARNING', 'INFO', 'DEBUG', 'TRACE',
+  'README', 'LICENSE', 'CHANGELOG', 'TODO', 'FIXME', 'NOTE', 'HACK',
+  'dev', 'prod', 'test', 'staging', 'production', 'development',
+  'src', 'lib', 'dist', 'build', 'docs', 'tests', 'config',
+  'index', 'main', 'app', 'server', 'client', 'utils', 'helpers'
+]);
+
+// Common env var prefixes to ignore (not project-specific)
+const IGNORE_ENV_PREFIXES = ['NODE_', 'PATH', 'HOME', 'USER', 'SHELL', 'TERM', 'PWD', 'CI'];
+
+// Markdown template variables (not actual env vars)
+const IGNORE_ENV_VARS = new Set(['ARGUMENTS']);
+
+/**
+ * Find all markdown files in directory.
+ */
+function findMarkdownFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => path.join(dir, f));
+}
+
+/**
+ * Extract code references from markdown content.
+ */
+function extractCodeRefs(content, filepath) {
+  const refs = [];
+  let match;
+  const lines = content.split('\n');
+
+  lines.forEach((line, idx) => {
+    // Skip code blocks
+    if (line.trim().startsWith('```')) return;
+
+    while ((match = CODE_REF_PATTERN.exec(line)) !== null) {
+      const ref = match[1];
+      // Filter out common terms
+      if (IGNORE_CODE_REFS.has(ref.replace('()', '').toLowerCase())) continue;
+      // Only check function calls and PascalCase classes
+      if (ref.endsWith('()') || /^[A-Z][a-z]/.test(ref)) {
+        refs.push({ ref, file: filepath, line: idx + 1 });
+      }
+    }
+  });
+
+  return refs;
+}
+
+/**
+ * Extract internal links from markdown content.
+ */
+function extractLinks(content, filepath) {
+  const links = [];
+  let match;
+  const lines = content.split('\n');
+
+  lines.forEach((line, idx) => {
+    while ((match = LINK_PATTERN.exec(line)) !== null) {
+      const href = match[2];
+      // Skip external links and anchors
+      if (href.startsWith('http') || href.startsWith('#') || href.startsWith('mailto:')) continue;
+      links.push({ href, file: filepath, line: idx + 1, text: match[1] });
+    }
+  });
+
+  return links;
+}
+
+/**
+ * Extract env var references from markdown content.
+ */
+function extractEnvVars(content, filepath) {
+  const vars = [];
+  let match;
+  const lines = content.split('\n');
+
+  lines.forEach((line, idx) => {
+    // Skip code blocks
+    if (line.trim().startsWith('```')) return;
+
+    while ((match = ENV_PATTERN.exec(line)) !== null) {
+      const envVar = match[1] || match[2];
+      // Filter common system vars and template variables
+      if (IGNORE_ENV_PREFIXES.some(p => envVar.startsWith(p))) continue;
+      if (IGNORE_ENV_VARS.has(envVar)) continue;
+      vars.push({ envVar, file: filepath, line: idx + 1 });
+    }
+  });
+
+  return vars;
+}
+
+/**
+ * Check if code reference exists in source directories.
+ */
+function checkCodeRefExists(ref, srcDirs) {
+  const name = ref.replace('()', '');
+  const patterns = [
+    `function ${name}`,
+    `const ${name}`,
+    `class ${name}`,
+    `def ${name}`,
+    `export.*${name}`,
+    `${name}:`  // object methods
+  ];
+
+  for (const srcDir of srcDirs) {
+    if (!fs.existsSync(srcDir)) continue;
+    for (const pattern of patterns) {
+      // Use spawnSync with args array to prevent command injection
+      const result = spawnSync('grep', ['-rl', pattern, srcDir], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5000
+      });
+      if (result.status === 0 && result.stdout.trim()) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Check if internal link target exists.
+ */
+function checkLinkExists(href, sourceFile) {
+  const sourceDir = path.dirname(sourceFile);
+  const targetPath = path.resolve(sourceDir, href.split('#')[0]);
+  return fs.existsSync(targetPath);
+}
+
+/**
+ * Load env vars from .env.example.
+ */
+function loadEnvExample(projectRoot) {
+  const envPath = path.join(projectRoot, '.env.example');
+  if (!fs.existsSync(envPath)) return new Set();
+
+  const content = fs.readFileSync(envPath, 'utf8');
+  const vars = new Set();
+
+  content.split('\n').forEach(line => {
+    const match = line.match(/^([A-Z][A-Z0-9_]+)=/);
+    if (match) vars.add(match[1]);
+  });
+
+  return vars;
+}
+
+/**
+ * Run all validations and generate report.
+ */
+function validate(docsDir, srcDirs, projectRoot) {
+  const issues = {
+    codeRefs: [],
+    links: [],
+    envVars: []
+  };
+  const stats = {
+    filesChecked: 0,
+    codeRefsChecked: 0,
+    linksChecked: 0,
+    envVarsChecked: 0,
+    codeRefsValid: 0,
+    linksValid: 0,
+    envVarsValid: 0
+  };
+
+  const mdFiles = findMarkdownFiles(docsDir);
+  stats.filesChecked = mdFiles.length;
+
+  if (mdFiles.length === 0) {
+    console.log(`No markdown files found in ${docsDir}`);
+    return;
+  }
+
+  const envExample = loadEnvExample(projectRoot);
+
+  for (const filepath of mdFiles) {
+    let content;
+    try {
+      content = fs.readFileSync(filepath, 'utf8');
+    } catch (err) {
+      // File deleted during validation - skip
+      continue;
+    }
+    const relPath = path.relative(projectRoot, filepath);
+
+    // Check code references
+    const codeRefs = extractCodeRefs(content, relPath);
+    stats.codeRefsChecked += codeRefs.length;
+    for (const { ref, file, line } of codeRefs) {
+      if (checkCodeRefExists(ref, srcDirs)) {
+        stats.codeRefsValid++;
+      } else {
+        issues.codeRefs.push({ ref, file, line });
+      }
+    }
+
+    // Check internal links
+    const links = extractLinks(content, filepath);
+    stats.linksChecked += links.length;
+    for (const { href, file, line, text } of links) {
+      if (checkLinkExists(href, file)) {
+        stats.linksValid++;
+      } else {
+        issues.links.push({ href, file: relPath, line, text });
+      }
+    }
+
+    // Check env vars
+    const envVars = extractEnvVars(content, relPath);
+    stats.envVarsChecked += envVars.length;
+    for (const { envVar, file, line } of envVars) {
+      if (envExample.has(envVar)) {
+        stats.envVarsValid++;
+      } else {
+        issues.envVars.push({ envVar, file, line });
+      }
+    }
+  }
+
+  // Generate report
+  console.log('\n## Docs Validation Report\n');
+  console.log(`**Files Checked:** ${stats.filesChecked}`);
+  console.log(`**Scan Date:** ${new Date().toISOString().split('T')[0]}\n`);
+
+  const hasIssues = issues.codeRefs.length || issues.links.length || issues.envVars.length;
+
+  if (hasIssues) {
+    console.log('### Potential Issues\n');
+
+    if (issues.codeRefs.length) {
+      console.log(`⚠️ **Code References** (${issues.codeRefs.length} issues)`);
+      for (const { ref, file, line } of issues.codeRefs.slice(0, 10)) {
+        console.log(`- \`${ref}\` in ${file}:${line} - not found in codebase`);
+      }
+      if (issues.codeRefs.length > 10) {
+        console.log(`- ... and ${issues.codeRefs.length - 10} more`);
+      }
+      console.log('');
+    }
+
+    if (issues.links.length) {
+      console.log(`⚠️ **Internal Links** (${issues.links.length} issues)`);
+      for (const { href, file, line } of issues.links.slice(0, 10)) {
+        console.log(`- \`${href}\` in ${file}:${line} - file not found`);
+      }
+      if (issues.links.length > 10) {
+        console.log(`- ... and ${issues.links.length - 10} more`);
+      }
+      console.log('');
+    }
+
+    if (issues.envVars.length) {
+      console.log(`⚠️ **Config Keys** (${issues.envVars.length} issues)`);
+      for (const { envVar, file, line } of issues.envVars.slice(0, 10)) {
+        console.log(`- \`${envVar}\` in ${file}:${line} - not in .env.example`);
+      }
+      if (issues.envVars.length > 10) {
+        console.log(`- ... and ${issues.envVars.length - 10} more`);
+      }
+      console.log('');
+    }
+  }
+
+  console.log('### Verified OK\n');
+  if (stats.codeRefsValid > 0) console.log(`✅ ${stats.codeRefsValid} code references validated`);
+  if (stats.linksValid > 0) console.log(`✅ ${stats.linksValid} internal links working`);
+  if (stats.envVarsValid > 0) console.log(`✅ ${stats.envVarsValid} config keys confirmed`);
+  if (stats.codeRefsValid === 0 && stats.linksValid === 0 && stats.envVarsValid === 0) {
+    console.log('ℹ️ No validatable references found');
+  }
+  console.log('');
+}
+
+/**
+ * Parse CLI arguments.
+ */
+function parseArgs(args) {
+  const result = {
+    docsDir: 'docs',
+    srcDirs: ['src', 'lib', 'app', 'scripts', '.claude']
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--src' && args[i + 1]) {
+      result.srcDirs = args[++i].split(',');
+    } else if (!arg.startsWith('-')) {
+      result.docsDir = arg;
+    }
+  }
+
+  return result;
+}
+
+// Main
+const args = parseArgs(process.argv.slice(2));
+const projectRoot = process.cwd();
+const docsDir = path.resolve(projectRoot, args.docsDir);
+const srcDirs = args.srcDirs.map(d => path.resolve(projectRoot, d));
+
+validate(docsDir, srcDirs, projectRoot);
+
+// Always exit 0 (non-blocking)
+process.exit(0);