skill-check 0.1.0

package/dist/core/fix.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import YAML from 'yaml';
+import { parseFrontmatter } from './frontmatter.js';
+const DESCRIPTION_PADDING = ' Include clear triggers, constraints, and expected outcomes.';
+const FRONTMATTER_FIXABLE_RULE_IDS = new Set([
+    'frontmatter.required',
+    'frontmatter.name_required',
+    'frontmatter.description_required',
+    'frontmatter.name_matches_directory',
+    'frontmatter.name_slug_format',
+    'frontmatter.field_order',
+    'description.use_when_phrase',
+    'description.min_recommended_length',
+]);
+const FIXABLE_RULE_IDS = new Set([
+    ...FRONTMATTER_FIXABLE_RULE_IDS,
+    'file.trailing_newline_single',
+]);
+function normalizeTrailingNewline(content) {
+    const withoutTrailingBreaks = content.replace(/(?:\r?\n)+$/u, '');
+    const lineEnding = content.includes('\r\n') ? '\r\n' : '\n';
+    return `${withoutTrailingBreaks}${lineEnding}`;
+}
+function ensureUseWhenPhrase(description) {
+    const trimmed = description.trim();
+    if (!trimmed)
+        return trimmed;
+    if (/\buse\s+when\b/i.test(trimmed))
+        return trimmed;
+    const first = trimmed[0];
+    if (!first)
+        return `Use when ${trimmed}`;
+    return `Use when ${first.toLowerCase()}${trimmed.slice(1)}`;
+}
+function ensureMinDescriptionLength(description, minLength) {
+    let value = description.trim();
+    while (value.length < minLength) {
+        value = `${value}${DESCRIPTION_PADDING}`;
+    }
+    return value;
+}
+function defaultDescription(slug) {
+    return `Use when ${slug} should be selected for a task based on explicit user intent and clear context.`;
+}
+function orderFrontmatter(frontmatter) {
+    const ordered = {};
+    if (Object.hasOwn(frontmatter, 'name')) {
+        ordered.name = frontmatter.name;
+    }
+    if (Object.hasOwn(frontmatter, 'description')) {
+        ordered.description = frontmatter.description;
+    }
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key === 'name' || key === 'description')
+            continue;
+        ordered[key] = value;
+    }
+    return ordered;
+}
+function renderFrontmatterContent(frontmatter, body, lineEnding) {
+    const yamlBlock = YAML.stringify(frontmatter)
+        .trimEnd()
+        .replace(/\n/g, lineEnding);
+    const normalizedBody = body.length > 0 && !body.startsWith('\n') && !body.startsWith('\r\n')
+        ? `${lineEnding}${body}`
+        : body;
+    return `---${lineEnding}${yamlBlock}${lineEnding}---${lineEnding}${normalizedBody}`;
+}
+export function isFixableRuleId(ruleId) {
+    return FIXABLE_RULE_IDS.has(ruleId);
+}
+function applyFixesForSkill(skill, ruleIds, minDescriptionChars) {
+    if (ruleIds.size === 0)
+        return [];
+    let content = fs.readFileSync(skill.filePath, 'utf8');
+    const lineEnding = content.includes('\r\n') ? '\r\n' : '\n';
+    const appliedRuleIds = new Set();
+    const needsFrontmatterFix = Array.from(ruleIds).some((ruleId) => FRONTMATTER_FIXABLE_RULE_IDS.has(ruleId));
+    if (needsFrontmatterFix) {
+        const parsed = parseFrontmatter(content);
+        const hasValidFrontmatter = Boolean(parsed.frontmatter);
+        const frontmatter = parsed.frontmatter ? { ...parsed.frontmatter } : {};
+        const body = parsed.body;
+        if (ruleIds.has('frontmatter.required') ||
+            ruleIds.has('frontmatter.name_required') ||
+            ruleIds.has('frontmatter.name_matches_directory') ||
+            ruleIds.has('frontmatter.name_slug_format') ||
+            (!hasValidFrontmatter && !frontmatter.name)) {
+            frontmatter.name = skill.slug;
+        }
+        const shouldEnsureDescription = ruleIds.has('frontmatter.required') ||
+            ruleIds.has('frontmatter.description_required') ||
+            ruleIds.has('description.use_when_phrase') ||
+            ruleIds.has('description.min_recommended_length') ||
+            !frontmatter.description;
+        if (shouldEnsureDescription) {
+            let description = typeof frontmatter.description === 'string'
+                ? frontmatter.description.trim()
+                : '';
+            if (!description) {
+                description = defaultDescription(skill.slug);
+            }
+            if (ruleIds.has('description.use_when_phrase')) {
+                description = ensureUseWhenPhrase(description);
+            }
+            if (ruleIds.has('description.min_recommended_length')) {
+                description = ensureMinDescriptionLength(description, minDescriptionChars);
+            }
+            frontmatter.description = description;
+        }
+        const orderedFrontmatter = orderFrontmatter(frontmatter);
+        const rewritten = renderFrontmatterContent(orderedFrontmatter, body, lineEnding);
+        if (rewritten !== content) {
+            content = rewritten;
+            for (const ruleId of ruleIds) {
+                if (FRONTMATTER_FIXABLE_RULE_IDS.has(ruleId)) {
+                    appliedRuleIds.add(ruleId);
+                }
+            }
+        }
+    }
+    if (ruleIds.has('file.trailing_newline_single')) {
+        const normalized = normalizeTrailingNewline(content);
+        if (normalized !== content) {
+            content = normalized;
+            appliedRuleIds.add('file.trailing_newline_single');
+        }
+    }
+    if (appliedRuleIds.size > 0) {
+        fs.writeFileSync(skill.filePath, content, 'utf8');
+    }
+    return Array.from(appliedRuleIds);
+}
+export function applyAutoFixes(result) {
+    const rulesByFile = new Map();
+    const skillByRelativePath = new Map(result.skills.map((skill) => [skill.relativePath, skill]));
+    let supportedDiagnostics = 0;
+    let unsupportedDiagnostics = 0;
+    for (const diagnostic of result.diagnostics) {
+        if (!isFixableRuleId(diagnostic.ruleId)) {
+            unsupportedDiagnostics += 1;
+            continue;
+        }
+        supportedDiagnostics += 1;
+        const skill = skillByRelativePath.get(diagnostic.file);
+        if (!skill)
+            continue;
+        const existing = rulesByFile.get(diagnostic.file) ?? new Set();
+        existing.add(diagnostic.ruleId);
+        rulesByFile.set(diagnostic.file, existing);
+    }
+    let appliedFixes = 0;
+    const updatedFiles = [];
+    for (const [relativePath, ruleIds] of rulesByFile) {
+        const skill = skillByRelativePath.get(relativePath);
+        if (!skill)
+            continue;
+        const applied = applyFixesForSkill(skill, ruleIds, result.config.limits.minDescriptionChars);
+        if (applied.length === 0)
+            continue;
+        appliedFixes += applied.length;
+        updatedFiles.push(relativePath);
+    }
+    return {
+        requestedDiagnostics: result.diagnostics.length,
+        supportedDiagnostics,
+        unsupportedDiagnostics,
+        appliedFixes,
+        filesUpdated: updatedFiles.length,
+        updatedFiles,
+    };
+}

