@alex-dbs/coderuler 0.0.0-stage → 1.3.1

package/dist/adapter/cli/self-update.d.ts

@@ -0,0 +1 @@
+export declare function createToolUpdater(cwd: string, env: NodeJS.ProcessEnv): () => Promise<number>;

package/dist/adapter/cli/self-update.js

@@ -0,0 +1,89 @@
+import { spawn } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access, realpath } from 'node:fs/promises';
+import { constants as osConstants } from 'node:os';
+import { basename, delimiter, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PACKAGE_NAME = '@alex-dbs/coderuler';
+const PACKAGE_ROOT = fileURLToPath(new URL('../../../', import.meta.url));
+const UPDATE_INSTRUCTIONS = 'Self-update requires the active global npm installation. For project-local installs, run npm install --save-dev @alex-dbs/coderuler@latest. Otherwise use your package manager or reinstall with npm install --global @alex-dbs/coderuler@latest.';
+async function findNpm(env) {
+    const path = process.platform === 'win32'
+        ? Object.entries(env).find(([name]) => name.toLowerCase() === 'path')?.[1]
+        : env.PATH;
+    for (const directory of (path ?? '').split(delimiter)) {
+        if (directory === '')
+            continue;
+        const shim = join(directory, process.platform === 'win32' ? 'npm.cmd' : 'npm');
+        try {
+            await access(shim, process.platform === 'win32' ? fsConstants.F_OK : fsConstants.X_OK);
+            const executable = await realpath(shim);
+            const cli = process.platform === 'win32'
+                ? join(dirname(executable), 'node_modules', 'npm', 'bin', 'npm-cli.js')
+                : executable;
+            if (basename(cli) !== 'npm-cli.js') {
+                throw new Error('The active npm executable is not a supported npm installation; update CodeRuler using your package manager.');
+            }
+            await access(cli, fsConstants.R_OK);
+            return cli;
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                throw error;
+        }
+    }
+    throw new Error('npm was not found on PATH; install npm or update CodeRuler using your package manager.');
+}
+function runNpm(executable, args, cwd, env, capture) {
+    const { promise, resolve: settle, reject } = Promise.withResolvers();
+    const child = spawn(process.execPath, [executable, ...args], {
+        cwd,
+        env,
+        stdio: capture ? ['inherit', 'pipe', 'inherit'] : 'inherit',
+    });
+    let stdout = '';
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (text) => { stdout += text; });
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+        settle({ status: code ?? 128 + (signal === null ? 0 : osConstants.signals[signal]), stdout });
+    });
+    return promise;
+}
+export function createToolUpdater(cwd, env) {
+    return async () => {
+        const packageRoot = await realpath(PACKAGE_ROOT);
+        if (basename(dirname(packageRoot)) !== '@alex-dbs' || basename(dirname(dirname(packageRoot))) !== 'node_modules') {
+            throw new Error(UPDATE_INSTRUCTIONS);
+        }
+        const executable = await findNpm(env);
+        const root = await runNpm(executable, ['root', '--global'], cwd, env, true);
+        if (root.status !== 0)
+            return root.status;
+        const globalRoot = root.stdout.trim();
+        let activePackage;
+        try {
+            activePackage = await realpath(join(globalRoot, PACKAGE_NAME));
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                throw error;
+            throw new Error(UPDATE_INSTRUCTIONS);
+        }
+        if (activePackage !== packageRoot || join(await realpath(globalRoot), PACKAGE_NAME) !== packageRoot) {
+            throw new Error(UPDATE_INSTRUCTIONS);
+        }
+        const prefix = await runNpm(executable, ['prefix', '--global'], cwd, env, true);
+        if (prefix.status !== 0)
+            return prefix.status;
+        const globalPrefix = prefix.stdout.trim();
+        const expectedRoot = process.platform === 'win32'
+            ? join(globalPrefix, 'node_modules')
+            : join(globalPrefix, 'lib', 'node_modules');
+        if (resolve(globalRoot) !== resolve(expectedRoot)) {
+            throw new Error('The active npm global prefix does not match this installation; update CodeRuler using your package manager.');
+        }
+        const result = await runNpm(executable, ['install', '--global', '--prefix', globalPrefix, `${PACKAGE_NAME}@latest`], cwd, env, false);
+        return result.status;
+    };
+}

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

