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

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;
+}

package/src/evaluators/test-location-evaluator.ts

@@ -1,3 +1,5 @@
+import type { CapabilityRegistry } from '../host/capability-registry';
+import type { TestPathResolver } from '../resolvers/test-path-resolver';
 import {
     type ConstraintRule,
     createFinding,
@@ -12,6 +14,7 @@ interface TestLocationConfig {
     expected?: string;
     forbid?: string[];
     requireCorrespondingTest?: boolean;
+    resolver?: string;
 }
 
 /**
@@ -22,12 +25,16 @@ interface TestLocationConfig {
  * - `expected`: glob the test files must match (required)
  * - `forbid`: globs where tests must not live (e.g. `**\/__tests__/**`)
  * - `requireCorrespondingTest`: when true, flags source files (from `rule.include`)
- *   that lack a test at the TypeScript-conventional path
+ *   that lack a test at the resolver's conventional path
+ * - `resolver`: language resolver name (`typescript` default, or `python`/`go`/`rust`)
  *
  * Discovery walks the workdir and applies `**` globs precisely, so it stays
  * self-contained (no `rg --files` shell-out).
  */
 export class TestLocationEvaluator implements RuleEvaluator {
+    /** Optional resolver registry; when absent, the TypeScript convention is used. */
+    constructor(private readonly resolvers?: CapabilityRegistry<TestPathResolver>) {}
+
     /** Evaluate test-file placement and optional coverage of source files. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         const config = (rule.evaluator.config ?? {}) as TestLocationConfig;
@@ -49,20 +56,15 @@ export class TestLocationEvaluator implements RuleEvaluator {
             const violated = forbid.find((pattern) => matchesGlob(file, pattern));
             if (violated !== undefined) {
                 findings.push(
-                    createFinding(
-                        rule,
-                        `Test file "${file}" is in a forbidden location (matches "${violated}")`,
-                        file,
-                        {
-                            code: 'test-location:forbidden',
-                        },
-                    ),
+                    createFinding(rule, `test file in forbidden location (matches "${violated}")`, file, {
+                        code: 'test-location:forbidden',
+                    }),
                 );
                 continue;
             }
             if (!matchesGlob(file, expected)) {
                 findings.push(
-                    createFinding(rule, `Test file "${file}" does not match expected pattern "${expected}"`, file, {
+                    createFinding(rule, `test file outside expected location (expected "${expected}")`, file, {
                         code: 'test-location:unexpected',
                     }),
                 );
@@ -70,23 +72,19 @@ export class TestLocationEvaluator implements RuleEvaluator {
         }
 
         if (config.requireCorrespondingTest) {
+            const resolver = this.selectResolver(config.resolver);
             const srcPatterns = rule.include ?? ['**/*.ts', '**/*.tsx'];
             const testSet = new Set(testFiles);
             for (const srcFile of allFiles) {
                 if (!srcPatterns.some((pattern) => matchesGlob(srcFile, pattern))) continue;
                 if (exclude.some((pattern) => matchesGlob(srcFile, pattern))) continue;
-                const testPath = resolveTestPath(srcFile);
+                const testPath = resolver.resolveTestPath(srcFile);
                 if (testPath === srcFile) continue;
                 if (!testSet.has(testPath)) {
                     findings.push(
-                        createFinding(
-                            rule,
-                            `Source file "${srcFile}" has no corresponding test → ${testPath}`,
-                            srcFile,
-                            {
-                                code: 'test-location:missing',
-                            },
-                        ),
+                        createFinding(rule, `no corresponding test → ${testPath}`, srcFile, {
+                            code: 'test-location:missing',
+                        }),
                     );
                 }
             }
@@ -94,22 +92,36 @@ export class TestLocationEvaluator implements RuleEvaluator {
 
         return { findings, fixes: [] };
     }
-}
 
-/**
- * Map a TypeScript source path to its conventional test path.
- *
- *   packages/core/src/foo/bar.ts → packages/core/tests/foo/bar.test.ts
- *   src/foo/bar.ts               → tests/foo/bar.test.ts
- */
-function resolveTestPath(srcRelPath: string): string {
-    if (srcRelPath.includes('.test.') || srcRelPath.includes('.spec.')) return srcRelPath;
-    const srcIdx = srcRelPath.indexOf('/src/');
-    if (srcIdx !== -1) {
-        const pkg = srcRelPath.slice(0, srcIdx);
-        const rel = srcRelPath.slice(srcIdx + '/src/'.length).replace(/\.(ts|tsx|js|jsx)$/, '.test.ts');
-        return `${pkg}/tests/${rel}`;
+    /**
+     * Pick the resolver named in config (default `typescript`).
+     *
+     * Falls back to the built-in TypeScript convention when no registry was
+     * injected; throws if a named resolver is requested but not registered.
+     */
+    private selectResolver(name = 'typescript'): TestPathResolver {
+        if (this.resolvers === undefined) {
+            if (name !== 'typescript') {
+                throw new Error(`test-location resolver "${name}" requested but no resolver registry is available`);
+            }
+            return TYPESCRIPT_FALLBACK;
+        }
+        return this.resolvers.get(name);
     }
-    const withoutExt = srcRelPath.replace(/\.(ts|tsx|js|jsx)$/, '');
-    return `tests/${withoutExt.replace(/^src\//, '')}.test.ts`;
 }
+
+/** Built-in TypeScript convention used when no resolver registry is injected. */
+const TYPESCRIPT_FALLBACK: TestPathResolver = {
+    name: 'typescript',
+    resolveTestPath(srcRelPath: string): string {
+        if (srcRelPath.includes('.test.') || srcRelPath.includes('.spec.')) return srcRelPath;
+        const srcIdx = srcRelPath.indexOf('/src/');
+        if (srcIdx !== -1) {
+            const pkg = srcRelPath.slice(0, srcIdx);
+            const rel = srcRelPath.slice(srcIdx + '/src/'.length).replace(/\.(ts|tsx|js|jsx)$/, '.test.ts');
+            return `${pkg}/tests/${rel}`;
+        }
+        const withoutExt = srcRelPath.replace(/\.(ts|tsx|js|jsx)$/, '');
+        return `tests/${withoutExt.replace(/^src\//, '')}.test.ts`;
+    },
+};

package/src/evaluators/tsdoc-export-evaluator.ts

@@ -20,8 +20,8 @@ interface ExportSite {
 }
 
 const KIND_PATTERN: Record<ExportKind, RegExp> = {
-    function: /^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/,
-    class: /^export\s+(?:abstract\s+)?class\s+([A-Za-z0-9_$]+)/,
+    function: /^export\s+(?:default\s+)?(?:async\s+)?function\s*\*?\s+([A-Za-z0-9_$]+)/,
+    class: /^export\s+(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z0-9_$]+)/,
     interface: /^export\s+interface\s+([A-Za-z0-9_$]+)/,
     type: /^export\s+type\s+([A-Za-z0-9_$]+)/,
     const: /^export\s+const\s+([A-Za-z0-9_$]+)/,
@@ -90,8 +90,22 @@ function findExports(lines: string[], requested: ReadonlySet<ExportKind>): Expor
     return sites;
 }
 
-/** True when the line immediately above a declaration closes a JSDoc block. */
+/**
+ * True when a JSDoc block precedes a declaration.
+ *
+ * Skips decorator lines (`@Component(...)`) so a documented but decorated class
+ * is not falsely flagged, then checks whether the nearest preceding non-decorator
+ * line closes (or is) a JSDoc comment.
+ */
 function precededByJsdoc(lines: string[], declarationLine: number): boolean {
-    const prev = lines[declarationLine - 2]?.trim();
-    return prev !== undefined && (prev.endsWith('*/') || prev.startsWith('/**'));
+    let cursor = declarationLine - 2; // zero-based line above the declaration
+    while (cursor >= 0) {
+        const prev = lines[cursor]?.trim() ?? '';
+        if (prev.startsWith('@')) {
+            cursor -= 1; // decorator — keep walking up
+            continue;
+        }
+        return prev.endsWith('*/') || prev.startsWith('/**');
+    }
+    return false;
 }