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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.2.5",
+    "version": "0.2.6",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -47,8 +47,8 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-rule-engine-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-ai-runner": "^0.2.5",
-        "@gobing-ai/ts-runtime": "^0.2.5",
+        "@gobing-ai/ts-ai-runner": "^0.2.6",
+        "@gobing-ai/ts-runtime": "^0.2.6",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/src/config/loader.ts

@@ -1,4 +1,4 @@
-import { basename, dirname, extname, join, resolve } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { NodeFileSystem } from '@gobing-ai/ts-runtime';
 import { parse } from 'yaml';
 import {
@@ -12,22 +12,39 @@ import {
 
 /** Options for loading rule presets. */
 export interface RuleLoaderOptions {
-    /** Project working directory. */
-    workdir: string;
-    /** Rule root directory. Defaults to ".spur/rules". */
-    rulesRoot?: string;
+    /**
+     * Ordered rule root directories, highest priority first. Presets, category
+     * folders, and rule files are resolved across all roots: the highest-priority
+     * root that provides a given relative path wins, and gaps are filled from
+     * lower-priority roots. The caller owns root discovery and ordering — this
+     * loader stays agnostic to any project layout convention.
+     */
+    roots: string[];
 }
 
-/** Load and normalize a preset by name. */
+/** Merged view of rule roots: winning file per relative path, plus categories. */
+interface MergedRoots {
+    /** Normalized relative path (e.g. `quality/coverage-gate.yaml`) → winning absolute path. */
+    readonly files: ReadonlyMap<string, string>;
+    /** Category folder names visible across all roots. */
+    readonly categories: ReadonlySet<string>;
+}
+
+/**
+ * Load and normalize a preset by name, resolving across one or more rule roots.
+ *
+ * Roots are merged in order: the first root to provide a relative path owns it,
+ * so a caller can layer project-local rules over shared/global rules and inherit
+ * the rest of a preset's categories from the lower-priority roots.
+ */
 export async function loadPresetRules(name: string, options: RuleLoaderOptions): Promise<ConstraintRule[]> {
-    const fs = new NodeFileSystem();
-    const root = resolve(options.workdir, options.rulesRoot ?? '.spur/rules');
-    const presetPath = await findDefinitionPath(root, name);
+    const merged = await buildMergedRoots(options.roots.map((root) => resolve(root)));
+    const presetPath = findMergedPreset(merged, name);
     if (presetPath === null) return [];
     const preset = PresetDefinitionSchema.parse(await readStructuredFile(presetPath)) as PresetDefinition;
     const rules: ConstraintRule[] = [];
     for (const entry of preset.extends) {
-        rules.push(...(await loadPresetEntry(root, entry, new Set([name]))));
+        rules.push(...(await loadPresetEntry(merged, entry, new Set([name]))));
     }
     const disabled = new Set(preset.disable ?? []);
     const normalized = rules.filter((rule) => !disabled.has(rule.id));
@@ -37,7 +54,6 @@ export async function loadPresetRules(name: string, options: RuleLoaderOptions):
             rule.fix = { ...(rule.fix ?? { mode: 'none' }), ...override.fix };
         }
     }
-    await fs.exists(root);
     return normalized;
 }
 
@@ -46,45 +62,124 @@ export async function loadRuleFile(filePath: string): Promise<ConstraintRule[]>
     return normalizeRuleFile(await readStructuredFile(resolve(filePath)), dirname(resolve(filePath)));
 }
 
-async function loadPresetEntry(root: string, entry: string, seen: Set<string>): Promise<ConstraintRule[]> {
-    const presetPath = await findDefinitionPath(root, entry);
+async function loadPresetEntry(merged: MergedRoots, entry: string, seen: Set<string>): Promise<ConstraintRule[]> {
+    // Sub-preset reference — recurse (cycle-guarded).
+    const presetPath = findMergedPreset(merged, entry);
     if (presetPath !== null && !seen.has(entry)) {
         seen.add(entry);
         const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath));
         if (preset.success) {
             const rules: ConstraintRule[] = [];
-            for (const child of preset.data.extends) rules.push(...(await loadPresetEntry(root, child, seen)));
+            for (const child of preset.data.extends) rules.push(...(await loadPresetEntry(merged, child, seen)));
             return rules.filter((rule) => !(preset.data.disable ?? []).includes(rule.id));
         }
     }
 
