1 +import assert from "node:assert/strict";
2 +import { spawnSync } from "node:child_process";
11 +import { tmpdir } from "node:os";
12 +import { dirname, join } from "node:path";
13 +import { test } from "node:test";
14 +import { fileURLToPath } from "node:url";
15 +import { checkSkill } from "./check.mjs";
17 +const cli = fileURLToPath(new URL("./check.mjs", import.meta.url));
18 +const header = '---\nname: example\ndescription: "Use when testing."\n---\n';
20 +function fixture(t, files = {}) {
21 + const temp = mkdtempSync(join(tmpdir(), "writing skills-"));
22 + t.after(() => rmSync(temp, { recursive: true, force: true }));
23 + const root = join(temp, "example");
24 + for (const [path, content] of Object.entries({
28 + const dest = join(root, path);
29 + mkdirSync(dirname(dest), { recursive: true });
30 + writeFileSync(dest, content);
35 +function codes(root) {
36 + return checkSkill(root).issues.map((issue) => issue.code);
39 +test("valid prose-only skill needs neither package nor tests", (t) => {
40 + const result = checkSkill(fixture(t));
41 + assert.equal(result.ok, true);
42 + assert.deepEqual(result.issues, []);
45 +for (const [label, content, expected] of [
46 + ["missing fences", "name: example", "frontmatter.fence"],
47 + ["unclosed fence", "---\nname: example", "frontmatter.fence"],
48 + ["invalid YAML", "---\nname: [\n---\n", "frontmatter.yaml"],
50 + "duplicate YAML key",
51 + header.replace("name: example", "name: example\nname: other"),
54 + ["non-mapping YAML", "---\n- example\n---\n", "frontmatter.mapping"],
55 + ["missing name", header.replace("name: example\n", ""), "name.invalid"],
56 + ["non-string name", header.replace("example", "123"), "name.invalid"],
58 + "consecutive hyphens",
59 + header.replace("example", "ex--ample"),
62 + ["uppercase name", header.replace("example", "Example"), "name.invalid"],
63 + ["leading hyphen", header.replace("example", "-example"), "name.invalid"],
64 + ["trailing hyphen", header.replace("example", "example-"), "name.invalid"],
65 + ["long name", header.replace("example", "a".repeat(65)), "name.invalid"],
66 + ["directory mismatch", header.replace("example", "other"), "name.directory"],
67 + ["missing description", "---\nname: example\n---\n", "description.invalid"],
69 + "empty description",
70 + header.replace('"Use when testing."', '" "'),
71 + "description.invalid",
74 + "non-string description",
75 + header.replace('"Use when testing."', "false"),
76 + "description.invalid",
80 + header.replace("Use when testing.", "x".repeat(1025)),
81 + "description.invalid",
84 + "non-boolean invocation flag",
87 + 'name: example\ndisable-model-invocation: "false"',
89 + "invocation.invalid",
93 + assert.ok(codes(fixture(t, { "SKILL.md": content })).includes(expected)),
97 +test("YAML folded descriptions, comments, CRLF and unknown metadata are valid", (t) => {
99 + "---\nname: example # comment\ndescription: >-\n Use when testing:\n quoted punctuation is not required here.\ndisable-model-invocation: true\nmetadata:\n topic: checks\n---\n";
102 + fixture(t, { "SKILL.md": `\uFEFF${content.replaceAll("\n", "\r\n")}` }),
108 +test("YAML scalar aliases resolve", (t) => {
109 + const root = fixture(t, {
110 + "SKILL.md": header.replace(
111 + 'description: "Use when testing."',
112 + 'label: &label "Use when testing."\ndescription: *label',
115 + assert.deepEqual(codes(root), []);
118 +test("unresolved YAML aliases fail even in optional metadata", (t) => {
119 + const root = fixture(t, {
120 + "SKILL.md": header.replace(
122 + "name: example\nmetadata: *missing",
125 + assert.ok(codes(root).includes("frontmatter.yaml"));
128 +test("local inline, image, reference and nested Markdown links resolve per document", (t) => {
129 + const root = fixture(t, {
130 + "SKILL.md": `${header}\n[ref](references/guide.md#part)\n\n[space][s]\n\n[s]: <references/a b.md>\n`,
131 + "references/guide.md":
132 + "[back](../SKILL.md)\n[encoded](a%20b.md?view=1#part)\n[parenthesized](a(b).md)",
133 + "references/a b.md": "OK",
134 + "references/a(b).md": "OK",
135 + "assets/pic.png": "fixture",
137 + assert.deepEqual(codes(root), []);
140 +test("missing local links report their source file", (t) => {
141 + const root = fixture(t, {
142 + "references/guide.md": "[missing](gone.md)\n",
144 + const result = checkSkill(root);
145 + assert.equal(result.ok, false);
147 + result.issues.map(({ path, code }) => [path, code]),
149 + ["references/guide.md", "link.missing"],
150 + ["references/guide.md", "link.missing"],
155 +test("external URLs, anchors, absolute links and code examples are not local-link checks", (t) => {
156 + const root = fixture(t, {
157 + "SKILL.md": `${header}
158 +[web](https://example.test/missing)
159 +[mail](mailto:test@example.test)
161 +[absolute](/missing)
162 +[windows](C:/missing)
163 +[network](//example.test/missing)
164 +\`[code](missing.md)\`
167 +[example](missing.md)
171 + assert.deepEqual(codes(root), []);
174 +test("bad URL encoding is an actionable issue", (t) => {
176 + codes(fixture(t, { "SKILL.md": `${header}[bad](missing%ZZ.md)` })).includes(
182 +test("dependencies and VCS internals are not traversed", (t) => {
186 + "node_modules/pkg/SKILL.md": "[bad](gone)",
187 + ".git/internal.md": "[bad](gone)",
194 +test("directory symlinks are not traversed", (t) => {
195 + const root = fixture(t);
196 + const external = join(dirname(root), "outside");
197 + mkdirSync(external);
198 + writeFileSync(join(external, "bad.md"), "[bad](gone)");
201 + join(root, "references"),
202 + process.platform === "win32" ? "junction" : "dir",
204 + assert.deepEqual(codes(root), []);
208 + "scripts/helper.mjs": 'throw new Error("must never execute");',
211 + "scripts/helper.test.mjs": 'throw new Error("must never execute");',
213 +const manifest = (command) => JSON.stringify({ scripts: { test: command } });
215 +for (const [label, files, expected] of [
216 + ["missing package and tests", helper, ["package.missing", "tests.missing"]],
219 + { ...helper, ...testFile, "package.json": "{" },
223 + "non-object manifest",
224 + { ...helper, ...testFile, "package.json": "null" },
228 + "missing test command",
229 + { ...helper, ...testFile, "package.json": "{}" },
233 + "non-string test command",
234 + { ...helper, ...testFile, "package.json": manifest(42) },
238 + "fake test command",
239 + { ...helper, ...testFile, "package.json": manifest("echo node --test") },
244 + { ...helper, "package.json": manifest("node --test") },
248 + "valid scripted skill",
252 + "package.json": manifest("node --test scripts/*.test.mjs"),
260 + "test/nested/helper.test.mjs": "",
261 + "package.json": manifest("node --test"),
266 + "domain-specific helper",
268 + "scripts/helper.ps1": "",
270 + "package.json": manifest("node --test"),
275 + test(label, (t) => assert.deepEqual(codes(fixture(t, files)), expected));
278 +test("CLI succeeds from unrelated cwd and paths with spaces", (t) => {
279 + const root = fixture(t, { "references/path with spaces.md": "OK" });
280 + const result = spawnSync(process.execPath, [cli, root], {
284 + assert.equal(result.status, 0, result.stderr);
285 + assert.equal(JSON.parse(result.stdout).ok, true);
288 +test("CLI returns 1 for findings", (t) => {
289 + const result = spawnSync(
291 + [cli, fixture(t, { "SKILL.md": "bad" })],
292 + { encoding: "utf8" },
294 + assert.equal(result.status, 1);
295 + assert.equal(JSON.parse(result.stdout).ok, false);
298 +test("CLI returns 2 for usage or inaccessible input", (t) => {
299 + const root = fixture(t);
300 + for (const args of [[], [root, "extra"], [join(root, "missing")]]) {
301 + const result = spawnSync(process.execPath, [cli, ...args], {
304 + assert.equal(result.status, 2, result.stderr);
305 + assert.ok(JSON.parse(result.stdout).error);
309 +test("checker audits itself", () => {
310 + const root = fileURLToPath(new URL("..", import.meta.url));
311 + assert.deepEqual(codes(root), []);
312 + assert.ok(readFileSync(join(root, "SKILL.md"), "utf8").includes("check.mjs"));