@gobing-ai/ts-rule-engine 0.2.6 → 0.2.8

package/src/evaluators/path-evaluator.ts

@@ -7,8 +7,18 @@ import {
     type RuleEvaluationResult,
     type RuleEvaluator,
 } from '../types';
+import { discoverFiles, matchesGlob } from './file-utils';
 
-/** Evaluates file or directory existence constraints. */
+/**
+ * Evaluates file/directory presence constraints.
+ *
+ * Two config shapes are supported:
+ * - Glob form: `{ must: 'present' | 'absent' }` scoped by the rule's `include` /
+ *   `exclude` globs. `present` flags each include glob that matches zero files;
+ *   `absent` flags each in-scope file that exists.
+ * - Explicit form: `{ paths: string[], mode?: 'require' | 'forbid' }` — checks the
+ *   exact paths relative to the workdir (`require` = must exist, `forbid` = must not).
+ */
 export class PathEvaluator implements RuleEvaluator {
     private readonly fs: NodeFileSystem;
 
@@ -16,9 +26,62 @@ export class PathEvaluator implements RuleEvaluator {
         this.fs = new NodeFileSystem();
     }
 
-    /** Evaluate required or forbidden paths. */
+    /** Evaluate required or forbidden paths in either config form. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         const config = rule.evaluator.config ?? {};
+        const must = config.must;
+        if (must === 'present' || must === 'absent') {
+            return this.evaluateGlob(rule, context, must);
+        }
+        return this.evaluateExplicit(rule, context, config);
+    }
+
+    /** Glob form driven by `must` + the rule's include/exclude globs. */
+    private async evaluateGlob(
+        rule: ConstraintRule,
+        context: RuleContext,
+        must: 'present' | 'absent',
+    ): Promise<RuleEvaluationResult> {
+        const include = rule.include ?? ['**'];
+        const exclude = rule.exclude ?? [];
+        const files = await discoverFiles({ workdir: context.workdir });
+        const inScope = (file: string) =>
+            include.some((glob) => matchesGlob(file, glob)) && !exclude.some((glob) => matchesGlob(file, glob));
+        const findings = [];
+
+        if (must === 'present') {
+            for (const pattern of include) {
+                const present = files.some(
+                    (file) => matchesGlob(file, pattern) && !exclude.some((g) => matchesGlob(file, g)),
+                );
+                if (!present) {
+                    findings.push(
+                        createFinding(rule, `expected files matching "${pattern}", but none found`, pattern, {
+                            code: 'path:missing',
+                        }),
+                    );
+                }
+            }
+        } else {
+            for (const file of files) {
+                if (inScope(file)) {
+                    findings.push(
+                        createFinding(rule, 'file should be absent (forbidden by rule)', file, {
+                            code: 'path:forbidden',
+                        }),
+                    );
+                }
+            }
+        }
+        return { findings, fixes: [] };
+    }
+
+    /** Explicit form: exact `paths` checked with `mode` require/forbid. */
+    private async evaluateExplicit(
+        rule: ConstraintRule,
+        context: RuleContext,
+        config: Record<string, unknown>,
+    ): Promise<RuleEvaluationResult> {
         const paths = arrayConfig(config, 'paths');
         const mode = stringConfig(config, 'mode', 'require');
         const findings = [];
@@ -39,7 +102,7 @@ function arrayConfig(config: Record<string, unknown>, key: string): string[] {
     const value = config[key];
     if (Array.isArray(value) && value.every((item) => typeof item === 'string')) return value;
     if (typeof value === 'string') return [value];
-    throw new Error(`path evaluator requires string[] config "${key}"`);
+    throw new Error(`path evaluator requires config "${key}" (string[]) or "must" (present|absent)`);
 }
 
 function stringConfig(config: Record<string, unknown>, key: string, fallback: string): string {

package/src/evaluators/regex-evaluator.ts

@@ -14,26 +14,38 @@ export class RegexEvaluator implements RuleEvaluator {
     /** Evaluate regex-based presence or absence constraints. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         const config = rule.evaluator.config ?? {};
-        const pattern = stringConfig(config, 'pattern');
+        const { pattern, flags } = normalizePattern(
+            stringConfig(config, 'pattern'),
+            stringConfig(config, 'flags', ''),
+            config.multiline === true,
+        );
         const mode = stringConfig(config, 'mode', 'forbid');
-        const flags = stringConfig(config, 'flags', 'm');
         const regex = new RegExp(pattern, flags);
         const files = await discoverFiles({ workdir: context.workdir, include: rule.include, exclude: rule.exclude });
         const findings = [];
 
         for (const file of files) {
             const content = await readWorkdirFile(context.workdir, file);
-            regex.lastIndex = 0;
-            const match = regex.exec(content);
-            if (mode === 'require' && match === null) {
-                findings.push(
-                    createFinding(rule, `Required pattern not found: ${pattern}`, file, { code: 'regex:missing' }),
-                );
+            if (mode === 'require') {
+                regex.lastIndex = 0;
+                if (!regex.test(content)) {
+                    findings.push(
+                        createFinding(rule, `required pattern not found: ${pattern}`, file, { code: 'regex:missing' }),
+                    );
+                }
+                continue;
             }
-            if (mode !== 'require' && match !== null) {
-                findings.push(
-                    createFinding(rule, `Forbidden pattern found: ${pattern}`, file, { code: 'regex:found' }),
-                );
+            // forbid: report each matching line so findings carry precise locations.
+            for (const [index, line] of content.split('\n').entries()) {
+                regex.lastIndex = 0;
+                if (regex.test(line)) {
+                    findings.push(
+                        createFinding(rule, `forbidden pattern found: ${pattern}`, file, {
+                            line: index + 1,
+                            code: 'regex:found',
+                        }),
+                    );
+                }
             }
         }
 
@@ -41,6 +53,35 @@ export class RegexEvaluator implements RuleEvaluator {
     }
 }
 
+/**
+ * Normalize a pattern + flags for JS `RegExp`.
+ *
+ * Accepts a leading `(?i)`/`(?im)` inline flag group (ripgrep/PCRE style) and
+ * folds it into the JS flags. `multiline` adds the `s` (dotAll) flag so `.`
+ * spans newlines, matching the old `--multiline` behavior. `m` is always set so
+ * `^`/`$` work per line.
+ */
+function normalizePattern(
+    rawPattern: string,
+    rawFlags: string,
+    multiline: boolean,
+): { pattern: string; flags: string } {
+    const flagSet = new Set<string>(['m']);
+    for (const flag of rawFlags) {
+        if ('gimsuy'.includes(flag)) flagSet.add(flag);
+    }
+    let pattern = rawPattern;
+    const inline = /^\(\?([a-z]+)\)/.exec(pattern);
+    if (inline) {
+        for (const flag of inline[1] ?? '') {
+            if ('imsu'.includes(flag)) flagSet.add(flag);
+        }
+        pattern = pattern.slice(inline[0].length);
+    }
+    if (multiline) flagSet.add('s');
+    return { pattern, flags: [...flagSet].join('') };
+}
+
 function stringConfig(config: Record<string, unknown>, key: string, fallback?: string): string {
     const value = config[key];
     if (typeof value === 'string') return value;

package/src/evaluators/schema-artifact-evaluator.ts

@@ -0,0 +1,134 @@
+import { resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+
+/**
+ * Evaluates JSON schema artifact files for structural integrity.
+ *
+ * Pure JS — no subprocess. Validates JSON validity, title, required properties,
+ * `$defs` / `definitions` entries, and the presence of a top-level `required` array.
+ *
+ * ## Options (in `evaluator.config`)
+ * - `file` — path to the JSON file relative to the workdir (required).
+ * - `requiredTitle` — expected `title` value (optional).
+ * - `requiredProperties` — top-level `properties` keys that must exist (optional).
+ * - `requiredDefs` — `$defs` or `definitions` keys that must exist (optional).
+ * - `requireRequiredArray` — enforce that `required` is a non-empty array (default: `false`).
+ */
+export class SchemaArtifactEvaluator implements RuleEvaluator {
+    private readonly fs: NodeFileSystem;
+
+    constructor() {
+        this.fs = new NodeFileSystem();
+    }
+
+    /** Evaluate the configured JSON schema artifact. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const config = rule.evaluator.config ?? {};
+        const file = config.file;
+        if (typeof file !== 'string' || file.length === 0) {
+            throw new Error('schema-artifact evaluator requires string config "file"');
+        }
+
+        const requiredTitle = typeof config.requiredTitle === 'string' ? config.requiredTitle : undefined;
+        const requiredProperties = stringArray(config.requiredProperties);
+        const requiredDefs = stringArray(config.requiredDefs);
+        const requireRequiredArray = config.requireRequiredArray === true;
+
+        // Check existence.
+        const absolutePath = resolve(context.workdir, file);
+        const exists = await this.fs.exists(absolutePath);
+        if (!exists) {
+            return {
+                findings: [
+                    createFinding(rule, 'schema artifact not found', file, {
+                        code: 'schema-artifact:missing',
+                    }),
+                ],
+                fixes: [],
+            };
+        }
+
+        // Read and parse.
+        let schema: Record<string, unknown>;
+        try {
+            const raw = await this.fs.readFile(absolutePath);
+            schema = JSON.parse(raw) as Record<string, unknown>;
+        } catch (err) {
+            return {
+                findings: [
+                    createFinding(rule, `invalid JSON: ${(err as Error).message}`, file, {
+                        code: 'schema-artifact:invalid',
+                    }),
+                ],
+                fixes: [],
+            };
+        }
+
+        const findings = [];
+
+        // Validate title.
+        if (requiredTitle !== undefined && schema.title !== requiredTitle) {
+            findings.push(
+                createFinding(
+                    rule,
+                    `${file} title expected '${requiredTitle}', got '${(schema.title as string | undefined) ?? '(missing)'}'`,
+                    file,
+                    { code: 'schema-artifact:violation' },
+                ),
+            );
+        }
+
+        // Validate required array.
+        if (requireRequiredArray && !Array.isArray(schema.required)) {
+            findings.push(
+                createFinding(rule, `${file} missing 'required' array at top level`, file, {
+                    code: 'schema-artifact:violation',
+                }),
+            );
+        }
+
+        // Validate properties.
+        if (requiredProperties !== undefined) {
+            const props = schema.properties as Record<string, unknown> | undefined;
+            for (const prop of requiredProperties) {
+                if (!props || !(prop in props)) {
+                    findings.push(
+                        createFinding(rule, `${file} missing properties.${prop}`, file, {
+                            code: 'schema-artifact:violation',
+                        }),
+                    );
+                }
+            }
+        }
+
+        // Validate $defs / definitions.
+        if (requiredDefs !== undefined) {
+            const defs =
+                (schema.$defs as Record<string, unknown> | undefined) ??
+                (schema.definitions as Record<string, unknown> | undefined);
+            for (const def of requiredDefs) {
+                if (!defs || !(def in defs)) {
+                    findings.push(
+                        createFinding(rule, `${file} missing $defs.${def}`, file, {
+                            code: 'schema-artifact:violation',
+                        }),
+                    );
+                }
+            }
+        }
+
+        return { findings, fixes: [] };
+    }
+}
+
+/** Return a string array if value is a string array, otherwise undefined. */
+function stringArray(value: unknown): string[] | undefined {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? (value as string[]) : undefined;
+}

package/src/evaluators/secrets-scanner-evaluator.ts

@@ -7,28 +7,106 @@ import {
 } from '../types';
 import { discoverFiles, readWorkdirFile } from './file-utils';
 
-/** Scans text files for high-confidence secret-like tokens. */
+/** Built-in secret category names. */
+export type SecretsCategory = 'api-key' | 'private-key' | 'password' | 'token' | 'connection-string';
+
+// Patterns are assembled from a keyword group plus a value-shape suffix rather
+// than written as literal `keyword: "value"` lines, so this source file does not
+// trip the secrets-scanner when it scans itself.
+const ASSIGN = '\\s*[=:]\\s*';
+const QUOTED = (body: string) => `["'\`]${body}["'\`]`;
+const keyworded = (keywords: string, value: string) => `(?i)(${keywords})${ASSIGN}${QUOTED(value)}`;
+
+/** Built-in category → regex source. A leading `(?i)` is folded into the JS `i` flag. */
+const BUILTIN_PATTERNS: Record<SecretsCategory, string> = {
+    'api-key': `${keyworded('api[_-]?key|apikey|api_secret|access[_-]?token|auth[_-]?token|secret[_-]?key', '[A-Za-z0-9_/+=.-]{8,}')}|sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}`,
+    'private-key': 'PRIVATE[_-]?KEY|-----BEGIN\\s+(?:RSA |OPENSSH |EC )?PRIVATE\\s+KEY',
+    password: keyworded('passw[o]rd|passwd|pwd|pass', '[^"\'`]{4,}'),
+    token: keyworded('bearer[_-]?token|refresh[_-]?token|session[_-]?token', '[A-Za-z0-9_\\-./+=]{8,}'),
+    'connection-string': '(?i)(mongodb|postgres|mysql|redis)://[^\\s"\'`]{8,}',
+};
+
+const ALL_CATEGORIES = Object.keys(BUILTIN_PATTERNS) as SecretsCategory[];
+
+/** A compiled scanner pattern with its reporting label. */
+interface ScanPattern {
+    regex: RegExp;
+    label: string;
+}
+
+/**
+ * Scans text files for secret-like tokens.
+ *
+ * Config (`evaluator.config`, all optional):
+ * - `categories`: subset of built-in categories to scan (default: all five —
+ *   `api-key`, `private-key`, `password`, `token`, `connection-string`).
+ * - `customPatterns`: extra `{ name, pattern }` entries to scan for.
+ * - `scope`: `{ include, exclude }` globs; falls back to the rule's `include` /
+ *   `exclude` when omitted.
+ */
 export class SecretsScannerEvaluator implements RuleEvaluator {
     constructor() {}
 
-    /** Evaluate source files against bundled secret patterns. */
+    /** Evaluate files against the selected secret categories and custom patterns. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
-        const files = await discoverFiles({ workdir: context.workdir, include: rule.include, exclude: rule.exclude });
+        const config = rule.evaluator.config ?? {};
+        const patterns = buildPatterns(config);
+        const scope = config.scope as { include?: unknown; exclude?: unknown } | undefined;
+        const include = stringArray(scope?.include) ?? rule.include;
+        const exclude = stringArray(scope?.exclude) ?? rule.exclude;
+        const files = await discoverFiles({ workdir: context.workdir, include, exclude });
+
         const findings = [];
-        const secretPattern = /(sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|BEGIN (?:RSA |OPENSSH )?PRIVATE KEY)/;
         for (const file of files) {
             const lines = (await readWorkdirFile(context.workdir, file)).split('\n');
             for (const [index, line] of lines.entries()) {
-                if (secretPattern.test(line)) {
-                    findings.push(
-                        createFinding(rule, 'Potential secret token found', file, {
-                            line: index + 1,
-                            code: 'secret:token',
-                        }),
-                    );
+                for (const pattern of patterns) {
+                    pattern.regex.lastIndex = 0;
+                    if (pattern.regex.test(line)) {
+                        findings.push(
+                            createFinding(rule, `potential secret (${pattern.label})`, file, {
+                                line: index + 1,
+                                code: `secret:${pattern.label}`,
+                            }),
+                        );
+                        break;
+                    }
                 }
             }
         }
         return { findings, fixes: [] };
     }
 }
+
+/** Compile the selected built-in categories plus any custom patterns. */
+function buildPatterns(config: Record<string, unknown>): ScanPattern[] {
+    const categories = stringArray(config.categories) ?? ALL_CATEGORIES;
+    const patterns: ScanPattern[] = [];
+    for (const category of categories) {
+        const source = BUILTIN_PATTERNS[category as SecretsCategory];
+        if (source !== undefined) patterns.push({ regex: compile(source), label: category });
+    }
+    const custom = config.customPatterns;
+    if (Array.isArray(custom)) {
+        for (const entry of custom as { name?: unknown; pattern?: unknown }[]) {
+            if (typeof entry.name === 'string' && typeof entry.pattern === 'string') {
+                patterns.push({ regex: compile(entry.pattern), label: entry.name });
+            }
+        }
+    }
+    return patterns;
+}
+
+/** Compile a pattern, folding a leading `(?i)` group into the JS `i` flag. */
+function compile(source: string): RegExp {
+    const inline = /^\(\?([a-z]+)\)/.exec(source);
+    if (inline) {
+        const flags = [...(inline[1] ?? '')].filter((flag) => 'imsu'.includes(flag)).join('');
+        return new RegExp(source.slice(inline[0].length), flags);
+    }
+    return new RegExp(source);
+}
+
+function stringArray(value: unknown): string[] | undefined {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? (value as string[]) : undefined;
+}

package/src/evaluators/sg-evaluator.ts

@@ -0,0 +1,133 @@
+import { NodeProcessExecutor, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { matchesGlob } from './file-utils';
+
+/**
+ * Evaluates source code against an ast-grep pattern using the `sg` CLI.
+ *
+ * ## Options (in `evaluator.config`)
+ * - `pattern` — ast-grep pattern to search for (required).
+ * - `language` — language for ast-grep parsing (default: `typescript`).
+ *
+ * Include globs from the rule are forwarded to sg via `--glob` arguments.
+ * Exclude globs from the rule are applied in-process after parsing sg output.
+ */
+export class SgEvaluator implements RuleEvaluator {
+    private readonly executor: ProcessExecutor;
+
+    constructor(executor: ProcessExecutor = new NodeProcessExecutor()) {
+        this.executor = executor;
+    }
+
+    /** Run sg and emit one finding per matched AST node. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const config = rule.evaluator.config ?? {};
+        const pattern = config.pattern;
+        if (typeof pattern !== 'string' || pattern.length === 0) {
+            throw new Error('sg evaluator requires string config "pattern"');
+        }
+
+        const language = typeof config.language === 'string' ? config.language : 'typescript';
+        const include = rule.include ?? [];
+        const exclude = rule.exclude ?? [];
+
+        const args: string[] = ['run', '--pattern', pattern, '--lang', language, '--json'];
+        for (const glob of include) {
+            args.push(`--glob=${glob}`);
+        }
+
+        const result = await this.executor.run({
+            command: 'sg',
+            args,
+            cwd: context.workdir,
+            timeout: 60_000,
+            rejectOnError: false,
+            label: 'sg',
+        });
+
+        const stdout = result.stdout.trim();
+
+        if (stdout.length === 0) {
+            if (result.exitCode !== 0 && result.exitCode !== null && result.stderr.trim().length > 0) {
+                throw new Error(`sg failed: ${result.stderr.trim()}`);
+            }
+            return { findings: [], fixes: [] };
+        }
+
+        const matches = parseSgJson(stdout);
+        const findings = [];
+        for (const match of matches) {
+            if (exclude.some((glob) => matchesGlob(match.file, glob))) continue;
+            findings.push(
+                createFinding(rule, 'matched sg pattern', match.file, {
+                    line: match.line,
+                    code: 'sg:match',
+                }),
+            );
+        }
+
+        return { findings, fixes: [] };
+    }
+}
+
+/** Parsed sg match entry. */
+interface SgMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+
+/**
+ * Parse `sg --json` output.
+ *
+ * Handles both a JSON array (sg >= 0.40) and newline-delimited JSON objects
+ * (older sg or `--json=stream`). Returns workdir-relative file paths as-is
+ * since sg emits paths relative to cwd.
+ */
+function parseSgJson(stdout: string): SgMatch[] {
+    // Try JSON array first (newer sg).
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed)) {
+            return parsed.flatMap((event) => {
+                const file = typeof event.file === 'string' ? event.file : '';
+                if (!file) return [];
+                return [
+                    {
+                        file,
+                        line: (event.range?.start?.line ?? 0) + 1,
+                        text: typeof event.text === 'string' ? event.text.trim() : '',
+                    },
+                ];
+            });
+        }
+    } catch {
+        // Fall through to line-delimited parsing.
+    }
+
+    // Fallback: newline-delimited JSON.
+    const results: SgMatch[] = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+            const event = JSON.parse(trimmed);
+            const file = typeof event.file === 'string' ? event.file : '';
+            if (!file) continue;
+            results.push({
+                file,
+                line: (event.range?.start?.line ?? 0) + 1,
+                text: typeof event.text === 'string' ? event.text.trim() : '',
+            });
+        } catch {
+            // Skip unparseable lines.
+        }
+    }
+    return results;
+}