-    const categoryDir = resolve(root, entry);
-    const fs = new NodeFileSystem();
-    if (!(await fs.exists(categoryDir))) return [];
-    const entries = (await fs.readDir(categoryDir)).filter((file) => /\.(ya?ml|json)$/i.test(file)).sort();
-    const rules: ConstraintRule[] = [];
-    for (const file of entries) {
-        rules.push(...(await loadRuleFile(join(categoryDir, file))));
+    // Category folder reference — load every winning file under that prefix.
+    if (merged.categories.has(entry)) {
+        const rules: ConstraintRule[] = [];
+        for (const absPath of mergedFilesInCategory(merged, entry)) {
+            rules.push(...(await loadRuleFile(absPath)));
+        }
+        return rules;
     }
-    return rules;
+
+    // Sub-path reference — a single winning rule file within a category.
+    const subPath = findMergedFile(merged, entry);
+    if (subPath !== null) return loadRuleFile(subPath);
+
+    return [];
 }
 
-async function findDefinitionPath(root: string, name: string): Promise<string | null> {
+/**
+ * Build the merged view across ordered roots.
+ *
+ * Roots are processed in the order supplied (highest priority first). The first
+ * root to provide a given relative path owns that file; later roots are shadowed.
+ */
+async function buildMergedRoots(roots: readonly string[]): Promise<MergedRoots> {
     const fs = new NodeFileSystem();
-    const candidates = [
-        resolve(root, `${name}.yaml`),
-        resolve(root, `${name}.yml`),
-        resolve(root, `${name}.json`),
-        resolve(root, name, 'index.yaml'),
-        resolve(root, name, 'index.yml'),
-        resolve(root, name, 'index.json'),
-    ];
-    for (const candidate of candidates) {
-        if (await fs.exists(candidate)) return candidate;
+    const files = new Map<string, string>();
+    const categories = new Set<string>();
+    for (const root of roots) {
+        for (const absPath of await walkYamlFiles(fs, root)) {
+            const relPath = relative(root, absPath).split(sep).join('/');
+            const slashIdx = relPath.indexOf('/');
+            if (slashIdx > 0) categories.add(relPath.slice(0, slashIdx));
+            if (!files.has(relPath)) files.set(relPath, absPath);
+        }
+        for (const dir of await listImmediateDirs(fs, root)) categories.add(dir);
+    }
+    return { files, categories };
+}
+
+/** Find a preset definition across roots: `<name>.{yaml,yml,json}` or `<name>/index.*`. */
+function findMergedPreset(merged: MergedRoots, name: string): string | null {
+    return firstHit(merged, [
+        `${name}.yaml`,
+        `${name}.yml`,
+        `${name}.json`,
+        `${name}/index.yaml`,
+        `${name}/index.yml`,
+        `${name}/index.json`,
+    ]);
+}
+
+/** Find a single rule file by sub-path entry (e.g. `typescript/tsdoc-exports`). */
+function findMergedFile(merged: MergedRoots, entry: string): string | null {
+    const hasExt = /\.(ya?ml|json)$/i.test(entry);
+    return firstHit(merged, hasExt ? [entry] : [`${entry}.yaml`, `${entry}.yml`, `${entry}.json`]);
+}
+
+/** Return the winning absolute path for the first matching relative candidate. */
+function firstHit(merged: MergedRoots, relCandidates: readonly string[]): string | null {
+    for (const rel of relCandidates) {
+        const hit = merged.files.get(rel);
+        if (hit !== undefined) return hit;
     }
     return null;
 }
 
+/** Winning files under a category prefix, sorted by relative path. */
+function mergedFilesInCategory(merged: MergedRoots, category: string): string[] {
+    const prefix = `${category}/`;
+    return [...merged.files.entries()]
+        .filter(([relPath]) => relPath.startsWith(prefix))
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([, absPath]) => absPath);
+}
+
+/** Recursively collect YAML/JSON file paths under a directory, skipping root-level `presets/`. */
+async function walkYamlFiles(fs: NodeFileSystem, dir: string, depth = 0): Promise<string[]> {
+    const stat = await fs.stat(dir);
+    if (stat === null || !stat.isDirectory()) return [];
+    const acc: string[] = [];
+    for (const entry of (await fs.readDir(dir)).sort()) {
+        if (depth === 0 && entry === 'presets') continue;
+        const fullPath = join(dir, entry);
+        const entryStat = await fs.stat(fullPath);
+        if (entryStat?.isDirectory()) {
+            acc.push(...(await walkYamlFiles(fs, fullPath, depth + 1)));
+        } else if (entryStat?.isFile() && /\.(ya?ml|json)$/i.test(entry)) {
+            acc.push(fullPath);
+        }
+    }
+    return acc;
+}
+
+/** List immediate subdirectory names of a root (excluding `presets`). */
+async function listImmediateDirs(fs: NodeFileSystem, dir: string): Promise<string[]> {
+    const stat = await fs.stat(dir);
+    if (stat === null || !stat.isDirectory()) return [];
+    const dirs: string[] = [];
+    for (const entry of await fs.readDir(dir)) {
+        if (entry === 'presets') continue;
+        const entryStat = await fs.stat(join(dir, entry));
+        if (entryStat?.isDirectory()) dirs.push(entry);
+    }
+    return dirs;
+}
+
 async function readStructuredFile(path: string): Promise<unknown> {
     const content = await new NodeFileSystem().readFile(path);
     return extname(path) === '.json' ? JSON.parse(content) : parse(content);

package/src/evaluators/coverage-gate-evaluator.ts

@@ -0,0 +1,137 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { matchesGlob } from './file-utils';
+
+/** Single-file coverage extracted from an lcov record. */
+interface FileCoverage {
+    linesFound: number;
+    linesHit: number;
+}
+
+/** Per-file threshold override with justification. */
+interface CoverageExemption {
+    path: string;
+    threshold: number;
+    reason: string;
+}
+
+/** Evaluator config shape extracted from `rule.evaluator.config`. */
+interface CoverageGateConfig {
+    lcovPath?: string;
+    threshold?: number;
+    include?: string[];
+    exclude?: string[];
+    exemptions?: CoverageExemption[];
+}
+
+/**
+ * Coverage gate evaluator — reads an lcov tracefile and enforces per-file line
+ * coverage thresholds.
+ *
+ * Config (`evaluator.config`):
+ * - `lcovPath`: path to lcov.info (default: `coverage/lcov.info`)
+ * - `threshold`: default line-coverage percentage (default: `90`)
+ * - `include` / `exclude`: glob patterns scoping the check
+ * - `exemptions`: per-file threshold overrides with a reason
+ *
+ * A missing lcov file is reported as a single non-blocking finding rather than an
+ * error, so the gate degrades gracefully when coverage was not generated.
+ */
+export class CoverageGateEvaluator implements RuleEvaluator {
+    private readonly fs: NodeFileSystem;
+
+    constructor() {
+        this.fs = new NodeFileSystem();
+    }
+
+    /** Evaluate per-file coverage against the configured threshold. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const config = (rule.evaluator.config ?? {}) as CoverageGateConfig;
+        const lcovPath = config.lcovPath
+            ? resolve(context.workdir, config.lcovPath)
+            : resolve(context.workdir, 'coverage', 'lcov.info');
+
+        if (!(await this.fs.exists(lcovPath))) {
+            return {
+                findings: [
+                    createFinding(rule, 'No lcov file found — coverage not generated. Skipping gate.', lcovPath, {
+                        code: 'coverage:missing-lcov',
+                    }),
+                ],
+                fixes: [],
+            };
+        }
+
+        const coverage = parseLcov(await this.fs.readFile(lcovPath));
+        const threshold = config.threshold ?? 90;
+        const exemptions = new Map((config.exemptions ?? []).map((entry) => [entry.path, entry]));
+        const findings = [];
+
+        for (const [rawPath, cov] of coverage) {
+            if (cov.linesFound === 0) continue;
+            const filePath = normalizeLcovSourcePath(context.workdir, rawPath);
+            if (config.include !== undefined && !config.include.some((p) => matchesGlob(filePath, p))) continue;
+            if (config.exclude?.some((p) => matchesGlob(filePath, p))) continue;
+            if (isAlwaysExcluded(filePath)) continue;
+
+            const pct = Math.round((cov.linesHit / cov.linesFound) * 100);
+            const exemption = exemptions.get(filePath);
+            const effectiveThreshold = exemption?.threshold ?? threshold;
+            if (pct >= effectiveThreshold) continue;
+
+            const message = exemption
+                ? `${pct}% line coverage (exemption: ${effectiveThreshold}%, reason: ${exemption.reason})`
+                : `${pct}% line coverage (threshold: ${effectiveThreshold}%)`;
+            findings.push(createFinding(rule, message, filePath, { code: 'coverage:below-threshold' }));
+        }
+
+        return { findings, fixes: [] };
+    }
+}
+
+/** Parse an lcov tracefile into a map of source path → coverage counts. */
+function parseLcov(raw: string): Map<string, FileCoverage> {
+    const result = new Map<string, FileCoverage>();
+    let file: string | null = null;
+    let linesFound = 0;
+    let linesHit = 0;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('SF:')) {
+            file = trimmed.slice(3);
+            linesFound = 0;
+            linesHit = 0;
+        } else if (trimmed.startsWith('LF:')) {
+            linesFound = Number(trimmed.slice(3));
+        } else if (trimmed.startsWith('LH:')) {
+            linesHit = Number(trimmed.slice(3));
+        } else if (trimmed === 'end_of_record' && file !== null) {
+            result.set(file, { linesFound, linesHit });
+            file = null;
+        }
+    }
+    return result;
+}
+
+/** Standard exclusions applied regardless of config (tests, generated, deps). */
+function isAlwaysExcluded(filePath: string): boolean {
+    return (
+        filePath.includes('node_modules') ||
+        filePath.includes('.test.') ||
+        filePath.includes('.spec.') ||
+        filePath.includes('__tests__')
+    );
+}
+
+/** Normalize an lcov `SF:` path to a workdir-relative forward-slash path. */
+function normalizeLcovSourcePath(workdir: string, filePath: string): string {
+    const normalized = isAbsolute(filePath) ? relative(workdir, filePath) : filePath;
+    return normalized.replaceAll('\\', '/');
+}

package/src/evaluators/file-utils.ts

@@ -53,3 +53,41 @@ export function matchesAny(path: string, patterns: string[] | undefined): boolea
         return clean.length === 0 || path.includes(clean) || path.endsWith(clean);
     });
 }
