@jkeskikangas/skillcheck 0.1.0

package/bin/skillcheck.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../dist/cli.js";
+
+process.exit(run());

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+import type { LintResult, OutputFormat } from "./types.js";
+type ParseSuccess = {
+    paths: string[];
+    options: {
+        format: OutputFormat;
+        maxLines: number;
+        fix: boolean;
+        skillsOnly: boolean;
+        rubricsOnly: boolean;
+    };
+};
+type ParseResult = ParseSuccess | {
+    error: string;
+} | {
+    help: true;
+};
+export declare function parseCliArgs(argv: string[]): ParseResult;
+export declare function formatLintOutput(result: LintResult, format: OutputFormat, fix: boolean): string;
+export declare function run(argv?: string[]): number;
+export {};

package/dist/cli.js

@@ -0,0 +1,101 @@
+import { parseArgs } from "node:util";
+import { lint } from "./index.js";
+import { formatStylish } from "./formatters/stylish.js";
+import { formatJson } from "./formatters/json.js";
+export function parseCliArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                format: { type: "string", default: "stylish" },
+                "max-lines": { type: "string", default: "500" },
+                fix: { type: "boolean", default: false },
+                "skills-only": { type: "boolean", default: false },
+                "rubrics-only": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+            },
+        });
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    if (parsed.values.help)
+        return { help: true };
+    if (parsed.positionals.length === 0) {
+        return { error: "at least one path is required." };
+    }
+    const format = parsed.values.format;
+    if (format !== "stylish" && format !== "json") {
+        return { error: `unknown format '${format}'. Use 'stylish' or 'json'.` };
+    }
+    const maxLines = parseInt(parsed.values["max-lines"], 10);
+    if (isNaN(maxLines) || maxLines <= 0) {
+        return { error: "--max-lines must be a positive integer." };
+    }
+    return {
+        paths: parsed.positionals,
+        options: {
+            format: format,
+            maxLines,
+            fix: parsed.values.fix,
+            skillsOnly: parsed.values["skills-only"],
+            rubricsOnly: parsed.values["rubrics-only"],
+        },
+    };
+}
+export function formatLintOutput(result, format, fix) {
+    if (result.diagnostics.length === 0) {
+        const parts = [];
+        if (result.skillCount > 0)
+            parts.push(`${result.skillCount} skill${result.skillCount === 1 ? "" : "s"}`);
+        if (result.rubricCount > 0)
+            parts.push(`${result.rubricCount} rubric${result.rubricCount === 1 ? "" : "s"}`);
+        return `[OK] ${parts.join(" and ")} valid.`;
+    }
+    const output = format === "json"
+        ? formatJson(result.diagnostics)
+        : formatStylish(result.diagnostics);
+    const lines = [output];
+    const fixable = result.diagnostics.filter((d) => d.fix);
+    if (fixable.length > 0) {
+        lines.push(fix
+            ? `Applied ${fixable.length} fix${fixable.length === 1 ? "" : "es"}.`
+            : "Tip: re-run with --fix to apply automated fixes.");
+    }
+    return lines.join("\n");
+}
+const USAGE = `Usage: skillcheck [options] <path...>
+
+Options:
+  --format <stylish|json>  Output format (default: stylish)
+  --max-lines <n>          Max allowed SKILL.md lines (default: 500)
+  --fix                    Auto-fix rubric drift
+  --skills-only            Skip rubric checks
+  --rubrics-only           Skip skill checks
+  -h, --help               Show this help
+`;
+export function run(argv = process.argv.slice(2)) {
+    const parsed = parseCliArgs(argv);
+    if ("error" in parsed) {
+        process.stderr.write(`Error: ${parsed.error}\n`);
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    if ("help" in parsed) {
+        process.stderr.write(USAGE);
+        return 0;
+    }
+    const result = lint(parsed.paths, parsed.options);
+    const output = formatLintOutput(result, parsed.options.format, parsed.options.fix);
+    if (result.diagnostics.length === 0) {
+        process.stdout.write(output + "\n");
+        return 0;
+    }
+    process.stdout.write(output.split("\n")[0] + "\n");
+    const extra = output.split("\n").slice(1).filter(Boolean);
+    for (const line of extra)
+        process.stderr.write(line + "\n");
+    return 1;
+}

package/dist/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.test.js

@@ -0,0 +1,202 @@
+import { describe, it, expect, vi } from "vitest";
+import { resolve } from "node:path";
+import { parseCliArgs, formatLintOutput, run } from "./cli.js";
+const FIXTURES = resolve(import.meta.dirname, "../fixtures");
+describe("parseCliArgs", () => {
+    it("parses valid args", () => {
+        const result = parseCliArgs(["skills/"]);
+        expect(result).toEqual({
+            paths: ["skills/"],
+            options: {
+                format: "stylish",
+                maxLines: 500,
+                fix: false,
+                skillsOnly: false,
+                rubricsOnly: false,
+            },
+        });
+    });
+    it("returns error for missing paths", () => {
+        const result = parseCliArgs([]);
+        expect(result).toEqual({ error: "at least one path is required." });
+    });
+    it("returns error for unknown format", () => {
+        const result = parseCliArgs(["--format", "xml", "skills/"]);
+        expect(result).toEqual({
+            error: "unknown format 'xml'. Use 'stylish' or 'json'.",
+        });
+    });
+    it("returns help", () => {
+        const result = parseCliArgs(["--help"]);
+        expect(result).toEqual({ help: true });
+    });
+    it("returns help with -h", () => {
+        const result = parseCliArgs(["-h"]);
+        expect(result).toEqual({ help: true });
+    });
+    it("parses --fix", () => {
+        const result = parseCliArgs(["--fix", "skills/"]);
+        expect("options" in result && result.options.fix).toBe(true);
+    });
+    it("parses --max-lines", () => {
+        const result = parseCliArgs(["--max-lines", "100", "skills/"]);
+        expect("options" in result && result.options.maxLines).toBe(100);
+    });
+    it("returns error for invalid --max-lines", () => {
+        const result = parseCliArgs(["--max-lines", "abc", "skills/"]);
+        expect(result).toEqual({ error: "--max-lines must be a positive integer." });
+    });
+    it("returns error for zero --max-lines", () => {
+        const result = parseCliArgs(["--max-lines", "0", "skills/"]);
+        expect(result).toEqual({ error: "--max-lines must be a positive integer." });
+    });
+    it("parses --rubrics-only", () => {
+        const result = parseCliArgs(["--rubrics-only", "skills/"]);
+        expect("options" in result && result.options.rubricsOnly).toBe(true);
+    });
+    it("parses --skills-only", () => {
+        const result = parseCliArgs(["--skills-only", "skills/"]);
+        expect("options" in result && result.options.skillsOnly).toBe(true);
+    });
+    it("parses json format", () => {
+        const result = parseCliArgs(["--format", "json", "skills/"]);
+        expect("options" in result && result.options.format).toBe("json");
+    });
+    it("returns error for unknown option", () => {
+        const result = parseCliArgs(["--unknown", "skills/"]);
+        expect("error" in result).toBe(true);
+    });
+    it("handles multiple paths", () => {
+        const result = parseCliArgs(["a/", "b/"]);
+        expect("paths" in result && result.paths).toEqual(["a/", "b/"]);
+    });
+});
+describe("formatLintOutput", () => {
+    it("formats OK message when no diagnostics", () => {
+        const result = { diagnostics: [], skillCount: 2, rubricCount: 1 };
+        expect(formatLintOutput(result, "stylish", false)).toBe("[OK] 2 skills and 1 rubric valid.");
+    });
+    it("formats singular counts", () => {
+        const result = { diagnostics: [], skillCount: 1, rubricCount: 0 };
+        expect(formatLintOutput(result, "stylish", false)).toBe("[OK] 1 skill valid.");
+    });
+    it("formats stylish output with diagnostics", () => {
+        const result = {
+            diagnostics: [
+                { rule: "test-rule", message: "bad stuff", file: "/foo/SKILL.md" },
+            ],
+            skillCount: 1,
+            rubricCount: 0,
+        };
+        const output = formatLintOutput(result, "stylish", false);
+        expect(output).toContain("/foo/SKILL.md");
+        expect(output).toContain("test-rule");
+        expect(output).toContain("1 problem");
+    });
+    it("formats json output", () => {
+        const result = {
+            diagnostics: [
+                { rule: "r", message: "m", file: "/f" },
+            ],
+            skillCount: 1,
+            rubricCount: 0,
+        };
+        const output = formatLintOutput(result, "json", false);
+        // The JSON output is the first "section" before any tip/fix lines
+        // formatJson produces pretty-printed JSON; extract it by finding the closing ]
+        const jsonEnd = output.lastIndexOf("]");
+        const parsed = JSON.parse(output.slice(0, jsonEnd + 1));
+        expect(parsed).toEqual([{ rule: "r", message: "m", file: "/f" }]);
+    });
+    it("includes fix tip when not fixing", () => {
+        const result = {
+            diagnostics: [
+                { rule: "r", message: "m", file: "/f", fix: () => { } },
+            ],
+            skillCount: 1,
+            rubricCount: 0,
+        };
+        const output = formatLintOutput(result, "stylish", false);
+        expect(output).toContain("re-run with --fix");
+    });
+    it("includes fix summary when fixing", () => {
+        const result = {
+            diagnostics: [
+                { rule: "r", message: "m", file: "/f", fix: () => { } },
+            ],
+            skillCount: 1,
+            rubricCount: 0,
+        };
+        const output = formatLintOutput(result, "stylish", true);
+        expect(output).toContain("Applied 1 fix.");
+    });
+    it("pluralizes fix count", () => {
+        const result = {
+            diagnostics: [
+                { rule: "r", message: "m", file: "/f", fix: () => { } },
+                { rule: "r2", message: "m2", file: "/f", fix: () => { } },
+            ],
+            skillCount: 1,
+            rubricCount: 0,
+        };
+        const output = formatLintOutput(result, "stylish", true);
+        expect(output).toContain("Applied 2 fixes.");
+    });
+    it("no fixable diagnostics omits tip", () => {
+        const result = {
+            diagnostics: [
+                { rule: "r", message: "m", file: "/f" },
+            ],
+            skillCount: 1,
+            rubricCount: 0,
+        };
+        const output = formatLintOutput(result, "stylish", false);
+        expect(output).not.toContain("fix");
+    });
+});
+describe("run", () => {
+    it("returns 0 for valid skill", () => {
+        const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        try {
+            const code = run([resolve(FIXTURES, "valid-skill")]);
+            expect(code).toBe(0);
+        }
+        finally {
+            stderrSpy.mockRestore();
+            stdoutSpy.mockRestore();
+        }
+    });
+    it("returns 1 for invalid skill", () => {
+        const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        try {
+            const code = run([resolve(FIXTURES, "invalid-skill")]);
+            expect(code).toBe(1);
+        }
+        finally {
+            stderrSpy.mockRestore();
+            stdoutSpy.mockRestore();
+        }
+    });
+    it("returns 2 for missing paths", () => {
+        const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        try {
+            const code = run([]);
+            expect(code).toBe(2);
+        }
+        finally {
+            stderrSpy.mockRestore();
+        }
+    });
+    it("returns 0 for help", () => {
+        const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        try {
+            const code = run(["--help"]);
+            expect(code).toBe(0);
+        }
+        finally {
+            stderrSpy.mockRestore();
+        }
+    });
+});

package/dist/discover.d.ts

@@ -0,0 +1,5 @@
+export interface DiscoverResult {
+    skillDirs: string[];
+    rubricFiles: string[];
+}
+export declare function discover(basePath: string): DiscoverResult;

package/dist/discover.js

@@ -0,0 +1,51 @@
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+export function discover(basePath) {
+    const abs = resolve(basePath);
+    const skillDirs = [];
+    const rubricFiles = [];
+    if (existsSync(join(abs, "SKILL.md"))) {
+        skillDirs.push(abs);
+        collectRubrics(abs, rubricFiles);
+    }
+    else {
+        let entries;
+        try {
+            entries = readdirSync(abs);
+        }
+        catch {
+            return { skillDirs, rubricFiles };
+        }
+        for (const entry of entries.sort()) {
+            const child = join(abs, entry);
+            try {
+                if (!statSync(child).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (existsSync(join(child, "SKILL.md")))
+                skillDirs.push(child);
+            collectRubrics(child, rubricFiles);
+        }
+    }
+    return { skillDirs, rubricFiles: rubricFiles.sort() };
+}
+function collectRubrics(dir, out) {
+    const refsDir = join(dir, "references");
+    if (!existsSync(refsDir))
+        return;
+    let entries;
+    try {
+        entries = readdirSync(refsDir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.includes("rubric") && entry.endsWith(".md")) {
+            out.push(join(refsDir, entry));
+        }
+    }
+}

package/dist/discover.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/discover.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { resolve } from "node:path";
+import { discover } from "./discover.js";
+const FIXTURES = resolve(import.meta.dirname, "../fixtures");
+describe("discover", () => {
+    it("finds a single skill dir", () => {
+        const result = discover(resolve(FIXTURES, "valid-skill"));
+        expect(result.skillDirs).toEqual([resolve(FIXTURES, "valid-skill")]);
+    });
+    it("finds children skill dirs from parent", () => {
+        const result = discover(FIXTURES);
+        expect(result.skillDirs.length).toBeGreaterThanOrEqual(2);
+        expect(result.skillDirs).toContain(resolve(FIXTURES, "valid-skill"));
+        expect(result.skillDirs).toContain(resolve(FIXTURES, "invalid-skill"));
+    });
+    it("collects rubric files", () => {
+        const result = discover(resolve(FIXTURES, "valid-rubric"));
+        expect(result.rubricFiles.length).toBe(1);
+        expect(result.rubricFiles[0]).toContain("test-rubric.md");
+    });
+    it("returns empty for nonexistent path", () => {
+        const result = discover("/nonexistent/path/that/does/not/exist");
+        expect(result.skillDirs).toEqual([]);
+        expect(result.rubricFiles).toEqual([]);
+    });
+    it("collects rubrics from parent scan", () => {
+        const result = discover(FIXTURES);
+        expect(result.rubricFiles.length).toBeGreaterThanOrEqual(1);
+    });
+});

package/dist/formatters/json.d.ts

@@ -0,0 +1,2 @@
+import type { LintDiagnostic } from "../types.js";
+export declare function formatJson(diagnostics: LintDiagnostic[]): string;

package/dist/formatters/json.js

@@ -0,0 +1,8 @@
+export function formatJson(diagnostics) {
+    const output = diagnostics.map((d) => ({
+        rule: d.rule,
+        message: d.message,
+        file: d.file,
+    }));
+    return JSON.stringify(output, null, 2);
+}

package/dist/formatters/json.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/formatters/json.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { formatJson } from "./json.js";
+describe("formatJson", () => {
+    it("returns empty array for no diagnostics", () => {
+        expect(JSON.parse(formatJson([]))).toEqual([]);
+    });
+    it("maps diagnostics correctly", () => {
+        const result = JSON.parse(formatJson([
+            { rule: "r1", message: "m1", file: "/f1" },
+            { rule: "r2", message: "m2", file: "/f2", fix: () => { } },
+        ]));
+        expect(result).toEqual([
+            { rule: "r1", message: "m1", file: "/f1" },
+            { rule: "r2", message: "m2", file: "/f2" },
+        ]);
+    });
+    it("excludes fix functions from output", () => {
+        const output = formatJson([
+            { rule: "r", message: "m", file: "/f", fix: () => { } },
+        ]);
+        expect(output).not.toContain("fix");
+    });
+});

package/dist/formatters/stylish.d.ts

@@ -0,0 +1,2 @@
+import type { LintDiagnostic } from "../types.js";
+export declare function formatStylish(diagnostics: LintDiagnostic[]): string;

package/dist/formatters/stylish.js

@@ -0,0 +1,25 @@
+export function formatStylish(diagnostics) {
+    if (diagnostics.length === 0)
+        return "";
+    // Group by file
+    const byFile = new Map();
+    for (const d of diagnostics) {
+        const existing = byFile.get(d.file);
+        if (existing) {
+            existing.push(d);
+        }
+        else {
+            byFile.set(d.file, [d]);
+        }
+    }
+    const lines = [];
+    for (const [file, diags] of byFile) {
+        lines.push(file);
+        for (const d of diags) {
+            lines.push(`  ${d.rule}  ${d.message}`);
+        }
+        lines.push("");
+    }
+    lines.push(`${diagnostics.length} problem${diagnostics.length === 1 ? "" : "s"}`);
+    return lines.join("\n");
+}

package/dist/formatters/stylish.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/formatters/stylish.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { formatStylish } from "./stylish.js";
+describe("formatStylish", () => {
+    it("returns empty string for no diagnostics", () => {
+        expect(formatStylish([])).toBe("");
+    });
+    it("groups diagnostics by file", () => {
+        const output = formatStylish([
+            { rule: "r1", message: "m1", file: "/a/SKILL.md" },
+            { rule: "r2", message: "m2", file: "/b/SKILL.md" },
+            { rule: "r3", message: "m3", file: "/a/SKILL.md" },
+        ]);
+        const lines = output.split("\n");
+        expect(lines[0]).toBe("/a/SKILL.md");
+        expect(lines[1]).toBe("  r1  m1");
+        expect(lines[2]).toBe("  r3  m3");
+        expect(lines[4]).toBe("/b/SKILL.md");
+        expect(lines[5]).toBe("  r2  m2");
+    });
+    it("shows singular 'problem' for 1 diagnostic", () => {
+        const output = formatStylish([
+            { rule: "r", message: "m", file: "/f" },
+        ]);
+        expect(output).toContain("1 problem");
+        expect(output).not.toContain("problems");
+    });
+    it("shows plural 'problems' for multiple diagnostics", () => {
+        const output = formatStylish([
+            { rule: "r1", message: "m1", file: "/f" },
+            { rule: "r2", message: "m2", file: "/f" },
+        ]);
+        expect(output).toContain("2 problems");
+    });
+});

package/dist/frontmatter.d.ts

@@ -0,0 +1,3 @@
+import type { Frontmatter, FrontmatterBlock, MarkdownText } from "./types.js";
+export declare function readFrontmatterBlock(text: MarkdownText): FrontmatterBlock;
+export declare function parseFrontmatter(frontmatterText: FrontmatterBlock): Frontmatter;

package/dist/frontmatter.js

@@ -0,0 +1,108 @@
+export function readFrontmatterBlock(text) {
+    if (!text.startsWith("---\n")) {
+        throw new Error("SKILL.md must start with YAML frontmatter (---).");
+    }
+    const end = text.indexOf("\n---\n", 4);
+    if (end === -1) {
+        throw new Error("SKILL.md frontmatter is missing closing --- delimiter.");
+    }
+    return text.slice(4, end);
+}
+export function parseFrontmatter(frontmatterText) {
+    const keys = new Set();
+    let name;
+    let description;
+    const lines = frontmatterText.split("\n");
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (!line.trim() || line.trimStart().startsWith("#")) {
+            index++;
+            continue;
+        }
+        const match = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+        if (!match) {
+            throw new Error(`Invalid frontmatter line: ${JSON.stringify(line)}`);
+        }
+        const key = match[1];
+        const rest = (match[2] ?? "").trimEnd();
+        keys.add(key);
+        // Block scalars for description: `description: >` or `description: |`
+        if (key === "description" && [">", "|", ">-", "|-"].includes(rest.trim())) {
+            const indicator = rest.trim();
+            index++;
+            const blockLines = [];
+            let indent;
+            while (index < lines.length) {
+                const raw = lines[index];
+                if (raw.trim() === "") {
+                    blockLines.push("");
+                    index++;
+                    continue;
+                }
+                const leading = raw.length - raw.trimStart().length;
+                if (indent === undefined) {
+                    indent = leading;
+                }
+                if (leading < (indent ?? 0)) {
+                    break;
+                }
+                blockLines.push(raw.slice(indent ?? 0));
+                index++;
+            }
+            if (indicator.startsWith(">")) {
+                // Fold: join lines with spaces; preserve blank lines as newlines.
+                const folded = [];
+                let paragraph = [];
+                for (const bl of blockLines) {
+                    if (bl === "") {
+                        if (paragraph.length) {
+                            folded.push(paragraph.join(" ").trim());
+                            paragraph = [];
+                        }
+                        folded.push("");
+                    }
+                    else {
+                        paragraph.push(bl.trimEnd());
+                    }
+                }
+                if (paragraph.length) {
+                    folded.push(paragraph.join(" ").trim());
+                }
+                description = folded.join("\n").trim();
+            }
+            else {
+                description = blockLines.join("\n").trim();
+            }
+            continue;
+        }
+        // Inline scalar
+        if (key === "name") {
+            let value = rest.trim();
+            value = value.replace(/^["']|["']$/g, "").trim();
+            if (value) {
+                name = value;
+            }
+        }
+        else if (key === "description") {
+            let value = rest.trim();
+            value = value.replace(/^["']|["']$/g, "").trim();
+            if (value) {
+                description = value;
+            }
+        }
+        // Mapping key with no scalar (e.g., `metadata:`), skip nested lines.
+        if (rest.trim() === "") {
+            index++;
+            continue;
+        }
+        index++;
+    }
+    if (name === undefined) {
+        throw new Error("Missing required frontmatter key: name");
+    }
+    if (description === undefined) {
+        throw new Error("Missing required frontmatter key: description");
+    }
+    return { keys, name: name.trim(), description: description.trim() };
+}

package/dist/frontmatter.test.d.ts

@@ -0,0 +1 @@
+export {};