package/dist/core/formatters.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisResult } from '../types.js';
+import type { SkillScore } from './quality-score.js';
+export declare function renderText(result: AnalysisResult, scores?: SkillScore[]): string;
+export declare function toJson(result: AnalysisResult): Record<string, unknown>;

package/dist/core/formatters.js

@@ -0,0 +1,182 @@
+import boxen from 'boxen';
+import Table from 'cli-table3';
+import pc from 'picocolors';
+function groupByFile(diagnostics) {
+    const grouped = new Map();
+    for (const diagnostic of diagnostics) {
+        const list = grouped.get(diagnostic.file) ?? [];
+        list.push(diagnostic);
+        grouped.set(diagnostic.file, list);
+    }
+    return grouped;
+}
+function renderDivider(char = '=') {
+    return char.repeat(72);
+}
+function renderSeverityLabel(severity) {
+    if (severity === 'error')
+        return pc.red(pc.bold('[ERROR]'));
+    return pc.yellow(pc.bold('[WARN ]'));
+}
+function renderStatusTag(summary) {
+    if (summary.errorCount > 0)
+        return pc.red(pc.bold('[FAIL]'));
+    if (summary.warningCount > 0)
+        return pc.yellow(pc.bold('[WARN]'));
+    return pc.green(pc.bold('[PASS]'));
+}
+function createAsciiTable() {
+    return new Table({
+        chars: {
+            top: '-',
+            'top-mid': '+',
+            'top-left': '+',
+            'top-right': '+',
+            bottom: '-',
+            'bottom-mid': '+',
+            'bottom-left': '+',
+            'bottom-right': '+',
+            left: '|',
+            'left-mid': '+',
+            mid: '-',
+            'mid-mid': '+',
+            right: '|',
+            'right-mid': '+',
+            middle: '|',
+        },
+        style: {
+            border: [],
+            compact: true,
+            head: [],
+        },
+        wordWrap: true,
+    });
+}
+function renderOverviewTable(result, fileCount) {
+    const status = result.summary.errorCount > 0
+        ? pc.red('FAIL')
+        : result.summary.warningCount > 0
+            ? pc.yellow('WARN')
+            : pc.green('PASS');
+    const table = createAsciiTable();
+    table.push([
+        pc.bold('Skills scanned'),
+        pc.cyan(String(result.summary.skillCount)),
+        pc.bold('Files flagged'),
+        pc.cyan(String(fileCount)),
+    ], [
+        pc.bold('Diagnostics'),
+        pc.cyan(String(result.diagnostics.length)),
+        pc.bold('Errors'),
+        pc.red(String(result.summary.errorCount)),
+    ], [
+        pc.bold('Warnings'),
+        pc.yellow(String(result.summary.warningCount)),
+        pc.bold('Status'),
+        pc.bold(status),
+    ]);
+    return table.toString();
+}
+function renderSummaryPanel(result) {
+    const status = result.summary.errorCount > 0
+        ? pc.red(pc.bold('FAIL'))
+        : result.summary.warningCount > 0
+            ? pc.yellow(pc.bold('WARN'))
+            : pc.green(pc.bold('PASS'));
+    return boxen([
+        `${pc.bold('Status')}    ${status}`,
+        `${pc.bold('Skills')}    ${pc.cyan(String(result.summary.skillCount))}`,
+        `${pc.bold('Errors')}    ${pc.red(String(result.summary.errorCount))}`,
+        `${pc.bold('Warnings')}  ${pc.yellow(String(result.summary.warningCount))}`,
+    ].join('\n'), {
+        borderColor: result.summary.errorCount > 0
+            ? 'red'
+            : result.summary.warningCount > 0
+                ? 'yellow'
+                : 'green',
+        borderStyle: 'classic',
+        padding: {
+            top: 0,
+            right: 1,
+            bottom: 0,
+            left: 1,
+        },
+    });
+}
+function renderScoreBar(score) {
+    const color = score >= 80 ? pc.green : score >= 50 ? pc.yellow : pc.red;
+    const filled = Math.round(score / 5);
+    const empty = 20 - filled;
+    return `${color('█'.repeat(filled))}${pc.dim('░'.repeat(empty))} ${color(String(score))}`;
+}
+export function renderText(result, scores) {
+    const lines = [];
+    const grouped = groupByFile(result.diagnostics);
+    const status = renderStatusTag(result.summary);
+    lines.push(pc.dim(renderDivider('=')));
+    lines.push(`${pc.bold('SKILL-CHECK VALIDATION REPORT')} ${status}`);
+    lines.push(pc.dim(renderDivider('=')));
+    lines.push(pc.bold('Overview'));
+    lines.push(pc.dim(renderDivider('-')));
+    lines.push(renderOverviewTable(result, grouped.size));
+    lines.push('');
+    if (grouped.size === 0) {
+        lines.push(pc.bold('Results'));
+        lines.push(pc.dim(renderDivider('-')));
+        lines.push(`${pc.green('[OK]')} No diagnostics found.`);
+        lines.push('');
+    }
+    else {
+        lines.push(pc.bold('Results'));
+        lines.push(pc.dim(renderDivider('-')));
+        const sortedFiles = Array.from(grouped.keys()).sort();
+        for (const file of sortedFiles) {
+            const diagnostics = grouped.get(file);
+            if (!diagnostics)
+                continue;
+            lines.push(`${pc.bold('[FILE]')} ${pc.bold(file)}`);
+            lines.push(`  ${pc.dim(`diagnostics: ${diagnostics.length}`)}`);
+            lines.push('');
+            for (const diagnostic of diagnostics) {
+                const location = `${diagnostic.line}:${diagnostic.column}`;
+                lines.push(`  ${renderSeverityLabel(diagnostic.severity)} ${pc.cyan(diagnostic.ruleId)} ${pc.dim(`at ${location}`)}`);
+                lines.push(`    message    : ${diagnostic.message}`);
+                if (diagnostic.suggestion) {
+                    lines.push(`    suggestion : ${pc.yellow(diagnostic.suggestion)}`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    if (scores && scores.length > 0) {
+        lines.push(pc.bold('Quality Scores'));
+        lines.push(pc.dim(renderDivider('-')));
+        for (const s of scores) {
+            lines.push(`  ${renderScoreBar(s.score)} ${pc.dim(s.relativePath)}`);
+        }
+        lines.push('');
+    }
+    lines.push(pc.dim(renderDivider('-')));
+    lines.push(renderSummaryPanel(result));
+    lines.push('');
+    const statusWord = result.summary.errorCount > 0
+        ? pc.red('FAIL')
+        : result.summary.warningCount > 0
+            ? pc.yellow('WARN')
+            : pc.green('PASS');
+    lines.push(`Summary: skills=${pc.cyan(String(result.summary.skillCount))} errors=${pc.red(String(result.summary.errorCount))} warnings=${pc.yellow(String(result.summary.warningCount))} status=${statusWord}`);
+    lines.push(pc.dim(renderDivider('-')));
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+export function toJson(result) {
+    return {
+        summary: result.summary,
+        diagnostics: result.diagnostics,
+        metadata: {
+            roots: result.config.roots,
+            include: result.config.include,
+            exclude: result.config.exclude,
+            format: result.config.output.format,
+        },
+    };
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,7 @@
+export interface FrontmatterParseResult {
+    frontmatter: Record<string, unknown> | null;
+    frontmatterRaw: string | null;
+    body: string;
+    error?: string;
+}
+export declare function parseFrontmatter(content: string): FrontmatterParseResult;

package/dist/core/frontmatter.js

@@ -0,0 +1,39 @@
+import YAML from 'yaml';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+export function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_RE);
+    if (!match) {
+        return {
+            frontmatter: null,
+            frontmatterRaw: null,
+            body: content,
+        };
+    }
+    const raw = match[1];
+    const body = content.slice(match[0].length);
+    try {
+        const parsed = YAML.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                frontmatter: null,
+                frontmatterRaw: raw,
+                body,
+                error: 'frontmatter must be a YAML object',
+            };
+        }
+        return {
+            frontmatter: parsed,
+            frontmatterRaw: raw,
+            body,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            frontmatter: null,
+            frontmatterRaw: raw,
+            body,
+            error: `invalid YAML frontmatter: ${message}`,
+        };
+    }
+}

package/dist/core/github-formatter.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult } from '../types.js';
+export declare function toGitHubAnnotations(result: AnalysisResult): string;

package/dist/core/github-formatter.js

@@ -0,0 +1,10 @@
+export function toGitHubAnnotations(result) {
+    const lines = [];
+    for (const d of result.diagnostics) {
+        const level = d.severity === 'error' ? 'error' : 'warning';
+        const title = d.ruleId;
+        const msg = d.suggestion ? `${d.message} (${d.suggestion})` : d.message;
+        lines.push(`::${level} file=${d.file},line=${d.line},col=${d.column},title=${title}::${msg}`);
+    }
+    return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}

package/dist/core/html-report.d.ts

@@ -0,0 +1,3 @@
+import type { AnalysisResult } from '../types.js';
+import type { SkillScore } from './quality-score.js';
+export declare function renderHtml(result: AnalysisResult, scores?: SkillScore[]): string;