@alex-dbs/coderuler 1.4.0 → 1.6.0

package/README.md

@@ -15,6 +15,7 @@ Install the CLI globally:
 ```sh
 npm install -g @alex-dbs/coderuler
 coderuler --help
+coderuler skill install
 ```
 
 The npm package is scoped. The command is `coderuler`. A global installation can load rules without a project-local dependency.
@@ -24,6 +25,7 @@ For a project-specific CLI version, install it locally:
 ```sh
 npm install --save-dev @alex-dbs/coderuler
 npx coderuler --help
+npx coderuler skill install
 ```
 
 The global installation is optional: with only the project-local dependency, run commands through `npx coderuler`.
@@ -158,7 +160,7 @@ A scope is a file or selected part of a file. CodeRuler validates selected rules
 The `settings` field sets AI options for one rule, such as its model, decision threshold, and input or output token prices.
 
 > [!TIP]
-> Browse the [`.coderuler` folder](.coderuler) for rule examples.
+> Browse the [`.coderuler.examples` folder](.coderuler.examples) for rule examples.
 
 ## Commands
 

package/dist/adapter/cli/commands/check.js

@@ -12,6 +12,7 @@ async function runCheck(target, options, context, services) {
         ? createProgress(context.writeError, () => context.terminal?.columns ?? 80)
         : undefined;
     let checkout;
+    let rulesCheckout;
     try {
         let reports;
         let durationMs;
@@ -24,21 +25,28 @@ async function runCheck(target, options, context, services) {
             }
             const area = await services.resolveTarget(checkout?.root ?? context.cwd, target);
             root = area.root;
-            let changedFiles = checkout?.changedFiles ?? (diffOnly
-                ? await services.changedFiles(area.root, options.base ?? 'HEAD')
-                : undefined);
-            const choice = options.rules === undefined
-                ? {}
-                : await services.resolveRuleSelector(options.rules, context.cwd, true);
+            let changes = checkout === undefined
+                ? (diffOnly ? await services.collectChanges(area.root, options.base ?? 'HEAD') : undefined)
+                : { changedFiles: checkout.changedFiles, changedLines: checkout.changedLines };
+            let choice = {};
+            if (options.rules !== undefined) {
+                rulesCheckout = await services.checkoutRuleRepository(options.rules);
+                choice = rulesCheckout === undefined
+                    ? await services.resolveRuleSelector(options.rules, context.cwd, true)
+                    : { explicit: rulesCheckout.root };
+            }
             const prepared = await planWalk(context.cwd, services, area.root, filepath => area.contains(filepath), choice, checkout?.rulesRoot ?? area.root);
             rules = options.tags.length === 0 && options.excludeTags.length === 0
                 ? prepared.rules
                 : prepared.rules.filter(({ rule }) => (options.tags.length === 0 ||
                     rule.tags?.some(tag => options.tags.includes(tag)) === true) &&
                     !rule.tags?.some(tag => options.excludeTags.includes(tag)));
-            if (changedFiles !== undefined) {
+            if (changes !== undefined) {
                 const ruleFiles = new Set(prepared.rules.map(entry => relative(area.root, resolve(entry.ruleFile)).split(sep).join('/')));
-                changedFiles = new Set([...changedFiles].filter(path => !ruleFiles.has(path)));
+                changes = {
+                    changedFiles: new Set([...changes.changedFiles].filter(path => !ruleFiles.has(path))),
+                    changedLines: new Map([...changes.changedLines].filter(([path]) => !ruleFiles.has(path))),
+                };
             }
             const concurrency = debug ? 1 : options.concurrency;
             walkthrough = verbose
@@ -59,7 +67,10 @@ async function runCheck(target, options, context, services) {
                 concurrency,
                 resolveDecision: services.decisionResolver(options.threshold),
                 ...(emit === undefined ? {} : { emit }),
-                ...(changedFiles === undefined ? {} : { changedFiles }),
+                ...(changes === undefined ? {} : {
+                    changedFiles: changes.changedFiles,
+                    changedLines: changes.changedLines,
+                }),
             };
             const startedAt = performance.now();
             reports = await services.runRules(rules, runContext);
@@ -87,7 +98,7 @@ async function runCheck(target, options, context, services) {
         }
     }
     finally {
-        await checkout?.cleanup();
+        await Promise.all([checkout?.cleanup(), rulesCheckout?.cleanup()]);
     }
 }
 export { runCheck };

package/dist/adapter/cli/program.js

@@ -128,7 +128,7 @@ export function createProgram(services) {
         .description('Run the declared test cases for the selected rules')
         .argument('[rule]', 'rule name, module path, or directory')
         .option('--ai', 'include aiTests that use the configured decision backend')
-        .option('--ai-scores', 'show Jev scores for aiTests')
+        .option('--ai-scores', 'show AI scores for aiTests')
         .option('--failures-only', 'show only failed test cases')
         .addOption(new Option('--timeout <duration>', 'per-test timeout (ms, s, or m)')
         .argParser(parseTimeout)
@@ -143,7 +143,7 @@ export function createProgram(services) {
         .command('check')
         .description('Evaluate every selected rule against the working tree')
         .argument('[path]', 'target file or folder that narrows selection', '.')
-        .option('--rules <rule>', 'rule name, module path, or directory')
+        .option('--rules <rule>', 'rule name, module path, directory, or Git repository URL[#revision]')
         .option('--tags <tags...>', 'run rules matching any listed tag', [])
         .option('--exclude-tags <tags...>', 'exclude rules matching any listed tag', [])
         .option('--json', 'print violations as {durationMs, reports} JSON on stdout')

package/dist/adapter/cli/reports.js

@@ -45,7 +45,7 @@ export function renderRuleTestResult(result, redact, color, lastInRule, showAISc
         ? ''
         : safe(` (expected ${result.expected}, actual ${result.actual})`);
     const aiScores = showAIScores && result.aiScores !== undefined && result.aiScores.length > 0
-        ? ` (${result.aiScores.length === 1 ? 'Jev score' : 'Jev scores'}: ${result.aiScores.join(', ')})`
+        ? ` (${result.aiScores.length === 1 ? 'AI score' : 'AI scores'}: ${result.aiScores.join(', ')})`
         : '';
     const duration = paint(safe(` (${formatDuration(result.durationMs)})`), 'dim', color);
     return `${branch}${label} ${safe(result.name)}${detail}${aiScores}${duration}\n`;

package/dist/adapter/cli/services.d.ts

@@ -1,8 +1,9 @@
-import type { LoadedRule, Project, RuleReport, RuleSelection, RunContext } from '../../app/ports.js';
+import type { DiffChanges, LoadedRule, Project, RuleReport, RuleSelection, RunContext } from '../../app/ports.js';
 import type { RuleTestResult } from '../../app/rule-tests.js';
 import type { TokenPricing } from '../../app/rule.js';
 import type { ViolationComment } from '../../app/violation-comments.js';
 import type { PullRequest, PullRequestCheckout } from '../github/pull-request.js';
+import type { RuleRepositoryCheckout } from '../git/rules.js';
 import type { SkillOptions } from '../skills/cli.js';
 import type { TerminalCapabilities } from './progress.js';
 import type { TextRedactor, TextWriter } from './text.js';
@@ -71,8 +72,9 @@ export interface ExecutionServices extends RuleServices {
     readonly decisionResolver: (thresholdOverride?: number, pricingOverrides?: Partial<TokenPricing>) => RunContext['resolveDecision'];
 }
 export interface CheckServices extends ExecutionServices {
-    readonly changedFiles: (root: string, base: string) => Promise<ReadonlySet<string>>;
+    readonly collectChanges: (root: string, base: string) => Promise<DiffChanges>;
     readonly checkoutPullRequest: (selector: string, baseBranch?: string) => Promise<PullRequestCheckout>;
+    readonly checkoutRuleRepository: (selector: string) => Promise<RuleRepositoryCheckout | undefined>;
     readonly commentOnPullRequest: (root: string, comments: readonly ViolationComment[], pullRequest?: PullRequest) => Promise<void>;
 }
 export type InspectServices = ExecutionServices;

package/dist/adapter/decision/jev.js

@@ -1,6 +1,7 @@
 const ENDPOINT = 'v1/systemone';
 const QUESTION_ID = 'follows_instructions';
 const TIMEOUT_MS = 30_000;
+const RETRY_DELAYS_MS = [3_000, 10_000, 30_000];
 const REDACTED = '[REDACTED]';
 const URL_LABEL = 'Decision base URL (TYPESAFE_BASE_URL)';
 function isMapping(value) {
@@ -53,6 +54,14 @@ function requestFailure(error, axios) {
     }
     return new Error(`Decision request failed: ${error instanceof Error ? error.message : String(error)}`);
 }
+function shouldRetry(error, axios) {
+    if (!axios.isAxiosError(error))
+        return false;
+    const status = error.response?.status;
+    return status === undefined
+        ? error.request !== undefined
+        : status === 408 || status === 429 || (status >= 500 && status < 600);
+}
 function readDecision(data) {
     if (!isMapping(data)) {
         throw new Error('Decision response is not a JSON object');
@@ -114,24 +123,32 @@ export class JevAdapter {
             },
         };
         const wire = JSON.stringify(body);
-        observer?.({ type: 'request', body: redact(wire, this.#needles) });
         let data;
-        try {
-            const response = await client.post(ENDPOINT, wire, {
-                headers: { 'Content-Type': 'application/json' },
-            });
-            data = response.data;
-            observer?.({ type: 'response', status: response.status, body: redact(JSON.stringify(data) ?? '', this.#needles) });
-        }
-        catch (error) {
-            if (axios.isAxiosError(error) && error.response !== undefined) {
-                observer?.({
-                    type: 'response',
-                    status: error.response.status,
-                    body: redact(JSON.stringify(error.response.data) ?? '', this.#needles),
+        for (let retry = 0;; retry += 1) {
+            observer?.({ type: 'request', body: redact(wire, this.#needles) });
+            try {
+                const response = await client.post(ENDPOINT, wire, {
+                    headers: { 'Content-Type': 'application/json' },
                 });
+                data = response.data;
+                observer?.({ type: 'response', status: response.status, body: redact(JSON.stringify(data) ?? '', this.#needles) });
+                break;
+            }
+            catch (error) {
+                if (axios.isAxiosError(error) && error.response !== undefined) {
+                    observer?.({
+                        type: 'response',
+                        status: error.response.status,
+                        body: redact(JSON.stringify(error.response.data) ?? '', this.#needles),
+                    });
+                }
+                const delayMs = RETRY_DELAYS_MS[retry];
+                if (delayMs === undefined || !shouldRetry(error, axios))
+                    throw requestFailure(error, axios);
+                const delay = Promise.withResolvers();
+                setTimeout(delay.resolve, delayMs);
+                await delay.promise;
             }
-            throw requestFailure(error, axios);
         }
         return readDecision(data);
     }

package/dist/adapter/decision/openai.d.ts

@@ -0,0 +1,11 @@
+import type { DecisionBackend, DecisionObserver, DecisionOutcome, DecisionRequest } from '../../app/ports.js';
+export interface OpenAIOptions {
+    readonly model: string;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+}
+export declare class OpenAIAdapter implements DecisionBackend {
+    #private;
+    constructor({ model, baseUrl, apiKey }: OpenAIOptions);
+    decide(request: DecisionRequest, observer?: DecisionObserver): Promise<DecisionOutcome>;
+}

package/dist/adapter/decision/openai.js

@@ -0,0 +1,160 @@
+import { isRecord } from '../../app/validate.js';
+const QUESTION_NAME = 'follows_instructions';
+const TIMEOUT_MS = 30_000;
+const REDACTED = '[REDACTED]';
+const URL_LABEL = 'Decision base URL (OPENAI_BASE_URL)';
+function baseUrlOf(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`${URL_LABEL} is not an absolute URL`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`${URL_LABEL} must use http or https`);
+    }
+    if (baseUrl.includes('?') || baseUrl.includes('#')) {
+        throw new Error(`${URL_LABEL} must not carry a query or a fragment`);
+    }
+    if (url.username !== '' || url.password !== '') {
+        throw new Error(`${URL_LABEL} must not embed credentials`);
+    }
+    return baseUrl;
+}
+function redactionNeedles(apiKey) {
+    if (apiKey === '')
+        return [];
+    const escaped = JSON.stringify(apiKey).slice(1, -1);
+    return escaped === apiKey ? [apiKey] : [escaped, apiKey];
+}
+function redact(text, needles) {
+    let redacted = text;
+    for (const needle of needles)
+        redacted = redacted.replaceAll(needle, REDACTED);
+    return redacted;
+}
+function formattedInstructions(request) {
+    const { rule, question, examples } = request.instructions;
+    const sections = [`Rule:\n${rule}`];
+    if (examples?.good !== undefined && examples.good.length > 0) {
+        sections.push(`Good examples (the rule is respected):\n${JSON.stringify(examples.good)}`);
+    }
+    if (examples?.bad !== undefined && examples.bad.length > 0) {
+        sections.push(`Bad examples (the rule is not respected):\n${JSON.stringify(examples.bad)}`);
+    }
+    sections.push(question);
+    return sections.join('\n\n');
+}
+function readDecision(data) {
+    if (!isRecord(data))
+        throw new Error('Decision response is not a JSON object');
+    const model = data.model;
+    if (typeof model !== 'string' || model.trim() === '') {
+        throw new Error('Decision response carries no model');
+    }
+    const answers = data.answers;
+    if (!Array.isArray(answers))
+        throw new Error('Decision response carries no answers');
+    const answer = answers.find((candidate) => isRecord(candidate) && candidate.name === QUESTION_NAME);
+    if (!isRecord(answer)) {
+        throw new Error(`Decision response carries no '${QUESTION_NAME}' answer`);
+    }
+    if (answer.type === 'refusal') {
+        throw new Error(`Decision response '${QUESTION_NAME}' answer was refused`);
+    }
+    if (answer.type !== 'predicate') {
+        throw new Error(`Decision response '${QUESTION_NAME}' answer is not a predicate answer`);
+    }
+    const probability = answer.probability;
+    if (typeof probability !== 'number' || !Number.isFinite(probability) || probability < 0 || probability > 1) {
+        throw new Error(`Decision response '${QUESTION_NAME}' answer is not a probability between 0 and 1`);
+    }
+    const rawUsage = data.usage;
+    if (rawUsage === undefined)
+        return { probability, model };
+    if (!isRecord(rawUsage))
+        throw new Error('Decision response usage must be an object');
+    const inputTokens = rawUsage.input_tokens;
+    const outputTokens = rawUsage.output_tokens;
+    if (typeof inputTokens !== 'number' || !Number.isSafeInteger(inputTokens) || inputTokens < 0 ||
+        typeof outputTokens !== 'number' || !Number.isSafeInteger(outputTokens) || outputTokens < 0) {
+        throw new Error('Decision response usage must carry nonnegative safe integer input_tokens and output_tokens');
+    }
+    return { probability, model, usage: { inputTokens, outputTokens } };
+}
+export class OpenAIAdapter {
+    #client;
+    #apiKey;
+    #baseUrl;
+    #model;
+    #needles;
+    constructor({ model, baseUrl, apiKey }) {
+        this.#model = model;
+        this.#baseUrl = baseUrlOf(baseUrl);
+        this.#apiKey = apiKey;
+        this.#needles = redactionNeedles(apiKey);
+    }
+    async decide(request, observer) {
+        const payload = {
+            model: this.#model,
+            input: JSON.stringify(request.state),
+            questions: [{
+                    type: 'predicate',
+                    name: QUESTION_NAME,
+                    instructions: formattedInstructions(request),
+                }],
+        };
+        const observedPayload = {
+            ...payload,
+            input: redact(payload.input, this.#needles),
+            questions: payload.questions.map(question => ({
+                ...question,
+                instructions: redact(question.instructions, this.#needles),
+            })),
+        };
+        observer?.({
+            type: 'request',
+            body: redact(JSON.stringify(observedPayload), this.#needles),
+        });
+        // Load the SDK only when an AI decision runs, matching Jev's lazy provider dependency.
+        const sdk = await import('openai');
+        let data;
+        let status;
+        try {
+            const client = this.#client ??= new sdk.default({
+                apiKey: this.#apiKey,
+                baseURL: this.#baseUrl,
+                timeout: TIMEOUT_MS,
+                maxRetries: 2,
+                fetchOptions: { redirect: 'manual' },
+                logLevel: 'off',
+                defaultHeaders: { Authorization: `Bearer ${this.#apiKey}` },
+            });
+            const result = await client.decisions.create(payload).withResponse();
+            data = result.data;
+            status = result.response.status;
+        }
+        catch (error) {
+            if (error instanceof sdk.APIError && error.status !== undefined) {
+                const body = error.error === undefined ? error.message : JSON.stringify(error.error) ?? error.message;
+                observer?.({ type: 'response', status: error.status, body: redact(body, this.#needles) });
+                throw new Error(`Decision request failed with HTTP ${error.status}`);
+            }
+            if (error instanceof sdk.APIConnectionTimeoutError) {
+                throw new Error(`Decision request timed out after ${TIMEOUT_MS} ms`);
+            }
+            if (error instanceof sdk.APIConnectionError) {
+                throw new Error('Decision request failed: network error');
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Decision request failed: ${redact(message, this.#needles)}`);
+        }
+        observer?.({
+            type: 'response',
+            status,
+            body: redact(JSON.stringify(data) ?? '', this.#needles),
+        });
+        return readDecision(data);
+    }
+}

package/dist/adapter/filesystem/rule-test-lsp.d.ts

@@ -0,0 +1,6 @@
+import type { MessagePort } from 'node:worker_threads';
+import type { LspBackend, LspBackendFactory, Project } from '../../app/ports.js';
+export declare function createRuleTestLspHost(port: MessagePort, project: Project, createBackend?: LspBackendFactory): {
+    close(): Promise<void>;
+};
+export declare function createRuleTestLspBackend(port: MessagePort, signal: AbortSignal): LspBackend;

package/dist/adapter/filesystem/rule-test-lsp.js

@@ -0,0 +1,189 @@
+import { createRunLsp } from '../../app/lsp.js';
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function send(port, response) {
+    try {
+        port.postMessage(response);
+    }
+    catch {
+        // A peer can close its port while an operation is settling.
+    }
+}
+export function createRuleTestLspHost(port, project, createBackend) {
+    const facade = createRunLsp(project, createBackend);
+    let closed = false;
+    let closePromise;
+    const onRequest = (value) => {
+        if (value === null || typeof value !== 'object')
+            return;
+        const candidate = value;
+        if (!Number.isSafeInteger(candidate.id) || !Array.isArray(candidate.args))
+            return;
+        const request = value;
+        void (async () => {
+            try {
+                let result;
+                switch (request.method) {
+                    case 'definitions':
+                        result = await facade.tools.definitions(...request.args);
+                        break;
+                    case 'declarations':
+                        result = await facade.tools.declarations(...request.args);
+                        break;
+                    case 'typeDefinitions':
+                        result = await facade.tools.typeDefinitions(...request.args);
+                        break;
+                    case 'implementations':
+                        result = await facade.tools.implementations(...request.args);
+                        break;
+                    case 'references':
+                        result = await facade.tools.references(...request.args);
+                        break;
+                    case 'hover':
+                        result = await facade.tools.hover(...request.args);
+                        break;
+                    case 'documentSymbols':
+                        result = await facade.tools.documentSymbols(...request.args);
+                        break;
+                    case 'workspaceSymbols':
+                        result = await facade.tools.workspaceSymbols(...request.args);
+                        break;
+                    case 'callers':
+                        result = await facade.tools.callers(...request.args);
+                        break;
+                    case 'callees':
+                        result = await facade.tools.callees(...request.args);
+                        break;
+                    case 'close':
+                        await facade.close();
+                        result = undefined;
+                        break;
+                    default: throw new Error('Unsupported rule-test LSP method');
+                }
+                send(port, { id: request.id, result });
+            }
+            catch (error) {
+                send(port, { id: request.id, error: describe(error) });
+            }
+        })();
+    };
+    const close = () => {
+        if (closePromise !== undefined)
+            return closePromise;
+        closed = true;
+        port.off('message', onRequest);
+        closePromise = (async () => {
+            try {
+                await facade.close();
+            }
+            finally {
+                port.close();
+            }
+        })();
+        return closePromise;
+    };
+    const onPortClose = () => {
+        if (!closed)
+            void close().catch(() => undefined);
+    };
+    port.on('message', onRequest);
+    port.once('close', onPortClose);
+    port.start();
+    return { close };
+}
+export function createRuleTestLspBackend(port, signal) {
+    let nextId = 0;
+    let portClosed = false;
+    let signalAborted = false;
+    let closePromise;
+    const pending = new Map();
+    const rejectPending = (error) => {
+        for (const request of pending.values())
+            request.reject(error);
+        pending.clear();
+    };
+    const onResponse = (value) => {
+        if (value === null || typeof value !== 'object')
+            return;
+        const candidate = value;
+        if (!Number.isSafeInteger(candidate.id))
+            return;
+        const response = value;
+        const request = pending.get(response.id);
+        if (request === undefined)
+            return;
+        pending.delete(response.id);
+        if ('error' in response)
+            request.reject(new Error(response.error));
+        else
+            request.resolve(response.result);
+    };
+    const onPortClose = () => {
+        if (portClosed)
+            return;
+        portClosed = true;
+        rejectPending(new Error('Rule test LSP host closed'));
+    };
+    const onAbort = () => {
+        signalAborted = true;
+        rejectPending(signal.reason instanceof Error ? signal.reason : new Error('Rule test LSP backend aborted'));
+    };
+    port.on('message', onResponse);
+    port.once('close', onPortClose);
+    port.start();
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    const request = (method, args, allowAborted = false) => {
+        if (portClosed)
+            return Promise.reject(new Error('Rule test LSP host closed'));
+        if (signalAborted && !allowAborted) {
+            return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error('Rule test LSP backend aborted'));
+        }
+        const id = nextId++;
+        const deferred = Promise.withResolvers();
+        pending.set(id, {
+            resolve: value => deferred.resolve(value),
+            reject: deferred.reject,
+        });
+        try {
+            port.postMessage({ id, method, args });
+        }
+        catch (error) {
+            pending.delete(id);
+            deferred.reject(error instanceof Error ? error : new Error(describe(error)));
+        }
+        return deferred.promise;
+    };
+    const close = () => {
+        if (closePromise !== undefined)
+            return closePromise;
+        closePromise = (async () => {
+            try {
+                await request('close', [], true);
+            }
+            finally {
+                signal.removeEventListener('abort', onAbort);
+                port.off('message', onResponse);
+                port.off('close', onPortClose);
+                port.close();
+                onPortClose();
+            }
+        })();
+        return closePromise;
+    };
+    return {
+        definitions: (target, options) => request('definitions', [target, options]),
+        declarations: (target, options) => request('declarations', [target, options]),
+        typeDefinitions: (target, options) => request('typeDefinitions', [target, options]),
+        implementations: (target, options) => request('implementations', [target, options]),
+        references: (target, options) => request('references', [target, options]),
+        hover: (target, options) => request('hover', [target, options]),
+        documentSymbols: (filepath, options) => request('documentSymbols', [filepath, options]),
+        workspaceSymbols: (query, options) => request('workspaceSymbols', [query, options]),
+        callers: (target, options) => request('callers', [target, options]),
+        callees: (target, options) => request('callees', [target, options]),
+        close,
+    };
+}

package/dist/adapter/filesystem/rule-test-worker.d.ts

@@ -1,12 +1,17 @@
+import { type MessagePort } from 'node:worker_threads';
 import type { RuleTestCase } from '../../app/rule-tests.js';
 import type { PreparedRuleDependencies } from './dependencies.js';
 export interface RuleTestWorkerRequest {
     readonly id: number;
+    readonly lspPort: MessagePort;
+    readonly rubyLspPort: MessagePort;
+    readonly typescriptLspPort: MessagePort;
     readonly root: string;
     readonly ruleFile: string;
     readonly files: RuleTestCase['files'];
     readonly ai: boolean;
     readonly dependencies?: PreparedRuleDependencies;
+    readonly includeDisabled?: boolean;
 }
 export interface RuleTestWorkerOutcome {
     readonly actual: RuleTestCase['expected'];