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

package/dist/resolvers/test-path-resolver.js

@@ -0,0 +1,112 @@
+/**
+ * Pluggable test-path resolution for the test-location evaluator.
+ *
+ * Each implementation maps a source file path to its conventional test file path
+ * for one language, so the same evaluator works across TypeScript, Python, Go, and
+ * Rust projects. Resolvers are registered on the host and selected per rule via
+ * `evaluator.config.resolver`.
+ */
+/**
+ * TypeScript conventions:
+ *   src/foo/bar.ts → tests/foo/bar.test.ts
+ *   packages/core/src/foo/bar.ts → packages/core/tests/foo/bar.test.ts
+ */
+export class TypeScriptTestPathResolver {
+    /** Registry key. */
+    name = 'typescript';
+    constructor() { }
+    /** Map a TS/JS source path to its `tests/…test.ts` counterpart. */
+    resolveTestPath(srcRelPath) {
+        if (srcRelPath.includes('.test.') || srcRelPath.includes('.spec.'))
+            return srcRelPath;
+        const srcIdx = srcRelPath.indexOf('/src/');
+        if (srcIdx !== -1) {
+            const pkg = srcRelPath.slice(0, srcIdx);
+            const rel = srcRelPath.slice(srcIdx + '/src/'.length).replace(/\.(ts|tsx|js|jsx)$/, '.test.ts');
+            return `${pkg}/tests/${rel}`;
+        }
+        const withoutExt = srcRelPath.replace(/\.(ts|tsx|js|jsx)$/, '');
+        return `tests/${withoutExt.replace(/^src\//, '')}.test.ts`;
+    }
+}
+/**
+ * Python conventions (pytest):
+ *   src/foo/bar.py → tests/foo/test_bar.py
+ */
+export class PythonTestPathResolver {
+    /** Registry key. */
+    name = 'python';
+    constructor() { }
+    /** Map a Python source path to its `tests/…/test_*.py` counterpart. */
+    resolveTestPath(srcRelPath) {
+        if (!srcRelPath)
+            throw new Error('empty source path');
+        if (srcRelPath.endsWith('_test.py') || srcRelPath.includes('/test_') || srcRelPath.startsWith('test_')) {
+            return srcRelPath;
+        }
+        if (srcRelPath.startsWith('tests/'))
+            return srcRelPath;
+        if (!srcRelPath.endsWith('.py'))
+            throw new Error(`unsupported extension for python resolver: ${srcRelPath}`);
+        const srcIdx = srcRelPath.indexOf('/src/');
+        if (srcIdx !== -1) {
+            const pkg = srcRelPath.slice(0, srcIdx);
+            return `${pkg}/tests/${testify(srcRelPath.slice(srcIdx + '/src/'.length))}`;
+        }
+        if (srcRelPath.startsWith('src/'))
+            return `tests/${testify(srcRelPath.slice(4))}`;
+        return `tests/${testify(srcRelPath)}`;
+    }
+}
+/**
+ * Go conventions:
+ *   foo/bar.go → foo/bar_test.go (sibling)
+ */
+export class GoTestPathResolver {
+    /** Registry key. */
+    name = 'go';
+    constructor() { }
+    /** Map a Go source path to its sibling `_test.go` file. */
+    resolveTestPath(srcRelPath) {
+        if (!srcRelPath)
+            throw new Error('empty source path');
+        if (srcRelPath.endsWith('_test.go'))
+            return srcRelPath;
+        if (!srcRelPath.endsWith('.go'))
+            throw new Error(`unsupported extension for go resolver: ${srcRelPath}`);
+        return srcRelPath.replace(/\.go$/, '_test.go');
+    }
+}
+/**
+ * Rust conventions (Cargo integration tests):
+ *   crate/src/foo.rs → crate/tests/foo.rs
+ */
+export class RustTestPathResolver {
+    /** Registry key. */
+    name = 'rust';
+    constructor() { }
+    /** Map a Rust source path to its `tests/` integration-test counterpart. */
+    resolveTestPath(srcRelPath) {
+        if (!srcRelPath)
+            throw new Error('empty source path');
+        if (srcRelPath.startsWith('tests/') || srcRelPath.includes('/tests/'))
+            return srcRelPath;
+        if (!srcRelPath.endsWith('.rs'))
+            throw new Error(`unsupported extension for rust resolver: ${srcRelPath}`);
+        const srcIdx = srcRelPath.indexOf('/src/');
+        if (srcIdx !== -1) {
+            const crate = srcRelPath.slice(0, srcIdx);
+            return `${crate}/tests/${srcRelPath.slice(srcIdx + '/src/'.length)}`;
+        }
+        if (srcRelPath.startsWith('src/'))
+            return `tests/${srcRelPath.slice(4)}`;
+        return `tests/${srcRelPath}`;
+    }
+}
+/** Prefix the basename of a Python source path with `test_`. */
+function testify(rel) {
+    const lastSlash = rel.lastIndexOf('/');
+    const dir = lastSlash >= 0 ? rel.slice(0, lastSlash + 1) : '';
+    const base = lastSlash >= 0 ? rel.slice(lastSlash + 1) : rel;
+    return `${dir}test_${base}`;
+}

