@studiomeyer-io/skilldoctor 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,220 @@
+import { A as AnalyzeOptions, F as FileReport, a as AnalysisReport, P as ParsedFile, b as ParsedFrontmatter, c as FileKind, d as Finding, G as Grade, S as Severity, R as RuleDescriptor } from './types-lUfaWSNG.cjs';
+export { e as FindingCategory, f as SEVERITY_RANK } from './types-lUfaWSNG.cjs';
+
+/**
+ * Analyzer — the central orchestration layer. Parses, lints, security-scans,
+ * and grades one file or a set of files, and runs cross-file rules
+ * (duplicate names).
+ *
+ * This module is pure with respect to the filesystem when given content
+ * directly (`analyzeContent`); `analyzePaths` reads files for convenience.
+ */
+
+/** Analyze a single file given its content. */
+declare function analyzeContent(filePath: string, content: string, options?: AnalyzeOptions): FileReport;
+/** Analyze multiple files given their {path, content} pairs (no FS access). */
+declare function analyzeFiles(inputs: readonly {
+    filePath: string;
+    content: string;
+}[], options?: AnalyzeOptions): AnalysisReport;
+/** Analyze a list of file paths, reading each from disk. */
+declare function analyzePaths(paths: readonly string[], options?: AnalyzeOptions): AnalysisReport;
+/** Re-parse content (used by the CLI to feed the fixer). */
+declare function parseForFix(filePath: string, content: string): ParsedFile;
+
+/**
+ * Parsing layer: split an agent-instruction file into frontmatter + body,
+ * parse the YAML frontmatter, and classify the file kind.
+ *
+ * We do NOT execute anything. We only read text. The YAML parser is configured
+ * defensively (no custom tags, no anchors expansion blow-up via the default
+ * parser limits in the `yaml` package).
+ */
+
+/**
+ * Extract a frontmatter block from raw file contents.
+ *
+ * Frontmatter must start on line 1 with `---` and end with a line that is
+ * exactly `---` (optionally followed by trailing whitespace). Anything after
+ * the closing fence is the body.
+ */
+declare function extractFrontmatter(raw: string): {
+    frontmatter: ParsedFrontmatter;
+    body: string;
+    bodyStartLine: number;
+};
+/**
+ * Classify the file kind from its path and parsed frontmatter.
+ *
+ * Heuristics (deliberately conservative — when unsure we lean "skill" only if
+ * the filename is SKILL.md, otherwise "unknown" or "agents-md"):
+ *  - `AGENTS.md` (any case) -> agents-md
+ *  - `SKILL.md` (any case) -> skill
+ *  - a `.md` file inside an `agents/` directory with frontmatter -> subagent
+ *  - a `.md` file with `name`+`description` frontmatter -> skill (best guess)
+ *  - otherwise -> unknown
+ */
+declare function detectKind(filePath: string, frontmatter: ParsedFrontmatter): FileKind;
+/** Parse raw file contents at a given path into a ParsedFile. */
+declare function parseFile(filePath: string, raw: string, forceKind?: FileKind): ParsedFile;
+
+/**
+ * Grading: turn a set of findings into a 0-100 score and an A-F letter grade.
+ *
+ * Security findings are weighted more heavily than lint findings, because the
+ * whole point of skilldoctor is to surface supply-chain risk. The mapping is
+ * deterministic and documented so grades are reproducible.
+ */
+
+/** Compute a 0-100 score from findings (100 = clean). */
+declare function scoreFindings(findings: readonly Finding[]): number;
+/** Map a numeric score to a letter grade. */
+declare function scoreToGrade(score: number): Grade;
+/** Tally findings by severity. */
+declare function tally(findings: readonly Finding[]): Record<Severity, number>;
+/**
+ * Aggregate per-file scores into one overall score. We use a worst-weighted
+ * average: the mean of file scores, pulled toward the single worst file so a
+ * batch with one dangerous skill cannot be averaged into a good grade.
+ */
+declare function aggregateScore(fileScores: readonly number[]): number;
+
+/**
+ * Central rule registry — the single source of truth for every rule
+ * skilldoctor can emit. SARIF requires every emitted `ruleId` to have a
+ * matching `reportingDescriptor` in `driver.rules`, so we generate that list
+ * from here. The README rule table is also derived from this.
+ */
+
+declare const RULES: readonly RuleDescriptor[];
+/** Look up a rule descriptor by id. Throws if unknown (programmer error). */
+declare function getRule(ruleId: string): RuleDescriptor;
+/** All registered rule ids. */
+declare function allRuleIds(): string[];
+
+/**
+ * --fix engine. Mechanically repairs the safe, unambiguous subset of findings.
+ *
+ * HARD RULE: we never rewrite the markdown body content (that could neutralize
+ * malicious instructions silently, or mangle legitimate prose). We only touch
+ * the YAML frontmatter, and only in deterministic, reversible ways:
+ *   1. trim trailing whitespace on frontmatter lines
+ *   2. add a missing `description:` stub with a TODO marker
+ *   3. de-duplicate tools within `allowed-tools` / `tools` (preserving order)
+ *
+ * The fixer is idempotent: running it twice produces identical output.
+ */
+
+/** Marker used for an inserted stub so humans (and tests) can find it. */
+declare const DESCRIPTION_STUB = "TODO describe what this skill does and when to use it.";
+interface FixResult {
+    /** The (possibly) rewritten file contents. */
+    output: string;
+    /** True if anything changed. */
+    changed: boolean;
+    /** Names of the fixes applied. */
+    applied: string[];
+}
+/**
+ * Apply mechanical fixes to a parsed file's raw text and return the result.
+ * Only skill/subagent files with frontmatter are fixed; AGENTS.md/unknown are
+ * returned unchanged.
+ */
+declare function fixFile(file: ParsedFile): FixResult;
+
+/**
+ * File discovery. Given path(s) — a file, a directory, or a glob — resolve the
+ * set of candidate markdown files to analyze.
+ *
+ * Deliberately dependency-free: a small recursive walker plus a minimal glob
+ * matcher cover our needs (`**`, `*`, `?`) without pulling in fast-glob/globby.
+ */
+/** True if a path string contains glob metacharacters. */
+declare function isGlob(p: string): boolean;
+/**
+ * Convert a glob to an anchored RegExp. Supports `**` (any depth, incl. zero),
+ * `*` (within a path segment), `?` (single char), and literal text. Forward
+ * slashes only (we normalize input to posix).
+ */
+declare function globToRegExp(glob: string): RegExp;
+/**
+ * Resolve one or more input specs into a deduplicated, sorted list of absolute
+ * file paths. Each spec may be a file, a directory, or a glob.
+ */
+declare function discoverFiles(specs: readonly string[]): string[];
+
+/**
+ * Terminal reporter. Human-readable, optionally colorized (auto-disabled when
+ * not a TTY or when NO_COLOR is set). No external dependency — small ANSI
+ * helpers only.
+ */
+
+interface TerminalOptions {
+    /** Force color on/off. Defaults to auto-detect. */
+    color?: boolean;
+}
+/** Render a full analysis report as a terminal string. */
+declare function renderTerminal(report: AnalysisReport, options?: TerminalOptions): string;
+
+/**
+ * JSON reporter. A stable, documented machine-readable shape of an analysis
+ * report. Keep this versioned so downstream consumers can rely on it.
+ */
+
+declare const JSON_REPORT_VERSION: 1;
+interface JsonReport {
+    /** Schema version of this JSON output. */
+    schemaVersion: typeof JSON_REPORT_VERSION;
+    /** The tool that produced it. */
+    tool: {
+        name: "skilldoctor";
+        version: string;
+    };
+    /** Aggregate grade + score. */
+    summary: {
+        grade: string;
+        score: number;
+        fileCount: number;
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+    /** Per-file results. */
+    files: AnalysisReport["files"];
+}
+/** Build the JSON report object. */
+declare function toJsonReport(report: AnalysisReport, toolVersion: string): JsonReport;
+/** Serialize the JSON report. */
+declare function jsonString(report: AnalysisReport, toolVersion: string): string;
+
+/**
+ * SARIF 2.1.0 reporter.
+ *
+ * Produces a valid SARIF log that GitHub code scanning accepts:
+ *  - exactly one run with a tool.driver
+ *  - driver.rules[] contains a reportingDescriptor for EVERY ruleId we emit
+ *    (so no result references a missing rule)
+ *  - each result has a ruleId, ruleIndex, level, message, and a physical
+ *    location with a region (1-based line/column)
+ *  - each result carries partialFingerprints for stable de-duplication across
+ *    runs (we hash ruleId + relative file + a normalized snippet, NOT the line
+ *    number, so cosmetic line shifts don't churn fingerprints)
+ *
+ * Spec ref: SARIF v2.1.0 (OASIS). Schema:
+ * https://json.schemastore.org/sarif-2.1.0.json
+ */
+
+declare const SARIF_VERSION = "2.1.0";
+declare const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+/** Build the SARIF log object for an analysis report. */
+declare function toSarif(report: AnalysisReport, options?: {
+    baseDir?: string;
+    version?: string;
+}): unknown;
+/** Serialize the SARIF log to a JSON string. */
+declare function sarifString(report: AnalysisReport, options?: {
+    baseDir?: string;
+    version?: string;
+}): string;
+
+export { AnalysisReport, AnalyzeOptions, DESCRIPTION_STUB, FileKind, FileReport, Finding, type FixResult, Grade, JSON_REPORT_VERSION, type JsonReport, ParsedFile, ParsedFrontmatter, RULES, RuleDescriptor, SARIF_SCHEMA, SARIF_VERSION, Severity, aggregateScore, allRuleIds, analyzeContent, analyzeFiles, analyzePaths, detectKind, discoverFiles, extractFrontmatter, fixFile, getRule, globToRegExp, isGlob, jsonString, parseFile, parseForFix, renderTerminal, sarifString, scoreFindings, scoreToGrade, tally, toJsonReport, toSarif };

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import { A as AnalyzeOptions, F as FileReport, a as AnalysisReport, P as ParsedFile, b as ParsedFrontmatter, c as FileKind, d as Finding, G as Grade, S as Severity, R as RuleDescriptor } from './types-lUfaWSNG.js';
+export { e as FindingCategory, f as SEVERITY_RANK } from './types-lUfaWSNG.js';
+
+/**
+ * Analyzer — the central orchestration layer. Parses, lints, security-scans,
+ * and grades one file or a set of files, and runs cross-file rules
+ * (duplicate names).
+ *
+ * This module is pure with respect to the filesystem when given content
+ * directly (`analyzeContent`); `analyzePaths` reads files for convenience.
+ */
+
+/** Analyze a single file given its content. */
+declare function analyzeContent(filePath: string, content: string, options?: AnalyzeOptions): FileReport;
+/** Analyze multiple files given their {path, content} pairs (no FS access). */
+declare function analyzeFiles(inputs: readonly {
+    filePath: string;
+    content: string;
+}[], options?: AnalyzeOptions): AnalysisReport;
+/** Analyze a list of file paths, reading each from disk. */
+declare function analyzePaths(paths: readonly string[], options?: AnalyzeOptions): AnalysisReport;
+/** Re-parse content (used by the CLI to feed the fixer). */
+declare function parseForFix(filePath: string, content: string): ParsedFile;
+
+/**
+ * Parsing layer: split an agent-instruction file into frontmatter + body,
+ * parse the YAML frontmatter, and classify the file kind.
+ *
+ * We do NOT execute anything. We only read text. The YAML parser is configured
+ * defensively (no custom tags, no anchors expansion blow-up via the default
+ * parser limits in the `yaml` package).
+ */
+
+/**
+ * Extract a frontmatter block from raw file contents.
+ *
+ * Frontmatter must start on line 1 with `---` and end with a line that is
+ * exactly `---` (optionally followed by trailing whitespace). Anything after
+ * the closing fence is the body.
+ */
+declare function extractFrontmatter(raw: string): {
+    frontmatter: ParsedFrontmatter;
+    body: string;
+    bodyStartLine: number;
+};
+/**
+ * Classify the file kind from its path and parsed frontmatter.
+ *
+ * Heuristics (deliberately conservative — when unsure we lean "skill" only if
+ * the filename is SKILL.md, otherwise "unknown" or "agents-md"):
+ *  - `AGENTS.md` (any case) -> agents-md
+ *  - `SKILL.md` (any case) -> skill
+ *  - a `.md` file inside an `agents/` directory with frontmatter -> subagent
+ *  - a `.md` file with `name`+`description` frontmatter -> skill (best guess)
+ *  - otherwise -> unknown
+ */
+declare function detectKind(filePath: string, frontmatter: ParsedFrontmatter): FileKind;
+/** Parse raw file contents at a given path into a ParsedFile. */
+declare function parseFile(filePath: string, raw: string, forceKind?: FileKind): ParsedFile;
+
+/**
+ * Grading: turn a set of findings into a 0-100 score and an A-F letter grade.
+ *
+ * Security findings are weighted more heavily than lint findings, because the
+ * whole point of skilldoctor is to surface supply-chain risk. The mapping is
+ * deterministic and documented so grades are reproducible.
+ */
+
+/** Compute a 0-100 score from findings (100 = clean). */
+declare function scoreFindings(findings: readonly Finding[]): number;
+/** Map a numeric score to a letter grade. */
+declare function scoreToGrade(score: number): Grade;
+/** Tally findings by severity. */
+declare function tally(findings: readonly Finding[]): Record<Severity, number>;
+/**
+ * Aggregate per-file scores into one overall score. We use a worst-weighted
+ * average: the mean of file scores, pulled toward the single worst file so a
+ * batch with one dangerous skill cannot be averaged into a good grade.
+ */
+declare function aggregateScore(fileScores: readonly number[]): number;
+
+/**
+ * Central rule registry — the single source of truth for every rule
+ * skilldoctor can emit. SARIF requires every emitted `ruleId` to have a
+ * matching `reportingDescriptor` in `driver.rules`, so we generate that list
+ * from here. The README rule table is also derived from this.
+ */
+
+declare const RULES: readonly RuleDescriptor[];
+/** Look up a rule descriptor by id. Throws if unknown (programmer error). */
+declare function getRule(ruleId: string): RuleDescriptor;
+/** All registered rule ids. */
+declare function allRuleIds(): string[];
+
+/**
+ * --fix engine. Mechanically repairs the safe, unambiguous subset of findings.
+ *
+ * HARD RULE: we never rewrite the markdown body content (that could neutralize
+ * malicious instructions silently, or mangle legitimate prose). We only touch
+ * the YAML frontmatter, and only in deterministic, reversible ways:
+ *   1. trim trailing whitespace on frontmatter lines
+ *   2. add a missing `description:` stub with a TODO marker
+ *   3. de-duplicate tools within `allowed-tools` / `tools` (preserving order)
+ *
+ * The fixer is idempotent: running it twice produces identical output.
+ */
+
+/** Marker used for an inserted stub so humans (and tests) can find it. */
+declare const DESCRIPTION_STUB = "TODO describe what this skill does and when to use it.";
+interface FixResult {
+    /** The (possibly) rewritten file contents. */
+    output: string;
+    /** True if anything changed. */
+    changed: boolean;
+    /** Names of the fixes applied. */
+    applied: string[];
+}
+/**
+ * Apply mechanical fixes to a parsed file's raw text and return the result.
+ * Only skill/subagent files with frontmatter are fixed; AGENTS.md/unknown are
+ * returned unchanged.
+ */
+declare function fixFile(file: ParsedFile): FixResult;
+
+/**
+ * File discovery. Given path(s) — a file, a directory, or a glob — resolve the
+ * set of candidate markdown files to analyze.
+ *
+ * Deliberately dependency-free: a small recursive walker plus a minimal glob
+ * matcher cover our needs (`**`, `*`, `?`) without pulling in fast-glob/globby.
+ */
+/** True if a path string contains glob metacharacters. */
+declare function isGlob(p: string): boolean;
+/**
+ * Convert a glob to an anchored RegExp. Supports `**` (any depth, incl. zero),
+ * `*` (within a path segment), `?` (single char), and literal text. Forward
+ * slashes only (we normalize input to posix).
+ */
+declare function globToRegExp(glob: string): RegExp;
+/**
+ * Resolve one or more input specs into a deduplicated, sorted list of absolute
+ * file paths. Each spec may be a file, a directory, or a glob.
+ */
+declare function discoverFiles(specs: readonly string[]): string[];
+
+/**
+ * Terminal reporter. Human-readable, optionally colorized (auto-disabled when
+ * not a TTY or when NO_COLOR is set). No external dependency — small ANSI
+ * helpers only.
+ */
+
+interface TerminalOptions {
+    /** Force color on/off. Defaults to auto-detect. */
+    color?: boolean;
+}
+/** Render a full analysis report as a terminal string. */
+declare function renderTerminal(report: AnalysisReport, options?: TerminalOptions): string;
+
+/**
+ * JSON reporter. A stable, documented machine-readable shape of an analysis
+ * report. Keep this versioned so downstream consumers can rely on it.
+ */
+
+declare const JSON_REPORT_VERSION: 1;
+interface JsonReport {
+    /** Schema version of this JSON output. */
+    schemaVersion: typeof JSON_REPORT_VERSION;
+    /** The tool that produced it. */
+    tool: {
+        name: "skilldoctor";
+        version: string;
+    };
+    /** Aggregate grade + score. */
+    summary: {
+        grade: string;
+        score: number;
+        fileCount: number;
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+    /** Per-file results. */
+    files: AnalysisReport["files"];
+}
+/** Build the JSON report object. */
+declare function toJsonReport(report: AnalysisReport, toolVersion: string): JsonReport;
+/** Serialize the JSON report. */
+declare function jsonString(report: AnalysisReport, toolVersion: string): string;
+
+/**
+ * SARIF 2.1.0 reporter.
+ *
+ * Produces a valid SARIF log that GitHub code scanning accepts:
+ *  - exactly one run with a tool.driver
+ *  - driver.rules[] contains a reportingDescriptor for EVERY ruleId we emit
+ *    (so no result references a missing rule)
+ *  - each result has a ruleId, ruleIndex, level, message, and a physical
+ *    location with a region (1-based line/column)
+ *  - each result carries partialFingerprints for stable de-duplication across
+ *    runs (we hash ruleId + relative file + a normalized snippet, NOT the line
+ *    number, so cosmetic line shifts don't churn fingerprints)
+ *
+ * Spec ref: SARIF v2.1.0 (OASIS). Schema:
+ * https://json.schemastore.org/sarif-2.1.0.json
+ */
+
+declare const SARIF_VERSION = "2.1.0";
+declare const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+/** Build the SARIF log object for an analysis report. */
+declare function toSarif(report: AnalysisReport, options?: {
+    baseDir?: string;
+    version?: string;
+}): unknown;
+/** Serialize the SARIF log to a JSON string. */
+declare function sarifString(report: AnalysisReport, options?: {
+    baseDir?: string;
+    version?: string;
+}): string;
+
+export { AnalysisReport, AnalyzeOptions, DESCRIPTION_STUB, FileKind, FileReport, Finding, type FixResult, Grade, JSON_REPORT_VERSION, type JsonReport, ParsedFile, ParsedFrontmatter, RULES, RuleDescriptor, SARIF_SCHEMA, SARIF_VERSION, Severity, aggregateScore, allRuleIds, analyzeContent, analyzeFiles, analyzePaths, detectKind, discoverFiles, extractFrontmatter, fixFile, getRule, globToRegExp, isGlob, jsonString, parseFile, parseForFix, renderTerminal, sarifString, scoreFindings, scoreToGrade, tally, toJsonReport, toSarif };