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

package/README.md

@@ -1,3 +1,567 @@
 # @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';
+
+// Returns { rules, extensions } — same shape as loadPreset(). A rule file may
+// declare an `extensions` block; the refs are gated by allowExtensions at load time.
+const { rules, extensions } = 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,14 +22,17 @@ 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.
+ * Collect extension refs declared by a preset's or rule file's `extensions` block.
  *
- * Paths are resolved relative to the preset file's directory. Use the returned
- * refs with {@link loadExtensionsIntoHost}.
+ * Paths are resolved relative to the declaring file's directory. Use the returned
+ * refs with {@link loadExtensionsIntoHost}. Rule files and presets are treated
+ * identically — both flow through the same trust gate at load time.
  */
-export declare function collectPresetExtensions(presetName: string, presetDir: string, extensions: Partial<Record<ExtensionKind, string[] | undefined>> | undefined): ExtensionRef[];
+export declare function collectExtensions(sourceName: string, sourceDir: string, extensions: Partial<Record<ExtensionKind, string[] | undefined>> | undefined): ExtensionRef[];
 /**
  * Import each extension module and register its export on the matching host
  * registry.

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;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,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

@@ -6,18 +6,19 @@ const HOST_REGISTRY_BY_KIND = {
     formatters: 'formatters',
 };
 /**
- * Collect extension refs declared by a preset's `extensions` block.
+ * Collect extension refs declared by a preset's or rule file's `extensions` block.
  *
- * Paths are resolved relative to the preset file's directory. Use the returned
- * refs with {@link loadExtensionsIntoHost}.
+ * Paths are resolved relative to the declaring file's directory. Use the returned
+ * refs with {@link loadExtensionsIntoHost}. Rule files and presets are treated
+ * identically — both flow through the same trust gate at load time.
  */
-export function collectPresetExtensions(presetName, presetDir, extensions) {
+export function collectExtensions(sourceName, sourceDir, extensions) {
     if (extensions === undefined)
         return [];
     const refs = [];
     for (const kind of ['resolvers', 'evaluators', 'fixers', 'formatters']) {
         for (const path of extensions[kind] ?? []) {
-            refs.push({ kind, presetName, absPath: resolve(presetDir, path) });
+            refs.push({ kind, presetName: sourceName, absPath: resolve(sourceDir, path) });
         }
     }
     return refs;
@@ -41,8 +42,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 +63,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,16 @@ 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[]>;
+/**
+ * Load a direct rule file from disk.
+ *
+ * Returns the normalized rules plus any extension modules the file declares in an
+ * `extensions` block, resolved to absolute paths. Rule-file extensions are treated
+ * exactly like preset extensions — pass the refs to {@link loadExtensionsIntoHost},
+ * which enforces the same `allowExtensions` trust gate. A single-rule file (one rule
+ * object, not a `rules:` array) cannot declare extensions and yields `extensions: []`.
+ */
+export declare function loadRuleFile(filePath: string, options?: RuleFileLoadOptions): Promise<LoadedPreset>;
 //# 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,EAOtB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEpE,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,CAahG;AAyCD,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAEzG;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CAS7G"}