+
+/**
+ * Segment-aware glob matching with `**` (any depth) and `*` (single segment).
+ *
+ * Stricter than {@link matchesAny}: it anchors the whole path, so `apps/**` does
+ * not match `vendor/apps/x`. Used by evaluators that enforce path policies
+ * (coverage scoping, test-file location) where a loose match would change findings.
+ */
+export function matchesGlob(path: string, pattern: string): boolean {
+    const normalized = path.replaceAll('\\', '/');
+    if (pattern.startsWith('**/')) {
+        const suffix = pattern.slice(3);
+        if (suffix.indexOf('*') === -1) {
+            return normalized.endsWith(suffix) || normalized.endsWith(`/${suffix}`);
+        }
+    }
+    if (pattern === normalized) return true;
+    return matchSegments(normalized.split('/'), pattern.split('/'), 0, 0);
+}
+
+/** Recursive segment-level glob matcher backing {@link matchesGlob}. */
+function matchSegments(file: string[], pattern: string[], fi: number, pi: number): boolean {
+    if (pi >= pattern.length) return fi >= file.length;
+    if (fi >= file.length) return pattern.slice(pi).every((segment) => segment === '**');
+    const pat = pattern[pi] ?? '';
+    if (pat === '**') {
+        return matchSegments(file, pattern, fi, pi + 1) || matchSegments(file, pattern, fi + 1, pi);
+    }
+    if (!matchSegment(file[fi] ?? '', pat)) return false;
+    return matchSegments(file, pattern, fi + 1, pi + 1);
+}
+
+/** Match one path segment against a pattern segment where `*` matches any run of non-`/` chars. */
+function matchSegment(segment: string, pattern: string): boolean {
+    if (pattern.indexOf('*') === -1) return segment === pattern;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*');
+    return new RegExp(`^${escaped}$`).test(segment);
+}

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

