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

package/README.md

@@ -1,3 +1,565 @@
 # @gobing-ai/ts-rule-engine
 
-Constraint rule schemas, preset loading, evaluator orchestration, and result formatting for TypeScript/Bun projects.
+Constraint rule loading, evaluation, formatting, and fix generation for Bun/TypeScript projects.
+
+This package is a library. It does not ship a CLI. Downstream tools can use it to load rule presets, evaluate a workspace, format findings, collect fix candidates, and optionally apply those fixes.
+
+## Briefing
+
+`ts-rule-engine` is a policy workflow engine: loaders turn rule files and presets into `ConstraintRule` objects, `RuleEngine` dispatches each rule to a matching evaluator through `RuleEngineHost`, and the result can be formatted for users or converted into fix candidates for controlled application.
+
+```mermaid
+erDiagram
+    RULE_ENGINE ||--|| RULE_ENGINE_HOST : uses
+    RULE_ENGINE ||--o{ CONSTRAINT_RULE : evaluates
+    RULE_ENGINE_HOST ||--o{ EVALUATOR : registers
+    RULE_ENGINE_HOST ||--o{ RESOLVER : registers
+    RULE_ENGINE_HOST ||--o{ FORMATTER : registers
+    RULE_ENGINE ||--o{ FIXER : owns
+    PRESET ||--o{ CONSTRAINT_RULE : composes
+    PRESET ||--o{ EXTENSION : declares
+    EXTENSION }o--|| RULE_ENGINE_HOST : loads_into
+    EVALUATOR ||--o{ FINDING : emits
+    FIXER ||--o{ FIX : emits
+    FORMATTER ||--|| RESULT : renders
+```
+
+| Entity | One-line Description |
+|--------|----------------------|
+| `RuleEngine` | Orchestrates the evaluation workflow for enabled rules in a target workspace. |
+| `RuleEngineHost` | Holds named capability registries for evaluators, resolvers, and formatters. |
+| `ConstraintRule` | Declarative policy unit with matching scope, severity, evaluator config, and optional fix config. |
+| `Preset` | YAML/JSON composition unit that collects rule categories, other presets, disabled rules, and extension refs. |
+| `Evaluator` | Executes one rule type and emits findings plus any evaluator-native fixes. |
+| `Resolver` | Maps source paths to related test paths or skeletons for rules such as `test-location`. |
+| `Formatter` | Renders a `RuleEngineResult` as text, JSON, or a downstream custom report format. |
+| `Fixer` | Produces file edits from findings when a rule opts into manual or automatic fix modes. |
+| `Extension` | Trusted local module declared by presets to register custom resolvers, evaluators, or formatters. |
+| `Finding` | Structured policy violation or evaluator error with severity, location, and machine-readable code. |
+| `Fix` | Candidate byte-range or file-level edit returned separately from findings and applied only on request. |
+| `RuleEngineResult` | Aggregate output containing all findings and fixes for one evaluation run. |
+
+## Install
+
+```bash
+bun add @gobing-ai/ts-rule-engine
+```
+
+## Mental Model
+
+```mermaid
+flowchart TD
+    Files["YAML / JSON rule files"] --> Loader["loadRuleFile() / loadPreset()"]
+    Loader --> Rules["ConstraintRule[]"]
+    Rules --> Engine["RuleEngine"]
+    Engine --> Host["RuleEngineHost registries"]
+    Host --> Evaluators["evaluators by type"]
+    Host --> Resolvers["test path resolvers"]
+    Host --> Formatters["text / json formatters"]
+    Engine --> Result["{ findings, fixes }"]
+    Result --> Formatter["TextFormatter / JsonFormatter"]
+    Result --> Apply["applyFixes()"]
+```
+
+Core concepts:
+
+- `ConstraintRule`: one policy check. It has an `id`, `severity`, evaluator type/config, optional include/exclude globs, and optional fix config.
+- `RuleEngine`: runs enabled rules against a `workdir`.
+- `RuleEngineHost`: registry container for evaluators, formatters, and test-path resolvers.
+- `RuleEvaluator`: implementation of one rule type, such as `regex`, `path`, or `coverage-gate`.
+- `Fix`: byte-range replacement candidate. Fixes are collected separately from findings and are only written when you call `applyFixes()`.
+- Preset: YAML/JSON file that composes rule categories and can expose extension modules.
+
+## Quick Start
+
+```ts
+import { RuleEngine, TextFormatter, type ConstraintRule } from '@gobing-ai/ts-rule-engine';
+
+const rules: ConstraintRule[] = [
+  {
+    id: 'no-console-log',
+    description: 'Do not commit console.log calls',
+    enabled: true,
+    severity: 'error',
+    include: ['src/**/*.ts'],
+    evaluator: {
+      type: 'regex',
+      config: {
+        mode: 'forbid',
+        pattern: 'console\\.log\\(',
+      },
+    },
+  },
+];
+
+const engine = new RuleEngine();
+const result = await engine.evaluate(rules, process.cwd());
+
+console.log(new TextFormatter().format(result));
+process.exitCode = result.findings.some((finding) => finding.severity === 'error') ? 1 : 0;
+```
+
+## Rule Files
+
+Rule files can be YAML, JSON, or a single rule object. File loads honor a top-level `$schema` ref by default, then validate the internal Zod schema. The `$schema` value is resolved from the bundled package schema (shipped under `node_modules/@gobing-ai/ts-rule-engine/schemas/`) — no network access. Quote the value, since YAML treats a leading `@` as reserved. Relative paths and (opt-in) remote URLs are also supported; see `@gobing-ai/ts-runtime` → *Structured config* for the full resolution rules. A multi-rule YAML file looks like this:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+include:
+  - "packages/*/src/**/*.ts"
+exclude:
+  - "**/*.test.ts"
+severity: error
+rules:
+  - id: no-console-log
+    description: Do not commit console.log calls
+    evaluator:
+      type: regex
+      config:
+        mode: forbid
+        pattern: "console\\.log\\("
+
+  - id: source-files-have-tests
+    description: Source files should have matching tests
+    evaluator:
+      type: test-location
+      config:
+        expected: "packages/*/tests/**/*.test.ts"
+        requireCorrespondingTest: true
+        resolver: typescript
+    include:
+      - "packages/*/src/**/*.ts"
+```
+
+Load a rule file directly:
+
+```ts
+import { loadRuleFile } from '@gobing-ai/ts-rule-engine';
+
+const rules = await loadRuleFile('.rules/typescript.yaml');
+```
+
+## Presets
+
+Presets compose category folders, other presets, and rule-file subpaths across one or more roots. Preset loads also honor top-level `$schema` refs by default, resolved from the bundled package schema (no network access).
+
+Example layout:
+
+```text
+.spur/rules/
+  recommended.yaml
+  quality/
+    coverage.yaml
+  architecture/
+    imports.yaml
+```
+
+Example preset:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/preset.schema.json"
+name: recommended
+extends:
+  - quality
+  - architecture/imports
+disable:
+  - legacy-rule
+overrides:
+  no-console-log:
+    fix:
+      mode: suggest
+```
+
+Load just the rules:
+
+```ts
+import { loadPresetRules } from '@gobing-ai/ts-rule-engine';
+
+const rules = await loadPresetRules('recommended', {
+  roots: ['.spur/rules'],
+});
+```
+
+Load rules plus extension refs:
+
+```ts
+import { loadPreset, loadExtensionsIntoHost, RuleEngine } from '@gobing-ai/ts-rule-engine';
+
+const loaded = await loadPreset('recommended', {
+  roots: ['.spur/rules'],
+});
+
+const engine = new RuleEngine();
+await loadExtensionsIntoHost(engine.host, loaded.extensions, {
+  allowExtensions: true,
+});
+
+const result = await engine.evaluate(loaded.rules, process.cwd());
+```
+
+Roots are ordered highest priority first. If two roots contain the same relative rule file, the first root wins and lower-priority roots fill gaps.
+
+## Evaluating With Fixes
+
+Some evaluators have built-in fixer providers. Fixes are never written during evaluation; they are returned as candidates.
+
+```ts
+import { RuleEngine } from '@gobing-ai/ts-rule-engine';
+
+const engine = new RuleEngine();
+const result = await engine.evaluateWithFixes(rules, process.cwd(), 'auto');
+
+const preview = await engine.applyFixes(process.cwd(), result.fixes, true);
+console.log(preview.diff);
+
+// Write changes after you have decided to apply them.
+await engine.applyFixes(process.cwd(), result.fixes);
+```
+
+Fix authority levels:
+
+| Mode | Meaning |
+| ---- | ------- |
+| `none` | Do not emit provider fixes. This is the default when `rule.fix` is absent. |
+| `suggest` | Emit fixes only when caller allows at least `suggest`. |
+| `auto` | Emit fixes when caller allows `auto`. |
+
+The effective fix mode is the lower authority between `rule.fix.mode` and the caller's `maxFixMode` argument.
+
+Example rule with regex replacement:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: rename-foo
+    description: Replace foo with bar
+    evaluator:
+      type: regex
+      config:
+        mode: forbid
+        pattern: "\\bfoo\\b"
+        flags: g
+    fix:
+      mode: auto
+      replacement: bar
+    include:
+      - "src/**/*.ts"
+```
+
+Built-in fixer providers:
+
+| Evaluator type | Fix behavior |
+| -------------- | ------------ |
+| `regex`, `rg` | Replaces line matches using `fix.replacement`. |
+| `path`, `file-exist` | Deletes files for `must: absent` rules in `auto` mode. |
+| `test-location` | Creates a missing test file using the selected resolver's skeleton when available. |
+
+## Built-in Evaluators
+
+| Type | Purpose | Notes |
+| ---- | ------- | ----- |
+| `regex`, `rg` | Match or require text patterns in files. | Pure JS file scanning. Supports inline `(?i)` flags and `multiline`. |
+| `path`, `file-exist` | Check required or forbidden paths. | Supports explicit `paths` or glob-style `must: present/absent`. |
+| `exit-code` | Run a command and evaluate its exit code. | Uses `ProcessExecutor`; inject one through `new RuleEngine({ processExecutor })` for tests. |
+| `forbidden-import` | Block forbidden imports/usages. | Useful for package boundary rules. |
+| `import-boundary` | Enforce scoped architectural import boundaries. | Supports per-boundary scope, excludes, and forbidden patterns. |
+| `secrets-scanner` | Detect hardcoded secrets. | Built-in categories plus custom patterns. |
+| `agent-detection` | Detect coding-agent related files. | Project hygiene use case. |
+| `coverage-gate` | Enforce per-file lcov line coverage thresholds. | Reads `lcov.info`. Supports exemptions. |
+| `tsdoc-export` | Require JSDoc/TSDoc before exported declarations. | TypeScript source scanning. |
+| `test-location` | Enforce test placement and matching source/test pairs. | Uses named test-path resolvers. |
+| `schema-artifact` | Validate JSON schema artifact structure. | Checks existence, JSON validity, title, properties, defs, required array. |
+| `sg` | Run an ast-grep pattern. | Requires the `sg` CLI in the execution environment. |
+
+### Common Evaluator Examples
+
+Regex forbid:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: no-debugger
+    description: Do not commit debugger statements
+    evaluator:
+      type: regex
+      config:
+        mode: forbid
+        pattern: "\\bdebugger\\b"
+    include: ["src/**/*.ts"]
+```
+
+Path presence:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: package-readme-required
+    description: Each package should document its public API
+    evaluator:
+      type: path
+      config:
+        paths: ["README.md"]
+```
+
+Glob absence:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: no-dist-in-source
+    description: Built artifacts should not be committed
+    evaluator:
+      type: path
+      config:
+        must: absent
+    include: ["dist/**"]
+```
+
+Coverage gate:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: coverage-gate
+    description: Source files must meet coverage threshold
+    evaluator:
+      type: coverage-gate
+      config:
+        lcovPath: .coverage/lcov.info
+        threshold: 90
+        exemptions:
+          - path: packages/legacy/src/adapter.ts
+            threshold: 70
+            reason: legacy branch coverage tracked separately
+```
+
+Import boundary:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: db-boundary
+    description: Only ts-db may import drizzle
+    evaluator:
+      type: import-boundary
+      config:
+        boundaries:
+          - scope: "packages/*/src/**/*.ts"
+            exclude:
+              - "packages/db/src/**"
+            forbidden:
+              - drizzle-orm
+```
+
+Schema artifact:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: rule-schema-artifact
+    description: Rule JSON schema artifact is complete
+    evaluator:
+      type: schema-artifact
+      config:
+        file: schema/rules.schema.json
+        requiredTitle: ConstraintRule
+        requiredProperties: ["rules"]
+        requiredDefs: ["evaluator"]
+        requireRequiredArray: true
+```
+
+ast-grep:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: no-throw-string
+    description: Throw Error objects, not strings
+    evaluator:
+      type: sg
+      config:
+        pattern: throw "$MSG"
+        language: typescript
+    include: ["src/**/*.ts"]
+```
+
+## Test-Path Resolvers
+
+The `test-location` evaluator can require source files to have corresponding test files. The resolver is selected by `evaluator.config.resolver`.
+
+| Resolver | Source path | Expected test path |
+| -------- | ----------- | ------------------ |
+| `typescript` | `src/foo/bar.ts` | `tests/foo/bar.test.ts` |
+| `typescript` | `packages/core/src/foo.ts` | `packages/core/tests/foo.test.ts` |
+| `python` | `src/foo/bar.py` | `tests/foo/test_bar.py` |
+| `go` | `foo/bar.go` | `foo/bar_test.go` |
+| `rust` | `crate/src/foo.rs` | `crate/tests/foo.rs` |
+
+Example:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: python-sources-have-tests
+    description: Python sources should have pytest files
+    evaluator:
+      type: test-location
+      config:
+        expected: "tests/**/*.py"
+        resolver: python
+        requireCorrespondingTest: true
+    include: ["src/**/*.py"]
+```
+
+## Custom Evaluators
+
+Register a custom evaluator directly:
+
+```ts
+import {
+  RuleEngine,
+  createFinding,
+  type RuleEvaluator,
+} from '@gobing-ai/ts-rule-engine';
+
+const evaluator: RuleEvaluator = {
+  async evaluate(rule, context) {
+    if (!context.workdir.includes('service')) {
+      return {
+        findings: [
+          createFinding(rule, 'workspace path must include "service"', null, {
+            code: 'custom:not-service',
+          }),
+        ],
+        fixes: [],
+      };
+    }
+    return { findings: [], fixes: [] };
+  },
+};
+
+const engine = new RuleEngine();
+engine.registerEvaluator('workspace-name', evaluator);
+```
+
+Then use it in a rule:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
+rules:
+  - id: workspace-name
+    description: Check workspace naming convention
+    evaluator:
+      type: workspace-name
+```
+
+## Preset Extensions
+
+Preset extensions are trusted local modules. They are disabled unless the caller explicitly passes `allowExtensions: true` to `loadExtensionsIntoHost()`.
+
+Preset:
+
+```yaml
+$schema: "@gobing-ai/ts-rule-engine/schemas/preset.schema.json"
+name: local
+extends:
+  - quality
+extensions:
+  resolvers:
+    - ./extensions/custom-resolver.ts
+  evaluators:
+    - ./extensions/custom-evaluator.ts
+  formatters:
+    - ./extensions/compact-formatter.ts
+```
+
+Resolver extension:
+
+```ts
+export default {
+  name: 'custom',
+  resolveTestPath(srcRelPath: string): string {
+    return srcRelPath.replace(/^src\//, 'tests/').replace(/\.ts$/, '.spec.ts');
+  },
+};
+```
+
+Evaluator extension:
+
+```ts
+import type { RuleEvaluator } from '@gobing-ai/ts-rule-engine';
+
+const evaluator: RuleEvaluator & { name: string } = {
+  name: 'custom-check',
+  async evaluate() {
+    return { findings: [], fixes: [] };
+  },
+};
+
+export default evaluator;
+```
+
+Load extensions:
+
+```ts
+const loaded = await loadPreset('local', { roots: ['.spur/rules'] });
+const engine = new RuleEngine();
+
+await loadExtensionsIntoHost(engine.host, loaded.extensions, {
+  allowExtensions: true,
+  logger: { warn: console.warn },
+});
+```
+
+Supported extension kinds:
+
+| Kind | Registry | Required shape |
+| ---- | -------- | -------------- |
+| `resolvers` | `host.resolvers` | object with `name` and `resolveTestPath()` |
+| `evaluators` | `host.evaluators` | object with `name` and `evaluate()` |
+| `formatters` | `host.formatters` | object with `name` and `format()` |
+
+`fixers` can be declared in preset metadata but are not loaded into `RuleEngineHost` by `loadExtensionsIntoHost()` because fixer providers live on the engine's fixer map.
+
+## Formatting Results
+
+```ts
+import { JsonFormatter, TextFormatter } from '@gobing-ai/ts-rule-engine';
+
+const text = new TextFormatter().format(result);
+const json = new JsonFormatter().format(result);
+```
+
+Text output is intended for humans:
+
+```text
+ERROR no-console-log src/index.ts:12 forbidden pattern found: console\.log\(
+```
+
+JSON output is the full `RuleEngineResult` object.
+
+## Error Handling
+
+Evaluator runtime errors are captured as findings with:
+
+- `kind: "error"`
+- `code: "evaluator:<type>"`
+- `filePath: null`
+
+That lets downstream tools distinguish policy violations from misconfigured or failing evaluators.
+
+```ts
+const errors = result.findings.filter((finding) => finding.kind === 'error');
+const violations = result.findings.filter((finding) => finding.kind !== 'error');
+```
+
+## Package Boundary
+
+This package owns rule definitions, preset loading, evaluators, formatters, test-path resolvers, and fix application. It does not own:
+
+- CLI argument parsing
+- process exit policy
+- repository-specific rule catalogs
+- publishing or CI integration
+
+Those concerns should live in downstream tools that consume this library.