package/dist/types.d.ts

@@ -49,6 +49,17 @@ export interface ConstraintRuleFile {
     /** Rule definitions. */
     rules: ConstraintRule[];
 }
+/** Relative module paths a preset contributes per capability kind. */
+export interface PresetExtensions {
+    /** Test-path resolver module paths. */
+    resolvers?: string[];
+    /** Evaluator module paths. */
+    evaluators?: string[];
+    /** Fixer module paths. */
+    fixers?: string[];
+    /** Formatter module paths. */
+    formatters?: string[];
+}
 /** Preset definition that composes category folders or other presets. */
 export interface PresetDefinition {
     /** Preset name. */
@@ -63,6 +74,8 @@ export interface PresetDefinition {
             mode: FixMode;
         };
     }>;
+    /** Custom capability modules contributed by this preset (opt-in to load). */
+    extensions?: PresetExtensions;
 }
 /** Candidate fix emitted by an evaluator or fixer. */
 export interface Fix {
@@ -79,6 +92,15 @@ export interface Fix {
     /** Whether this fix may be applied automatically. */
     mode: Exclude<FixMode, 'none'>;
 }
+/**
+ * What a finding represents.
+ *
+ * - `violation`: the rule ran and the project breached its policy (the default).
+ * - `error`: the rule could not run — a misconfiguration or runtime fault in the
+ *   evaluator itself. These are not policy breaches and callers may surface them
+ *   separately (e.g. "rule misconfigured") rather than as project violations.
+ */
+export type FindingKind = 'violation' | 'error';
 /** Finding emitted by a constraint rule. */
 export interface ConstraintFinding {
     /** Rule identifier. */
@@ -95,6 +117,8 @@ export interface ConstraintFinding {
     column?: number;
     /** Machine-readable evaluator/source code. */
     code?: string;
+    /** Whether this is a policy violation or an evaluator error. Absent means `violation`. */
+    kind?: FindingKind;
 }
 /** Aggregate result returned by a rule evaluator. */
 export interface RuleEvaluationResult {
@@ -214,5 +238,11 @@ export declare const PresetDefinitionSchema: z.ZodObject<{
             }>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
+    extensions: z.ZodOptional<z.ZodObject<{
+        resolvers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        evaluators: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fixers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        formatters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 //# sourceMappingURL=types.d.ts.map

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":"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"}

package/dist/types.js

@@ -46,4 +46,12 @@ export const PresetDefinitionSchema = z.object({
     overrides: z
         .record(z.string(), z.object({ fix: z.object({ mode: z.enum(['none', 'suggest', 'auto']) }).optional() }))
         .optional(),
+    extensions: z
+        .object({
+        resolvers: z.array(z.string()).optional(),
+        evaluators: z.array(z.string()).optional(),
+        fixers: z.array(z.string()).optional(),
+        formatters: z.array(z.string()).optional(),
+    })
+        .optional(),
 });

package/package.json

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

package/src/config/extensions.ts

@@ -0,0 +1,108 @@
+import { resolve } from 'node:path';
+import type { RuleEngineHost } from '../host/rule-engine-host';
+
+/** A capability kind a preset extension can contribute. */
+export type ExtensionKind = 'resolvers' | 'evaluators' | 'fixers' | 'formatters';
+
+/** A single extension module reference, resolved to an absolute path. */
+export interface ExtensionRef {
+    /** Capability registry the module registers into. */
+    readonly kind: ExtensionKind;
+    /** Absolute path to the module to import. */
+    readonly absPath: string;
+    /** Name of the preset that declared this extension (for diagnostics). */
+    readonly presetName: string;
+}
+
+/** Options controlling preset-extension loading. */
+export interface LoadExtensionsOptions {
+    /**
+     * Whether to actually import extension modules. Defaults to `false`: loading
+     * arbitrary code referenced by a preset is a trust decision the caller must
+     * make explicitly. When refs exist and this is false, loading throws.
+     */
+    allowExtensions?: boolean;
+    /** Optional sink for non-fatal warnings (e.g. built-in overrides). */
+    logger?: { warn: (message: string) => void };
+}
+
+/** Host registries that can receive extension capabilities (fixers live on the engine, not the host). */
+const HOST_REGISTRY_BY_KIND: Partial<Record<ExtensionKind, 'resolvers' | 'evaluators' | 'formatters'>> = {
+    resolvers: 'resolvers',
+    evaluators: 'evaluators',
+    formatters: 'formatters',
+};
+
+/**
+ * Collect extension refs declared by a preset's `extensions` block.
+ *
+ * Paths are resolved relative to the preset file's directory. Use the returned
+ * refs with {@link loadExtensionsIntoHost}.
+ */
+export function collectPresetExtensions(
+    presetName: string,
+    presetDir: string,
+    extensions: Partial<Record<ExtensionKind, string[] | undefined>> | undefined,
+): ExtensionRef[] {
+    if (extensions === undefined) return [];
+    const refs: ExtensionRef[] = [];
+    for (const kind of ['resolvers', 'evaluators', 'fixers', 'formatters'] as ExtensionKind[]) {
+        for (const path of extensions[kind] ?? []) {
+            refs.push({ kind, presetName, absPath: resolve(presetDir, path) });
+        }
+    }
+    return refs;
+}
+
+/**
+ * Import each extension module and register its export on the matching host
+ * registry.
+ *
+ * A module must default-export (or named-export `extension`) an object with a
+ * `name: string` and the capability implementation. Loading is gated by
+ * {@link LoadExtensionsOptions.allowExtensions}; when refs are present but
+ * loading is not allowed, this throws so the requirement is never silently dropped.
+ *
+ * @throws When extensions are present but `allowExtensions` is not true, or when
+ *   a module cannot be imported or lacks a valid `name`.
+ */
+export async function loadExtensionsIntoHost(
+    host: RuleEngineHost,
+    refs: readonly ExtensionRef[],
+    options: LoadExtensionsOptions = {},
+): Promise<void> {
+    if (refs.length === 0) return;
+    if (options.allowExtensions !== true) {
+        const first = refs[0] as ExtensionRef;
+        throw new Error(
+            `preset "${first.presetName}" declares ${first.kind} extension "${first.absPath}", but extensions are disabled — pass allowExtensions: true to load preset extension modules`,
+        );
+    }
+
+    for (const ref of refs) {
+        const moduleExports = (await import(ref.absPath)) as Record<string, unknown>;
+        const candidate = moduleExports.default ?? moduleExports.extension;
+        if (
+            candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof (candidate as { name?: unknown }).name !== 'string'
+        ) {
+            throw new Error(
+                `preset "${ref.presetName}" extension "${ref.absPath}" must export an object with a string "name"`,
+            );
+        }
+        const name = (candidate as { name: string }).name;
+        const registryKey = HOST_REGISTRY_BY_KIND[ref.kind];
+        if (registryKey === undefined) {
+            throw new Error(`preset "${ref.presetName}" ${ref.kind} extensions are not supported`);
+        }
+        const registry = host[registryKey] as unknown as {
+            register: (name: string, impl: unknown, origin: 'builtin' | 'extension') => void;
+            has?: (name: string) => boolean;
+        };
+        if (options.logger && registry.has?.(name)) {
+            options.logger.warn(`preset "${ref.presetName}" ${ref.kind} extension overrides existing "${name}"`);
+        }
+        registry.register(name, candidate, 'extension');
+    }
+}

package/src/config/loader.ts

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