skill-checker 0.1.6 → 0.1.8

package/README.md

@@ -59,6 +59,18 @@ skill-checker scan ./my-skill --policy strict
 
 Exit code `0` = no critical issues, `1` = critical issues detected.
 
+### Recommended Scan Path
+
+Skill Checker is designed to scan individual skill directories containing a `SKILL.md` file at the root. Running `scan .` from a project root or non-skill directory will produce noisy results (e.g. STRUCT-001 for missing SKILL.md).
+
+```bash
+# Correct: point to a skill directory
+skill-checker scan ./path/to/my-skill/
+
+# Avoid: scanning project root or arbitrary directories
+skill-checker scan .
+```
+
 ## Hook Integration
 
 Skill Checker can run automatically as a Claude Code [PreToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks), intercepting skill file writes before they happen.
@@ -98,28 +110,6 @@ The hook is fail-closed — if the scanner is unavailable, JSON parsing fails, o
 - `jq` must be installed for JSON parsing
 - `skill-checker` must be globally installed or available via `npx`
 
-## Dependency Security Maintenance
-
-Latest dependency audit follow-up (2026-03-07):
-
-- Production dependency risk remains unaffected (`npm audit --omit=dev`: **0 vulnerabilities**).
-- Current `npm audit` still reports **5 moderate** findings in dev tooling chain (`vitest` → `vite` → `esbuild`).
-- Upgrade to `vitest@4.0.18` is **temporarily deferred** because it requires Node `^20 || ^22 || >=24`, while this project currently supports Node `>=18`.
-- Scope of impact is limited to development/test tooling and does not affect runtime package dependencies.
-- Auditable risk acceptance record: [docs/RISK_ACCEPTANCE_DEVDEPS.md](docs/RISK_ACCEPTANCE_DEVDEPS.md).
-
-Verification commands used in this review cycle:
-
-```bash
-npm run lint
-npm test
-npm run build
-npm audit --omit=dev
-npm audit
-```
-
-Next review date: **2026-04-04**.
-
 ## Scoring
 
 Base score starts at **100**. Each finding deducts points by severity:

package/dist/cli.js

@@ -1,5 +1,7 @@
 // src/cli.ts
 import { createRequire } from "module";
+import { existsSync as existsSync4 } from "fs";
+import { join as join5 } from "path";
 import { Command } from "commander";
 
 // src/parser.ts
@@ -150,14 +152,23 @@ function enumerateFiles(dirPath, warnings) {
             content = readFileSync(fullPath, "utf-8");
           } catch {
           }
-        } else if (lstats.size <= 5e7) {
+        } else {
           let fd;
           try {
             fd = openSync(fullPath, "r");
-            const buf = Buffer.alloc(PARTIAL_READ_LIMIT);
-            const bytesRead = readSync(fd, buf, 0, PARTIAL_READ_LIMIT, 0);
-            content = buf.slice(0, bytesRead).toString("utf-8");
-            warnings.push(`Large file partially scanned (first ${PARTIAL_READ_LIMIT} bytes): ${relativePath} (${lstats.size} bytes total)`);
+            const headBuf = Buffer.alloc(PARTIAL_READ_LIMIT);
+            const headBytesRead = readSync(fd, headBuf, 0, PARTIAL_READ_LIMIT, 0);
+            const headContent = headBuf.slice(0, headBytesRead).toString("utf-8");
+            const tailOffset = Math.max(0, lstats.size - PARTIAL_READ_LIMIT);
+            const tailBuf = Buffer.alloc(PARTIAL_READ_LIMIT);
+            const tailBytesRead = readSync(fd, tailBuf, 0, PARTIAL_READ_LIMIT, tailOffset);
+            const tailContent = tailBuf.slice(0, tailBytesRead).toString("utf-8");
+            content = tailOffset > 0 ? `${headContent}
+/* ... window gap ... */
+${tailContent}` : headContent;
+            warnings.push(
+              `Large file window-scanned (head+tail ${PARTIAL_READ_LIMIT} bytes each): ${relativePath} (${lstats.size} bytes total)`
+            );
           } catch {
             warnings.push(`Large file could not be read: ${relativePath} (${lstats.size} bytes)`);
           } finally {
@@ -168,8 +179,6 @@ function enumerateFiles(dirPath, warnings) {
               }
             }
           }
