@gobing-ai/ts-rule-engine 0.2.1

package/dist/host/builtins.js

@@ -0,0 +1,23 @@
+import { AgentDetectionEvaluator } from '../evaluators/agent-detection-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 { JsonFormatter } from '../formatters/json.js';
+import { TextFormatter } from '../formatters/text.js';
+/** Register bundled evaluators and formatters on a host. */
+export function registerBuiltins(host, executor) {
+    const regex = new RegexEvaluator();
+    const path = new PathEvaluator();
+    host.evaluators.register('regex', regex, 'builtin');
+    host.evaluators.register('rg', regex, 'builtin');
+    host.evaluators.register('path', path, 'builtin');
+    host.evaluators.register('file-exist', path, 'builtin');
+    host.evaluators.register('forbidden-import', new ForbiddenImportEvaluator(), 'builtin');
+    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.formatters.register('text', new TextFormatter(), 'builtin');
+    host.formatters.register('json', new JsonFormatter(), 'builtin');
+}

package/dist/host/capability-registry.d.ts

@@ -0,0 +1,24 @@
+/** Registry origin for a host capability. */
+export type CapabilityOrigin = 'builtin' | 'extension';
+/** Registry entry metadata. */
+export interface CapabilityEntry<TCapability> {
+    /** Capability implementation. */
+    capability: TCapability;
+    /** Registration origin. */
+    origin: CapabilityOrigin;
+}
+/** Typed registry used by the rule engine host. */
+export declare class CapabilityRegistry<TCapability> {
+    private readonly kind;
+    private readonly capabilities;
+    constructor(kind: string);
+    /** Register or replace a capability. */
+    register(name: string, capability: TCapability, origin?: CapabilityOrigin): void;
+    /** Return true when a capability exists. */
+    has(name: string): boolean;
+    /** Get a registered capability or throw a clear error. */
+    get(name: string): TCapability;
+    /** List registered capability names. */
+    list(): string[];
+}
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/host/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../src/host/capability-registry.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,+BAA+B;AAC/B,MAAM,WAAW,eAAe,CAAC,WAAW;IACxC,iCAAiC;IACjC,UAAU,EAAE,WAAW,CAAC;IACxB,2BAA2B;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC5B;AAED,mDAAmD;AACnD,qBAAa,kBAAkB,CAAC,WAAW;IAG3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;gBAEnD,IAAI,EAAE,MAAM;IAEzC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAE,gBAA8B,GAAG,IAAI;IAI7F,4CAA4C;IAC5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,0DAA0D;IAC1D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAQ9B,wCAAwC;IACxC,IAAI,IAAI,MAAM,EAAE;CAGnB"}

package/dist/host/capability-registry.js

@@ -0,0 +1,28 @@
+/** Typed registry used by the rule engine host. */
+export class CapabilityRegistry {
+    kind;
+    capabilities = new Map();
+    constructor(kind) {
+        this.kind = kind;
+    }
+    /** Register or replace a capability. */
+    register(name, capability, origin = 'extension') {
+        this.capabilities.set(name, { capability, origin });
+    }
+    /** Return true when a capability exists. */
+    has(name) {
+        return this.capabilities.has(name);
+    }
+    /** Get a registered capability or throw a clear error. */
+    get(name) {
+        const entry = this.capabilities.get(name);
+        if (entry === undefined) {
+            throw new Error(`Unknown ${this.kind}: ${name}`);
+        }
+        return entry.capability;
+    }
+    /** List registered capability names. */
+    list() {
+        return [...this.capabilities.keys()];
+    }
+}

package/dist/host/rule-engine-host.d.ts

@@ -0,0 +1,11 @@
+import type { ResultFormatter, RuleEvaluator } from '../types';
+import { CapabilityRegistry } from './capability-registry';
+/** Host container for rule-engine capabilities. */
+export declare class RuleEngineHost {
+    /** Evaluator registry keyed by evaluator type. */
+    readonly evaluators: CapabilityRegistry<RuleEvaluator>;
+    /** Formatter registry keyed by formatter name. */
+    readonly formatters: CapabilityRegistry<ResultFormatter>;
+    constructor();
+}
+//# sourceMappingURL=rule-engine-host.d.ts.map

package/dist/host/rule-engine-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-engine-host.d.ts","sourceRoot":"","sources":["../../src/host/rule-engine-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,mDAAmD;AACnD,qBAAa,cAAc;IACvB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAC;IACvD,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;;CAM5D"}

package/dist/host/rule-engine-host.js