package/dist/config/extensions.d.ts

@@ -22,6 +22,8 @@ export interface LoadExtensionsOptions {
     logger?: {
         warn: (message: string) => void;
     };
+    /** Optional module loader seam for tests or embedders with custom import policy. */
+    moduleLoader?: (absPath: string) => Promise<Record<string, unknown>>;
 }
 /**
  * Collect extension refs declared by a preset's `extensions` block.

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

@@ -1 +1 @@
-{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/config/extensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEjF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAChD;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC7E,YAAY,EAAE,CAShB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CACxC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAmCf"}
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/config/extensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEjF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAC7C,oFAAoF;IACpF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxE;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC7E,YAAY,EAAE,CAShB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CACxC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAoCf"}

package/dist/config/extensions.js

@@ -41,8 +41,9 @@ export async function loadExtensionsIntoHost(host, refs, options = {}) {
         const first = refs[0];
         throw new Error(`preset "${first.presetName}" declares ${first.kind} extension "${first.absPath}", but extensions are disabled — pass allowExtensions: true to load preset extension modules`);
     }
+    const loadModule = options.moduleLoader ?? defaultModuleLoader;
     for (const ref of refs) {
-        const moduleExports = (await import(ref.absPath));
+        const moduleExports = await loadModule(ref.absPath);
         const candidate = moduleExports.default ?? moduleExports.extension;
         if (candidate === null ||
             typeof candidate !== 'object' ||
@@ -61,3 +62,6 @@ export async function loadExtensionsIntoHost(host, refs, options = {}) {
         registry.register(name, candidate, 'extension');
     }
 }
+async function defaultModuleLoader(absPath) {
+    return (await import(absPath));
+}

package/dist/config/loader.d.ts

@@ -1,4 +1,5 @@
 import { type ConstraintRule } from '../types';
+import { type ExtensionRef } from './extensions';
 /** Options for loading rule presets. */
 export interface RuleLoaderOptions {
     /**
@@ -9,6 +10,23 @@ export interface RuleLoaderOptions {
      * loader stays agnostic to any project layout convention.
      */
     roots: string[];
+    /** When true, honor top-level `$schema` refs in preset and rule files. Defaults to true. */
+    validateSchema?: boolean;
+    /** Optional fetch implementation for remote HTTP(S) schema refs. */
+    fetch?: (input: string) => Promise<Response>;
+}
+export interface RuleFileLoadOptions {
+    /** When true, honor top-level `$schema` refs. Defaults to true. */
+    validateSchema?: boolean;
+    /** Optional fetch implementation for remote HTTP(S) schema refs. */
+    fetch?: (input: string) => Promise<Response>;
+}
+/** Loaded preset rules plus extension module refs declared by composed presets. */
+export interface LoadedPreset {
+    /** Normalized rules after preset disable/override handling. */
+    readonly rules: ConstraintRule[];
+    /** Extension modules declared by the preset graph, resolved to absolute paths. */
+    readonly extensions: ExtensionRef[];
 }
 /**
  * Load and normalize a preset by name, resolving across one or more rule roots.
@@ -17,7 +35,8 @@ export interface RuleLoaderOptions {
  * 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 loadPreset(name: string, options: RuleLoaderOptions): Promise<LoadedPreset>;
 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[]>;
+export declare function loadRuleFile(filePath: string, options?: RuleFileLoadOptions): Promise<ConstraintRule[]>;
 //# sourceMappingURL=loader.d.ts.map

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;;;;;;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"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,cAAc,EAMtB,MAAM,UAAU,CAAC;AAClB,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4FAA4F;IAC5F,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAChC,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChD;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC;CACvC;AAUD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBhG;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAEzG;AAED,yCAAyC;AACzC,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGjH"}

package/dist/config/loader.js

@@ -1,7 +1,7 @@
-import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
-import { NodeFileSystem } from '@gobing-ai/ts-runtime';
-import { parse } from 'yaml';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { loadStructuredConfig, NodeFileSystem } from '@gobing-ai/ts-runtime';
 import { ConstraintRuleFileSchema, ConstraintRuleSchema, PresetDefinitionSchema, } from '../types.js';
+import { collectPresetExtensions } from './extensions.js';
 /**
  * Load and normalize a preset by name, resolving across one or more rule roots.
  *
@@ -9,15 +9,18 @@ import { ConstraintRuleFileSchema, ConstraintRuleSchema, PresetDefinitionSchema,
  * 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) {
+export async function loadPreset(name, options) {
     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));
+        return { rules: [], extensions: [] };
+    const preset = PresetDefinitionSchema.parse(await readStructuredFile(presetPath, options));
     const rules = [];
+    const extensions = collectPresetExtensions(preset.name, dirname(presetPath), preset.extensions);
     for (const entry of preset.extends) {
-        rules.push(...(await loadPresetEntry(merged, entry, new Set([name]))));
+        const loaded = await loadPresetEntry(merged, entry, new Set([name]), options);
+        rules.push(...loaded.rules);
+        extensions.push(...loaded.extensions);
     }
     const disabled = new Set(preset.disable ?? []);
     const normalized = rules.filter((rule) => !disabled.has(rule.id));
@@ -27,41 +30,52 @@ export async function loadPresetRules(name, options) {
             rule.fix = { ...(rule.fix ?? { mode: 'none' }), ...override.fix };
         }
     }
-    return normalized;
+    return { rules: normalized, extensions };
+}
+export async function loadPresetRules(name, options) {
+    return (await loadPreset(name, options)).rules;
 }
 /** Load a direct rule file from disk. */