-        } else {
-          warnings.push(`File too large to scan: ${relativePath} (${lstats.size} bytes). Content not checked.`);
         }
       }
       files.push({
@@ -189,15 +198,12 @@ function enumerateFiles(dirPath, warnings) {
 // src/checks/structural.ts
 var HYPHEN_CASE_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 var MAX_NAME_LENGTH = 64;
-var EXECUTABLE_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".exe",
-  ".bat",
-  ".cmd",
+var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".sh",
   ".bash",
   ".ps1",
-  ".com",
-  ".msi"
+  ".bat",
+  ".cmd"
 ]);
 var BINARY_EXTENSIONS2 = /* @__PURE__ */ new Set([
   ".exe",
@@ -209,6 +215,10 @@ var BINARY_EXTENSIONS2 = /* @__PURE__ */ new Set([
   ".class",
   ".pyc"
 ]);
+var INSTALLER_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".com",
+  ".msi"
+]);
 var structuralChecks = {
   name: "Structural Validity",
   category: "STRUCT",
@@ -262,7 +272,7 @@ var structuralChecks = {
     }
     for (const file of skill.files) {
       const ext = file.extension.toLowerCase();
-      if (BINARY_EXTENSIONS2.has(ext) || EXECUTABLE_EXTENSIONS.has(ext)) {
+      if (BINARY_EXTENSIONS2.has(ext) || INSTALLER_EXTENSIONS.has(ext)) {
         results.push({
           id: "STRUCT-006",
           category: "STRUCT",
@@ -271,6 +281,15 @@ var structuralChecks = {
           message: `Found unexpected file: ${file.path} (${ext})`,
           source: file.path
         });
+      } else if (SCRIPT_EXTENSIONS.has(ext)) {
+        results.push({
+          id: "STRUCT-006",
+          category: "STRUCT",
+          severity: "LOW",
+          title: "Script file present",
+          message: `Found script file: ${file.path} (${ext}). Content is scanned separately.`,
+          source: file.path
+        });
       }
     }
     const name = skill.frontmatter.name;
@@ -355,6 +374,15 @@ function isInDocumentationContext(lines, lineIndex) {
   }
   return false;
 }
+function isNearDocumentationHeader(lines, lineIndex) {
+  for (let i = lineIndex; i >= Math.max(0, lineIndex - 15); i--) {
+    const l = lines[i];
+    if (/^#{1,4}\s+.*(install|setup|prerequisite|requirement|depend|getting\s+started|quickstart)/i.test(l)) {
+      return true;
+    }
+  }
+  return false;
+}
 function isLicenseFile(filePath) {
   const name = filePath.split("/").pop()?.toUpperCase() ?? "";
   const base = name.replace(/\.[^.]+$/, "");
@@ -1695,14 +1723,58 @@ var supplyChainChecks = {
       if (NPM_INSTALL_PATTERN.test(line) || PIP_INSTALL_PATTERN.test(line)) {
         const allLines = getAllLines(skill);
         const globalIdx = findGlobalLineIndex(allLines, source, lineNum);
-        const isDoc = globalIdx >= 0 && isInDocumentationContext(
+        const isDoc = source === "SKILL.md" && globalIdx >= 0 && isInDocumentationContext(
           allLines.map((l) => l.line),
           globalIdx
         );
-        if (!isDoc) {
+        const srcLines = getLinesForSource(skill, source);
+        const localIdx = getLocalIndex(source, lineNum, skill.bodyStartLine);
+        const inCodeBlock = localIdx >= 0 && isInCodeBlock(srcLines, localIdx);
+        if (isDoc && !inCodeBlock) {
+        } else {
           let severity = "HIGH";
           let reducedFrom;
           let msgSuffix = "";
+          if (inCodeBlock) {
+            const isNearDoc = source === "SKILL.md" && globalIdx >= 0 && isNearDocumentationHeader(
+              allLines.map((l) => l.line),
+              globalIdx
+            );
+            if (isNearDoc) {
+              severity = "LOW";
+              reducedFrom = "HIGH";
+              msgSuffix = " [reduced: in code block within documentation]";
+            } else {
+              const r = reduceSeverity(severity, "in code block");
+              severity = r.severity;
+              reducedFrom = r.reducedFrom;
+              msgSuffix = ` ${r.annotation}`;
+            }
+          }
+          results.push({
+            id: "SUPPLY-003",
+            category: "SUPPLY",
+            severity,
+            title: "Package installation command",
+            message: `${source}:${lineNum}: Installs packages. Verify package names are legitimate.${msgSuffix}`,
+            line: lineNum,
+            snippet: line.trim().slice(0, 120),
+            source,
+            reducedFrom
+          });
+        }
+      }
+      if (GIT_CLONE_PATTERN.test(line)) {
+        const allLines = getAllLines(skill);
+        const globalIdx = findGlobalLineIndex(allLines, source, lineNum);
+        const isDoc = source === "SKILL.md" && globalIdx >= 0 && isInDocumentationContext(
+          allLines.map((l) => l.line),
+          globalIdx
+        );
+        if (!isDoc) {
+          let severity = "MEDIUM";
+          let reducedFrom;
+          let msgSuffix = "";
           const srcLines = getLinesForSource(skill, source);
           const localIdx = getLocalIndex(source, lineNum, skill.bodyStartLine);
           if (localIdx >= 0 && isInCodeBlock(srcLines, localIdx)) {
@@ -1712,11 +1784,11 @@ var supplyChainChecks = {
             msgSuffix = ` ${r.annotation}`;
           }
           results.push({
-            id: "SUPPLY-003",
+            id: "SUPPLY-006",
             category: "SUPPLY",
             severity,
-            title: "Package installation command",
-            message: `${source}:${lineNum}: Installs packages. Verify package names are legitimate.${msgSuffix}`,
+            title: "git clone command",
+            message: `${source}:${lineNum}: Clones a git repository. Verify the source.${msgSuffix}`,
             line: lineNum,
             snippet: line.trim().slice(0, 120),
             source,
@@ -1724,18 +1796,6 @@ var supplyChainChecks = {
           });
         }
       }
-      if (GIT_CLONE_PATTERN.test(line)) {
-        results.push({
-          id: "SUPPLY-006",
-          category: "SUPPLY",
-          severity: "MEDIUM",
-          title: "git clone command",
-          message: `${source}:${lineNum}: Clones a git repository. Verify the source.`,
-          line: lineNum,
-          snippet: line.trim().slice(0, 120),
-          source
-        });
-      }
       const urls = line.match(URL_PATTERN) || [];
       for (const url of urls) {
         if (url.startsWith("http://")) {
@@ -2565,6 +2625,11 @@ program.command("scan").description("Scan a skill directory for security issues"
       process.exit(1);
     }
     const config = loadConfig(path, opts.config);
+    if (!existsSync4(join5(path, "SKILL.md"))) {
+      console.error(
+        "Warning: No SKILL.md found in the specified directory. This tool is designed to scan skill directories. Results may contain noise. See: skill-checker scan --help"
+      );
+    }
     if (opts.policy) {
       config.policy = opts.policy;
     }