@feiyoug/skill-lab 0.0.0 → 0.0.2

package/src/analyzer/result.ts

@@ -0,0 +1,393 @@
+import type { Permission, Risk } from "../shared/mod.js";
+import { scoreState } from "./steps/003-risks/scoring.js";
+import { DEFAULT_ANALYZER_CONFIG } from "./config/mod.js";
+import type { AnalyzerConfig } from "./config/mod.js";
+import type { AnalyzerState, ScanConfig } from "./types.js";
+
+const INDENT = "  ";
+const SUB_INDENT = "    ";
+
+// ---------------------------------------------------------------------------
+// SARIF types (minimal — only what we emit)
+// ---------------------------------------------------------------------------
+
+type SarifArtifactLocation = {
+    uri: string;
+    uriBaseId?: string;
+};
+
+type SarifRegion = {
+    startLine: number;
+    endLine?: number;
+};
+
+type SarifLocation = {
+    physicalLocation: {
+        artifactLocation: SarifArtifactLocation;
+        region: SarifRegion;
+    };
+};
+
+type SarifResult = {
+    ruleId: string;
+    level: "error" | "warning" | "note";
+    message: { text: string };
+    locations: SarifLocation[];
+    fingerprints?: Record<string, string>;
+};
+
+type SarifRule = {
+    id: string;
+    shortDescription: { text: string };
+    help: { text: string };
+    properties?: { tags: string[] };
+};
+
+type SarifLog = {
+    $schema: string;
+    version: "2.1.0";
+    runs: Array<{
+        tool: {
+            driver: {
+                name: string;
+                version: string;
+                informationUri: string;
+                rules: SarifRule[];
+            };
+        };
+        results: SarifResult[];
+        artifacts: Array<{ location: SarifArtifactLocation }>;
+    }>;
+};
+
+// ---------------------------------------------------------------------------
+// SkillAnalyzerResult class
+// ---------------------------------------------------------------------------
+
+export class SkillAnalyzerResult {
+    readonly analyzedAt: string;
+
+    private _score: number | undefined;
+    private _riskLevel: "safe" | "caution" | "attention" | "risky" | "avoid" | undefined;
+    private _summary: string | undefined;
+
+    constructor(
+        private readonly state: AnalyzerState,
+        private readonly config: AnalyzerConfig = DEFAULT_ANALYZER_CONFIG,
+    ) {
+        this.analyzedAt = new Date().toISOString();
+    }
+
+    get skillId(): string {
+        return this.state.skillId;
+    }
+
+    get skillVersionId(): string {
+        return this.state.skillVersionId;
+    }
+
+    get permissions(): Permission[] {
+        return this.state.permissions;
+    }
+
+    get risks(): Risk[] {
+        return this.state.risks;
+    }
+
+    get warnings(): string[] {
+        return this.state.warnings;
+    }
+
+    get metadata(): {
+        scannedFiles: Set<string>;
+        skippedFiles: Array<{ path: string; reason: string }>;
+        rulesUsed: string[];
+        frontmatterRangeEnd?: number;
+        config: ScanConfig;
+    } {
+        return this.state.metadata;
+    }
+
+    get score(): number {
+        return this._ensureScored().score;
+    }
+
+    get riskLevel(): "safe" | "caution" | "attention" | "risky" | "avoid" {
+        return this._ensureScored().riskLevel;
+    }
+
+    get summary(): string {
+        return this._ensureScored().summary;
+    }
+
+    private _ensureScored() {
+        if (this._score === undefined) {
+            const scored = scoreState(this.state, this.config);
+            this._score = scored.score;
+            this._riskLevel = scored.riskLevel;
+            this._summary = scored.summary;
+        }
+        return {
+            score: this._score!,
+            riskLevel: this._riskLevel!,
+            summary: this._summary!,
+        };
+    }
+
+    // -----------------------------------------------------------------------
+    // toString() — human-readable terminal output
+    // -----------------------------------------------------------------------
+
+    toString(): string {
+        const lines: string[] = [];
+        const hr = "=".repeat(60);
+
+        lines.push(hr);
+        lines.push("Analysis Results");
+        lines.push(hr);
+        lines.push(`${INDENT}Skill: ${this.skillId}@${this.skillVersionId}`);
+
+        // lines.push("");
+        // lines.push(`${INDENT}Permissions (${this.permissions.length})`);
+        // if (this.permissions.length === 0) {
+        //     lines.push(`${SUB_INDENT}- none`);
+        // } else {
+        //     for (const p of this.permissions) {
+        //         lines.push(`${SUB_INDENT}- ${p.tool}.${p.permission} [${p.scope}]`);
+        //         if (p.args && p.args.length > 0) {
+        //             lines.push(`${SUB_INDENT}${INDENT}args: ${p.args.join(", ")}`);
+        //         }
+        //         lines.push(`${SUB_INDENT}${INDENT}source: ${p.source}`);
+        //         if (p.references.length > 0) {
+        //             lines.push(
+        //                 `${SUB_INDENT}${INDENT}ref: ${_formatRef(p.references[0])}`,
+        //             );
+        //         }
+        //     }
+        // }
+
+        lines.push("");
+        lines.push(`${INDENT}Risks (${this.risks.length})`);
+        if (this.risks.length === 0) {
+            lines.push(`${SUB_INDENT}- none`);
+        } else {
+            const SEVERITY_ORDER: Record<string, number> = { critical: 0, warning: 1, info: 2 };
+
+            const groups = new Map<string, Risk[]>();
+            for (const r of this.risks) {
+                const key = r.groupKey ?? `${r.type}:${r.reference.file}:${r.reference.line}`;
+                const bucket = groups.get(key) ?? [];
+                bucket.push(r);
+                groups.set(key, bucket);
+            }
+
+            const sortedGroups = Array.from(groups.entries())
+                .map(([groupKey, risks]) => ({
+                    groupKey,
+                    risks,
+                    sortKey: Math.min(...risks.map((r) => SEVERITY_ORDER[r.severity] ?? 99)),
+                }))
+                .sort((a, b) => a.sortKey - b.sortKey);
+
+            for (const group of sortedGroups) {
+                if (group.risks.length === 1) {
+                    const r = group.risks[0];
+                    lines.push(`${SUB_INDENT}- ${r.severity} ${r.type}`);
+                    lines.push(`${SUB_INDENT}${INDENT}message: ${r.message}`);
+                    lines.push(`${SUB_INDENT}${INDENT}ref: ${_formatRef(r.reference)}`);
+                    if (r.permissions.length > 0) {
+                        lines.push(
+                            `${SUB_INDENT}${INDENT}permissions: ${r.permissions.join(", ")}`,
+                        );
+                    }
+                    continue;
+                }
+
+                const topRisk = group.risks.reduce((best, r) =>
+                    (SEVERITY_ORDER[r.severity] ?? 99) < (SEVERITY_ORDER[best.severity] ?? 99)
+                        ? r
+                        : best
+                );
+                lines.push(`${SUB_INDENT}[${group.groupKey}] (${topRisk.severity})`);
+                for (const r of group.risks) {
+                    lines.push(`${SUB_INDENT}${INDENT}- ${r.message}`);
+                    lines.push(`${SUB_INDENT}${INDENT}  ref: ${_formatRef(r.reference)}`);
+                }
+            }
+        }
+
+        lines.push("");
+        lines.push(`${INDENT}Warnings (${this.warnings.length})`);
+        if (this.warnings.length === 0) {
+            lines.push(`${SUB_INDENT}- none`);
+        } else {
+            for (const w of this.warnings) {
+                lines.push(`${SUB_INDENT}- ${w}`);
+            }
+        }
+
+        lines.push("");
+        lines.push(`${INDENT}Risk Level: ${this.riskLevel}`);
+        lines.push(`${INDENT}Score: ${this.score}`);
+        lines.push(`${INDENT}Summary: ${this.summary}`);
+
+        return lines.join("\n");
+    }
+
+    // -----------------------------------------------------------------------
+    // toJson() — plain JSON matching legacy AnalyzerResult shape
+    // -----------------------------------------------------------------------
+
+    toJson(): string {
+        return JSON.stringify(
+            {
+                analyzedAt: this.analyzedAt,
+                skillId: this.skillId,
+                skillVersionId: this.skillVersionId,
+                permissions: this.permissions,
+                risks: this.risks,
+                score: this.score,
+                riskLevel: this.riskLevel,
+                summary: this.summary,
+                warnings: this.warnings,
+                metadata: {
+                    ...this.metadata,
+                    scannedFiles: [...this.metadata.scannedFiles],
+                },
+            },
+            null,
+            2,
+        );
+    }
+
+    // -----------------------------------------------------------------------
+    // toSarif() — SARIF 2.1.0 for GitHub Code Scanning
+    // -----------------------------------------------------------------------
+
+    async toSarif(toolVersion: string): Promise<string> {
+        // --- rules ---
+        const rules: SarifRule[] = [];
+        const seenRiskTypes = new Set<string>();
+
+        for (const r of this.risks) {
+            if (!seenRiskTypes.has(r.type)) {
+                seenRiskTypes.add(r.type);
+                rules.push({
+                    id: r.type,
+                    shortDescription: { text: r.type },
+                    help: { text: r.message },
+                    properties: { tags: ["security"] },
+                });
+            }
+        }
+
+        if (this.warnings.length > 0) {
+            rules.push({
+                id: "slab/warning",
+                shortDescription: { text: "Analysis warning" },
+                help: { text: "Warnings produced during skill analysis." },
+                properties: { tags: ["maintainability"] },
+            });
+        }
+
+        for (const p of this.permissions) {
+            rules.push({
+                id: p.id,
+                shortDescription: { text: `${p.tool}.${p.permission} [${p.scope}]` },
+                help: {
+                    text: p.comment ??
+                        `Permission detected: ${p.tool} ${p.permission} (${p.scope})`,
+                },
+                properties: { tags: ["permissions"] },
+            });
+        }
+
+        // --- results ---
+        const results: SarifResult[] = [];
+
+        for (const r of this.risks) {
+            const fp = await _fingerprint(`${r.type}:${r.reference.file}:${r.reference.line}`);
+            results.push({
+                ruleId: r.type,
+                level: _sarifLevel(r.severity),
+                message: { text: r.message },
+                locations: [
+                    _sarifLocation(r.reference.file, r.reference.line, r.reference.lineEnd),
+                ],
+                fingerprints: { "slab/v1": fp },
+            });
+        }
+
+        for (const w of this.warnings) {
+            results.push({
+                ruleId: "slab/warning",
+                level: "note",
+                message: { text: w },
+                locations: [_sarifLocation("SKILL.md", 1)],
+            });
+        }
+
+        // --- artifacts ---
+        const artifacts = [...this.metadata.scannedFiles].map((f) => ({
+            location: { uri: f, uriBaseId: "%SRCROOT%" },
+        }));
+
+        const log: SarifLog = {
+            $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+            version: "2.1.0",
+            runs: [
+                {
+                    tool: {
+                        driver: {
+                            name: "slab",
+                            version: toolVersion,
+                            informationUri: "https://github.com/FeiyouG/skill-lab",
+                            rules,
+                        },
+                    },
+                    results,
+                    artifacts,
+                },
+            ],
+        };
+
+        return JSON.stringify(log, null, 2);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function _formatRef(ref: { file: string; line: number; lineEnd?: number; type: string }): string {
+    if (ref.lineEnd !== undefined && ref.lineEnd !== ref.line) {
+        return `${ref.file}:${ref.line}-${ref.lineEnd} (${ref.type})`;
+    }
+    return `${ref.file}:${ref.line} (${ref.type})`;
+}
+
+function _sarifLevel(severity: string): "error" | "warning" | "note" {
+    if (severity === "critical") return "error";
+    if (severity === "warning") return "warning";
+    return "note";
+}
+
+function _sarifLocation(file: string, startLine: number, endLine?: number): SarifLocation {
+    const region: SarifRegion = { startLine };
+    if (endLine !== undefined && endLine !== startLine) {
+        region.endLine = endLine;
+    }
+    return {
+        physicalLocation: {
+            artifactLocation: { uri: file, uriBaseId: "%SRCROOT%" },
+            region,
+        },
+    };
+}
+
+async function _fingerprint(input: string): Promise<string> {
+    const encoded = new TextEncoder().encode(input);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/analyzer/rules/bash/astTypes.ts

@@ -0,0 +1,5 @@
+/** ast-grep node types for Bash (via @ast-grep/lang-bash). */
+export const BASH_NODE = {
+    COMMAND: "command",
+    WORD: "word",
+} as const;

package/src/analyzer/rules/bash/commands/bd.ts

@@ -0,0 +1,23 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const BD_RULES: AstGrepRule[] = [
+    {
+        id: "shell-bd",
+        description: "Detects bd task commands",
+        grammar: "bash",
+        patterns: [
+            "bd ready",
+            "bd show $ID",
+            "bd update $ID $$$ARGS",
+            "bd close $ID",
+            "bd sync",
+            "bd create $$$ARGS",
+        ],
+        permission: {
+            tool: "bd",
+            scope: "sys",
+            permission: "shell",
+            metadata: { id: "ID" },
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/cron.ts

@@ -0,0 +1,21 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const CRON_RULES: AstGrepRule[] = [
+    {
+        id: "shell-cron",
+        description: "Detects cron persistence",
+        grammar: "bash",
+        patterns: ["crontab $FILE", "echo $ENTRY | crontab -"],
+        permission: {
+            tool: "crontab",
+            scope: "sys",
+            permission: "shell",
+            metadata: { file: "FILE" },
+            mappedRisks: [{
+                code: "PERSISTENCE:persistence",
+                severity: "warning",
+                message: "Persistence mechanism detected",
+            }],
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/docker.ts

@@ -0,0 +1,37 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const DOCKER_RULES: AstGrepRule[] = [
+    {
+        id: "shell-docker",
+        description: "Detects docker commands",
+        grammar: "bash",
+        patterns: [
+            "docker run $$$ARGS",
+            "docker exec $$$ARGS",
+            "docker build $$$ARGS",
+            "docker pull $$$ARGS",
+            "docker push $$$ARGS",
+        ],
+        permission: {
+            tool: "docker",
+            scope: "sys",
+            permission: "shell",
+        },
+    },
+    {
+        id: "shell-docker-compose",
+        description: "Detects docker compose commands",
+        grammar: "bash",
+        patterns: [
+            "docker-compose up $$$ARGS",
+            "docker-compose down $$$ARGS",
+            "docker compose up $$$ARGS",
+            "docker compose down $$$ARGS",
+        ],
+        permission: {
+            tool: "docker-compose",
+            scope: "sys",
+            permission: "shell",
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/eval.ts

@@ -0,0 +1,52 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const EVAL_RULES: AstGrepRule[] = [
+    {
+        id: "shell-eval",
+        description: "Detects eval execution",
+        grammar: "bash",
+        patterns: ["eval $CMD", 'eval "$CMD"', "eval '$CMD'"],
+        permission: {
+            tool: "eval",
+            scope: "sys",
+            permission: "shell",
+            metadata: { command: "CMD" },
+        },
+    },
+    {
+        id: "shell-sh-c",
+        description: "Detects sh -c execution",
+        grammar: "bash",
+        patterns: ["sh -c $CMD", 'sh -c "$CMD"', "sh -c '$CMD'"],
+        permission: {
+            tool: "sh",
+            scope: "sys",
+            permission: "shell",
+            metadata: { command: "CMD" },
+        },
+    },
+    {
+        id: "shell-bash-c",
+        description: "Detects bash -c execution",
+        grammar: "bash",
+        patterns: ["bash -c $CMD", 'bash -c "$CMD"', "bash -c '$CMD'"],
+        permission: {
+            tool: "bash",
+            scope: "sys",
+            permission: "shell",
+            metadata: { command: "CMD" },
+        },
+    },
+    {
+        id: "shell-source",
+        description: "Detects source command",
+        grammar: "bash",
+        patterns: ["source $FILE", ". $FILE"],
+        permission: {
+            tool: "source",
+            scope: "fs",
+            permission: "read",
+            metadata: { file: "FILE" },
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/generic.ts

@@ -0,0 +1,16 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const GENERIC_SHELL_RULES: AstGrepRule[] = [
+    {
+        id: "shell-generic-command",
+        description: "Catches unrecognized shell command invocations",
+        grammar: "bash",
+        patterns: ["$TOOL $$$ARGS"],
+        permission: {
+            tool: "detected",
+            scope: "sys",
+            permission: "shell",
+            metadata: { tool: "TOOL", args: "ARGS" },
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/gh.ts

@@ -0,0 +1,21 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const GH_RULES: AstGrepRule[] = [
+    {
+        id: "shell-gh",
+        description: "Detects GitHub CLI commands",
+        grammar: "bash",
+        patterns: [
+            "gh pr $$$ARGS",
+            "gh issue $$$ARGS",
+            "gh repo $$$ARGS",
+            "gh api $$$ARGS",
+            "gh auth $$$ARGS",
+        ],
+        permission: {
+            tool: "gh",
+            scope: "sys",
+            permission: "shell",
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/git.ts

@@ -0,0 +1,28 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+
+export const GIT_RULES: AstGrepRule[] = [
+    {
+        id: "shell-git",
+        description: "Detects git commands",
+        grammar: "bash",
+        patterns: [
+            "git status",
+            "git add $PATH",
+            "git commit $$$ARGS",
+            "git pull $$$ARGS",
+            "git push $$$ARGS",
+            "git checkout $BRANCH",
+            "git merge $BRANCH",
+            "git rebase $BRANCH",
+            "git clone $URL",
+            "git fetch $$$ARGS",
+            "git log $$$ARGS",
+        ],
+        permission: {
+            tool: "git",
+            scope: "sys",
+            permission: "shell",
+            metadata: { url: "URL", branch: "BRANCH", path: "PATH" },
+        },
+    },
+];

package/src/analyzer/rules/bash/commands/mod.ts

@@ -0,0 +1,38 @@
+import type { AstGrepRule } from "../../../astgrep/client.js";
+import { BD_RULES } from "./bd.js";
+import { CRON_RULES } from "./cron.js";
+import { DOCKER_RULES } from "./docker.js";
+import { EVAL_RULES } from "./eval.js";
+import { GENERIC_SHELL_RULES } from "./generic.js";
+import { GH_RULES } from "./gh.js";
+import { GIT_RULES } from "./git.js";
+import { NODE_ECOSYSTEM_RULES } from "./node.js";
+import { OPENSPEC_RULES } from "./openspec.js";
+import { PIP_RULES } from "./pip.js";
+import { SUDO_RULES } from "./sudo.js";
+
+export * from "./bd.js";
+export * from "./cron.js";
+export * from "./docker.js";
+export * from "./eval.js";
+export * from "./generic.js";
+export * from "./gh.js";
+export * from "./git.js";
+export * from "./node.js";
+export * from "./openspec.js";
+export * from "./pip.js";
+export * from "./sudo.js";
+
+export const BASH_COMMAND_RULES: AstGrepRule[] = [
+    ...GIT_RULES,
+    ...GH_RULES,
+    ...NODE_ECOSYSTEM_RULES,
+    ...PIP_RULES,
+    ...DOCKER_RULES,
+    ...BD_RULES,
+    ...SUDO_RULES,
+    ...EVAL_RULES,
+    ...OPENSPEC_RULES,
+    ...CRON_RULES,
+    ...GENERIC_SHELL_RULES,
+];