@@ -0,0 +1,12 @@
+import { CapabilityRegistry } from './capability-registry.js';
+/** Host container for rule-engine capabilities. */
+export class RuleEngineHost {
+    /** Evaluator registry keyed by evaluator type. */
+    evaluators;
+    /** Formatter registry keyed by formatter name. */
+    formatters;
+    constructor() {
+        this.evaluators = new CapabilityRegistry('evaluator');
+        this.formatters = new CapabilityRegistry('formatter');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './config/loader';
+export * from './engine';
+export * from './formatters/json';
+export * from './formatters/text';
+export * from './host/capability-registry';
+export * from './host/rule-engine-host';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './config/loader.js';
+export * from './engine.js';
+export * from './formatters/json.js';
+export * from './formatters/text.js';
+export * from './host/capability-registry.js';
+export * from './host/rule-engine-host.js';
+export * from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,218 @@
+import { z } from 'zod';
+/** Finding severity emitted by the rule engine. */
+export type RuleSeverity = 'error' | 'warning' | 'info';
+/** Fix authority level for candidate fixes. */
+export type FixMode = 'none' | 'suggest' | 'auto';
+/** Structured configuration for a rule evaluator. */
+export interface RuleEvaluatorConfig {
+    /** Evaluator type key registered in the host. */
+    type: string;
+    /** Evaluator-specific options. */
+    config?: Record<string, unknown>;
+}
+/** Constraint rule definition loaded from YAML or JSON. */
+export interface ConstraintRule {
+    /** Stable rule identifier. */
+    id: string;
+    /** Human-readable description. */
+    description: string;
+    /** Whether this rule is active. */
+    enabled: boolean;
+    /** Finding severity emitted by this rule. */
+    severity: RuleSeverity;
+    /** Evaluator configuration. */
+    evaluator: RuleEvaluatorConfig;
+    /** Optional include globs or paths. */
+    include?: string[];
+    /** Optional exclude globs or paths. */
+    exclude?: string[];
+    /** Optional fix metadata. */
+    fix?: RuleFixConfig;
+}
+/** Fix configuration authored on a rule. */
+export interface RuleFixConfig {
+    /** Maximum fix mode allowed by the rule. */
+    mode: FixMode;
+    /** Optional replacement text used by simple fixers. */
+    replacement?: string;
+    /** Optional fixer-specific parameters. */
+    params?: Record<string, unknown>;
+}
+/** Rule file shape before normalization. */
+export interface ConstraintRuleFile {
+    /** File-level default include patterns. */
+    include?: string[];
+    /** File-level default exclude patterns. */
+    exclude?: string[];
+    /** File-level default severity. */
+    severity?: RuleSeverity;
+    /** Rule definitions. */
+    rules: ConstraintRule[];
+}
+/** Preset definition that composes category folders or other presets. */
+export interface PresetDefinition {
+    /** Preset name. */
+    name: string;
+    /** Category folders or preset names to compose. */
+    extends: string[];
+    /** Rule IDs to disable. */
+    disable?: string[];
+    /** Per-rule overrides. */
+    overrides?: Record<string, {
+        fix?: {
+            mode: FixMode;
+        };
+    }>;
+}
+/** Candidate fix emitted by an evaluator or fixer. */
+export interface Fix {
+    /** Rule that produced this fix. */
+    ruleId: string;
+    /** Relative or absolute target file path. */
+    filePath: string;
+    /** Byte start offset. */
+    start: number;
+    /** Byte end offset. */
+    end: number;
+    /** Replacement content. */
+    replacement: string;
+    /** Whether this fix may be applied automatically. */
+    mode: Exclude<FixMode, 'none'>;
+}
+/** Finding emitted by a constraint rule. */
+export interface ConstraintFinding {
+    /** Rule identifier. */
+    ruleId: string;
+    /** Finding severity. */
+    severity: RuleSeverity;
+    /** Finding message. */
+    message: string;
+    /** Relative or absolute path involved in the finding. */
+    filePath: string | null;
+    /** Optional one-based line number. */
+    line?: number;
+    /** Optional column number. */
+    column?: number;
+    /** Machine-readable evaluator/source code. */
+    code?: string;
+}
+/** Aggregate result returned by a rule evaluator. */
+export interface RuleEvaluationResult {
+    /** Findings emitted by the evaluator. */
+    findings: ConstraintFinding[];
+    /** Candidate fixes emitted by the evaluator. */
+    fixes: Fix[];
+}
+/** Context passed to evaluator implementations. */
+export interface RuleContext {
+    /** Working directory being evaluated. */
+    workdir: string;
+    /** Rule being evaluated. */
+    rule: ConstraintRule;
+}
+/** Evaluator implementation contract. */
+export interface RuleEvaluator {
+    /** Evaluate a rule against the supplied context. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+/** Formatter implementation contract. */
+export interface ResultFormatter {
+    /** Format an engine result for CLI or machine output. */
+    format(result: RuleEngineResult): string;
+}
+/** Engine-level evaluation result. */
+export interface RuleEngineResult {
+    /** Findings emitted by enabled rules. */
+    findings: ConstraintFinding[];
+    /** Candidate fixes emitted by enabled rules. */
+    fixes: Fix[];
+}
+/** Create a finding with inherited rule severity. */
+export declare function createFinding(rule: ConstraintRule, message: string, filePath: string | null, extras?: Omit<Partial<ConstraintFinding>, 'ruleId' | 'severity' | 'message' | 'filePath'>): ConstraintFinding;
+/** Zod schema for rule fix configuration. */
+export declare const RuleFixConfigSchema: z.ZodDefault<z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        suggest: "suggest";
+        auto: "auto";
+    }>>;
+    replacement: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>>;
+/** Zod schema for a single constraint rule. */
+export declare const ConstraintRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+    evaluator: z.ZodObject<{
+        type: z.ZodString;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fix: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            suggest: "suggest";
+            auto: "auto";
+        }>>;
+        replacement: z.ZodOptional<z.ZodString>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Zod schema for a constraint rule file. */
+export declare const ConstraintRuleFileSchema: z.ZodObject<{
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    severity: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+    rules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodDefault<z.ZodString>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        severity: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>>;
+        evaluator: z.ZodObject<{
+            type: z.ZodString;
+            config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fix: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            mode: z.ZodDefault<z.ZodEnum<{
+                none: "none";
+                suggest: "suggest";
+                auto: "auto";
+            }>>;
+            replacement: z.ZodOptional<z.ZodString>;
+            params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Zod schema for a preset definition. */
+export declare const PresetDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    extends: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    disable: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        fix: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<{
+                none: "none";
+                suggest: "suggest";
+                auto: "auto";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/** Create a finding with inherited rule severity. */
+export function createFinding(rule, message, filePath, extras = {}) {
+    return {
+        ruleId: rule.id,
+        severity: rule.severity,
+        message,
+        filePath,
+        ...extras,
+    };
+}
+/** Zod schema for rule fix configuration. */
+export const RuleFixConfigSchema = z
+    .object({
+    mode: z.enum(['none', 'suggest', 'auto']).default('none'),
+    replacement: z.string().optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+})
+    .default({ mode: 'none' });
+/** Zod schema for a single constraint rule. */
+export const ConstraintRuleSchema = z.object({
+    id: z.string().min(1),
+    description: z.string().default(''),
+    enabled: z.boolean().default(true),
+    severity: z.enum(['error', 'warning', 'info']).default('error'),
+    evaluator: z.object({
+        type: z.string().min(1),
+        config: z.record(z.string(), z.unknown()).optional(),
+    }),
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+    fix: RuleFixConfigSchema.optional(),
+});
+/** Zod schema for a constraint rule file. */
+export const ConstraintRuleFileSchema = z.object({
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+    severity: z.enum(['error', 'warning', 'info']).optional(),
+    rules: z.array(ConstraintRuleSchema),
+});
+/** Zod schema for a preset definition. */
+export const PresetDefinitionSchema = z.object({
+    name: z.string().min(1),
+    extends: z.array(z.string()).default([]),
+    disable: z.array(z.string()).optional(),
+    overrides: z
+        .record(z.string(), z.object({ fix: z.object({ mode: z.enum(['none', 'suggest', 'auto']) }).optional() }))
+        .optional(),
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@gobing-ai/ts-rule-engine",
+    "version": "0.2.1",
+    "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
+    "keywords": [
+        "typescript",
+        "rules",
+        "policy",
+        "quality",
+        "engine"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gobing-ai/ts-libs.git",
+        "directory": "packages/rule-engine"
+    },
+    "author": "Robin Min <minlongbing@gmail.com>",
+    "contributors": [
+        "Robin Min <minlongbing@gmail.com>"
+    ],
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/builder.ts fix-dist-esm-extensions dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "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": "workspace:*",
+        "@gobing-ai/ts-runtime": "workspace:*",
+        "yaml": "^2.7.0",
+        "zod": "^4.1.0"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/config/loader.ts

@@ -0,0 +1,122 @@
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { parse } from 'yaml';
+import {
+    type ConstraintRule,
+    type ConstraintRuleFile,
+    ConstraintRuleFileSchema,
+    ConstraintRuleSchema,
+    type PresetDefinition,
+    PresetDefinitionSchema,
+} from '../types';
+
+/** Options for loading rule presets. */
+export interface RuleLoaderOptions {
+    /** Project working directory. */
+    workdir: string;
+    /** Rule root directory. Defaults to ".spur/rules". */
+    rulesRoot?: string;
+}
+
+/** Load and normalize a preset by name. */
+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);
+    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]))));
+    }
+    const disabled = new Set(preset.disable ?? []);
+    const normalized = rules.filter((rule) => !disabled.has(rule.id));
+    for (const rule of normalized) {
+        const override = preset.overrides?.[rule.id];
+        if (override?.fix !== undefined) {
+            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: 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);
+    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)));
+            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))));
+    }
+    return rules;
+}
+
+async function findDefinitionPath(root: string, name: string): Promise<string | null> {
+    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;
+    }
+    return null;
+}
+
+async function readStructuredFile(path: string): Promise<unknown> {
+    const content = await new NodeFileSystem().readFile(path);
+    return extname(path) === '.json' ? JSON.parse(content) : parse(content);
+}
+
+function normalizeRuleFile(raw: unknown, sourceDir: string): ConstraintRule[] {
+    const maybeFile = ConstraintRuleFileSchema.safeParse(raw);
+    if (maybeFile.success) return normalizeFileRules(maybeFile.data, sourceDir);
+    const maybeRule = ConstraintRuleSchema.safeParse(raw);
+    if (maybeRule.success) return [normalizeRule(maybeRule.data, {}, sourceDir)];
+    throw new Error(`Invalid rule file: ${basename(sourceDir)}`);
+}
+
+function normalizeFileRules(file: ConstraintRuleFile, sourceDir: string): ConstraintRule[] {
+    return file.rules.map((rule) =>
+        normalizeRule(
+            {
+                ...rule,
+                severity: rule.severity ?? file.severity ?? 'error',
+                include: rule.include ?? file.include,
+                exclude: rule.exclude ?? file.exclude,
+            },
+            {},
+            sourceDir,
+        ),
+    );
+}
+
+function normalizeRule(rule: ConstraintRule, _defaults: Partial<ConstraintRule>, _sourceDir: string): ConstraintRule {
+    return {
+        ...rule,
+        enabled: rule.enabled ?? true,
+        severity: rule.severity ?? 'error',
+    };
+}