-export async function loadRuleFile(filePath) {
-    return normalizeRuleFile(await readStructuredFile(resolve(filePath)), dirname(resolve(filePath)));
+export async function loadRuleFile(filePath, options = {}) {
+    const resolved = resolve(filePath);
+    return normalizeRuleFile(await readStructuredFile(resolved, options), dirname(resolved));
 }
-async function loadPresetEntry(merged, entry, seen) {
+async function loadPresetEntry(merged, entry, seen, options) {
     // Sub-preset reference — recurse, erroring on a genuine cycle.
     const presetPath = findMergedPreset(merged, entry);
     if (presetPath !== null) {
         if (seen.has(entry)) {
             throw new Error(`Circular preset dependency detected: ${[...seen, entry].join(' → ')}`);
         }
-        seen.add(entry);
-        const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath));
+        const nextSeen = new Set([...seen, entry]);
+        const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath, options));
         if (preset.success) {
             const rules = [];
-            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 extensions = collectPresetExtensions(preset.data.name, dirname(presetPath), preset.data.extensions);
+            for (const child of preset.data.extends) {
+                const loaded = await loadPresetEntry(merged, child, nextSeen, options);
+                rules.push(...loaded.rules);
+                extensions.push(...loaded.extensions);
+            }
+            return { rules: rules.filter((rule) => !(preset.data.disable ?? []).includes(rule.id)), extensions };
         }
     }
     // 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)));
