@alex-dbs/coderuler 0.0.0-stage → 1.3.0

package/dist/app/evaluators.js

@@ -0,0 +1,175 @@
+import { isRecord, validateAiUsage, validateJsonValue } from './validate.js';
+const QUESTION = 'Is the rule respected?';
+function fail(detail) {
+    throw new Error(detail);
+}
+export function pass() {
+    return { status: 'pass' };
+}
+export function violation(message, locations) {
+    return { status: 'violation', message, ...(locations === undefined ? {} : { locations }) };
+}
+function assertExampleList(value, label) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        fail(`${label} must be an array of non-empty strings`);
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            fail(`${label} must be an array of non-empty strings`);
+        const entry = value[index];
+        if (typeof entry !== 'string' || entry === '')
+            fail(`${label} must be an array of non-empty strings`);
+    }
+}
+function assertAiOptions(options) {
+    if (typeof options.rule !== 'string' || options.rule === '') {
+        fail('ai rule must be a non-empty string');
+    }
+    const examples = options.examples;
+    if (examples !== undefined) {
+        if (!isRecord(examples))
+            fail('ai examples must be an object');
+        assertExampleList(examples['good'], 'ai examples.good');
+        assertExampleList(examples['bad'], 'ai examples.bad');
+    }
+    const message = options.violationMessage;
+    if (message !== undefined && (typeof message !== 'string' || message === '')) {
+        fail('ai violationMessage must be a non-empty string');
+    }
+    const input = options.input;
+    if (input !== undefined && typeof input !== 'function')
+        fail('ai input must be a function');
+}
+export function ai(options) {
+    assertAiOptions(options);
+    return (_subject, context) => context.ai(options);
+}
+function projectScope(scope) {
+    const captures = scope.captures;
+    if (scope.data === undefined) {
+        return captures === undefined
+            ? { id: scope.id, source: scope.source }
+            : { id: scope.id, source: scope.source, captures };
+    }
+    const data = scope.data;
+    return captures === undefined
+        ? { id: scope.id, data }
+        : { id: scope.id, data, captures };
+}
+function projectState(subject) {
+    if (subject.kind === 'group') {
+        const files = [];
+        const byFilepath = new Map();
+        for (const member of subject.members) {
+            let file = byFilepath.get(member.filepath);
+            if (file === undefined) {
+                file = { filepath: member.filepath, scopes: [] };
+                byFilepath.set(member.filepath, file);
+                files.push(file);
+            }
+            file.scopes.push(projectScope(member));
+        }
+        return { files };
+    }
+    return { filepath: subject.filepath, scope: projectScope(subject) };
+}
+function instructionsOf(options) {
+    const good = options.examples?.good ?? [];
+    const bad = options.examples?.bad ?? [];
+    if (good.length === 0 && bad.length === 0)
+        return { rule: options.rule, question: QUESTION };
+    return { rule: options.rule, question: QUESTION, examples: { good, bad } };
+}
+export async function evaluateAi(subject, options, context, runtime, observer) {
+    assertAiOptions(options);
+    const state = options.input === undefined
+        ? projectState(subject)
+        : validateJsonValue(await options.input(subject, context), 'ai input');
+    let decision;
+    let usage;
+    try {
+        decision = await runtime.backend.decide({ state, instructions: instructionsOf(options) }, observer === undefined ? undefined : exchange => {
+            if (exchange.type !== 'usage')
+                observer(exchange);
+        });
+        const tokens = decision.usage;
+        usage = tokens === undefined
+            ? { calls: 1, unreportedCalls: 1, inputTokens: 0, outputTokens: 0, inputCost: 0, outputCost: 0 }
+            : validateAiUsage({
+                calls: 1,
+                unreportedCalls: 0,
+                inputTokens: tokens.inputTokens,
+                outputTokens: tokens.outputTokens,
+                inputCost: tokenCost(tokens.inputTokens, runtime.pricing.inputCostPerMillion),
+                outputCost: tokenCost(tokens.outputTokens, runtime.pricing.outputCostPerMillion),
+            }, 'Decision outcome');
+    }
+    catch (error) {
+        observer?.({
+            type: 'usage',
+            usage: { calls: 1, unreportedCalls: 1, inputTokens: 0, outputTokens: 0, inputCost: 0, outputCost: 0 },
+        });
+        throw error;
+    }
+    observer?.({ type: 'usage', usage });
+    if (decision.probability > runtime.threshold) {
+        return {
+            status: 'pass', probability: decision.probability, threshold: runtime.threshold, model: decision.model, usage,
+        };
+    }
+    return {
+        status: 'violation',
+        ...(options.violationMessage === undefined ? {} : { message: options.violationMessage }),
+        probability: decision.probability,
+        threshold: runtime.threshold,
+        model: decision.model,
+        usage,
+    };
+}
+function tokenCost(tokens, price) {
+    const product = tokens * price;
+    return Number.isFinite(product) ? product / 1_000_000 : (tokens / 1_000_000) * price;
+}
+function regexValue(scope) {
+    const { data, source } = scope;
+    if (data === undefined || (typeof data === 'object' && data !== null))
+        return source;
+    return String(data);
+}
+export function regex(options) {
+    const { pattern: callerPattern, violationMessage, input } = options;
+    if (!(callerPattern instanceof RegExp))
+        fail('regex pattern must be a RegExp');
+    if (violationMessage !== undefined && (typeof violationMessage !== 'string' || violationMessage === '')) {
+        fail('regex violationMessage must be a non-empty string');
+    }
+    if (input !== undefined && typeof input !== 'function')
+        fail('regex input must be a function');
+    const pattern = new RegExp(callerPattern.source, callerPattern.flags);
+    return async (subject, context) => {
+        const members = subject.kind === 'group' ? subject.members : [subject];
+        const evaluations = [];
+        for (const member of members) {
+            const value = input === undefined ? regexValue(member) : await input(member, context);
+            pattern.lastIndex = 0;
+            evaluations.push({
+                filepath: member.filepath,
+                scopeId: member.id,
+                input: value,
+                matched: pattern.test(value),
+            });
+        }
+        context.trace('regex', { pattern: pattern.source, flags: pattern.flags, evaluations });
+        const locations = [];
+        for (const { matched, filepath, scopeId } of evaluations) {
+            if (!matched)
+                locations.push({ filepath, scopeId });
+        }
+        if (locations.length === 0)
+            return pass();
+        return violationMessage === undefined
+            ? { status: 'violation', locations }
+            : violation(violationMessage, locations);
+    };
+}