@@ -0,0 +1,101 @@
+import type { 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 { SkillOptions } from '../skills/cli.js';
+import type { TerminalCapabilities } from './progress.js';
+import type { TextRedactor, TextWriter } from './text.js';
+export interface CliTarget {
+    readonly root: string;
+    readonly path: string;
+    readonly kind: 'file' | 'directory';
+    contains(filepath: string): boolean;
+}
+export interface RuleSelectorResolution {
+    readonly explicit?: string;
+    readonly name?: string;
+}
+export interface CheckOptions {
+    readonly rules?: string;
+    readonly tags: readonly string[];
+    readonly excludeTags: readonly string[];
+    readonly json?: boolean;
+    readonly jsonl?: boolean;
+    readonly outputAll?: boolean;
+    readonly debug?: boolean;
+    readonly verbose?: boolean;
+    readonly diffOnly?: boolean;
+    readonly pr?: string;
+    readonly autoComment?: boolean;
+    readonly base?: string;
+    readonly concurrency: number;
+    readonly threshold?: number;
+}
+export interface InspectOptions {
+    readonly json?: boolean;
+    readonly jsonl?: boolean;
+    readonly raw?: boolean;
+    readonly inputCostPerMillion?: number;
+    readonly outputCostPerMillion?: number;
+}
+export interface TestOptions {
+    readonly timeout: number;
+    readonly concurrency: number;
+    readonly ai?: boolean;
+    readonly failuresOnly?: boolean;
+}
+export interface DependencyOptions {
+    readonly global?: boolean;
+    readonly directory?: string;
+}
+export interface CliContext {
+    readonly cwd: string;
+    readonly version: string;
+    readonly redact: TextRedactor;
+    readonly write: TextWriter;
+    readonly writeError: TextWriter;
+    readonly terminal?: TerminalCapabilities;
+}
+export interface RuleServices {
+    readonly loadRules: (selection: RuleSelection) => Promise<readonly LoadedRule[]>;
+    readonly resolveRuleSelector: (selector: string, invocationCwd: string, allowDirectory?: boolean) => Promise<RuleSelectorResolution>;
+}
+export interface ExecutionServices extends RuleServices {
+    readonly createProject: (root: string, options?: {
+        readonly excludeFiles?: readonly string[];
+    }) => Project;
+    readonly resolveTarget: (root: string, target: string) => Promise<CliTarget>;
+    readonly runRules: (rules: readonly LoadedRule[], context: RunContext) => Promise<readonly RuleReport[]>;
+    readonly decisionResolver: (thresholdOverride?: number, pricingOverrides?: Partial<TokenPricing>) => RunContext['resolveDecision'];
+}
+export interface CheckServices extends ExecutionServices {
+    readonly changedFiles: (root: string, base: string) => Promise<ReadonlySet<string>>;
+    readonly checkoutPullRequest: (selector: string, baseBranch?: string) => Promise<PullRequestCheckout>;
+    readonly commentOnPullRequest: (root: string, comments: readonly ViolationComment[], pullRequest?: PullRequest) => Promise<void>;
+}
+export type InspectServices = ExecutionServices;
+export type ValidateServices = RuleServices;
+export interface TestServices extends RuleServices {
+    readonly testRules: (rules: readonly LoadedRule[], onResult: (result: RuleTestResult, lastInRule: boolean) => void, timeoutMs: number, concurrency: number, includeAI: boolean) => Promise<readonly RuleTestResult[]>;
+}
+export interface UpdateServices {
+    readonly updateTool: () => Promise<number>;
+}
+export interface SkillServices {
+    readonly manageSkill: (operation: 'install' | 'update', options: SkillOptions) => Promise<number>;
+}
+export interface DependencyServices {
+    readonly manageDependencies: (operation: 'add' | 'remove' | 'sync', packages: readonly string[], options: DependencyOptions) => Promise<void>;
+}
+export interface CliServices extends CliContext {
+    readonly load: {
+        readonly check: (context: CliContext) => Promise<CheckServices>;
+        readonly inspect: (context: CliContext) => Promise<InspectServices>;
+        readonly test: (context: CliContext) => Promise<TestServices>;
+        readonly validate: (context: CliContext) => Promise<ValidateServices>;
+        readonly update: (context: CliContext) => Promise<UpdateServices>;
+        readonly skill: (context: CliContext) => Promise<SkillServices>;
+        readonly deps: (context: CliContext) => Promise<DependencyServices>;
+    };
+}

package/dist/adapter/cli/services.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+export type TextWriter = (text: string) => void;
+export type TextRedactor = (text: string) => string;
+export declare function escapeText(text: string): string;
+export declare function createRedactor(values: readonly (string | undefined)[]): TextRedactor;
+export declare function escapeDiagnostic(text: string): string;

package/dist/adapter/cli/text.js

@@ -0,0 +1,36 @@
+const REDACTED = '[REDACTED]';
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/g;
+export function escapeText(text) {
+    return text.replace(CONTROL_CHARACTERS, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+export function createRedactor(values) {
+    const needles = new Set();
+    for (const value of values) {
+        if (value === undefined || value.trim() === '')
+            continue;
+        for (const candidate of [value, value.trim()]) {
+            needles.add(candidate);
+            needles.add(escapeText(candidate));
+            needles.add(JSON.stringify(candidate).slice(1, -1));
+        }
+    }
+    const replacements = [...needles]
+        .filter(needle => needle !== '')
+        .sort((left, right) => right.length - left.length)
+        .map(needle => [needle, needle.replace(/[^\r\n]+/g, REDACTED)]);
+    if (replacements.length === 0)
+        return text => text;
+    return text => {
+        let redacted = text;
+        for (const [needle, replacement] of replacements) {
+            redacted = redacted.replaceAll(needle, replacement);
+        }
+        return redacted;
+    };
+}
+export function escapeDiagnostic(text) {
+    return text
+        .split('\n')
+        .map(segment => escapeText(segment))
+        .join('\n');
+}

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

@@ -0,0 +1 @@
+export declare const installedVersion: string;

package/dist/adapter/cli/version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs';
+const manifest = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
+export const installedVersion = manifest.version;

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

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

package/dist/adapter/decision/jev.js

@@ -0,0 +1,138 @@
+const ENDPOINT = 'v1/systemone';
+const QUESTION_ID = 'follows_instructions';
+const TIMEOUT_MS = 30_000;
+const REDACTED = '[REDACTED]';
+const URL_LABEL = 'Decision base URL (TYPESAFE_BASE_URL)';
+function isMapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+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 requestFailure(error, axios) {
+    if (axios.isAxiosError(error)) {
+        const status = error.response?.status;
+        if (status !== undefined) {
+            return new Error(`Decision request failed with HTTP ${status}`);
+        }
+        if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
+            return new Error(`Decision request timed out after ${TIMEOUT_MS} ms`);
+        }
+        const code = error.code;
+        return code === undefined
+            ? new Error('Decision request failed: network error')
+            : new Error(`Decision request failed: ${code}`);
+    }
+    return new Error(`Decision request failed: ${error instanceof Error ? error.message : String(error)}`);
+}
+function readDecision(data) {
+    if (!isMapping(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');
+    }
+    if (!isMapping(data.answers)) {
+        throw new Error('Decision response carries no answers');
+    }
+    const answer = data.answers[QUESTION_ID];
+    if (!isMapping(answer)) {
+        throw new Error(`Decision response carries no '${QUESTION_ID}' answer`);
+    }
+    if (answer.type !== 'noul') {
+        throw new Error(`Decision response '${QUESTION_ID}' answer is not a noul answer`);
+    }
+    const probability = answer.noul;
+    if (typeof probability !== 'number' || !Number.isFinite(probability) || probability < 0 || probability > 1) {
+        throw new Error(`Decision response '${QUESTION_ID}' answer is not a probability between 0 and 1`);
+    }
+    const rawUsage = data.usage;
+    if (rawUsage === undefined)
+        return { probability, model };
+    if (!isMapping(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 JevAdapter {
+    #clientOptions;
+    #client;
+    #model;
+    #needles;
+    constructor({ model, baseUrl, apiKey }) {
+        this.#model = model;
+        this.#needles = redactionNeedles(apiKey);
+        this.#clientOptions = {
+            baseURL: baseUrlOf(baseUrl),
+            timeout: TIMEOUT_MS,
+            maxRedirects: 0,
+            headers: { Authorization: `Bearer ${apiKey}` },
+        };
+    }
+    async decide(request, observer) {
+        const { default: axios } = await import('axios');
+        const client = this.#client ??= axios.create(this.#clientOptions);
+        const body = {
+            model: this.#model,
+            state: request.state,
+            questions: {
+                [QUESTION_ID]: { type: 'noul', instructions: request.instructions },
+            },
+        };
+        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),
+                });
+            }
+            throw requestFailure(error, axios);
+        }
+        return readDecision(data);
+    }
+}