+            rules.push(...normalizeRuleFile(await readStructuredFile(absPath, options), dirname(absPath)));
         }
-        return rules;
+        return { rules, extensions: [] };
     }
     // Sub-path reference — a single winning rule file within a category.
     const subPath = findMergedFile(merged, entry);
     if (subPath !== null)
-        return loadRuleFile(subPath);
-    return [];
+        return {
+            rules: normalizeRuleFile(await readStructuredFile(subPath, options), dirname(subPath)),
+            extensions: [],
+        };
+    return { rules: [], extensions: [] };
 }
 /**
  * Build the merged view across ordered roots.
@@ -155,9 +169,11 @@ async function listImmediateDirs(fs, dir) {
     }
     return dirs;
 }
-async function readStructuredFile(path) {
-    const content = await new NodeFileSystem().readFile(path);
-    return extname(path) === '.json' ? JSON.parse(content) : parse(content);
+async function readStructuredFile(path, options = {}) {
+    return await loadStructuredConfig(path, {
+        validateSchema: options.validateSchema,
+        fetch: options.fetch,
+    });
 }
 function normalizeRuleFile(raw, sourceDir) {
     const maybeFile = ConstraintRuleFileSchema.safeParse(raw);

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export interface RuleFixConfig {
 }
 /** Rule file shape before normalization. */
 export interface ConstraintRuleFile {
+    /** Optional JSON Schema ref used by editors and loader validation. */
+    $schema?: string;
     /** File-level default include patterns. */
     include?: string[];
     /** File-level default exclude patterns. */
@@ -62,6 +64,8 @@ export interface PresetExtensions {
 }
 /** Preset definition that composes category folders or other presets. */
 export interface PresetDefinition {
+    /** Optional JSON Schema ref used by editors and loader validation. */
+    $schema?: string;
     /** Preset name. */
     name: string;
     /** Category folders or preset names to compose. */
@@ -191,6 +195,7 @@ export declare const ConstraintRuleSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Zod schema for a constraint rule file. */
 export declare const ConstraintRuleFileSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     include: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     severity: z.ZodOptional<z.ZodEnum<{
@@ -226,6 +231,7 @@ export declare const ConstraintRuleFileSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Zod schema for a preset definition. */
 export declare const PresetDefinitionSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     extends: z.ZodDefault<z.ZodArray<z.ZodString>>;
     disable: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,+CAA+C;AAC/C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAElD,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAChC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC3B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,YAAY,CAAC;IACvB,+BAA+B;IAC/B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6BAA6B;IAC7B,GAAG,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IAC/B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,wBAAwB;IACxB,KAAK,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC7B,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC7B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE;YAAE,IAAI,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;IACxD,6EAA6E;IAC7E,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,sDAAsD;AACtD,MAAM,WAAW,GAAG;IAChB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;AAEhD,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAC9B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACjC,yCAAyC;IACzC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,gDAAgD;IAChD,KAAK,EAAE,GAAG,EAAE,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IACxB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,IAAI,EAAE,cAAc,CAAC;CACxB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACvF;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC5B,yDAAyD;IACzD,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAAC;CAC5C;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC7B,yCAAyC;IACzC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,gDAAgD;IAChD,KAAK,EAAE,GAAG,EAAE,CAAC;CAChB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CACzB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,GAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAM,GAC9F,iBAAiB,CAQnB;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB;;;;;;;;kBAMF,CAAC;AAE/B,+CAA+C;AAC/C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;iBAY/B,CAAC;AAEH,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMnC,CAAC;AAEH,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;iBAgBjC,CAAC"}

package/dist/types.js

@@ -33,6 +33,7 @@ export const ConstraintRuleSchema = z.object({
 });
 /** Zod schema for a constraint rule file. */
 export const ConstraintRuleFileSchema = z.object({
+    $schema: z.string().optional(),
     include: z.array(z.string()).optional(),
     exclude: z.array(z.string()).optional(),
     severity: z.enum(['error', 'warning', 'info']).optional(),
@@ -40,6 +41,7 @@ export const ConstraintRuleFileSchema = z.object({
 });
 /** Zod schema for a preset definition. */
 export const PresetDefinitionSchema = z.object({
+    $schema: z.string().optional(),
     name: z.string().min(1),
     extends: z.array(z.string()).default([]),
     disable: z.array(z.string()).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.2.7",
+    "version": "0.2.8",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -32,6 +32,7 @@
     },
     "files": [
         "dist",
+        "schemas",
         "src",
         "README.md"
     ],
@@ -47,8 +48,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.7",
-        "@gobing-ai/ts-runtime": "^0.2.7",
+        "@gobing-ai/ts-ai-runner": "^0.2.8",
+        "@gobing-ai/ts-runtime": "^0.2.8",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/schemas/preset.schema.json

@@ -0,0 +1,40 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://raw.githubusercontent.com/gobing-ai/ts-libs/main/packages/rule-engine/schemas/preset.schema.json",
+    "title": "@gobing-ai/ts-rule-engine Preset",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["name"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "name": { "type": "string" },
+        "extends": { "type": "array", "items": { "type": "string" } },
+        "disable": { "type": "array", "items": { "type": "string" } },
+        "overrides": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "fix": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "mode": { "enum": ["none", "suggest", "auto"] }
+                        }
+                    }
+                }
+            }
+        },
+        "extensions": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "resolvers": { "type": "array", "items": { "type": "string" } },
+                "evaluators": { "type": "array", "items": { "type": "string" } },
+                "fixers": { "type": "array", "items": { "type": "string" } },
+                "formatters": { "type": "array", "items": { "type": "string" } }
+            }
+        }
+    }
+}