package/dist/app/execute.d.ts

@@ -0,0 +1,2 @@
+import type { LoadedRule, RuleReport, RunContext } from './ports.js';
+export declare function executeRules(rules: readonly LoadedRule[], context: RunContext): Promise<readonly RuleReport[]>;

package/dist/app/execute.js

@@ -0,0 +1,427 @@
+import { matchesGlob } from 'node:path';
+import { mapConcurrent } from './concurrency.js';
+import { evaluateAi } from './evaluators.js';
+import { wholeFileScope } from './selection.js';
+import { addUsage } from './usage.js';
+import { validateCheckResult, validatePredicateResult, validateScopeMatch, validateScopeSubjects, } from './validate.js';
+function isEligibleRelativePath(filepath) {
+    if (filepath === '' || filepath.startsWith('/'))
+        return false;
+    const segments = filepath.split('/');
+    const last = segments.length - 1;
+    for (let index = 0; index < last; index += 1) {
+        const segment = segments[index];
+        if (segment === '' || segment === '.' || segment === '..')
+            return false;
+    }
+    const name = segments[last];
+    return name !== undefined && name !== '' && name !== '.' && name !== '..';
+}
+function folderPath(filepath, level) {
+    const segments = filepath.split('/');
+    segments.pop();
+    const keep = segments.length + level;
+    if (keep <= 0)
+        return '.';
+    return segments.slice(0, keep).join('/');
+}
+export async function executeRules(rules, context) {
+    let completedSelections = 0;
+    let completedEvaluations = 0;
+    const emit = (event) => {
+        context.emit?.(event);
+    };
+    const changedFiles = context.changedFiles;
+    const changedPaths = changedFiles === undefined
+        ? undefined
+        : [...changedFiles].filter(filepath => isEligibleRelativePath(filepath) && context.isTarget(filepath));
+    const traceFor = (name, evaluationId) => (message, details) => {
+        emit({
+            type: 'trace',
+            name,
+            message,
+            ...(evaluationId === undefined ? {} : { evaluationId }),
+            ...(details === undefined ? {} : { details }),
+        });
+    };
+    const projectContextFor = (name) => ({
+        project: context.project,
+        trace: traceFor(name),
+    });
+    const fail = (name, stage, error, evaluationId) => {
+        const message = error instanceof Error ? error.message : String(error);
+        emit({
+            type: 'error',
+            stage,
+            message,
+            ...(name === undefined ? {} : { name }),
+            ...(evaluationId === undefined ? {} : { evaluationId }),
+        });
+        return error instanceof Error ? error : new Error(message);
+    };
+    const statCache = new Map();
+    const assertEligible = async (name, subjects) => {
+        for (const subject of subjects) {
+            const { filepath } = subject;
+            if (!isEligibleRelativePath(filepath)) {
+                throw new Error(`Rule "${name}" selected an ineligible filepath "${filepath}"`);
+            }
+            if (!context.isTarget(filepath)) {
+                throw new Error(`Rule "${name}" selected "${filepath}" outside the CLI target`);
+            }
+            let pending = statCache.get(filepath);
+            if (pending === undefined) {
+                pending = context.project.stat(filepath);
+                statCache.set(filepath, pending);
+            }
+            const info = await pending;
+            if (info?.kind !== 'file') {
+                throw new Error(`Rule "${name}" selected a path that is not a regular file: "${filepath}"`);
+            }
+        }
+    };
+    const selectFromRule = async (name, selection, evaluationId, changedOnly = false) => {
+        const exclude = selection.exclude ?? [];
+        const candidates = await context.project.glob(selection.files);
+        const chosen = [];
+        for (const filepath of candidates) {
+            const excluded = exclude.some(pattern => matchesGlob(filepath, pattern));
+            const targeted = context.isTarget(filepath);
+            const changed = !changedOnly || changedFiles === undefined || changedFiles.has(filepath);
+            const selected = !excluded && targeted && changed;
+            const reason = excluded ? 'excluded' : !targeted ? 'outside target' : changed ? undefined : 'unchanged';
+            emit({
+                type: 'file',
+                name,
+                filepath,
+                selected,
+                ...(evaluationId === undefined ? {} : { evaluationId }),
+                ...(reason === undefined ? {} : { reason }),
+            });
+            if (selected)
+                chosen.push(filepath);
+        }
+        const scope = selection.scope;
+        const collected = await mapConcurrent(chosen, context.concurrency, async (filepath) => {
+            const source = await context.project.readText(filepath);
+            const matches = scope === undefined
+                ? wholeFileScope({ filepath, source })
+                : (await scope({ filepath, source }));
+            if (!Array.isArray(matches)) {
+                throw new Error(`Rule "${name}" scope selector must return an array of scopes`);
+            }
+            const subjects = [];
+            for (let index = 0; index < matches.length; index += 1) {
+                const label = `Rule "${name}" scope ${filepath}[${index}]`;
+                if (!Object.hasOwn(matches, index))
+                    throw new Error(`${label}: missing scope entry`);
+                const valid = validateScopeMatch(matches[index], label);
+                subjects.push({ kind: 'scope', filepath, ...valid });
+            }
+            return subjects;
+        });
+        return collected.flat();
+    };
+    const selectionContextFor = (name, changedOnly) => ({
+        project: context.project,
+        trace: traceFor(name),
+        select: selection => selectFromRule(name, selection, undefined, changedOnly),
+    });
+    const runtimeOf = (plan) => {
+        let runtime = plan.runtime;
+        if (runtime === undefined) {
+            runtime = context.resolveDecision(plan.rule.settings);
+            plan.runtime = runtime;
+        }
+        return runtime;
+    };
+    const evaluateSubject = async (plan, subject, evaluationId, reportFailure) => {
+        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;
+        const retainAccountingFailure = (error) => {
+            if (accountingFailure !== undefined)
+                return;
+            const failure = error instanceof Error ? error : new Error(String(error));
+            accountingFailure = { error: failure };
+            reportFailure(failure);
+        };
+        const throwIfAccountingFailed = () => {
+            if (accountingFailure !== undefined)
+                throw accountingFailure.error;
+        };
+        const observer = exchange => {
+            if (exchange.type === 'request') {
+                emit({ type: 'request', evaluationId, name, subject, body: exchange.body });
+            }
+            else if (exchange.type === 'response') {
+                emit({ type: 'response', evaluationId, name, subject, status: exchange.status, body: exchange.body });
+            }
+            else {
+                const next = exchange.usage;
+                try {
+                    trackedUsage = addUsage(trackedUsage, next);
+                }
+                catch (error) {
+                    retainAccountingFailure(error);
+                }
+                // Individual usage remains valid even when its aggregate cannot be represented.
+                try {
+                    emit({ type: 'usage', evaluationId, name, subject, usage: next });
+                }
+                catch (error) {
+                    retainAccountingFailure(error);
+                }
+                throwIfAccountingFailed();
+            }
+        };
+        const checkContext = {
+            project: context.project,
+            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 pending = pendingAi ??= new Set();
+                pending.add(call);
+                // Observe both outcomes immediately; the check still receives the original promise.
+                void call.then(() => { pending.delete(call); }, () => { pending.delete(call); });
+                return call;
+            },
+        };
+        let result;
+        try {
+            try {
+                const raw = await rule.check.call(rule, subject, checkContext);
+                throwIfAccountingFailed();
+                const valid = validateCheckResult(raw, `Rule "${name}" check result`, subject);
+                const { status, message, model, probability, threshold, usage, locations } = valid;
+                // Snapshot declared fields before draining: custom checks still own their returned objects.
+                // Validate the snapshot too, since accessors may change values between reads.
+                result = validateCheckResult({
+                    status,
+                    ...(message === undefined ? {} : { message }),
+                    ...(probability === undefined ? {} : { probability }),
+                    ...(threshold === undefined ? {} : { threshold }),
+                    ...(model === undefined ? {} : { model }),
+                    ...(locations === undefined ? {} : { locations }),
+                    ...(usage === undefined ? {} : { usage: {
+                            calls: usage.calls,
+                            unreportedCalls: usage.unreportedCalls,
+                            inputTokens: usage.inputTokens,
+                            outputTokens: usage.outputTokens,
+                            inputCost: usage.inputCost,
+                            outputCost: usage.outputCost,
+                        } }),
+                }, `Rule "${name}" check result`);
+            }
+            catch (error) {
+                const cause = accountingFailure === undefined ? error : accountingFailure.error;
+                const failure = cause instanceof Error ? cause : new Error(String(cause));
+                reportFailure(failure);
+                throw failure;
+            }
+            finally {
+                // Promise.all may reject while sibling calls are still producing usage events.
+                while (pendingAi !== undefined && pendingAi.size > 0) {
+                    await Promise.allSettled(pendingAi);
+                }
+            }
+            // A custom check may catch context.ai failures, but cannot discard accounting failures.
+            throwIfAccountingFailed();
+        }
+        catch (error) {
+            throw fail(name, 'check', error, evaluationId);
+        }
+        const normalized = trackedUsage === undefined ? result : { ...result, usage: trackedUsage };
+        emit({ type: 'result', evaluationId, name, subject, result: normalized });
+        context.emit?.({
+            type: 'progress', phase: 'evaluation', completed: ++completedEvaluations, total: tasks.length,
+        });
+        plan.evaluationFinishedAt = performance.now();
+        return normalized;
+    };
+    const plans = [];
+    context.emit?.({ type: 'progress', phase: 'selection', completed: 0, total: rules.length });
+    for (const entry of rules) {
+        const selectionStartedAt = performance.now();
+        const rule = entry.rule;
+        const { name, ruleFile } = entry;
+        emit({ type: 'rule', name, ruleFile });
+        const plan = {
+            name,
+            ruleFile,
+            rule,
+            subjects: [],
+            evaluationSubjects: [],
+            evaluations: [],
+            skipped: undefined,
+            runtime: undefined,
+            durationMs: 0,
+            evaluationStartedAt: undefined,
+            evaluationFinishedAt: 0,
+        };
+        plans.push(plan);
+        if (!rule.enabled) {
+            emit({ type: 'gate', name, enabled: false, applies: false, reason: 'disabled' });
+            plan.skipped = 'disabled';
+            context.emit?.({
+                type: 'progress', phase: 'selection', completed: ++completedSelections, total: rules.length,
+            });
+            plan.durationMs = performance.now() - selectionStartedAt;
+            continue;
+        }
+        let gate;
+        try {
+            gate = validatePredicateResult(await rule.when.call(rule, projectContextFor(name)), `Rule "${name}" when`);
+        }
+        catch (error) {
+            throw fail(name, 'when', error);
+        }
+        const applies = typeof gate === 'boolean' ? gate : gate.applies;
+        const gateReason = typeof gate === 'boolean' ? undefined : gate.reason;
+        if (!applies) {
+            emit({
+                type: 'gate',
+                name,
+                enabled: true,
+                applies: false,
+                ...(gateReason === undefined ? {} : { reason: gateReason }),
+            });
+            plan.skipped = gateReason ?? 'when returned false';
+            context.emit?.({
+                type: 'progress', phase: 'selection', completed: ++completedSelections, total: rules.length,
+            });
+            plan.durationMs = performance.now() - selectionStartedAt;
+            continue;
+        }
+        emit({
+            type: 'gate',
+            name,
+            enabled: true,
+            applies: true,
+            ...(gateReason === undefined ? {} : { reason: gateReason }),
+        });
+        const changedOnly = rule.group === 'scope' || rule.group === 'file';
+        let selected;
+        try {
+            const raw = await rule.select.call(rule, selectionContextFor(name, changedOnly));
+            const subjects = validateScopeSubjects(raw, `Rule "${name}" selection`);
+            selected = changedOnly && changedFiles !== undefined
+                ? subjects.filter(subject => changedFiles.has(subject.filepath))
+                : subjects;
+            await assertEligible(name, selected);
+        }
+        catch (error) {
+            throw fail(name, 'select', error);
+        }
+        const kept = [];
+        try {
+            for (const subject of selected) {
+                const predicate = validatePredicateResult(await rule.filter.call(rule, subject, projectContextFor(name)), `Rule "${name}" filter`);
+                const accepted = typeof predicate === 'boolean' ? predicate : predicate.applies;
+                const reason = typeof predicate === 'boolean' ? undefined : predicate.reason;
+                emit(reason === undefined
+                    ? { type: 'scope', name, subject, accepted }
+                    : { type: 'scope', name, subject, accepted, reason });
+                if (accepted)
+                    kept.push(subject);
+            }
+        }
+        catch (error) {
+            throw fail(name, 'filter', error);
+        }
+        plan.subjects = kept;
+        if (kept.length === 0)
+            plan.skipped = 'no matching subjects';
+        context.emit?.({
+            type: 'progress', phase: 'selection', completed: ++completedSelections, total: rules.length,
+        });
+        plan.durationMs = performance.now() - selectionStartedAt;
+    }
+    for (const plan of plans) {
+        if (plan.skipped !== undefined)
+            continue;
+        const groupingStartedAt = performance.now();
+        const grouping = plan.rule.group;
+        try {
+            const subjects = groupSubjects(plan.subjects, grouping);
+            plan.evaluationSubjects = changedPaths === undefined || grouping === 'scope' || grouping === 'file'
+                ? subjects
+                : subjects.filter(subject => subject.kind === 'group' && changedPaths.some(filepath => subject.group.path === '.' || filepath.startsWith(`${subject.group.path}/`)));
+            for (const subject of plan.evaluationSubjects) {
+                if (subject.kind === 'group')
+                    emit({ type: 'group', name: plan.name, subject });
+            }
+            if (plan.evaluationSubjects.length === 0)
+                plan.skipped = 'no changed subjects';
+        }
+        catch (error) {
+            throw fail(plan.name, 'group', error);
+        }
+        plan.durationMs += performance.now() - groupingStartedAt;
+    }
+    const tasks = [];
+    for (const plan of plans) {
+        for (const subject of plan.evaluationSubjects) {
+            tasks.push({ plan, subject, evaluationId: tasks.length + 1 });
+        }
+    }
+    context.emit?.({ type: 'progress', phase: 'evaluation', completed: 0, total: tasks.length });
+    const results = await mapConcurrent(tasks, context.concurrency, (task, _index, reportFailure) => evaluateSubject(task.plan, task.subject, task.evaluationId, reportFailure));
+    for (let index = 0; index < tasks.length; index += 1) {
+        const task = tasks[index];
+        task.plan.evaluations.push({ subject: task.subject, result: results[index] });
+    }
+    return plans.map(plan => {
+        const durationMs = plan.durationMs + (plan.evaluationStartedAt === undefined
+            ? 0
+            : plan.evaluationFinishedAt - plan.evaluationStartedAt);
+        if (plan.skipped !== undefined) {
+            return {
+                name: plan.name,
+                ruleFile: plan.ruleFile,
+                status: 'skipped',
+                durationMs,
+                reason: plan.skipped,
+                evaluations: [],
+            };
+        }
+        const status = plan.evaluations.some(evaluation => evaluation.result.status === 'violation')
+            ? 'violation'
+            : 'pass';
+        return { name: plan.name, ruleFile: plan.ruleFile, status, durationMs, evaluations: plan.evaluations };
+    });
+}
+function groupSubjects(subjects, grouping) {
+    if (grouping === 'scope')
+        return [...subjects];
+    const descriptors = [];
+    const buckets = new Map();
+    for (const subject of subjects) {
+        const descriptor = grouping === 'file'
+            ? { type: 'file', path: subject.filepath }
+            : grouping === 'project'
+                ? { type: 'project', path: '.' }
+                : {
+                    type: 'folder',
+                    path: folderPath(subject.filepath, grouping === 'folder' ? 0 : grouping.level),
+                };
+        const key = `${descriptor.type}\u0000${descriptor.path}`;
+        let bucket = buckets.get(key);
+        if (bucket === undefined) {
+            bucket = [];
+            buckets.set(key, bucket);
+            descriptors.push(descriptor);
+        }
+        bucket.push(subject);
+    }
+    return descriptors.map(descriptor => {
+        const members = buckets.get(`${descriptor.type}\u0000${descriptor.path}`);
+        return { kind: 'group', group: descriptor, members };
+    });
+}

package/dist/app/jsonpath.d.ts

@@ -0,0 +1 @@
+export declare function assertNonExecutable(selector: string, where: string): void;

package/dist/app/jsonpath.js

@@ -0,0 +1,8 @@
+import { JSONPath } from 'jsonpath-plus';
+export function assertNonExecutable(selector, where) {
+    for (const token of JSONPath.toPathArray(selector)) {
+        if (token.startsWith('?(') || token.startsWith('(')) {
+            throw new Error(`The ${where} must not contain executable JSONPath expressions`);
+        }
+    }
+}