@studiomeyer-io/skilldoctor 0.1.0

package/dist/types-lUfaWSNG.d.cts

@@ -0,0 +1,117 @@
+/**
+ * Core domain types for skilldoctor.
+ *
+ * These types describe what a parsed agent-skill / instruction file looks like,
+ * what a finding is, and the shape of an analysis result. They form the public
+ * library API surface (re-exported from `index.ts`).
+ */
+/** The kind of agent-instruction file we detected. */
+type FileKind = 
+/** A Claude Code / Agent Skills `SKILL.md` (has a `name`+`description` frontmatter). */
+"skill"
+/** A Claude Code subagent definition (frontmatter with `name`+`description`, body = system prompt). */
+ | "subagent"
+/** An `AGENTS.md` instruction file (plain markdown, no frontmatter required). */
+ | "agents-md"
+/** A markdown file with frontmatter we could not confidently classify. */
+ | "unknown";
+/** Severity of a finding, ordered from most to least serious. */
+type Severity = "error" | "warning" | "info";
+/** Numeric rank for a severity — higher means more serious. Used for `--fail-on`. */
+declare const SEVERITY_RANK: Record<Severity, number>;
+/** Category groups findings for reporting and weighting. */
+type FindingCategory = "lint" | "security";
+/** A single problem found in a file. */
+interface Finding {
+    /** Stable rule identifier, e.g. `skill/missing-description` or `sec/prompt-injection`. */
+    ruleId: string;
+    /** Human-readable rule title (short). */
+    title: string;
+    /** Category — lint or security. */
+    category: FindingCategory;
+    /** Severity of this occurrence. */
+    severity: Severity;
+    /** One-line explanation of the problem in context. */
+    message: string;
+    /** 1-based line number in the source file (best effort; 1 if unknown). */
+    line: number;
+    /** 1-based column number (best effort; 1 if unknown). */
+    column: number;
+    /** Optional snippet of the offending text (truncated, never executed). */
+    evidence?: string;
+    /** Whether `--fix` can mechanically repair this finding. */
+    fixable: boolean;
+}
+/** Frontmatter parsed from a file, normalized to a plain record. */
+interface ParsedFrontmatter {
+    /** Whether a frontmatter block was present at all. */
+    present: boolean;
+    /** Raw frontmatter source (between the `---` fences), if present. */
+    raw: string;
+    /** Parsed key/value data. `undefined` when frontmatter is absent or unparseable. */
+    data: Record<string, unknown> | undefined;
+    /** A YAML parse error message, if parsing failed. */
+    error: string | undefined;
+    /** 1-based line where the frontmatter body starts (line after the opening fence). */
+    startLine: number;
+    /** 1-based line where the frontmatter body ends (the closing fence line). */
+    endLine: number;
+}
+/** A fully parsed agent-instruction file, ready to lint. */
+interface ParsedFile {
+    /** Absolute or relative path as supplied by the caller. */
+    filePath: string;
+    /** Detected file kind. */
+    kind: FileKind;
+    /** Parsed frontmatter. */
+    frontmatter: ParsedFrontmatter;
+    /** The markdown body (everything after the frontmatter block). */
+    body: string;
+    /** 1-based line number where the body begins in the original file. */
+    bodyStartLine: number;
+    /** The complete, unmodified file contents. */
+    raw: string;
+}
+/** Result of analyzing one file. */
+interface FileReport {
+    filePath: string;
+    kind: FileKind;
+    findings: Finding[];
+    /** Numeric score 0-100 for this file. */
+    score: number;
+    /** Letter grade A-F derived from the score. */
+    grade: Grade;
+}
+/** Aggregate result of analyzing one or more files. */
+interface AnalysisReport {
+    files: FileReport[];
+    /** Aggregate numeric score 0-100 across all files (worst-weighted average). */
+    score: number;
+    /** Aggregate letter grade. */
+    grade: Grade;
+    /** Total finding counts by severity across all files. */
+    totals: Record<Severity, number>;
+}
+/** Letter grades. */
+type Grade = "A" | "B" | "C" | "D" | "F";
+/** A rule's static descriptor (used for SARIF `driver.rules` and docs). */
+interface RuleDescriptor {
+    ruleId: string;
+    title: string;
+    category: FindingCategory;
+    defaultSeverity: Severity;
+    /** Short description of what the rule checks and why. */
+    description: string;
+    /** Whether occurrences of this rule are mechanically fixable. */
+    fixable: boolean;
+}
+/** Options controlling analysis behavior. */
+interface AnalyzeOptions {
+    /**
+     * Override the auto-detected file kind. Mostly useful for tests and for
+     * files whose name does not follow convention.
+     */
+    forceKind?: FileKind;
+}
+
+export { type AnalyzeOptions as A, type FileReport as F, type Grade as G, type ParsedFile as P, type RuleDescriptor as R, type Severity as S, type AnalysisReport as a, type ParsedFrontmatter as b, type FileKind as c, type Finding as d, type FindingCategory as e, SEVERITY_RANK as f };