package/schemas/rule-file.schema.json

@@ -0,0 +1,49 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://raw.githubusercontent.com/gobing-ai/ts-libs/main/packages/rule-engine/schemas/rule-file.schema.json",
+    "title": "@gobing-ai/ts-rule-engine Rule File",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["rules"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } },
+        "severity": { "enum": ["error", "warning", "info"] },
+        "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" } }
+    },
+    "$defs": {
+        "rule": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "evaluator"],
+            "properties": {
+                "id": { "type": "string" },
+                "description": { "type": "string" },
+                "enabled": { "type": "boolean" },
+                "severity": { "enum": ["error", "warning", "info"] },
+                "include": { "type": "array", "items": { "type": "string" } },
+                "exclude": { "type": "array", "items": { "type": "string" } },
+                "evaluator": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type"],
+                    "properties": {
+                        "type": { "type": "string" },
+                        "config": { "type": "object", "additionalProperties": true }
+                    }
+                },
+                "fix": { "$ref": "#/$defs/fix" }
+            }
+        },
+        "fix": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "mode": { "enum": ["none", "suggest", "auto"] },
+                "replacement": { "type": "string" },
+                "params": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

package/src/config/extensions.ts

@@ -24,6 +24,8 @@ export interface LoadExtensionsOptions {
     allowExtensions?: boolean;
     /** Optional sink for non-fatal warnings (e.g. built-in overrides). */
     logger?: { warn: (message: string) => void };
+    /** Optional module loader seam for tests or embedders with custom import policy. */
+    moduleLoader?: (absPath: string) => Promise<Record<string, unknown>>;
 }
 
 /** Host registries that can receive extension capabilities (fixers live on the engine, not the host). */
