@alex-dbs/coderuler 1.3.1 → 1.5.0

package/dist/adapter/git/rules.js

@@ -0,0 +1,126 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isolatedGitEnvironment } from './environment.js';
+const invalidRepositoryUrl = 'Invalid rule repository URL; use HTTPS or SSH with Git credentials.';
+function parseRuleRepositorySelector(selector) {
+    const schemeMatch = /^([a-z][a-z\d+.-]*):\/\//i.exec(selector);
+    const schemePrefix = /^([a-z][a-z\d+.-]*):/i.exec(selector);
+    const windowsDrivePath = /^[a-z]:[\\/]/i.test(selector);
+    const malformedUrl = schemeMatch === null
+        && schemePrefix !== null
+        && !windowsDrivePath
+        && (/^(?:https?|ssh|file|ftp|git(?:\+(?:https?|ssh))?):/i.test(selector)
+            || /^[\\/]/.test(selector.slice(schemePrefix[0].length))
+            || selector.slice(schemePrefix[0].length).includes('@'));
+    const looksLikeUrl = schemeMatch !== null || malformedUrl;
+    const looksLikeScp = /^[^/@:\s]*@[^/:\s]*:/.test(selector);
+    if (!looksLikeUrl && !looksLikeScp)
+        return undefined;
+    const separator = selector.indexOf('#');
+    const transport = separator === -1 ? selector : selector.slice(0, separator);
+    const revision = separator === -1 ? undefined : selector.slice(separator + 1);
+    if (revision === '')
+        throw new Error('Rule repository revision must not be empty.');
+    if (looksLikeUrl) {
+        if (schemeMatch === null)
+            throw new Error(invalidRepositoryUrl);
+        let url;
+        try {
+            url = new URL(transport);
+        }
+        catch {
+            throw new Error(invalidRepositoryUrl);
+        }
+        if ((url.protocol !== 'https:' && url.protocol !== 'ssh:')
+            || url.hostname === ''
+            || url.search !== ''
+            || transport.includes('?')
+            || (url.protocol === 'https:' && (url.username !== '' || url.password !== ''))
+            || (url.protocol === 'ssh:' && hasSshPassword(transport, url))) {
+            throw new Error(invalidRepositoryUrl);
+        }
+    }
+    else {
+        const match = /^([^/@:\s]+)@([^/:\s]+):(.+)$/.exec(transport);
+        if (match === null)
+            throw new Error(invalidRepositoryUrl);
+    }
+    return { transport, revision };
+}
+function hasSshPassword(transport, url) {
+    if (url.password !== '')
+        return true;
+    const authorityStart = transport.indexOf('://') + 3;
+    const authorityEnd = transport.slice(authorityStart).search(/[/?#]/);
+    const authority = authorityEnd === -1
+        ? transport.slice(authorityStart)
+        : transport.slice(authorityStart, authorityStart + authorityEnd);
+    const userInfoEnd = authority.lastIndexOf('@');
+    return userInfoEnd !== -1 && authority.slice(0, userInfoEnd).includes(':');
+}
+export function createRuleRepositoryCheckout(env) {
+    const isolatedEnv = isolatedGitEnvironment(env);
+    const runGit = (cwd, args, allowedExitCodes = [0]) => {
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const child = spawn('git', [...args], {
+            cwd,
+            env: isolatedEnv,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', error => reject(new Error(`Cannot run Git: ${error.message}`, {
+            cause: error,
+        })));
+        child.on('close', (code, signal) => {
+            if (code !== null && allowedExitCodes.includes(code))
+                resolve({ stdout, code });
+            else
+                reject(new Error(`Git ${args[0]} failed: ${stderr.trim() || signal || `exit ${code}`}`));
+        });
+        return promise;
+    };
+    return async (selector) => {
+        const parsed = parseRuleRepositorySelector(selector);
+        if (parsed === undefined)
+            return undefined;
+        const workspace = await mkdtemp(join(await realpath(tmpdir()), 'coderuler-rules-'));
+        const root = join(workspace, 'repository');
+        const cleanup = () => rm(workspace, { recursive: true, force: true });
+        try {
+            await runGit(workspace, ['init', root]);
+            const worktree = await runGit(root, ['config', '--null', '--get-all', 'core.worktree'], [0, 1]);
+            if (worktree.code === 0) {
+                throw new Error('Rule repository checkout requires Git core.worktree to be unset; remove the inherited repository-location override.');
+            }
+            if (parsed.revision !== undefined) {
+                if (parsed.revision.startsWith('+')
+                    && !parsed.revision.startsWith('refs/heads/+')) {
+                    throw new Error('Invalid rule repository revision.');
+                }
+                const result = await runGit(root, [
+                    'check-ref-format',
+                    `refs/coderuler/${parsed.revision}`,
+                ], [0, 1]);
+                if (result.code !== 0)
+                    throw new Error('Invalid rule repository revision.');
+            }
+            await runGit(root, ['remote', 'add', 'origin', parsed.transport]);
+            await runGit(root, [
+                'fetch', '--depth=1', '--no-tags', '--', 'origin', `${parsed.revision ?? 'HEAD'}:`,
+            ]);
+            await runGit(root, ['checkout', '--detach', 'FETCH_HEAD']);
+            return { root, cleanup };
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+    };
+}

package/dist/adapter/github/pull-request.d.ts

@@ -1,3 +1,4 @@
+import type { LineRange } from '../../app/rule.js';
 export interface PullRequest {
     readonly repository: string;
     readonly number: number;
@@ -7,6 +8,7 @@ export interface PullRequestCheckout {
     readonly root: string;
     readonly rulesRoot: string;
     readonly changedFiles: ReadonlySet<string>;
+    readonly changedLines: ReadonlyMap<string, readonly LineRange[]>;
     readonly pullRequest: PullRequest;
     cleanup(): Promise<void>;
 }

package/dist/adapter/github/pull-request.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { mkdtemp, realpath, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { changedFiles } from '../git/changes.js';
+import { collectChanges } from '../git/changes.js';
 import { isolatedGitEnvironment } from '../git/environment.js';
 import { createGithubApi, mapping } from './api.js';
 export function repositoryName(value) {
@@ -127,9 +127,15 @@ export function createPullRequestCheckout(cwd, env) {
             const head = (await runGit(root, ['rev-parse', 'HEAD'])).stdout.trim();
             await runGit(root, ['worktree', 'add', '--detach', rulesRoot, 'refs/coderuler/base']);
             const mergeBase = (await runGit(root, ['merge-base', 'refs/coderuler/base', 'refs/coderuler/head'])).stdout.trim();
-            const files = await changedFiles(root, mergeBase, isolatedEnv);
+            const changes = await collectChanges(root, mergeBase, isolatedEnv);
             await assertNoWorktreeOverride(rulesRoot);
-            return { root, rulesRoot, changedFiles: files, pullRequest: { ...pullRequest, head }, cleanup };
+            return {
+                root,
+                rulesRoot,
+                ...changes,
+                pullRequest: { ...pullRequest, head },
+                cleanup,
+            };
         }
         catch (error) {
             await cleanup();

package/dist/app/evaluators.js

@@ -23,8 +23,11 @@ function assertExampleList(value, label) {
     }
 }
 function assertAiOptions(options) {
-    if (typeof options.rule !== 'string' || options.rule === '') {
-        fail('ai rule must be a non-empty string');
+    if (options.rule !== undefined && options.instruction !== undefined)
+        fail('ai rule and instruction are mutually exclusive');
+    const policy = options.instruction ?? options.rule;
+    if (typeof policy !== 'string' || policy === '') {
+        fail(`ai ${options.instruction === undefined ? 'rule' : 'instruction'} must be a non-empty string`);
     }
     const examples = options.examples;
     if (examples !== undefined) {
@@ -77,9 +80,13 @@ function projectState(subject) {
 function instructionsOf(options) {
     const good = options.examples?.good ?? [];
     const bad = options.examples?.bad ?? [];
+    const instructions = {
+        rule: options.instruction === undefined ? options.rule : options.instruction,
+        question: QUESTION,
+    };
     if (good.length === 0 && bad.length === 0)
-        return { rule: options.rule, question: QUESTION };
-    return { rule: options.rule, question: QUESTION, examples: { good, bad } };
+        return instructions;
+    return { ...instructions, examples: { good, bad } };
 }
 export async function evaluateAi(subject, options, context, runtime, observer) {
     assertAiOptions(options);

package/dist/app/execute.js

@@ -32,6 +32,7 @@ export async function executeRules(rules, context) {
         context.emit?.(event);
     };
     const changedFiles = context.changedFiles;
+    const changedLines = context.changedLines;
     const changedPaths = changedFiles === undefined
         ? undefined
         : [...changedFiles].filter(filepath => isEligibleRelativePath(filepath) && context.isTarget(filepath));
@@ -44,9 +45,11 @@ export async function executeRules(rules, context) {
             ...(details === undefined ? {} : { details }),
         });
     };
-    const projectContextFor = (name) => ({
+    const projectContextFor = (name, evaluationId) => ({
         project: context.project,
-        trace: traceFor(name),
+        ...(changedFiles === undefined ? {} : { changedFiles }),
+        ...(changedLines === undefined ? {} : { changedLines }),
+        trace: traceFor(name, evaluationId),
     });
     const fail = (name, stage, error, evaluationId) => {
         const message = error instanceof Error ? error.message : String(error);
@@ -106,7 +109,7 @@ export async function executeRules(rules, context) {
             const source = await context.project.readText(filepath);
             const matches = scope === undefined
                 ? wholeFileScope({ filepath, source })
-                : (await scope({ filepath, source }));
+                : (await scope({ filepath, source }, projectContextFor(name, evaluationId)));
             if (!Array.isArray(matches)) {
                 throw new Error(`Rule "${name}" scope selector must return an array of scopes`);
             }
@@ -123,8 +126,7 @@ export async function executeRules(rules, context) {
         return collected.flat();
     };
     const selectionContextFor = (name, changedOnly) => ({
-        project: context.project,
-        trace: traceFor(name),
+        ...projectContextFor(name),
         select: selection => selectFromRule(name, selection, undefined, changedOnly),
     });
     const runtimeOf = (plan) => {
@@ -139,7 +141,6 @@ export async function executeRules(rules, context) {
         plan.evaluationStartedAt ??= performance.now();
         const { name, rule } = plan;
         emit({ type: 'evaluation', evaluationId, name, subject });
-        const trace = traceFor(name, evaluationId);
         let trackedUsage;
         let pendingAi;
         let accountingFailure;
@@ -180,12 +181,11 @@ export async function executeRules(rules, context) {
             }
         };
         const checkContext = {
-            project: context.project,
+            ...projectContextFor(name, evaluationId),
             ruleName: name,
-            trace,
             select: selection => selectFromRule(name, selection, evaluationId),
             ai: options => {
-                const call = evaluateAi(subject, options, { project: context.project, ruleName: name, trace }, runtimeOf(plan), observer);
+                const call = evaluateAi(subject, options, { ...projectContextFor(name, evaluationId), ruleName: name }, runtimeOf(plan), observer);
                 const pending = pendingAi ??= new Set();
                 pending.add(call);
                 // Observe both outcomes immediately; the check still receives the original promise.

package/dist/app/ports.d.ts

@@ -1,4 +1,8 @@
-import type { AiUsage, CheckResult, GroupSubject, JsonValue, Rule, RuleSettings, ScopeSubject, Subject, TokenPricing, TokenUsage } from './rule.js';
+import type { AiUsage, CheckResult, GroupSubject, JsonValue, LineRange, Rule, RuleSettings, ScopeSubject, Subject, TokenPricing, TokenUsage } from './rule.js';
+export interface DiffChanges {
+    readonly changedFiles: ReadonlySet<string>;
+    readonly changedLines: ReadonlyMap<string, readonly LineRange[]>;
+}
 export interface Project {
     readonly root: string;
     glob(patterns: string | readonly string[]): Promise<readonly string[]>;
@@ -72,6 +76,7 @@ export interface RunContext {
     readonly project: Project;
     readonly isTarget: (filepath: string) => boolean;
     readonly changedFiles?: ReadonlySet<string>;
+    readonly changedLines?: ReadonlyMap<string, readonly LineRange[]>;
     readonly concurrency: number;
     readonly resolveDecision: (settings: RuleSettings) => DecisionRuntime;
     readonly emit?: (event: RunEvent) => void;

package/dist/app/rule-tests.d.ts

@@ -9,6 +9,7 @@ export interface RuleTestResult {
     readonly name: string;
     readonly expected: RuleTestCase['expected'];
     readonly actual: RuleTestCase['expected'] | 'timeout';
+    readonly aiScores?: readonly number[];
     readonly durationMs: number;
 }
 export declare function test(name: string): {

package/dist/app/rule.d.ts

@@ -11,15 +11,16 @@ export interface SourceFile {
     readonly filepath: string;
     readonly source: string;
 }
+export interface LineRange {
+    readonly start: number;
+    readonly end: number;
+}
 export interface ScopeMatch<T = JsonValue> {
     readonly id: string;
     readonly source: string;
     readonly data?: T;
     readonly captures?: Readonly<Record<string, string | readonly string[]>>;
-    readonly lines?: {
-        readonly start: number;
-        readonly end: number;
-    };
+    readonly lines?: LineRange;
 }
 export interface ScopeSubject<T = JsonValue> extends ScopeMatch<T> {
     readonly kind: 'scope';
@@ -34,13 +35,15 @@ export interface GroupSubject<T = JsonValue> {
     readonly members: readonly ScopeSubject<T>[];
 }
 export type Subject<T = JsonValue> = ScopeSubject<T> | GroupSubject<T>;
-export type ScopeSelector<T = JsonValue> = (file: SourceFile) => Awaitable<readonly ScopeMatch<T>[]>;
+export type ScopeSelector<T = JsonValue> = {
+    bivarianceHack(file: SourceFile, context?: ProjectContext): Awaitable<readonly ScopeMatch<T>[]>;
+}['bivarianceHack'];
 export type Grouping = 'scope' | 'file' | 'folder' | 'project' | {
     readonly by: 'folder';
     readonly level: number;
 };
 export interface RuleSettings {
-    readonly backend?: 'jev';
+    readonly backend?: 'jev' | 'openai';
     readonly model?: string;
     readonly threshold?: number;
     readonly inputCostPerMillion?: number;
@@ -63,10 +66,7 @@ export interface AiUsage extends TokenUsage {
 export interface ViolationLocation {
     readonly filepath: string;
     readonly scopeId?: string;
-    readonly lines?: {
-        readonly start: number;
-        readonly end: number;
-    };
+    readonly lines?: LineRange;
 }
 export interface CheckResult {
     readonly status: 'pass' | 'violation';
@@ -81,15 +81,23 @@ export interface AiExamples {
     readonly good?: readonly string[];
     readonly bad?: readonly string[];
 }
-export interface AiOptions<T = JsonValue> {
-    readonly rule: string;
+export type AiOptions<T = JsonValue> = {
     readonly examples?: AiExamples;
     readonly violationMessage?: string;
     readonly input?: (subject: Subject<T>, context: ProjectContext) => Awaitable<JsonValue>;
-}
+} & ({
+    /** @deprecated Use `instruction` instead. */
+    readonly rule: string;
+    readonly instruction?: never;
+} | {
+    readonly instruction: string;
+    readonly rule?: never;
+});
 export type Evaluator<T = JsonValue> = (subject: Subject<T>, context: CheckContext<T>) => Awaitable<CheckResult>;
 export interface ProjectContext {
     readonly project: Project;
+    readonly changedFiles?: ReadonlySet<string>;
+    readonly changedLines?: ReadonlyMap<string, readonly LineRange[]>;
     trace(message: string, details?: JsonValue): void;
 }
 export interface Selection<T = JsonValue> {

package/dist/app/validate.js

@@ -24,8 +24,9 @@ function isStringList(value, allowEmpty) {
 }
 function validateSettings(settings, at) {
     const backend = settings['backend'];
-    if (backend !== undefined && backend !== 'jev')
-        invalid(at, 'settings.backend must be "jev"');
+    if (backend !== undefined && backend !== 'jev' && backend !== 'openai') {
+        invalid(at, 'settings.backend must be "jev" or "openai"');
+    }
     const model = settings['model'];
     if (model !== undefined && (typeof model !== 'string' || model.trim() === '')) {
         invalid(at, 'settings.model must be a non-blank string');

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { Rule } from './app/rule.js';
 export { test } from './app/rule-tests.js';
 export type { RuleTestCase } from './app/rule-tests.js';
-export type { AiExamples, AiOptions, AiUsage, Awaitable, CheckContext, CheckResult, Evaluator, Grouping, GroupSubject, JsonValue, PredicateResult, ProjectContext, RuleSettings, ScopeMatch, ScopeSelector, ScopeSubject, Selection, SelectionContext, SourceFile, Subject, TokenPricing, TokenUsage, ViolationLocation, } from './app/rule.js';
+export type { AiExamples, AiOptions, AiUsage, Awaitable, CheckContext, CheckResult, Evaluator, Grouping, GroupSubject, JsonValue, PredicateResult, LineRange, ProjectContext, RuleSettings, ScopeMatch, ScopeSelector, ScopeSubject, Selection, SelectionContext, SourceFile, Subject, TokenPricing, TokenUsage, ViolationLocation, } from './app/rule.js';
 export { ai, pass, regex, violation } from './app/evaluators.js';
 export type { RegexOptions } from './app/evaluators.js';
-export type { CsvOptions, CsvRow, DecisionBackend, DecisionExchange, DecisionInstructions, DecisionObserver, DecisionOutcome, DecisionRequest, DecisionRuntime, LoadedRule, Project, RuleEvaluation, RuleLoader, RuleReport, RuleSelection, RunContext, RunEvent, } from './app/ports.js';
+export type { CsvOptions, DiffChanges, CsvRow, DecisionBackend, DecisionExchange, DecisionInstructions, DecisionObserver, DecisionOutcome, DecisionRequest, DecisionRuntime, LoadedRule, Project, RuleEvaluation, RuleLoader, RuleReport, RuleSelection, RunContext, RunEvent, } from './app/ports.js';
 import { astGrep } from './adapter/scope/astgrep.js';
 import { csv } from './adapter/scope/csv.js';
 import { file } from './adapter/scope/file.js';

package/dist/infra/runtime.js

@@ -17,7 +17,7 @@ function loadEnvironment(cwd) {
     }
 }
 export function createServices(cwd, env) {
-    const redact = createRedactor([env.TYPESAFE_API_KEY, env.GITHUB_TOKEN]);
+    const redact = createRedactor([env.TYPESAFE_API_KEY, env.OPENAI_API_KEY, env.GITHUB_TOKEN]);
     let dependenciesPromise;
     let ruleServicesPromise;
     const getDependencies = (context) => dependenciesPromise ??= (async () => {
@@ -69,14 +69,18 @@ export function createServices(cwd, env) {
                     resolveTarget: project.resolveTarget,
                     runRules: execution.executeRules,
                     decisionResolver: (thresholdOverride, pricingOverrides) => settings.createDecisionResolver(env, thresholdOverride, pricingOverrides),
-                    async changedFiles(root, base) {
-                        const { changedFiles } = await import('../adapter/git/changes.js');
-                        return changedFiles(root, base);
+                    async collectChanges(root, base) {
+                        const { collectChanges } = await import('../adapter/git/changes.js');
+                        return collectChanges(root, base);
                     },
                     async checkoutPullRequest(selector, baseBranch) {
                         const { createPullRequestCheckout } = await import('../adapter/github/pull-request.js');
                         return createPullRequestCheckout(cwd, env)(selector, baseBranch);
                     },
+                    async checkoutRuleRepository(selector) {
+                        const { createRuleRepositoryCheckout } = await import('../adapter/git/rules.js');
+                        return createRuleRepositoryCheckout(env)(selector);
+                    },
                     async commentOnPullRequest(root, comments, pullRequest) {
                         const { createGithubCommenter } = await import('../adapter/github/comments.js');
                         return createGithubCommenter(env)(root, comments, pullRequest);
@@ -160,7 +164,11 @@ export async function runCli(argv) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const redact = createRedactor([process.env.TYPESAFE_API_KEY, process.env.GITHUB_TOKEN]);
+        const redact = createRedactor([
+            process.env.TYPESAFE_API_KEY,
+            process.env.OPENAI_API_KEY,
+            process.env.GITHUB_TOKEN,
+        ]);
         process.stderr.write(`coderuler: ${redact(escapeDiagnostic(message))}\n`);
         return EXIT_FAILURE;
     }

package/dist/infra/settings.js

@@ -1,9 +1,13 @@
 import { JevAdapter } from '../adapter/decision/jev.js';
+import { OpenAIAdapter } from '../adapter/decision/openai.js';
 const DEFAULT_BACKEND = 'jev';
 const DEFAULT_MODEL = 'jev-latest';
 const DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+const OPENAI_DEFAULT_MODEL = 'gpt-6-luna';
+const OPENAI_DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 const DEFAULT_THRESHOLD = 0.4;
 const DEFAULT_INPUT_COST_PER_MILLION = 0.042;
+const OPENAI_DEFAULT_INPUT_COST_PER_MILLION = 0.10;
 const DEFAULT_OUTPUT_COST_PER_MILLION = 0;
 const THRESHOLD_MESSAGE = 'must be a number between 0 and 1';
 const DECIMAL = /^(?:[0-9]+(?:\.[0-9]+)?|\.[0-9]+)$/;
@@ -56,9 +60,10 @@ export function createDecisionResolver(env, thresholdOverride, pricingOverrides)
         validatePrice(outputOverride, '--output-cost-per-million');
     return settings => {
         const backend = settings.backend ?? setting(env, 'RK_BACKEND') ?? DEFAULT_BACKEND;
-        if (backend !== 'jev') {
-            throw new Error(`Unknown decision backend '${backend}'; supported backends: ${DEFAULT_BACKEND}`);
+        if (backend !== 'jev' && backend !== 'openai') {
+            throw new Error(`Unknown decision backend '${backend}'; supported backends: jev, openai`);
         }
+        const isOpenAI = backend === 'openai';
         let threshold;
         if (flagThreshold !== undefined) {
             threshold = flagThreshold;
@@ -77,14 +82,20 @@ export function createDecisionResolver(env, thresholdOverride, pricingOverrides)
             validatePrice(settings.outputCostPerMillion, 'rule.settings.outputCostPerMillion');
         }
         const pricing = {
-            inputCostPerMillion: price(inputOverride, settings.inputCostPerMillion, env, 'RK_INPUT_COST_PER_MILLION', DEFAULT_INPUT_COST_PER_MILLION),
+            inputCostPerMillion: price(inputOverride, settings.inputCostPerMillion, env, 'RK_INPUT_COST_PER_MILLION', isOpenAI ? OPENAI_DEFAULT_INPUT_COST_PER_MILLION : DEFAULT_INPUT_COST_PER_MILLION),
             outputCostPerMillion: price(outputOverride, settings.outputCostPerMillion, env, 'RK_OUTPUT_COST_PER_MILLION', DEFAULT_OUTPUT_COST_PER_MILLION),
         };
-        const model = settings.model ?? setting(env, 'TYPESAFE_DEFAULT_MODEL') ?? DEFAULT_MODEL;
-        const baseUrl = setting(env, 'TYPESAFE_BASE_URL') ?? DEFAULT_BASE_URL;
-        const apiKey = setting(env, 'TYPESAFE_API_KEY');
-        if (apiKey === undefined) {
-            throw new Error('No decision API key: set TYPESAFE_API_KEY');
+        const model = settings.model ??
+            setting(env, isOpenAI ? 'OPENAI_DEFAULT_MODEL' : 'TYPESAFE_DEFAULT_MODEL') ??
+            (isOpenAI ? OPENAI_DEFAULT_MODEL : DEFAULT_MODEL);
+        const baseUrl = setting(env, isOpenAI ? 'OPENAI_BASE_URL' : 'TYPESAFE_BASE_URL') ??
+            (isOpenAI ? OPENAI_DEFAULT_BASE_URL : DEFAULT_BASE_URL);
+        const apiKeyName = isOpenAI ? 'OPENAI_API_KEY' : 'TYPESAFE_API_KEY';
+        const apiKey = setting(env, apiKeyName);
+        if (apiKey === undefined)
+            throw new Error(`No decision API key: set ${apiKeyName}`);
+        if (isOpenAI) {
+            return { backend: new OpenAIAdapter({ model, baseUrl, apiKey }), threshold, pricing };
         }
         return { backend: new JevAdapter({ model, baseUrl, apiKey }), threshold, pricing };
     };

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@alex-dbs/coderuler",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "license": "Apache-2.0",
+  "keywords": [
+    "ai",
+    "ai-agent",
+    "agent",
+    "rule",
+    "rules",
+    "coding-standards",
+    "standard",
+    "code-quality",
+    "code-review",
+    "security",
+    "linter",
+    "checker",
+    "static-analysis",
+    "policy-as-code",
+    "typescript",
+    "developer-tools"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alex-dbs/coderuler.git"
@@ -72,6 +90,7 @@
     "jsonpath-plus": "11.2.1",
     "npm-install-checks": "9.0.0",
     "npm-package-arg": "14.0.0",
+    "openai": "7.45.1",
     "pacote": "22.0.0",
     "skills": "1.7.2",
     "ssri": "14.0.0",

package/skills/coderuler-new-rule/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coderuler-new-rule
-description: Create CodeRuler rules, including custom selection, filters and checks, inline tests, and inspection.
+description: Create CodeRuler rules, including custom selection, filters and checks, inline or companion tests, and inspection.
 ---
 
 # Create a CodeRuler rule
@@ -29,7 +29,13 @@ Start the name with its language or technology prefix, such as `go-`, `ts-`, or
 
 Keep rules short, with only a few lines of policy code. Reuse built-in selectors, evaluators, and standard libraries before writing custom logic. Add helpers only for real reuse.
 
-Add a named `tests` export in the same file. Use `.passes()` and `.violates()` cases that exercise the policy. Omit `.skips()` assertions when creating a rule: skipped inputs never reach the check and provide no evidence of policy behavior.
+Test cases can live in the rule module or in a sibling `.test` module. For example, `sample.rule.ts` pairs with `sample.test.ts`; keep the same extension for `.mts`, `.js`, and `.mjs`. The `test` command combines exports from both modules. It runs ordinary `tests` by default; include `--ai` to run `aiTests`.
+
+For a deterministic rule, export named `tests` with `.passes()` and `.violates()` cases. For an AI rule, put every test case in `aiTests` and do not add a separate `tests` export. Omit `.skips()` assertions when creating a rule: skipped inputs never reach the check and provide no evidence of policy behavior.
+
+For an AI rule, use `instruction` to state what compliant code does, beginning with a direct requirement. Add only applicability boundaries or real exceptions needed to define the policy; keep one policy per rule. Keep reporting language in `violationMessage`, examples in `examples`, and test cases in `aiTests`—not in the instruction. See [AI instruction style](reference.md#ai-instruction-style).
+
+Keep Jev's input to the smallest scope that still supports a correct decision. For function-local code rules, use `scopes.astGrep` to select one function or method per scope and filter for relevant syntax, such as pointer dereferences.
 
 Run the relevant cases before the policy change and require an assertion mismatch for the intended violation, not a loading error. Implement the policy, then require every case to pass.
 
@@ -90,17 +96,17 @@ coderuler validate
 coderuler test
 ```
 
-`validate` checks the module contract, not policy behavior or TypeScript semantics. `check` and `validate` do not execute inline tests. `test` with no selected cases is an error, not success.
+`validate` checks the module contract, not policy behavior or TypeScript semantics. `check` and `validate` do not run test cases or load sibling `.test` modules. `test` with no selected cases is an error, not success.
 
 Useful test options:
 
 ```sh
 coderuler test . --failures-only
 coderuler test . --concurrency 4 --timeout 30s
-coderuler test .coderuler/k8s-semantic-policy.rule.ts --ai --timeout 45s
+coderuler test .coderuler/semantic-policy.rule.ts --ai --ai-scores --timeout 45s
 ```
 
-Replace the semantic-policy filename with the actual AI rule. `--ai` authorizes live provider calls for `aiTests`, requires provider configuration, and may incur charges. Outcomes can vary; provider errors are errors, not passes.
+Replace the semantic-policy filename with the actual AI rule. `--ai` authorizes live provider calls for `aiTests`, requires provider configuration, and can incur charges. `--ai-scores` displays each Jev probability; use it with `--ai`. A test marked `PASS` means its expectation matched, not that its code is compliant. Expected violations need scores near `0`; compliant cases need scores near `1`. For wording changes, compare both groups on the same fixtures and configuration. Follow [the comparison procedure](reference.md#ai-instruction-style) rather than changing fixtures or thresholds to make a candidate pass.
 
 ## 4. Inspect the rule on the project