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

package/dist/evaluators/schema-artifact-evaluator.js

@@ -0,0 +1,102 @@
+import { resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createFinding, } from '../types.js';
+/**
+ * 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 {
+    fs;
+    constructor() {
+        this.fs = new NodeFileSystem();
+    }
+    /** Evaluate the configured JSON schema artifact. */
+    async evaluate(rule, context) {
+        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;
+        try {
+            const raw = await this.fs.readFile(absolutePath);
+            schema = JSON.parse(raw);
+        }
+        catch (err) {
+            return {
+                findings: [
+                    createFinding(rule, `invalid JSON: ${err.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 ?? '(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;
+            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 ??
+                schema.definitions;
+            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) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
+}

package/dist/evaluators/secrets-scanner-evaluator.d.ts

@@ -1,8 +1,19 @@
 import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
-/** 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';
+/**
+ * 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 declare class SecretsScannerEvaluator implements RuleEvaluator {
     constructor();
-    /** Evaluate source files against bundled secret patterns. */
+    /** Evaluate files against the selected secret categories and custom patterns. */
     evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
 }
 //# sourceMappingURL=secrets-scanner-evaluator.d.ts.map

package/dist/evaluators/secrets-scanner-evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secrets-scanner-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/secrets-scanner-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB,+DAA+D;AAC/D,qBAAa,uBAAwB,YAAW,aAAa;;IAGzD,6DAA6D;IACvD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAmB5F"}
+{"version":3,"file":"secrets-scanner-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/secrets-scanner-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,mBAAmB,CAAC;AA0BrG;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,YAAW,aAAa;;IAGzD,iFAAiF;IAC3E,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA4B5F"}

package/dist/evaluators/secrets-scanner-evaluator.js

@@ -1,24 +1,87 @@
 import { createFinding, } from '../types.js';
 import { discoverFiles, readWorkdirFile } from './file-utils.js';
-/** Scans text files for high-confidence secret-like tokens. */
+// 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) => `["'\`]${body}["'\`]`;
+const keyworded = (keywords, value) => `(?i)(${keywords})${ASSIGN}${QUOTED(value)}`;
+/** Built-in category → regex source. A leading `(?i)` is folded into the JS `i` flag. */
+const BUILTIN_PATTERNS = {
+    '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);
+/**
+ * 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 {
     constructor() { }
-    /** Evaluate source files against bundled secret patterns. */
+    /** Evaluate files against the selected secret categories and custom patterns. */
     async evaluate(rule, context) {
-        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;
+        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) {
+    const categories = stringArray(config.categories) ?? ALL_CATEGORIES;
+    const patterns = [];
+    for (const category of categories) {
+        const source = BUILTIN_PATTERNS[category];
+        if (source !== undefined)
+            patterns.push({ regex: compile(source), label: category });
+    }
+    const custom = config.customPatterns;
+    if (Array.isArray(custom)) {
+        for (const entry of custom) {
+            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) {
+    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) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
+}

package/dist/evaluators/sg-evaluator.d.ts

@@ -0,0 +1,19 @@
+import { type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * 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 declare class SgEvaluator implements RuleEvaluator {
+    private readonly executor;
+    constructor(executor?: ProcessExecutor);
+    /** Run sg and emit one finding per matched AST node. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# sourceMappingURL=sg-evaluator.d.ts.map

package/dist/evaluators/sg-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sg-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/sg-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,aAAa;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAE/B,QAAQ,GAAE,eAA2C;IAIjE,wDAAwD;IAClD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAgD5F"}

package/dist/evaluators/sg-evaluator.js

@@ -0,0 +1,112 @@
+import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
+import { createFinding, } from '../types.js';
+import { matchesGlob } from './file-utils.js';
+/**
+ * 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 {
+    executor;
+    constructor(executor = new NodeProcessExecutor()) {
+        this.executor = executor;
+    }
+    /** Run sg and emit one finding per matched AST node. */
+    async evaluate(rule, context) {
+        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 = ['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: [] };
+    }
+}
+/**
+ * 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) {
+    // 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 = [];
+    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/dist/evaluators/test-location-evaluator.d.ts

@@ -0,0 +1,32 @@
+import type { CapabilityRegistry } from '../host/capability-registry';
+import type { TestPathResolver } from '../resolvers/test-path-resolver';
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * Evaluator that enforces where test files live and, optionally, that every
+ * source file has a corresponding test.
+ *
+ * Config (`evaluator.config`):
+ * - `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 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 declare class TestLocationEvaluator implements RuleEvaluator {
+    private readonly resolvers?;
+    /** Optional resolver registry; when absent, the TypeScript convention is used. */
+    constructor(resolvers?: CapabilityRegistry<TestPathResolver> | undefined);
+    /** Evaluate test-file placement and optional coverage of source files. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+    /**
+     * 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;
+}
+//# sourceMappingURL=test-location-evaluator.d.ts.map

package/dist/evaluators/test-location-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-location-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/test-location-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAWlB;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IAE3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IADvC,kFAAkF;gBACrD,SAAS,CAAC,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,YAAA;IAE7E,0EAA0E;IACpE,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyDzF;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CASzB"}

package/dist/evaluators/test-location-evaluator.js

@@ -0,0 +1,105 @@
+import { createFinding, } from '../types.js';
+import { discoverFiles, matchesGlob } from './file-utils.js';
+/**
+ * Evaluator that enforces where test files live and, optionally, that every
+ * source file has a corresponding test.
+ *
+ * Config (`evaluator.config`):
+ * - `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 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 {
+    resolvers;
+    /** Optional resolver registry; when absent, the TypeScript convention is used. */
+    constructor(resolvers) {
+        this.resolvers = resolvers;
+    }
+    /** Evaluate test-file placement and optional coverage of source files. */
+    async evaluate(rule, context) {
+        const config = (rule.evaluator.config ?? {});
+        const expected = config.expected;
+        if (typeof expected !== 'string' || expected.length === 0) {
+            throw new Error('test-location evaluator requires a non-empty "expected" config');
+        }
+        const forbid = config.forbid ?? [];
+        const include = rule.include ?? ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'];
+        const exclude = rule.exclude ?? [];
+        const allFiles = await discoverFiles({ workdir: context.workdir });
+        const findings = [];
+        const testPatterns = config.requireCorrespondingTest ? [expected] : include;
+        const testFiles = allFiles.filter((file) => testPatterns.some((pattern) => matchesGlob(file, pattern)));
+        for (const file of testFiles) {
+            if (exclude.some((pattern) => matchesGlob(file, pattern)))
+                continue;
+            const violated = forbid.find((pattern) => matchesGlob(file, pattern));
+            if (violated !== undefined) {
+                findings.push(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 outside expected location (expected "${expected}")`, file, {
+                    code: 'test-location:unexpected',
+                }));
+            }
+        }
+        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 = resolver.resolveTestPath(srcFile);
+                if (testPath === srcFile)
+                    continue;
+                if (!testSet.has(testPath)) {
+                    findings.push(createFinding(rule, `no corresponding test → ${testPath}`, srcFile, {
+                        code: 'test-location:missing',
+                    }));
+                }
+            }
+        }
+        return { findings, fixes: [] };
+    }
+    /**
+     * 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.
+     */
+    selectResolver(name = 'typescript') {
+        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);
+    }
+}
+/** Built-in TypeScript convention used when no resolver registry is injected. */
+const TYPESCRIPT_FALLBACK = {
+    name: 'typescript',
+    resolveTestPath(srcRelPath) {
+        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/dist/evaluators/tsdoc-export-evaluator.d.ts

@@ -0,0 +1,15 @@
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * Evaluator that flags exported declarations missing a JSDoc block.
+ *
+ * Self-contained: it scans matching source files line-by-line and checks whether
+ * the line immediately preceding an export ends a JSDoc comment. Config
+ * (`evaluator.config.kinds`) selects which export kinds to check; `rule.include`
+ * and `rule.exclude` scope the files using full `**` globs.
+ */
+export declare class TsdocExportEvaluator implements RuleEvaluator {
+    constructor();
+    /** Evaluate exports under the configured kinds for a preceding JSDoc block. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# sourceMappingURL=tsdoc-export-evaluator.d.ts.map

package/dist/evaluators/tsdoc-export-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc-export-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/tsdoc-export-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAwBlB;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,aAAa;;IAItD,+EAA+E;IACzE,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA8B5F"}

package/dist/evaluators/tsdoc-export-evaluator.js

@@ -0,0 +1,91 @@
+import { createFinding, } from '../types.js';
+import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils.js';
+/** Export kinds this evaluator can check for a preceding JSDoc block. */
+const VALID_KINDS = ['function', 'class', 'type', 'const', 'enum', 'interface'];
+const KIND_PATTERN = {
+    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_$]+)/,
+    enum: /^export\s+(?:const\s+)?enum\s+([A-Za-z0-9_$]+)/,
+};
+/**
+ * Evaluator that flags exported declarations missing a JSDoc block.
+ *
+ * Self-contained: it scans matching source files line-by-line and checks whether
+ * the line immediately preceding an export ends a JSDoc comment. Config
+ * (`evaluator.config.kinds`) selects which export kinds to check; `rule.include`
+ * and `rule.exclude` scope the files using full `**` globs.
+ */
+export class TsdocExportEvaluator {
+    constructor() {
+        // V8 function coverage requires explicit constructor
+    }
+    /** Evaluate exports under the configured kinds for a preceding JSDoc block. */
+    async evaluate(rule, context) {
+        const kinds = rule.evaluator.config?.kinds ?? [...VALID_KINDS];
+        for (const kind of kinds) {
+            if (!VALID_KINDS.includes(kind)) {
+                throw new Error(`Unknown export kind "${kind}"; expected one of: ${VALID_KINDS.join(', ')}`);
+            }
+        }
+        const requested = new Set(kinds);
+        const include = rule.include ?? ['**/*.ts', '**/*.tsx'];
+        const exclude = rule.exclude ?? [];
+        const files = await discoverFiles({ workdir: context.workdir, include: ['.ts', '.tsx'] });
+        const findings = [];
+        for (const file of files) {
+            if (!include.some((pattern) => matchesGlob(file, pattern)))
+                continue;
+            if (exclude.some((pattern) => matchesGlob(file, pattern)))
+                continue;
+            const lines = (await readWorkdirFile(context.workdir, file)).split('\n');
+            for (const site of findExports(lines, requested)) {
+                if (!precededByJsdoc(lines, site.line)) {
+                    findings.push(createFinding(rule, `Exported ${site.kind} "${site.name}" is missing a JSDoc comment`, file, {
+                        line: site.line,
+                        code: 'tsdoc:missing',
+                    }));
+                }
+            }
+        }
+        return { findings, fixes: [] };
+    }
+}
+/** Find exported declarations of the requested kinds within a file's lines. */
+function findExports(lines, requested) {
+    const sites = [];
+    for (const [index, raw] of lines.entries()) {
+        const line = raw.trimStart();
+        if (!line.startsWith('export'))
+            continue;
+        for (const kind of requested) {
+            const match = KIND_PATTERN[kind].exec(line);
+            if (match) {
+                sites.push({ kind, name: match[1] ?? 'unknown', line: index + 1 });
+                break;
+            }
+        }
+    }
+    return sites;
+}
+/**
+ * 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, declarationLine) {
+    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;
+}