package/src/engine.ts

@@ -0,0 +1,50 @@
+import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { registerBuiltins } from './host/builtins';
+import { RuleEngineHost } from './host/rule-engine-host';
+import type { ConstraintFinding, ConstraintRule, RuleEngineResult, RuleEvaluator } from './types';
+import { createFinding } from './types';
+
+/** Options for constructing a RuleEngine. */
+export interface RuleEngineOptions {
+    /** Optional executor supplied to process-backed evaluators. */
+    processExecutor?: ProcessExecutor;
+    /** Optional preconfigured host. */
+    host?: RuleEngineHost;
+}
+
+/** Orchestrates enabled constraint rules through a typed evaluator host. */
+export class RuleEngine {
+    /** Capability host used by this engine. */
+    readonly host: RuleEngineHost;
+
+    constructor(options: RuleEngineOptions = {}) {
+        this.host = options.host ?? new RuleEngineHost();
+        registerBuiltins(this.host, options.processExecutor);
+    }
+
+    /** Register or replace an evaluator. */
+    registerEvaluator(type: string, evaluator: RuleEvaluator): void {
+        this.host.evaluators.register(type, evaluator, 'extension');
+    }
+
+    /** Evaluate all enabled rules against a working directory. */
+    async evaluate(rules: ConstraintRule[], workdir: string): Promise<RuleEngineResult> {
+        const findings: ConstraintFinding[] = [];
+        const fixes = [];
+        for (const rule of rules) {
+            if (rule.enabled === false) continue;
+            try {
+                const result = await this.host.evaluators.get(rule.evaluator.type).evaluate(rule, { rule, workdir });
+                findings.push(...result.findings);
+                fixes.push(...result.fixes);
+            } catch (error) {
+                findings.push(
+                    createFinding(rule, error instanceof Error ? error.message : String(error), null, {
+                        code: `evaluator:${rule.evaluator.type}`,
+                    }),
+                );
+            }
+        }
+        return { findings, fixes };
+    }
+}