@@ -0,0 +1,115 @@
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { discoverFiles, matchesGlob } from './file-utils';
+
+/** Evaluator config shape extracted from `rule.evaluator.config`. */
+interface TestLocationConfig {
+    expected?: string;
+    forbid?: string[];
+    requireCorrespondingTest?: boolean;
+}
+
+/**
+ * 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 TypeScript-conventional path
+ *
+ * Discovery walks the workdir and applies `**` globs precisely, so it stays
+ * self-contained (no `rg --files` shell-out).
+ */
+export class TestLocationEvaluator implements RuleEvaluator {
+    /** 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;
+        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 "${file}" is in a 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, {
+                        code: 'test-location:unexpected',
+                    }),
+                );
+            }
+        }
+
+        if (config.requireCorrespondingTest) {
+            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);
+                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',
+                            },
+                        ),
+                    );
+                }
+            }
+        }
+
+        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}`;
+    }
+    const withoutExt = srcRelPath.replace(/\.(ts|tsx|js|jsx)$/, '');
+    return `tests/${withoutExt.replace(/^src\//, '')}.test.ts`;
+}

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

@@ -0,0 +1,97 @@
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils';
+
+/** Export kinds this evaluator can check for a preceding JSDoc block. */
+const VALID_KINDS = ['function', 'class', 'type', 'const', 'enum', 'interface'] as const;
+type ExportKind = (typeof VALID_KINDS)[number];
+
+/** A discovered exported declaration. */
+interface ExportSite {
+    kind: ExportKind;
+    name: string;
+    /** One-based line number of the declaration. */
+    line: number;
+}
+
+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_$]+)/,
+    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 implements RuleEvaluator {
+    constructor() {
+        // V8 function coverage requires explicit constructor
+    }
+    /** Evaluate exports under the configured kinds for a preceding JSDoc block. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const kinds = (rule.evaluator.config?.kinds as string[] | undefined) ?? [...VALID_KINDS];
+        for (const kind of kinds) {
+            if (!(VALID_KINDS as readonly string[]).includes(kind)) {
+                throw new Error(`Unknown export kind "${kind}"; expected one of: ${VALID_KINDS.join(', ')}`);
+            }
+        }
+        const requested = new Set(kinds as ExportKind[]);
+        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: string[], requested: ReadonlySet<ExportKind>): ExportSite[] {
+    const sites: ExportSite[] = [];
+    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 the line immediately above a declaration closes a JSDoc block. */
+function precededByJsdoc(lines: string[], declarationLine: number): boolean {
+    const prev = lines[declarationLine - 2]?.trim();
+    return prev !== undefined && (prev.endsWith('*/') || prev.startsWith('/**'));
+}

package/src/host/builtins.ts

@@ -1,10 +1,13 @@
 import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
 import { AgentDetectionEvaluator } from '../evaluators/agent-detection-evaluator';
+import { CoverageGateEvaluator } from '../evaluators/coverage-gate-evaluator';
 import { ExitCodeEvaluator } from '../evaluators/exit-code-evaluator';
 import { ForbiddenImportEvaluator } from '../evaluators/forbidden-import-evaluator';
 import { PathEvaluator } from '../evaluators/path-evaluator';
 import { RegexEvaluator } from '../evaluators/regex-evaluator';
 import { SecretsScannerEvaluator } from '../evaluators/secrets-scanner-evaluator';
+import { TestLocationEvaluator } from '../evaluators/test-location-evaluator';
+import { TsdocExportEvaluator } from '../evaluators/tsdoc-export-evaluator';
 import { JsonFormatter } from '../formatters/json';
 import { TextFormatter } from '../formatters/text';
 import type { RuleEngineHost } from './rule-engine-host';
@@ -21,6 +24,9 @@ export function registerBuiltins(host: RuleEngineHost, executor?: ProcessExecuto
     host.evaluators.register('exit-code', new ExitCodeEvaluator(executor), 'builtin');
     host.evaluators.register('secrets-scanner', new SecretsScannerEvaluator(), 'builtin');
     host.evaluators.register('agent-detection', new AgentDetectionEvaluator(), 'builtin');
+    host.evaluators.register('coverage-gate', new CoverageGateEvaluator(), 'builtin');
+    host.evaluators.register('tsdoc-export', new TsdocExportEvaluator(), 'builtin');
+    host.evaluators.register('test-location', new TestLocationEvaluator(), 'builtin');
     host.formatters.register('text', new TextFormatter(), 'builtin');
     host.formatters.register('json', new JsonFormatter(), 'builtin');
 }