@@ -79,8 +81,9 @@ export async function loadExtensionsIntoHost(
         );
     }
 
+    const loadModule = options.moduleLoader ?? defaultModuleLoader;
     for (const ref of refs) {
-        const moduleExports = (await import(ref.absPath)) as Record<string, unknown>;
+        const moduleExports = await loadModule(ref.absPath);
         const candidate = moduleExports.default ?? moduleExports.extension;
         if (
             candidate === null ||
@@ -106,3 +109,7 @@ export async function loadExtensionsIntoHost(
         registry.register(name, candidate, 'extension');
     }
 }
+
+async function defaultModuleLoader(absPath: string): Promise<Record<string, unknown>> {
+    return (await import(absPath)) as Record<string, unknown>;
+}

package/src/config/loader.ts

@@ -1,6 +1,5 @@
-import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
-import { NodeFileSystem } from '@gobing-ai/ts-runtime';
-import { parse } from 'yaml';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { loadStructuredConfig, NodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     type ConstraintRuleFile,
@@ -9,6 +8,7 @@ import {
     type PresetDefinition,
     PresetDefinitionSchema,
 } from '../types';
+import { collectPresetExtensions, type ExtensionRef } from './extensions';
 
 /** Options for loading rule presets. */
 export interface RuleLoaderOptions {
@@ -20,6 +20,25 @@ export interface RuleLoaderOptions {
      * loader stays agnostic to any project layout convention.
      */
     roots: string[];
+    /** When true, honor top-level `$schema` refs in preset and rule files. Defaults to true. */
+    validateSchema?: boolean;
+    /** Optional fetch implementation for remote HTTP(S) schema refs. */
+    fetch?: (input: string) => Promise<Response>;
+}
+
+export interface RuleFileLoadOptions {
+    /** When true, honor top-level `$schema` refs. Defaults to true. */
+    validateSchema?: boolean;
+    /** Optional fetch implementation for remote HTTP(S) schema refs. */
+    fetch?: (input: string) => Promise<Response>;
+}
+
+/** Loaded preset rules plus extension module refs declared by composed presets. */
+export interface LoadedPreset {
+    /** Normalized rules after preset disable/override handling. */
+    readonly rules: ConstraintRule[];
+    /** Extension modules declared by the preset graph, resolved to absolute paths. */
+    readonly extensions: ExtensionRef[];
 }
 
 /** Merged view of rule roots: winning file per relative path, plus categories. */
@@ -37,14 +56,17 @@ interface MergedRoots {
  * 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[]> {
+export async function loadPreset(name: string, options: RuleLoaderOptions): Promise<LoadedPreset> {
     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;
+    if (presetPath === null) return { rules: [], extensions: [] };
+    const preset = PresetDefinitionSchema.parse(await readStructuredFile(presetPath, options)) as PresetDefinition;
     const rules: ConstraintRule[] = [];
+    const extensions = collectPresetExtensions(preset.name, dirname(presetPath), preset.extensions);
     for (const entry of preset.extends) {
-        rules.push(...(await loadPresetEntry(merged, entry, new Set([name]))));
+        const loaded = await loadPresetEntry(merged, entry, new Set([name]), options);
+        rules.push(...loaded.rules);
+        extensions.push(...loaded.extensions);
     }
     const disabled = new Set(preset.disable ?? []);
     const normalized = rules.filter((rule) => !disabled.has(rule.id));
@@ -54,27 +76,42 @@ export async function loadPresetRules(name: string, options: RuleLoaderOptions):
             rule.fix = { ...(rule.fix ?? { mode: 'none' }), ...override.fix };
         }
     }
-    return normalized;
+    return { rules: normalized, extensions };
+}
+
+export async function loadPresetRules(name: string, options: RuleLoaderOptions): Promise<ConstraintRule[]> {
+    return (await loadPreset(name, options)).rules;
 }
 
 /** Load a direct rule file from disk. */
-export async function loadRuleFile(filePath: string): Promise<ConstraintRule[]> {
-    return normalizeRuleFile(await readStructuredFile(resolve(filePath)), dirname(resolve(filePath)));
+export async function loadRuleFile(filePath: string, options: RuleFileLoadOptions = {}): Promise<ConstraintRule[]> {
+    const resolved = resolve(filePath);
+    return normalizeRuleFile(await readStructuredFile(resolved, options), dirname(resolved));
 }
 
-async function loadPresetEntry(merged: MergedRoots, entry: string, seen: Set<string>): Promise<ConstraintRule[]> {
+async function loadPresetEntry(
+    merged: MergedRoots,
+    entry: string,
+    seen: Set<string>,
+    options: Pick<RuleLoaderOptions, 'validateSchema' | 'fetch'>,
+): Promise<LoadedPreset> {
     // Sub-preset reference — recurse, erroring on a genuine cycle.
     const presetPath = findMergedPreset(merged, entry);
     if (presetPath !== null) {
         if (seen.has(entry)) {
             throw new Error(`Circular preset dependency detected: ${[...seen, entry].join(' → ')}`);
         }
-        seen.add(entry);
-        const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath));
+        const nextSeen = new Set([...seen, entry]);
+        const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath, options));
         if (preset.success) {
             const rules: ConstraintRule[] = [];
-            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 extensions = collectPresetExtensions(preset.data.name, dirname(presetPath), preset.data.extensions);
+            for (const child of preset.data.extends) {
+                const loaded = await loadPresetEntry(merged, child, nextSeen, options);
+                rules.push(...loaded.rules);
+                extensions.push(...loaded.extensions);
+            }
+            return { rules: rules.filter((rule) => !(preset.data.disable ?? []).includes(rule.id)), extensions };
         }
     }
 
@@ -82,16 +119,20 @@ async function loadPresetEntry(merged: MergedRoots, entry: string, seen: Set<str
     if (merged.categories.has(entry)) {
         const rules: ConstraintRule[] = [];
         for (const absPath of mergedFilesInCategory(merged, entry)) {
-            rules.push(...(await loadRuleFile(absPath)));
+            rules.push(...normalizeRuleFile(await readStructuredFile(absPath, options), dirname(absPath)));
         }
-        return rules;
+        return { rules, extensions: [] };
     }
 
     // Sub-path reference — a single winning rule file within a category.
     const subPath = findMergedFile(merged, entry);
-    if (subPath !== null) return loadRuleFile(subPath);
+    if (subPath !== null)
+        return {
+            rules: normalizeRuleFile(await readStructuredFile(subPath, options), dirname(subPath)),
+            extensions: [],
+        };
 
-    return [];
+    return { rules: [], extensions: [] };
 }
 
 /**
@@ -183,9 +224,14 @@ async function listImmediateDirs(fs: NodeFileSystem, dir: string): Promise<strin
     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);
+async function readStructuredFile(
+    path: string,
+    options: Pick<RuleLoaderOptions, 'validateSchema' | 'fetch'> = {},
+): Promise<unknown> {
+    return await loadStructuredConfig(path, {
+        validateSchema: options.validateSchema,
+        fetch: options.fetch,
+    });
 }
 
 function normalizeRuleFile(raw: unknown, sourceDir: string): ConstraintRule[] {

package/src/types.ts

@@ -46,6 +46,8 @@ export interface RuleFixConfig {
 
 /** Rule file shape before normalization. */
 export interface ConstraintRuleFile {
+    /** Optional JSON Schema ref used by editors and loader validation. */
+    $schema?: string;
     /** File-level default include patterns. */
     include?: string[];
     /** File-level default exclude patterns. */
@@ -70,6 +72,8 @@ export interface PresetExtensions {
 
 /** Preset definition that composes category folders or other presets. */
 export interface PresetDefinition {
+    /** Optional JSON Schema ref used by editors and loader validation. */
+    $schema?: string;
     /** Preset name. */
     name: string;
     /** Category folders or preset names to compose. */
@@ -206,6 +210,7 @@ export const ConstraintRuleSchema = z.object({
 
 /** Zod schema for a constraint rule file. */
 export const ConstraintRuleFileSchema = z.object({
+    $schema: z.string().optional(),
     include: z.array(z.string()).optional(),
     exclude: z.array(z.string()).optional(),
     severity: z.enum(['error', 'warning', 'info']).optional(),
@@ -214,6 +219,7 @@ export const ConstraintRuleFileSchema = z.object({
 
 /** Zod schema for a preset definition. */
 export const PresetDefinitionSchema = z.object({
+    $schema: z.string().optional(),
     name: z.string().min(1),
     extends: z.array(z.string()).default([]),
     disable: z.array(z.string()).optional(),