@luquimbo/bi-superpowers 1.0.0

package/bin/commands/lint.js

@@ -0,0 +1,419 @@
+/**
+ * Lint Command (checkup)
+ * ======================
+ * Validates skill files for proper structure and format.
+ *
+ * Usage:
+ *   super checkup                Lint all skills
+ *   super checkup dax.md         Lint specific skill
+ *   super checkup --fix          Auto-fix issues (where possible)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tui = require('../utils/tui');
+
+// Lint rules configuration
+const RULES = {
+  // Required sections
+  requiredSections: {
+    enabled: true,
+    severity: 'error',
+    sections: ['Trigger', 'Identity', 'MANDATORY RULES'],
+  },
+
+  // Trigger section validation
+  triggerFormat: {
+    enabled: true,
+    severity: 'warning',
+    description: 'Trigger section should have bullet points with quoted phrases',
+  },
+
+  // Title validation
+  hasTitle: {
+    enabled: true,
+    severity: 'error',
+    description: 'Skill must have an H1 title',
+  },
+
+  // Code block validation
+  codeBlocks: {
+    enabled: true,
+    severity: 'warning',
+    description: 'Code blocks should have language specified',
+  },
+
+  // Link validation
+  brokenLinks: {
+    enabled: true,
+    severity: 'warning',
+    description: 'Internal links should point to existing files',
+  },
+
+  // Maximum file size
+  maxSize: {
+    enabled: true,
+    severity: 'warning',
+    maxBytes: 50000, // 50KB
+  },
+
+  // Naming convention
+  naming: {
+    enabled: true,
+    severity: 'error',
+    pattern: /^[a-z0-9-]+\.md$/,
+    description: 'Skill files should be lowercase-kebab-case.md',
+  },
+};
+
+/**
+ * Lint a single skill file
+ * @param {string} filePath - Path to skill file
+ * @returns {Object} Lint result with errors and warnings
+ */
+function lintFile(filePath) {
+  const result = {
+    file: path.basename(filePath),
+    path: filePath,
+    errors: [],
+    warnings: [],
+  };
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    result.errors.push({ rule: 'file-read', message: `Cannot read file: ${e.message}` });
+    return result;
+  }
+
+  const lines = content.split('\n');
+  const filename = path.basename(filePath);
+
+  // Rule: File naming convention
+  if (RULES.naming.enabled && !RULES.naming.pattern.test(filename)) {
+    addIssue(
+      result,
+      'naming',
+      RULES.naming.severity,
+      `File name "${filename}" should be lowercase-kebab-case.md`
+    );
+  }
+
+  // Rule: Max file size
+  if (RULES.maxSize.enabled) {
+    const stats = fs.statSync(filePath);
+    if (stats.size > RULES.maxSize.maxBytes) {
+      addIssue(
+        result,
+        'maxSize',
+        RULES.maxSize.severity,
+        `File size (${(stats.size / 1024).toFixed(1)}KB) exceeds ${RULES.maxSize.maxBytes / 1024}KB limit`
+      );
+    }
+  }
+
+  // Rule: Has H1 title
+  if (RULES.hasTitle.enabled) {
+    const hasH1 = lines.some((line) => /^#\s+.+/.test(line));
+    if (!hasH1) {
+      addIssue(
+        result,
+        'hasTitle',
+        RULES.hasTitle.severity,
+        'Missing H1 title (should start with "# Title")'
+      );
+    }
+  }
+
+  // Rule: Required sections
+  if (RULES.requiredSections.enabled) {
+    RULES.requiredSections.sections.forEach((section) => {
+      const sectionPattern = new RegExp(`^##\\s+${section}`, 'mi');
+      if (!sectionPattern.test(content)) {
+        addIssue(
+          result,
+          'requiredSections',
+          RULES.requiredSections.severity,
+          `Missing required section: "## ${section}"`
+        );
+      }
+    });
+  }
+
+  // Rule: Trigger format validation
+  if (RULES.triggerFormat.enabled) {
+    const triggerSection = extractSection(content, 'Trigger');
+    if (triggerSection) {
+      const hasBullets = /[-*]\s+["'].+["']/.test(triggerSection);
+      if (!hasBullets) {
+        const lineNum = findSectionLine(lines, 'Trigger');
+        addIssue(
+          result,
+          'triggerFormat',
+          RULES.triggerFormat.severity,
+          'Trigger section should have bullet points with quoted phrases (e.g., - "keyword")',
+          lineNum
+        );
+      }
+    }
+  }
+
+  // Rule: Code blocks should have language
+  if (RULES.codeBlocks.enabled) {
+    lines.forEach((line, index) => {
+      if (line.trim() === '```') {
+        // Check if this is an opening code fence without language
+        const nextLine = lines[index + 1] || '';
+        // It's a problem if it's not a closing fence and doesn't have a language
+        if (!nextLine.trim().startsWith('```')) {
+          addIssue(
+            result,
+            'codeBlocks',
+            RULES.codeBlocks.severity,
+            'Code block missing language specifier (e.g., ```dax)',
+            index + 1
+          );
+        }
+      }
+    });
+  }
+
+  // Rule: Check internal links
+  if (RULES.brokenLinks.enabled) {
+    const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let match;
+    while ((match = linkPattern.exec(content)) !== null) {
+      const linkPath = match[2];
+      // Only check relative markdown links
+      if (linkPath.endsWith('.md') && !linkPath.startsWith('http')) {
+        const resolvedPath = path.resolve(path.dirname(filePath), linkPath);
+        if (!fs.existsSync(resolvedPath)) {
+          const lineNum = findLineWithText(lines, match[0]);
+          addIssue(
+            result,
+            'brokenLinks',
+            RULES.brokenLinks.severity,
+            `Broken internal link: ${linkPath}`,
+            lineNum
+          );
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Add an issue to the result
+ * @param {Object} result - Result object
+ * @param {string} rule - Rule name
+ * @param {string} severity - 'error' or 'warning'
+ * @param {string} message - Issue message
+ * @param {number} [line] - Line number
+ */
+function addIssue(result, rule, severity, message, line) {
+  const issue = { rule, message };
+  if (line) issue.line = line;
+
+  if (severity === 'error') {
+    result.errors.push(issue);
+  } else {
+    result.warnings.push(issue);
+  }
+}
+
+/**
+ * Extract a section from markdown content
+ * @param {string} content - Markdown content
+ * @param {string} sectionName - Section name (without ##)
+ * @returns {string|null} Section content or null
+ */
+function extractSection(content, sectionName) {
+  const pattern = new RegExp(`^##\\s+${sectionName}[\\s\\S]*?(?=^##|------|$)`, 'mi');
+  const match = content.match(pattern);
+  return match ? match[0] : null;
+}
+
+/**
+ * Find line number of a section
+ * @param {string[]} lines - Array of lines
+ * @param {string} sectionName - Section name
+ * @returns {number|null} Line number or null
+ */
+function findSectionLine(lines, sectionName) {
+  for (let i = 0; i < lines.length; i++) {
+    if (new RegExp(`^##\\s+${sectionName}`, 'i').test(lines[i])) {
+      return i + 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find line number containing text
+ * @param {string[]} lines - Array of lines
+ * @param {string} text - Text to find
+ * @returns {number|null} Line number or null
+ */
+function findLineWithText(lines, text) {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(text)) {
+      return i + 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - CLI arguments
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args) {
+  const options = {
+    files: [],
+    fix: false,
+    json: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--fix') {
+      options.fix = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (!arg.startsWith('-')) {
+      options.files.push(arg);
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Display lint summary
+ * @param {Object[]} results - Array of lint results
+ */
+function displaySummary(results) {
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0);
+  const filesWithIssues = results.filter(
+    (r) => r.errors.length > 0 || r.warnings.length > 0
+  ).length;
+
+  console.log('');
+  tui.section('Summary');
+
+  const table = tui.createTable(
+    ['Metric', 'Count'],
+    [
+      ['Files checked', results.length.toString()],
+      ['Files with issues', filesWithIssues.toString()],
+      ['Errors', tui.colors.error(totalErrors.toString())],
+      ['Warnings', tui.colors.warning(totalWarnings.toString())],
+    ]
+  );
+  console.log(table);
+
+  if (totalErrors > 0) {
+    console.log(`\n${tui.icons.error} ${tui.colors.error(`${totalErrors} error(s) found`)}`);
+  } else if (totalWarnings > 0) {
+    console.log(
+      `\n${tui.icons.warning} ${tui.colors.warning(`${totalWarnings} warning(s) found`)}`
+    );
+  } else {
+    console.log(`\n${tui.icons.success} ${tui.colors.success('All skills passed validation!')}`);
+  }
+}
+
+/**
+ * Main lint command handler
+ * @param {string[]} args - Command arguments
+ * @param {Object} config - CLI configuration with paths
+ */
+function lintCommand(args, config) {
+  const options = parseArgs(args);
+
+  // Try cache directory first, fall back to local skills
+  let skillsDir = config.skillsDir;
+  const localSkills = path.join(config.packageDir, '.agents', 'prompts', 'skills');
+
+  if (!fs.existsSync(skillsDir)) {
+    if (fs.existsSync(localSkills)) {
+      skillsDir = localSkills;
+    } else {
+      tui.error('Skills directory not found. Run "bi-superpowers unlock" first.');
+      process.exit(1);
+    }
+  }
+
+  tui.header('BI Agent Superpowers', 'Skill Linter');
+
+  // Determine which files to lint
+  let filesToLint = [];
+
+  if (options.files.length > 0) {
+    // Lint specific files
+    filesToLint = options.files
+      .map((f) => {
+        // Support both full path and just filename
+        if (fs.existsSync(f)) {
+          return f;
+        }
+        const fullPath = path.join(skillsDir, f);
+        if (fs.existsSync(fullPath)) {
+          return fullPath;
+        }
+        // Try adding .md extension
+        const withExt = path.join(skillsDir, f.endsWith('.md') ? f : `${f}.md`);
+        if (fs.existsSync(withExt)) {
+          return withExt;
+        }
+        tui.warning(`File not found: ${f}`);
+        return null;
+      })
+      .filter(Boolean);
+  } else {
+    // Lint all skills
+    filesToLint = fs
+      .readdirSync(skillsDir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => path.join(skillsDir, f));
+  }
+
+  if (filesToLint.length === 0) {
+    tui.warning('No skill files found to lint');
+    return;
+  }
+
+  tui.info(`Linting ${filesToLint.length} skill file(s)...`);
+  console.log('');
+
+  // Run linting
+  const results = filesToLint.map((file) => lintFile(file));
+
+  // Output results
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+
+  // Display individual results
+  results.forEach((result) => {
+    tui.lintResult(result);
+  });
+
+  // Display summary
+  displaySummary(results);
+
+  // Exit with error code if there are errors
+  const hasErrors = results.some((r) => r.errors.length > 0);
+  if (hasErrors) {
+    process.exit(1);
+  }
+}
+
+module.exports = lintCommand;

package/bin/commands/lint.test.js

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for the lint command (checkup)
+ *
+ * Run with: npm test
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+// Mock skill content for testing
+const validSkillContent = `# Test Skill
+
+## Trigger
+Activate this skill when user mentions:
+- "test keyword"
+- "another trigger"
+
+## Identity
+You are a **Test Expert** who helps users with testing.
+
+## MANDATORY RULES
+1. **ALWAYS TEST FIRST.** Never skip validation.
+2. **USE ASSERTIONS.** Verify expected outcomes.
+
+---
+
+## PHASE 0: Initial Assessment
+
+Start with basic questions.
+
+\`\`\`dax
+// Example DAX
+TestMeasure = SUM(Table[Column])
+\`\`\`
+`;
+
+const invalidSkillContent = `# Missing Sections
+
+This skill is missing required sections like Trigger and MANDATORY RULES.
+
+Some content here but no proper structure.
+`;
+
+describe('Lint Command', () => {
+  test('valid skill content should have required sections', () => {
+    const hasTrigger = /##\s+Trigger/i.test(validSkillContent);
+    const hasIdentity = /##\s+Identity/i.test(validSkillContent);
+    const hasMandatoryRules = /##\s+MANDATORY RULES/i.test(validSkillContent);
+
+    assert.strictEqual(hasTrigger, true, 'Should have Trigger section');
+    assert.strictEqual(hasIdentity, true, 'Should have Identity section');
+    assert.strictEqual(hasMandatoryRules, true, 'Should have MANDATORY RULES section');
+  });
+
+  test('invalid skill content should be missing required sections', () => {
+    const hasTrigger = /##\s+Trigger/i.test(invalidSkillContent);
+    const hasMandatoryRules = /##\s+MANDATORY RULES/i.test(invalidSkillContent);
+
+    assert.strictEqual(hasTrigger, false, 'Should not have Trigger section');
+    assert.strictEqual(hasMandatoryRules, false, 'Should not have MANDATORY RULES section');
+  });
+
+  test('skill should have H1 title', () => {
+    const hasH1 = /^#\s+.+/m.test(validSkillContent);
+    assert.strictEqual(hasH1, true, 'Should have H1 title');
+  });
+
+  test('code blocks should have language specifier', () => {
+    // Check for code blocks with language
+    const codeBlockWithLang = /```\w+/;
+    const hasLanguage = codeBlockWithLang.test(validSkillContent);
+    assert.strictEqual(hasLanguage, true, 'Code blocks should have language specifier');
+  });
+
+  test('trigger section should have quoted phrases', () => {
+    const triggerSection = validSkillContent.match(/##\s+Trigger[\s\S]*?(?=##|$)/i);
+    assert.ok(triggerSection, 'Should have Trigger section');
+
+    const hasQuotedPhrases = /[-*]\s+["'].+["']/.test(triggerSection[0]);
+    assert.strictEqual(hasQuotedPhrases, true, 'Trigger should have quoted phrases');
+  });
+});
+
+describe('File naming convention', () => {
+  test('kebab-case pattern should match valid names', () => {
+    const pattern = /^[a-z0-9-]+\.md$/;
+
+    assert.strictEqual(pattern.test('dax.md'), true);
+    assert.strictEqual(pattern.test('power-query.md'), true);
+    assert.strictEqual(pattern.test('data-model-design.md'), true);
+  });
+
+  test('kebab-case pattern should reject invalid names', () => {
+    const pattern = /^[a-z0-9-]+\.md$/;
+
+    assert.strictEqual(pattern.test('DAX.md'), false);
+    assert.strictEqual(pattern.test('PowerQuery.md'), false);
+    assert.strictEqual(pattern.test('my_skill.md'), false);
+    assert.strictEqual(pattern.test('skill.txt'), false);
+  });
+});