package/dist/types-lUfaWSNG.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Core domain types for skilldoctor.
+ *
+ * These types describe what a parsed agent-skill / instruction file looks like,
+ * what a finding is, and the shape of an analysis result. They form the public
+ * library API surface (re-exported from `index.ts`).
+ */
+/** The kind of agent-instruction file we detected. */
+type FileKind = 
+/** A Claude Code / Agent Skills `SKILL.md` (has a `name`+`description` frontmatter). */
+"skill"
+/** A Claude Code subagent definition (frontmatter with `name`+`description`, body = system prompt). */
+ | "subagent"
+/** An `AGENTS.md` instruction file (plain markdown, no frontmatter required). */
+ | "agents-md"
+/** A markdown file with frontmatter we could not confidently classify. */
+ | "unknown";
+/** Severity of a finding, ordered from most to least serious. */
+type Severity = "error" | "warning" | "info";
+/** Numeric rank for a severity — higher means more serious. Used for `--fail-on`. */
+declare const SEVERITY_RANK: Record<Severity, number>;
+/** Category groups findings for reporting and weighting. */
+type FindingCategory = "lint" | "security";
+/** A single problem found in a file. */
+interface Finding {
+    /** Stable rule identifier, e.g. `skill/missing-description` or `sec/prompt-injection`. */
+    ruleId: string;
+    /** Human-readable rule title (short). */
+    title: string;
+    /** Category — lint or security. */
+    category: FindingCategory;
+    /** Severity of this occurrence. */
+    severity: Severity;
+    /** One-line explanation of the problem in context. */
+    message: string;
+    /** 1-based line number in the source file (best effort; 1 if unknown). */
+    line: number;
+    /** 1-based column number (best effort; 1 if unknown). */
+    column: number;
+    /** Optional snippet of the offending text (truncated, never executed). */
+    evidence?: string;
+    /** Whether `--fix` can mechanically repair this finding. */
+    fixable: boolean;
+}
+/** Frontmatter parsed from a file, normalized to a plain record. */
+interface ParsedFrontmatter {
+    /** Whether a frontmatter block was present at all. */
+    present: boolean;
+    /** Raw frontmatter source (between the `---` fences), if present. */
+    raw: string;
+    /** Parsed key/value data. `undefined` when frontmatter is absent or unparseable. */
+    data: Record<string, unknown> | undefined;
+    /** A YAML parse error message, if parsing failed. */
+    error: string | undefined;
+    /** 1-based line where the frontmatter body starts (line after the opening fence). */
+    startLine: number;
+    /** 1-based line where the frontmatter body ends (the closing fence line). */
+    endLine: number;
+}
+/** A fully parsed agent-instruction file, ready to lint. */
+interface ParsedFile {
+    /** Absolute or relative path as supplied by the caller. */
+    filePath: string;
+    /** Detected file kind. */
+    kind: FileKind;
+    /** Parsed frontmatter. */
+    frontmatter: ParsedFrontmatter;
+    /** The markdown body (everything after the frontmatter block). */
+    body: string;
+    /** 1-based line number where the body begins in the original file. */
+    bodyStartLine: number;
+    /** The complete, unmodified file contents. */
+    raw: string;
+}
+/** Result of analyzing one file. */
+interface FileReport {
+    filePath: string;
+    kind: FileKind;
+    findings: Finding[];
+    /** Numeric score 0-100 for this file. */
+    score: number;
+    /** Letter grade A-F derived from the score. */
+    grade: Grade;
+}
+/** Aggregate result of analyzing one or more files. */
+interface AnalysisReport {
+    files: FileReport[];
+    /** Aggregate numeric score 0-100 across all files (worst-weighted average). */
+    score: number;
+    /** Aggregate letter grade. */
+    grade: Grade;
+    /** Total finding counts by severity across all files. */
+    totals: Record<Severity, number>;
+}
+/** Letter grades. */
+type Grade = "A" | "B" | "C" | "D" | "F";
+/** A rule's static descriptor (used for SARIF `driver.rules` and docs). */
+interface RuleDescriptor {
+    ruleId: string;
+    title: string;
+    category: FindingCategory;
+    defaultSeverity: Severity;
+    /** Short description of what the rule checks and why. */
+    description: string;
+    /** Whether occurrences of this rule are mechanically fixable. */
+    fixable: boolean;
+}
+/** Options controlling analysis behavior. */
+interface AnalyzeOptions {
+    /**
+     * Override the auto-detected file kind. Mostly useful for tests and for
+     * files whose name does not follow convention.
+     */
+    forceKind?: FileKind;
+}
+
+export { type AnalyzeOptions as A, type FileReport as F, type Grade as G, type ParsedFile as P, type RuleDescriptor as R, type Severity as S, type AnalysisReport as a, type ParsedFrontmatter as b, type FileKind as c, type Finding as d, type FindingCategory as e, SEVERITY_RANK as f };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@studiomeyer-io/skilldoctor",
+  "version": "0.1.0",
+  "description": "Linter and security scanner for AI-agent skill and instruction files (Claude Code SKILL.md, AGENTS.md, subagents). Prints an A-F grade, supports --fix, emits JSON + SARIF, ships as a GitHub Action.",
+  "type": "module",
+  "license": "MIT",
+  "author": "StudioMeyer",
+  "homepage": "https://github.com/studiomeyer-io/skilldoctor#readme",
+  "bugs": {
+    "url": "https://github.com/studiomeyer-io/skilldoctor/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "github:studiomeyer-io/skilldoctor"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude",
+    "claude-code",
+    "agents-md",
+    "linter",
+    "security",
+    "prompt-injection",
+    "ai-agents",
+    "sarif",
+    "supply-chain"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "skilldoctor": "./dist/cli.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "attw": "attw --pack .",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test && npm run typecheck && npm run attw"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@types/node": "^20.14.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.0"
+  }
+}