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

package/dist/config/loader.d.ts

@@ -1,12 +1,22 @@
 import { type ConstraintRule } from '../types';
 /** 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. */
+/**
+ * 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 declare function loadPresetRules(name: string, options: RuleLoaderOptions): Promise<ConstraintRule[]>;
 /** Load a direct rule file from disk. */
 export declare function loadRuleFile(filePath: string): Promise<ConstraintRule[]>;

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,cAAc,EAMtB,MAAM,UAAU,CAAC;AAElB,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2CAA2C;AAC3C,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAoBzG;AAED,yCAAyC;AACzC,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE9E"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,cAAc,EAMtB,MAAM,UAAU,CAAC;AAElB,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB;AAUD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAkBzG;AAED,yCAAyC;AACzC,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE9E"}

package/dist/config/loader.js

@@ -1,18 +1,23 @@
-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 { ConstraintRuleFileSchema, ConstraintRuleSchema, PresetDefinitionSchema, } from '../types.js';
-/** Load and normalize a preset by name. */
+/**
+ * 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, options) {
-    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));
     const rules = [];
     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));
@@ -22,52 +27,131 @@ export async function loadPresetRules(name, options) {
             rule.fix = { ...(rule.fix ?? { mode: 'none' }), ...override.fix };
         }
     }
-    await fs.exists(root);
     return normalized;
 }
 /** Load a direct rule file from disk. */
 export async function loadRuleFile(filePath) {
     return normalizeRuleFile(await readStructuredFile(resolve(filePath)), dirname(resolve(filePath)));
 }
-async function loadPresetEntry(root, entry, seen) {
-    const presetPath = await findDefinitionPath(root, entry);
+async function loadPresetEntry(merged, entry, seen) {
+    // 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 = [];
             for (const child of preset.data.extends)
-                rules.push(...(await loadPresetEntry(root, child, seen)));
+                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 = [];
-    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 = [];
+        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, name) {
+/**
+ * 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) {
     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();
+    const categories = new Set();
+    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, name) {
+    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, entry) {
+    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, relCandidates) {
+    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, category) {
+    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, dir, depth = 0) {
+    const stat = await fs.stat(dir);
+    if (stat === null || !stat.isDirectory())
+        return [];
+    const acc = [];
+    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, dir) {
+    const stat = await fs.stat(dir);
+    if (stat === null || !stat.isDirectory())
+        return [];
+    const dirs = [];
+    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) {
     const content = await new NodeFileSystem().readFile(path);
     return extname(path) === '.json' ? JSON.parse(content) : parse(content);

package/dist/evaluators/coverage-gate-evaluator.d.ts

@@ -0,0 +1,21 @@
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * 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 declare class CoverageGateEvaluator implements RuleEvaluator {
+    private readonly fs;
+    constructor();
+    /** Evaluate per-file coverage against the configured threshold. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# sourceMappingURL=coverage-gate-evaluator.d.ts.map

package/dist/evaluators/coverage-gate-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gate-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/coverage-gate-evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAyBlB;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;;IAMpC,mEAAmE;IAC7D,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA0C5F"}

package/dist/evaluators/coverage-gate-evaluator.js

@@ -0,0 +1,103 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createFinding, } from '../types.js';
+import { matchesGlob } from './file-utils.js';
+/**
+ * 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 {
+    fs;
+    constructor() {
+        this.fs = new NodeFileSystem();
+    }
+    /** Evaluate per-file coverage against the configured threshold. */
+    async evaluate(rule, context) {
+        const config = (rule.evaluator.config ?? {});
+        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) {
+    const result = new Map();
+    let file = 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) {
+    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, filePath) {
+    const normalized = isAbsolute(filePath) ? relative(workdir, filePath) : filePath;
+    return normalized.replaceAll('\\', '/');
+}

package/dist/evaluators/file-utils.d.ts

@@ -20,4 +20,12 @@ export declare function relativeToWorkdir(workdir: string, path: string): string
 export declare function relativeParent(path: string): string;
 /** Return true when a path matches any supplied fragment or suffix. */
 export declare function matchesAny(path: string, patterns: string[] | undefined): boolean;
+/**
+ * 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 declare function matchesGlob(path: string, pattern: string): boolean;
 //# sourceMappingURL=file-utils.d.ts.map

package/dist/evaluators/file-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/evaluators/file-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,cAAc,EAAW,MAAM,uBAAuB,CAAC;AAEjF,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACnC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,EAAE,CAAC,EAAE,UAAU,CAAC;CACnB;AAID,qFAAqF;AACrF,wBAAsB,aAAa,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWtF;AAED,gDAAgD;AAChD,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnH;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAMhF"}
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/evaluators/file-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,cAAc,EAAW,MAAM,uBAAuB,CAAC;AAEjF,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACnC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,EAAE,CAAC,EAAE,UAAU,CAAC;CACnB;AAID,qFAAqF;AACrF,wBAAsB,aAAa,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWtF;AAED,gDAAgD;AAChD,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnH;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAMhF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAUlE"}

package/dist/evaluators/file-utils.js

@@ -33,3 +33,43 @@ export function matchesAny(path, patterns) {
         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, pattern) {
+    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, pattern, fi, pi) {
+    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, pattern) {
+    if (pattern.indexOf('*') === -1)
+        return segment === pattern;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*');
+    return new RegExp(`^${escaped}$`).test(segment);
+}

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

@@ -0,0 +1,19 @@
+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 TypeScript-conventional path
+ *
+ * Discovery walks the workdir and applies `**` globs precisely, so it stays
+ * self-contained (no `rg --files` shell-out).
+ */
+export declare class TestLocationEvaluator implements RuleEvaluator {
+    /** Evaluate test-file placement and optional coverage of source files. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# 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,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAUlB;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACvD,0EAA0E;IACpE,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAiE5F"}

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

@@ -0,0 +1,85 @@
+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 TypeScript-conventional path
+ *
+ * Discovery walks the workdir and applies `**` globs precisely, so it stays
+ * self-contained (no `rg --files` shell-out).
+ */
+export class TestLocationEvaluator {
+    /** 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 "${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) {
+    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,77 @@
+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+(?: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 {
+    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 the line immediately above a declaration closes a JSDoc block. */
+function precededByJsdoc(lines, declarationLine) {
+    const prev = lines[declarationLine - 2]?.trim();
+    return prev !== undefined && (prev.endsWith('*/') || prev.startsWith('/**'));
+}

package/dist/host/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/host/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAS7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAavF"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/host/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAY7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAgBvF"}

package/dist/host/builtins.js

@@ -1,9 +1,12 @@
 import { AgentDetectionEvaluator } from '../evaluators/agent-detection-evaluator.js';
+import { CoverageGateEvaluator } from '../evaluators/coverage-gate-evaluator.js';
 import { ExitCodeEvaluator } from '../evaluators/exit-code-evaluator.js';
 import { ForbiddenImportEvaluator } from '../evaluators/forbidden-import-evaluator.js';
 import { PathEvaluator } from '../evaluators/path-evaluator.js';
 import { RegexEvaluator } from '../evaluators/regex-evaluator.js';
 import { SecretsScannerEvaluator } from '../evaluators/secrets-scanner-evaluator.js';
+import { TestLocationEvaluator } from '../evaluators/test-location-evaluator.js';
+import { TsdocExportEvaluator } from '../evaluators/tsdoc-export-evaluator.js';
 import { JsonFormatter } from '../formatters/json.js';
 import { TextFormatter } from '../formatters/text.js';
 /** Register bundled evaluators and formatters on a host. */
@@ -18,6 +21,9 @@ export function registerBuiltins(host, executor) {
     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');
 }