package/dist/adapter/filesystem/dependencies.d.ts

@@ -0,0 +1,26 @@
+import { Agent } from 'node:https';
+import type { ClientRequest, RequestOptions } from 'node:http';
+export interface PreparedRuleDependencies {
+    readonly directory: string;
+    readonly directDependencies: readonly string[];
+    readonly key: string;
+}
+export interface RuleDependencyManager {
+    prepare(directory: string): Promise<PreparedRuleDependencies>;
+    change(directory: string, operation: 'add' | 'remove', packages: readonly string[]): Promise<PreparedRuleDependencies & {
+        readonly directVersions: Readonly<Record<string, string>>;
+    }>;
+    sync(directory: string): Promise<PreparedRuleDependencies>;
+}
+type Manifest = Record<string, unknown>;
+export declare function ruleDependencyLockKey(parsed: Manifest | null, directory: string): string;
+export declare function readRuleDependencyLock(directory: string): Promise<string | null>;
+export declare function dependencyDirectory(ruleFile: string): Promise<string>;
+export declare class RegistryHttpsAgent extends Agent {
+    addRequest(request: ClientRequest, options: RequestOptions): void;
+}
+export declare function createRuleDependencyManager(options?: {
+    readonly cacheRoot?: string;
+    readonly onWarning?: (message: string) => void;
+}): RuleDependencyManager;
+export {};