skill-check 0.1.0

package/dist/core/html-report.js

@@ -0,0 +1,320 @@
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function groupByFile(diagnostics) {
+    const grouped = new Map();
+    for (const d of diagnostics) {
+        const list = grouped.get(d.file) ?? [];
+        list.push(d);
+        grouped.set(d.file, list);
+    }
+    return grouped;
+}
+function severityClass(severity) {
+    return severity === 'error' ? 'severity-error' : 'severity-warn';
+}
+function statusClass(summary) {
+    if (summary.errorCount > 0)
+        return 'status-fail';
+    if (summary.warningCount > 0)
+        return 'status-warn';
+    return 'status-pass';
+}
+function scoreColor(score) {
+    if (score >= 80)
+        return '#16a34a';
+    if (score >= 50)
+        return '#d97706';
+    return '#dc2626';
+}
+export function renderHtml(result, scores) {
+    const grouped = groupByFile(result.diagnostics);
+    const sortedFiles = Array.from(grouped.keys()).sort();
+    const status = statusClass(result.summary);
+    const generated = new Date().toISOString();
+    const summarySection = `
+    <section class="summary" aria-label="Summary">
+      <div class="summary-grid">
+        <div class="summary-card">
+          <span class="summary-value">${result.summary.skillCount}</span>
+          <span class="summary-label">Skills</span>
+        </div>
+        <div class="summary-card">
+          <span class="summary-value severity-error">${result.summary.errorCount}</span>
+          <span class="summary-label">Errors</span>
+        </div>
+        <div class="summary-card">
+          <span class="summary-value severity-warn">${result.summary.warningCount}</span>
+          <span class="summary-label">Warnings</span>
+        </div>
+        <div class="summary-card status-badge ${status}">
+          <span class="summary-value">${result.summary.errorCount > 0 ? 'FAIL' : result.summary.warningCount > 0 ? 'WARN' : 'PASS'}</span>
+        </div>
+      </div>
+    </section>`;
+    let diagnosticsSection;
+    if (grouped.size === 0) {
+        diagnosticsSection = `
+    <section class="diagnostics" aria-label="Diagnostics">
+      <p class="no-diagnostics">No diagnostics found.</p>
+    </section>`;
+    }
+    else {
+        const fileSections = sortedFiles
+            .map((file) => {
+            const diagnostics = grouped.get(file) ?? [];
+            const rows = diagnostics
+                .map((d) => `
+            <tr class="diagnostic-row" data-search="${escapeHtml([d.ruleId, d.message, d.file, d.suggestion ?? ''].join(' ').toLowerCase())}">
+              <td class="severity ${severityClass(d.severity)}">${d.severity}</td>
+              <td class="rule-id"><code>${escapeHtml(d.ruleId)}</code></td>
+              <td class="message">${escapeHtml(d.message)}</td>
+              <td class="location">${d.line}:${d.column}</td>
+              ${d.suggestion ? `<td class="suggestion">${escapeHtml(d.suggestion)}</td>` : '<td></td>'}
+            </tr>`)
+                .join('');
+            return `
+        <details class="file-block" open>
+          <summary class="file-summary">
+            <span class="file-path">${escapeHtml(file)}</span>
+            <span class="file-count">${diagnostics.length} diagnostic(s)</span>
+          </summary>
+          <div class="table-wrap">
+            <table class="diagnostics-table">
+              <thead>
+                <tr>
+                  <th>Severity</th>
+                  <th>Rule</th>
+                  <th>Message</th>
+                  <th>Location</th>
+                  <th>Suggestion</th>
+                </tr>
+              </thead>
+              <tbody>${rows}</tbody>
+            </table>
+          </div>
+        </details>`;
+        })
+            .join('');
+        diagnosticsSection = `
+    <section class="diagnostics" aria-label="Diagnostics">
+      <div class="filter-wrap">
+        <label for="report-filter">Filter</label>
+        <input type="search" id="report-filter" placeholder="Search by rule, message, file…" autocomplete="off" />
+      </div>
+      <div class="file-blocks">${fileSections}</div>
+    </section>`;
+    }
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>skill-check Report</title>
+  <style>
+    :root {
+      --bg: #f8fafc;
+      --bg-card: #fff;
+      --text: #1e293b;
+      --text-muted: #64748b;
+      --border: #e2e8f0;
+      --error: #dc2626;
+      --warn: #d97706;
+      --pass: #16a34a;
+      --code-bg: #f1f5f9;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0f172a;
+        --bg-card: #1e293b;
+        --text: #f1f5f9;
+        --text-muted: #94a3b8;
+        --border: #334155;
+        --code-bg: #334155;
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+      line-height: 1.5;
+      color: var(--text);
+      background: var(--bg);
+      margin: 0;
+      padding: 1rem 1.5rem 2rem;
+      max-width: 1200px;
+      margin-inline: auto;
+    }
+    header {
+      margin-bottom: 1.5rem;
+    }
+    header h1 {
+      font-size: 1.5rem;
+      font-weight: 700;
+      margin: 0;
+    }
+    .summary {
+      margin-bottom: 2rem;
+    }
+    .summary-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+      gap: 1rem;
+    }
+    .summary-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1rem;
+    }
+    .summary-value {
+      display: block;
+      font-size: 1.5rem;
+      font-weight: 700;
+    }
+    .summary-value.severity-error { color: var(--error); }
+    .summary-value.severity-warn { color: var(--warn); }
+    .summary-label {
+      font-size: 0.875rem;
+      color: var(--text-muted);
+    }
+    .status-badge .summary-value {
+      font-size: 1.25rem;
+    }
+    .status-badge.status-fail .summary-value { color: var(--error); }
+    .status-badge.status-warn .summary-value { color: var(--warn); }
+    .status-badge.status-pass .summary-value { color: var(--pass); }
+    .diagnostics h2 {
+      font-size: 1.125rem;
+      margin-bottom: 0.75rem;
+    }
+    .filter-wrap {
+      margin-bottom: 1rem;
+    }
+    .filter-wrap label {
+      margin-right: 0.5rem;
+      color: var(--text-muted);
+    }
+    .filter-wrap input {
+      padding: 0.5rem 0.75rem;
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      background: var(--bg-card);
+      color: var(--text);
+      width: min(100%, 320px);
+    }
+    .file-blocks { display: flex; flex-direction: column; gap: 0.75rem; }
+    .file-block {
+      background: var(--bg-card);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      overflow: hidden;
+    }
+    .file-summary {
+      padding: 0.75rem 1rem;
+      cursor: pointer;
+      font-weight: 500;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 1rem;
+    }
+    .file-path { word-break: break-all; }
+    .file-count { font-size: 0.875rem; color: var(--text-muted); flex-shrink: 0; }
+    .table-wrap { overflow-x: auto; }
+    .diagnostics-table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 0.875rem;
+    }
+    .diagnostics-table th,
+    .diagnostics-table td {
+      padding: 0.5rem 0.75rem;
+      text-align: left;
+      border-top: 1px solid var(--border);
+    }
+    .diagnostics-table th {
+      color: var(--text-muted);
+      font-weight: 500;
+    }
+    .diagnostic-row.hidden { display: none; }
+    .severity-error { color: var(--error); font-weight: 600; }
+    .severity-warn { color: var(--warn); font-weight: 600; }
+    .rule-id code {
+      background: var(--code-bg);
+      padding: 0.2em 0.4em;
+      border-radius: 4px;
+      font-size: 0.8125rem;
+    }
+    .no-diagnostics { color: var(--text-muted); margin: 0; }
+    .scores { margin-top: 2rem; }
+    .scores h2 { font-size: 1.125rem; margin-bottom: 0.75rem; }
+    .scores-grid { display: flex; flex-direction: column; gap: 0.5rem; }
+    .score-card { display: flex; align-items: center; gap: 0.75rem; }
+    .score-bar {
+      width: 120px; height: 20px; background: var(--border); border-radius: 4px;
+      position: relative; overflow: hidden; flex-shrink: 0;
+    }
+    .score-bar::before {
+      content: ''; position: absolute; inset: 0;
+      width: var(--score-pct); background: var(--score-color);
+      border-radius: 4px; transition: width 0.3s;
+    }
+    .score-value {
+      position: relative; z-index: 1; font-size: 0.75rem; font-weight: 700;
+      color: #fff; padding-left: 6px; line-height: 20px;
+    }
+    .score-path { font-size: 0.875rem; color: var(--text-muted); word-break: break-all; }
+    footer {
+      margin-top: 2rem;
+      font-size: 0.8125rem;
+      color: var(--text-muted);
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>skill-check Report</h1>
+  </header>
+  ${summarySection}
+  ${diagnosticsSection}
+  ${scores && scores.length > 0
+        ? `
+  <section class="scores" aria-label="Quality Scores">
+    <h2>Quality Scores</h2>
+    <div class="scores-grid">${scores
+            .map((s) => `
+      <div class="score-card">
+        <div class="score-bar" style="--score-pct: ${s.score}%; --score-color: ${scoreColor(s.score)}">
+          <span class="score-value">${s.score}</span>
+        </div>
+        <span class="score-path">${escapeHtml(s.relativePath)}</span>
+      </div>`)
+            .join('')}
+    </div>
+  </section>`
+        : ''}
+  <footer>
+    Generated: ${escapeHtml(generated)}
+  </footer>
+  <script>
+    (function() {
+      var filter = document.getElementById('report-filter');
+      if (!filter) return;
+      var rows = document.querySelectorAll('.diagnostic-row');
+      filter.addEventListener('input', function() {
+        var q = this.value.trim().toLowerCase();
+        rows.forEach(function(row) {
+          var text = (row.getAttribute('data-search') || '');
+          row.classList.toggle('hidden', q && text.indexOf(q) === -1);
+        });
+      });
+    })();
+  </script>
+</body>
+</html>`;
+}

package/dist/core/interactive-fix.d.ts

@@ -0,0 +1,9 @@
+import type { AnalysisResult, Diagnostic } from '../types.js';
+import { type AutoFixSummary } from './fix.js';
+export interface InteractiveFixResult extends AutoFixSummary {
+    skippedByUser: number;
+}
+export declare function selectFixableDiagnostics(result: AnalysisResult): Promise<{
+    accepted: Diagnostic[];
+    skipped: number;
+}>;

package/dist/core/interactive-fix.js

@@ -0,0 +1,22 @@
+import { confirm as clackConfirm, isCancel } from '@clack/prompts';
+import { isFixableRuleId } from './fix.js';
+export async function selectFixableDiagnostics(result) {
+    const fixable = result.diagnostics.filter((d) => isFixableRuleId(d.ruleId));
+    const accepted = [];
+    let skipped = 0;
+    for (const d of fixable) {
+        const answer = await clackConfirm({
+            message: `Fix ${d.ruleId} in ${d.file}:${d.line} — ${d.message}?`,
+            initialValue: true,
+        });
+        if (isCancel(answer))
+            break;
+        if (answer) {
+            accepted.push(d);
+        }
+        else {
+            skipped += 1;
+        }
+    }
+    return { accepted, skipped };
+}

package/dist/core/links.d.ts

@@ -0,0 +1,17 @@
+export interface MarkdownLink {
+    rawTarget: string;
+    normalizedTarget: string;
+    index: number;
+    line: number;
+    column: number;
+}
+export declare function getLineColumn(content: string, index: number): {
+    line: number;
+    column: number;
+};
+export declare function normalizeTarget(rawTarget: string): string;
+export declare function isExternalTarget(target: string): boolean;
+export declare function isLocalResolvableTarget(target: string): boolean;
+export declare function stripQueryAndFragment(target: string): string;
+export declare function extractMarkdownLinks(content: string): MarkdownLink[];
+export declare function resolveLocalTarget(filePath: string, target: string): string;

package/dist/core/links.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+function findFenceRanges(content) {
+    const ranges = [];
+    const lines = content.split(/\r?\n/);
+    let offset = 0;
+    let activeFence = null;
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        const fenceMatch = trimmed.match(/^(```+|~~~+)/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1][0];
+            if (!activeFence) {
+                activeFence = { marker, start: offset };
+            }
+            else if (activeFence.marker === marker) {
+                ranges.push({ start: activeFence.start, end: offset + line.length });
+                activeFence = null;
+            }
+        }
+        offset += line.length + 1;
+    }
+    if (activeFence) {
+        ranges.push({ start: activeFence.start, end: content.length });
+    }
+    return ranges;
+}
+function inRanges(index, ranges) {
+    return ranges.some((range) => index >= range.start && index <= range.end);
+}
+export function getLineColumn(content, index) {
+    const prior = content.slice(0, index);
+    const lines = prior.split(/\r?\n/);
+    const line = lines.length;
+    const column = (lines[lines.length - 1] ?? '').length + 1;
+    return { line, column };
+}
+export function normalizeTarget(rawTarget) {
+    let target = rawTarget.trim();
+    if (!target)
+        return '';
+    if (target.startsWith('<') && target.endsWith('>')) {
+        target = target.slice(1, -1).trim();
+    }
+    const titled = target.match(/^(\S+)\s+["'(].*$/);
+    if (titled) {
+        target = titled[1];
+    }
+    return target.replace(/^['"]|['"]$/g, '').trim();
+}
+export function isExternalTarget(target) {
+    return /^(https?:|mailto:|tel:|data:|javascript:)/i.test(target);
+}
+export function isLocalResolvableTarget(target) {
+    if (!target)
+        return false;
+    if (target.startsWith('#'))
+        return false;
+    if (target.startsWith('/'))
+        return false;
+    if (target.includes('{') || target.includes('}'))
+        return false;
+    if (isExternalTarget(target))
+        return false;
+    return true;
+}
+export function stripQueryAndFragment(target) {
+    return target.split('#')[0].split('?')[0].trim();
+}
+export function extractMarkdownLinks(content) {
+    const links = [];
+    const ranges = findFenceRanges(content);
+    const re = /\[[^\]]*\]\(([^)]+)\)/g;
+    let match = re.exec(content);
+    while (match !== null) {
+        if (!inRanges(match.index, ranges)) {
+            const rawTarget = match[1];
+            const normalizedTarget = normalizeTarget(rawTarget);
+            const { line, column } = getLineColumn(content, match.index);
+            links.push({
+                rawTarget,
+                normalizedTarget,
+                index: match.index,
+                line,
+                column,
+            });
+        }
+        match = re.exec(content);
+    }
+    return links;
+}
+export function resolveLocalTarget(filePath, target) {
+    const clean = stripQueryAndFragment(target);
+    return path.resolve(path.dirname(filePath), clean);
+}

package/dist/core/open-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Open a URL or file path in the user's default browser.
+ * Cross-platform: macOS (open), Linux (xdg-open), Windows (start).
+ * Uses the absolute file path (not file://) so the OS opens it with the default app and avoids browser file-URL restrictions.
+ */
+export declare function openInBrowser(urlOrPath: string): void;

package/dist/core/open-browser.js

@@ -0,0 +1,20 @@
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Open a URL or file path in the user's default browser.
+ * Cross-platform: macOS (open), Linux (xdg-open), Windows (start).
+ * Uses the absolute file path (not file://) so the OS opens it with the default app and avoids browser file-URL restrictions.
+ */
+export function openInBrowser(urlOrPath) {
+    const absolutePath = urlOrPath.startsWith('file:')
+        ? fileURLToPath(urlOrPath)
+        : path.resolve(urlOrPath);
+    const command = platform() === 'win32'
+        ? `start "" "${absolutePath}"`
+        : platform() === 'darwin'
+            ? `open "${absolutePath}"`
+            : `xdg-open "${absolutePath}"`;
+    execSync(command, { stdio: 'ignore' });
+}

package/dist/core/plugins.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedConfig, RuleDefinition } from '../types.js';
+export declare function loadPluginRules(config: ResolvedConfig): Promise<RuleDefinition[]>;

package/dist/core/plugins.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CliError } from './errors.js';
+export async function loadPluginRules(config) {
+    const rules = [];
+    for (const pluginRef of config.plugins) {
+        const isPathRef = pluginRef.startsWith('.') ||
+            pluginRef.startsWith('/') ||
+            pluginRef.includes(path.sep);
+        const resolvedRef = isPathRef
+            ? path.resolve(config.cwd, pluginRef)
+            : pluginRef;
+        let plugin;
+        try {
+            const module = isPathRef
+                ? await import(pathToFileURL(resolvedRef).href)
+                : await import(resolvedRef);
+            plugin = module;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new CliError(`Failed to load plugin "${pluginRef}": ${message}`, 2);
+        }
+        if (!Array.isArray(plugin.rules)) {
+            throw new CliError(`Plugin "${pluginRef}" must export a rules array.`, 2);
+        }
+        for (const rule of plugin.rules) {
+            if (!rule || typeof rule !== 'object') {
+                throw new CliError(`Plugin "${pluginRef}" contains an invalid rule entry.`, 2);
+            }
+            if (typeof rule.id !== 'string' || !rule.id) {
+                throw new CliError(`Plugin "${pluginRef}" has a rule without a valid id.`, 2);
+            }
+            if (typeof rule.evaluate !== 'function') {
+                throw new CliError(`Plugin "${pluginRef}" rule "${rule.id}" is missing evaluate().`, 2);
+            }
+            rules.push(rule);
+        }
+    }
+    return rules;
+}

package/dist/core/quality-score.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic, SkillArtifact } from '../types.js';
+export interface SkillScore {
+    skillId: string;
+    relativePath: string;
+    score: number;
+    breakdown: {
+        frontmatter: number;
+        description: number;
+        body: number;
+        links: number;
+        file: number;
+    };
+}
+export declare function computeSkillScores(skills: SkillArtifact[], diagnostics: Diagnostic[]): SkillScore[];

package/dist/core/quality-score.js

@@ -0,0 +1,55 @@
+const CATEGORY_WEIGHTS = {
+    frontmatter: 30,
+    description: 30,
+    body: 20,
+    links: 10,
+    file: 10,
+};
+function categorize(ruleId) {
+    if (ruleId.startsWith('frontmatter.'))
+        return 'frontmatter';
+    if (ruleId.startsWith('description.'))
+        return 'description';
+    if (ruleId.startsWith('body.'))
+        return 'body';
+    if (ruleId.startsWith('links.'))
+        return 'links';
+    return 'file';
+}
+export function computeSkillScores(skills, diagnostics) {
+    const diagnosticsByFile = new Map();
+    for (const d of diagnostics) {
+        const list = diagnosticsByFile.get(d.file) ?? [];
+        list.push(d);
+        diagnosticsByFile.set(d.file, list);
+    }
+    return skills.map((skill) => {
+        const fileDiagnostics = diagnosticsByFile.get(skill.relativePath) ?? [];
+        const penalties = {
+            frontmatter: 0,
+            description: 0,
+            body: 0,
+            links: 0,
+            file: 0,
+        };
+        for (const d of fileDiagnostics) {
+            const cat = categorize(d.ruleId);
+            const penalty = d.severity === 'error' ? 1 : 0.5;
+            penalties[cat] += penalty;
+        }
+        const breakdown = {};
+        let total = 0;
+        for (const [cat, weight] of Object.entries(CATEGORY_WEIGHTS)) {
+            const key = cat;
+            const raw = Math.max(0, weight - penalties[key] * weight);
+            breakdown[key] = Math.round(raw);
+            total += breakdown[key];
+        }
+        return {
+            skillId: skill.id,
+            relativePath: skill.relativePath,
+            score: Math.min(100, Math.max(0, total)),
+            breakdown,
+        };
+    });
+}

package/dist/core/report.d.ts

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

package/dist/core/report.js

@@ -0,0 +1,26 @@
+export function renderMarkdownReport(result) {
+    const lines = [];
+    lines.push('# Skill Check Report');
+    lines.push('');
+    lines.push(`Generated: ${new Date().toISOString()}`);
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- Skills: ${result.summary.skillCount}`);
+    lines.push(`- Errors: ${result.summary.errorCount}`);
+    lines.push(`- Warnings: ${result.summary.warningCount}`);
+    lines.push('');
+    lines.push('## Diagnostics');
+    lines.push('');
+    lines.push('| File | Severity | Rule | Message |');
+    lines.push('| --- | --- | --- | --- |');
+    if (result.diagnostics.length === 0) {
+        lines.push('| - | - | - | No diagnostics found |');
+    }
+    else {
+        for (const d of result.diagnostics) {
+            lines.push(`| ${d.file}:${d.line}:${d.column} | ${d.severity} | ${d.ruleId} | ${d.message} |`);
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}

package/dist/core/rule-engine.d.ts

@@ -0,0 +1,2 @@
+import type { Diagnostic, ResolvedConfig, RuleDefinition, SkillArtifact } from '../types.js';
+export declare function runRuleEngine(skills: SkillArtifact[], rules: RuleDefinition[], config: ResolvedConfig): Promise<Diagnostic[]>;