@feiyoug/skill-lab 0.0.0 → 0.0.2

package/src/analyzer/astgrep/client.ts

@@ -0,0 +1,184 @@
+import { initializeTreeSitter, parse, registerDynamicLanguage } from "../../.npm-build-vendor/ast-grep-wasm/mod.js";
+import type {
+    Finding,
+    PermissionScope,
+    Reference,
+    ReferenceType,
+    RuleRiskMapping,
+} from "../../shared/mod.js";
+import { ensureGrammar } from "../treesitter/registry.js";
+import type { TreesitterGrammar } from "../treesitter/registry.js";
+import type { AnalyzerLogger } from "../types.js";
+import { NO_OP_LOGGER } from "../logging.js";
+
+export type AstGrepGrammar = Exclude<TreesitterGrammar, "markdown" | "markdown-inline" | "tsx">;
+
+export type AstGrepRule = {
+    id: string;
+    description: string;
+    grammar: AstGrepGrammar;
+    patterns: string[];
+    permission: {
+        tool: string;
+        scope: PermissionScope;
+        permission: string;
+        metadata?: Record<string, string>;
+        mappedRisks?: RuleRiskMapping[];
+    };
+};
+
+export type AstGrepMatch = {
+    ruleId: string;
+    line: number;
+    lineEnd?: number;
+    extracted: Record<string, unknown>;
+};
+
+type SgRoot = ReturnType<typeof parse>;
+type SgRootCache = Map<number, Map<number, SgRoot>>;
+
+export class AstGrepClient {
+    private REGISTERED_GRAMMARS = new Set<AstGrepGrammar>();
+    private SG_ROOT_CACHE_BY_CONTENT: Partial<Record<AstGrepGrammar, SgRootCache>> = {};
+
+    /** Lazy runtime init promise — created on first use, shared across all calls. */
+    private parserInitialized: boolean = false;
+
+    constructor(
+        private readonly logger: AnalyzerLogger = NO_OP_LOGGER,
+        private readonly showProgressBar: boolean = false,
+    ) {}
+
+    /** Parse content for direct AST traversal using kind/composite rules. */
+    public async parse(
+        language: AstGrepGrammar,
+        content: string,
+    ): Promise<SgRoot> {
+        await this.ensureLanguageRegistered(language);
+        const sgRootByLen = this.getSgRootCache(language);
+        const len = content.length;
+        const rootByHash = sgRootByLen.get(len);
+        if (rootByHash) {
+            const hash = this.hashContent(content);
+            const cached = rootByHash.get(hash);
+            if (cached) return cached;
+        }
+
+        const sgRoot = parse(language, content);
+        const hash = this.hashContent(content);
+        const bucket = sgRootByLen.get(len) ?? new Map<number, SgRoot>();
+        bucket.set(hash, sgRoot);
+        sgRootByLen.set(len, bucket);
+
+        return sgRoot;
+    }
+
+    public async scanWithRules(
+        content: string,
+        language: AstGrepGrammar,
+        rules: AstGrepRule[],
+    ): Promise<AstGrepMatch[]> {
+        await this.ensureLanguageRegistered(language);
+        const matches: AstGrepMatch[] = [];
+
+        try {
+            const ast = await this.parse(language, content);
+            const root = ast.root();
+
+            for (const rule of rules) {
+                for (const pattern of rule.patterns) {
+                    const nodes = root.findAll(pattern);
+
+                    for (const node of nodes) {
+                        const range = node.range();
+                        const extracted: Record<string, unknown> = { pattern };
+
+                        if (rule.permission.metadata) {
+                            for (const [key, metaVar] of Object.entries(rule.permission.metadata)) {
+                                const varNode = node.getMatch(metaVar);
+                                if (varNode) {
+                                    extracted[key] = this.stripQuotes(varNode.text());
+                                }
+                            }
+                        }
+
+                        matches.push({
+                            ruleId: rule.id,
+                            line: range.start.line + 1,
+                            lineEnd: range.end.line + 1,
+                            extracted,
+                        });
+                    }
+                }
+            }
+        } catch (error) {
+            throw new Error(`Failed to match rules: ${error}`);
+        }
+
+        return matches;
+    }
+
+    public matchesToFindings(
+        file: string,
+        type: ReferenceType,
+        matches: AstGrepMatch[],
+        referencedBy?: Reference,
+    ): Finding[] {
+        return matches.map((match) => ({
+            ruleId: match.ruleId,
+            reference: {
+                file,
+                line: match.line,
+                lineEnd: match.lineEnd,
+                type,
+                referencedBy,
+            },
+            extracted: match.extracted,
+        }));
+    }
+
+    /** Initializes the ast-grep runtime once (without registering grammars yet). */
+    private async ensureRuntimeInit() {
+        if (this.parserInitialized) return;
+
+        await initializeTreeSitter();
+    }
+
+    /** Lazily register a single grammar the first time it is needed. */
+    private async ensureLanguageRegistered(language: AstGrepGrammar) {
+        if (this.REGISTERED_GRAMMARS.has(language)) return;
+
+        await this.ensureRuntimeInit();
+        const wasmPath = await ensureGrammar(language, {
+            logger: this.logger,
+            showProgressBar: this.showProgressBar,
+        });
+        await registerDynamicLanguage({ [language]: { libraryPath: wasmPath } });
+        this.REGISTERED_GRAMMARS.add(language);
+    }
+
+    private stripQuotes(value: string): string {
+        return value
+            .replace(/^['"`]/, "")
+            .replace(/['"`]$/, "")
+            .replace(/[;,)]+$/, "")
+            .trim();
+    }
+
+    private getSgRootCache(language: AstGrepGrammar): SgRootCache {
+        if (!this.SG_ROOT_CACHE_BY_CONTENT[language]) {
+            this.SG_ROOT_CACHE_BY_CONTENT[language] = new Map<number, Map<number, SgRoot>>();
+        }
+        return this.SG_ROOT_CACHE_BY_CONTENT[language]!;
+    }
+
+    private hashContent(content: string): number {
+        // FNV-1a 32-bit (fast, non-cryptographic)
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < content.length; i++) {
+            hash ^= content.charCodeAt(i);
+            hash = Math.imul(hash, 0x01000193);
+        }
+        return hash >>> 0;
+    }
+}

package/src/analyzer/astgrep/mod.ts

@@ -0,0 +1,2 @@
+export type { AstGrepMatch, AstGrepRule } from "./client.js";
+export { AstGrepClient } from "./client.js";

package/src/analyzer/config/default.ts

@@ -0,0 +1,98 @@
+import type { TreesitterGrammar } from "../treesitter/registry.js";
+import type { AnalyzerConfig, LanguagePolicy, RiskReportConfig } from "./types.js";
+
+export const NODE_BUILTIN_IMPORTS = [
+    "buffer",
+    "child_process",
+    "crypto",
+    "events",
+    "fs",
+    "fs/promises",
+    "http",
+    "https",
+    "os",
+    "path",
+    "stream",
+    "timers",
+    "url",
+    "util",
+    "node:buffer",
+    "node:child_process",
+    "node:crypto",
+    "node:events",
+    "node:fs",
+    "node:fs/promises",
+    "node:http",
+    "node:https",
+    "node:os",
+    "node:path",
+    "node:stream",
+    "node:timers",
+    "node:url",
+    "node:util",
+] as const;
+
+export const PYTHON_BUILTIN_IMPORTS = [
+    "argparse",
+    "collections",
+    "datetime",
+    "functools",
+    "hashlib",
+    "itertools",
+    "json",
+    "logging",
+    "math",
+    "os",
+    "os.path",
+    "pathlib",
+    "re",
+    "shutil",
+    "subprocess",
+    "sys",
+    "tempfile",
+    "typing",
+    "urllib",
+    "urllib.parse",
+    "urllib.request",
+] as const;
+
+export const DEFAULT_ALLOWLIST_LANGUAGES: Partial<Record<TreesitterGrammar, LanguagePolicy>> = {
+    javascript: { imports: [...NODE_BUILTIN_IMPORTS] },
+    typescript: { imports: [...NODE_BUILTIN_IMPORTS] },
+    tsx: { imports: [...NODE_BUILTIN_IMPORTS] },
+    python: { imports: [...PYTHON_BUILTIN_IMPORTS] },
+};
+
+export const DEFAULT_RISK_REPORT_CONFIG: Required<RiskReportConfig> = {
+    baseScore: {
+        info: 0,
+        warning: 1,
+        critical: 5,
+    },
+    uplift: {
+        "NETWORK:data_exfiltration": 5,
+        "NETWORK:remote_code_execution": 5,
+        "NETWORK:credential_leak": 7,
+        "NETWORK:localhost_secret_exposure": 2,
+    },
+    thresholds: {
+        safe: 0,
+        caution: 1,
+        attention: 3,
+        risky: 5,
+        avoid: 7,
+    },
+};
+
+export const DEFAULT_ANALYZER_CONFIG: AnalyzerConfig = {
+    scan: {
+        maxFileSize: 1_000_000,
+        maxFileCount: 100,
+        maxScanDepth: 5,
+    },
+    allowlist: {
+        languages: DEFAULT_ALLOWLIST_LANGUAGES,
+    },
+    denylist: undefined,
+    riskReport: DEFAULT_RISK_REPORT_CONFIG,
+};

package/src/analyzer/config/helpers.ts

@@ -0,0 +1,107 @@
+import type { TreesitterGrammar } from "../treesitter/registry.js";
+import { DEFAULT_ANALYZER_CONFIG } from "./default.js";
+import type { Allowlist, AnalyzerConfig, LanguagePolicy, NetworkPolicy } from "./types.js";
+
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Array<infer U> ? Array<U>
+        : T[K] extends Record<string, unknown> ? DeepPartial<T[K]>
+        : T[K];
+};
+
+export function resolveConfig(partial?: Partial<AnalyzerConfig>): AnalyzerConfig {
+    const defaultScan = DEFAULT_ANALYZER_CONFIG.scan ?? {};
+    const partialScan = partial?.scan ?? {};
+    const defaultRiskReport = DEFAULT_ANALYZER_CONFIG.riskReport ?? {};
+    const partialRiskReport = partial?.riskReport ?? {};
+
+    return {
+        scan: deepMergeJson(defaultScan, partialScan),
+        allowlist: mergeAllowlist(DEFAULT_ANALYZER_CONFIG.allowlist, partial?.allowlist),
+        denylist: mergeAllowlist(DEFAULT_ANALYZER_CONFIG.denylist, partial?.denylist),
+        riskReport: deepMergeJson(defaultRiskReport, partialRiskReport),
+    };
+}
+
+export function deepMergeJson<T extends Record<string, unknown>>(
+    base: T,
+    override: DeepPartial<T>,
+): T {
+    const result: Record<string, unknown> = { ...base };
+
+    for (const key of Object.keys(override)) {
+        const baseValue = result[key];
+        const overrideValue = override[key as keyof T];
+
+        if (overrideValue === undefined) continue;
+
+        if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+            result[key] = deepMergeJson(
+                baseValue as Record<string, unknown>,
+                overrideValue as Record<string, unknown>,
+            );
+            continue;
+        }
+
+        result[key] = overrideValue;
+    }
+
+    return result as T;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (typeof value !== "object" || value === null) return false;
+    if (Array.isArray(value)) return false;
+    return Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function mergeAllowlist(
+    base: Allowlist | undefined,
+    override: Allowlist | undefined,
+): Allowlist | undefined {
+    if (!base && !override) return undefined;
+
+    const languages = mergeLanguagePolicies(base?.languages, override?.languages);
+    const network = mergeNetworkPolicy(base?.network, override?.network);
+
+    if (!languages && !network) return undefined;
+    return { languages, network };
+}
+
+function mergeLanguagePolicies(
+    base: Partial<Record<TreesitterGrammar, LanguagePolicy>> | undefined,
+    override: Partial<Record<TreesitterGrammar, LanguagePolicy>> | undefined,
+): Partial<Record<TreesitterGrammar, LanguagePolicy>> | undefined {
+    if (!base && !override) return undefined;
+
+    const keys = new Set<TreesitterGrammar>([
+        ...Object.keys(base ?? {}) as TreesitterGrammar[],
+        ...Object.keys(override ?? {}) as TreesitterGrammar[],
+    ]);
+
+    const result: Partial<Record<TreesitterGrammar, LanguagePolicy>> = {};
+    for (const key of keys) {
+        const imports = mergeStringList(base?.[key]?.imports, override?.[key]?.imports);
+        if (!imports) continue;
+        result[key] = { imports };
+    }
+
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function mergeNetworkPolicy(
+    base: NetworkPolicy | undefined,
+    override: NetworkPolicy | undefined,
+): NetworkPolicy | undefined {
+    if (!base && !override) return undefined;
+    const domains = mergeStringList(base?.domains, override?.domains);
+    return domains ? { domains } : undefined;
+}
+
+function mergeStringList(
+    base: string[] | undefined,
+    override: string[] | undefined,
+): string[] | undefined {
+    if (!base && !override) return undefined;
+    const values = new Set<string>([...(base ?? []), ...(override ?? [])]);
+    return values.size > 0 ? [...values] : undefined;
+}

package/src/analyzer/config/mod.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./default.js";
+export { resolveConfig } from "./helpers.js";

package/src/analyzer/config/types.ts

@@ -0,0 +1,103 @@
+import type { RiskCode } from "../../shared/mod.js";
+import { PermissionScope } from "../../shared/mod.js";
+import type { TreesitterGrammar } from "../treesitter/registry.js";
+
+export const DEFAULT_SKILL_VERSION = "0.0.1";
+
+export type LanguagePolicy = {
+    imports?: string[];
+};
+
+export type NetworkPolicy = {
+    domains?: string[];
+};
+
+export type ScanConfig = {
+    maxFileSize?: number;
+    maxFileCount?: number;
+    maxScanDepth?: number;
+};
+
+export type Allowlist = {
+    languages?: Partial<Record<TreesitterGrammar, LanguagePolicy>>;
+    network?: NetworkPolicy;
+};
+
+export type Denylist = {
+    languages?: Partial<Record<TreesitterGrammar, LanguagePolicy>>;
+    network?: NetworkPolicy;
+};
+
+export type AnalyzerConfig = {
+    scan?: ScanConfig;
+    allowlist?: Allowlist;
+    denylist?: Denylist;
+    riskReport?: RiskReportConfig;
+};
+
+export type RiskUpliftConfig = Partial<Record<RiskCode, number>>;
+
+export type RiskThresholdConfig = {
+    safe: number;
+    caution: number;
+    attention: number;
+    risky: number;
+    avoid: number;
+};
+
+export type RiskReportConfig = {
+    baseScore?: {
+        info?: number;
+        warning?: number;
+        critical?: number;
+    };
+    uplift?: RiskUpliftConfig;
+    thresholds?: Partial<RiskThresholdConfig>;
+};
+
+export const ALLOWED_TOOLS_MAPPING: Record<
+    string,
+    { tool: string; scope: PermissionScope; permission: string }
+> = {
+    Bash: { tool: "bash", scope: "sys", permission: "shell" },
+    Read: { tool: "read", scope: "fs", permission: "read" },
+    Write: { tool: "write", scope: "fs", permission: "write" },
+    Edit: { tool: "edit", scope: "fs", permission: "write" },
+    WebFetch: { tool: "webfetch", scope: "net", permission: "fetch" },
+    Fetch: { tool: "fetch", scope: "net", permission: "fetch" },
+    Subprocess: { tool: "subprocess", scope: "sys", permission: "subprocess" },
+};
+
+export const TOOLS_MAPPING: Record<string, { scope: PermissionScope; permission: string }> = {
+    gh: { scope: "sys", permission: "shell" },
+    git: { scope: "sys", permission: "shell" },
+    jq: { scope: "sys", permission: "shell" },
+    curl: { scope: "net", permission: "fetch" },
+    wget: { scope: "net", permission: "fetch" },
+    npm: { scope: "sys", permission: "shell" },
+    pnpm: { scope: "sys", permission: "shell" },
+    yarn: { scope: "sys", permission: "shell" },
+    python: { scope: "sys", permission: "shell" },
+    node: { scope: "sys", permission: "shell" },
+    deno: { scope: "sys", permission: "shell" },
+    docker: { scope: "sys", permission: "shell" },
+};
+
+export const UNSUPPORTED_SKILL_FRONTMATTER_FIELDS = [
+    "argument-hint",
+    "disable-model-invocation",
+    "user-invocable",
+    "model",
+    "context",
+    "agent",
+    "hooks",
+] as const;
+
+export const FRONTMATTER_SUPPORTED_FIELDS = [
+    "name",
+    "description",
+    "license",
+    "compatibility",
+    "metadata",
+    "allowed-tools",
+] as const;

package/src/analyzer/logging.ts

@@ -0,0 +1,8 @@
+import type { AnalyzerLogger } from "./types.js";
+
+export const NO_OP_LOGGER: AnalyzerLogger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+};

package/src/analyzer/mod.ts

@@ -0,0 +1,118 @@
+import { DEFAULT_ANALYZER_CONFIG, DEFAULT_SKILL_VERSION, resolveConfig } from "./config/mod.js";
+import { NO_OP_LOGGER } from "./logging.js";
+import { SkillAnalyzerResult } from "./result.js";
+import { run001Discovery, run002Permissions, run003Risks } from "./steps/mod.js";
+import type { AnalyzerConfig, AnalyzerLogger, AnalyzerState } from "./types.js";
+import type { SkillReaderFactoryOptions } from "../skillreader/factory.js";
+import { SkillReaderFactory } from "../skillreader/factory.js";
+import { TreesitterClient } from "./treesitter/client.js";
+import { AstGrepClient } from "./astgrep/mod.js";
+
+export type { AnalyzerConfig, AnalyzerLogger, AnalyzerState } from "./types.js";
+export type {
+    Allowlist,
+    Denylist,
+    LanguagePolicy,
+    NetworkPolicy,
+    RiskReportConfig,
+    ScanConfig,
+} from "./config/mod.js";
+
+export { SkillAnalyzerResult } from "./result.js";
+export { DEFAULT_ANALYZER_CONFIG, DEFAULT_SKILL_VERSION, resolveConfig } from "./config/mod.js";
+
+export type AnalyzerAnalyzeInput = SkillReaderFactoryOptions & {
+    skillId?: string;
+    skillVersionId?: string;
+    config?: Partial<AnalyzerConfig>;
+    logger?: AnalyzerLogger;
+    showProgressBar?: boolean;
+};
+
+export class Analyzer {
+    analyze(input: AnalyzerAnalyzeInput): Promise<SkillAnalyzerResult> {
+        return runAnalysis({
+            options: {
+                source: input.source,
+                subDir: input.subDir,
+                gitRef: input.gitRef,
+                githubToken: input.githubToken,
+            },
+            skillId: input.skillId,
+            skillVersionId: input.skillVersionId,
+            config: input.config,
+            logger: input.logger,
+            showProgressBar: input.showProgressBar,
+        });
+    }
+}
+
+export async function runAnalysis(input: {
+    options: SkillReaderFactoryOptions;
+    skillId?: string;
+    skillVersionId?: string;
+    config?: Partial<AnalyzerConfig>;
+    logger?: AnalyzerLogger;
+    showProgressBar?: boolean;
+}): Promise<SkillAnalyzerResult> {
+    const config = resolveConfig(input.config);
+
+    let state = createInitialState({
+        skillId: input.skillId,
+        skillVersionId: input.skillVersionId,
+        config,
+    });
+
+    const skillReader = await SkillReaderFactory.create(input.options);
+
+    const validation = await skillReader.validate();
+    if (!validation.ok) {
+        throw new Error(validation.reason ?? "Invalid skill repository");
+    }
+
+    const logger = input.logger ?? NO_OP_LOGGER;
+    const showProgressBar = input.showProgressBar ?? false;
+
+    const context = {
+        skillReader,
+        treesitterClient: new TreesitterClient(logger, showProgressBar),
+        astgrepClient: new AstGrepClient(logger, showProgressBar),
+        logger,
+        showProgressBar,
+        config,
+    };
+
+    state = await run001Discovery(state, context);
+    state = await run002Permissions(state, context);
+    return await run003Risks(state, context);
+}
+
+export function createInitialState(input?: {
+    skillId?: string;
+    skillVersionId?: string;
+    config?: Partial<AnalyzerConfig>;
+}): AnalyzerState {
+    const resolvedConfig = resolveConfig(input?.config);
+    const scan = resolvedConfig.scan ?? DEFAULT_ANALYZER_CONFIG.scan ?? {
+        maxFileSize: 1_000_000,
+        maxFileCount: 100,
+        maxScanDepth: 5,
+    };
+    return {
+        skillId: input?.skillId ?? "unknown",
+        skillVersionId: input?.skillVersionId ?? DEFAULT_SKILL_VERSION,
+        files: [],
+        frontmatter: {},
+        scanQueue: [],
+        permissions: [],
+        findings: [],
+        risks: [],
+        warnings: [],
+        metadata: {
+            scannedFiles: new Set<string>(),
+            skippedFiles: [],
+            rulesUsed: [],
+            config: scan,
+        },
+    };
+}