@alex-dbs/coderuler 0.0.0-stage → 1.3.0

package/dist/app/ports.d.ts

@@ -0,0 +1,165 @@
+import type { AiUsage, CheckResult, GroupSubject, JsonValue, Rule, RuleSettings, ScopeSubject, Subject, TokenPricing, TokenUsage } from './rule.js';
+export interface Project {
+    readonly root: string;
+    glob(patterns: string | readonly string[]): Promise<readonly string[]>;
+    hasFiles(patterns: string | readonly string[]): Promise<boolean>;
+    stat(path: string): Promise<{
+        readonly kind: 'file' | 'directory';
+    } | undefined>;
+    readText(path: string): Promise<string>;
+    readJson(path: string): Promise<JsonValue>;
+    readYaml(path: string): Promise<readonly JsonValue[]>;
+    readCsv(path: string, options?: CsvOptions): Promise<readonly CsvRow[]>;
+}
+export interface CsvOptions {
+    readonly headers?: boolean;
+    readonly delimiter?: string;
+    readonly key?: string;
+}
+export type CsvRow = Readonly<Record<string, string>> | readonly string[];
+export interface RuleSelection {
+    readonly root: string;
+    readonly explicit?: string;
+    readonly name?: string;
+    readonly invocationCwd: string;
+}
+export interface LoadedRule {
+    readonly name: string;
+    readonly ruleFile: string;
+    readonly rule: Rule<unknown>;
+}
+export interface RuleLoader {
+    load(selection: RuleSelection): Promise<readonly LoadedRule[]>;
+}
+export interface DecisionInstructions {
+    readonly rule: string;
+    readonly question: string;
+    readonly examples?: {
+        readonly good: readonly string[];
+        readonly bad: readonly string[];
+    };
+}
+export interface DecisionRequest {
+    readonly state: JsonValue;
+    readonly instructions: DecisionInstructions;
+}
+export interface DecisionOutcome {
+    readonly probability: number;
+    readonly model: string;
+    readonly usage?: TokenUsage;
+}
+export type DecisionExchange = {
+    readonly type: 'request';
+    readonly body: string;
+} | {
+    readonly type: 'response';
+    readonly status: number;
+    readonly body: string;
+} | {
+    readonly type: 'usage';
+    readonly usage: AiUsage;
+};
+export type DecisionObserver = (exchange: DecisionExchange) => void;
+export interface DecisionBackend {
+    decide(request: DecisionRequest, observer?: DecisionObserver): Promise<DecisionOutcome>;
+}
+export interface DecisionRuntime {
+    readonly backend: DecisionBackend;
+    readonly threshold: number;
+    readonly pricing: TokenPricing;
+}
+export interface RunContext {
+    readonly project: Project;
+    readonly isTarget: (filepath: string) => boolean;
+    readonly changedFiles?: ReadonlySet<string>;
+    readonly concurrency: number;
+    readonly resolveDecision: (settings: RuleSettings) => DecisionRuntime;
+    readonly emit?: (event: RunEvent) => void;
+}
+export interface RuleEvaluation {
+    readonly subject: Subject;
+    readonly result: CheckResult;
+}
+export interface RuleReport {
+    readonly name: string;
+    readonly ruleFile: string;
+    readonly status: 'pass' | 'violation' | 'skipped';
+    readonly durationMs: number;
+    readonly reason?: string;
+    readonly evaluations: readonly RuleEvaluation[];
+}
+export type RunEvent = {
+    readonly type: 'progress';
+    readonly phase: 'selection' | 'evaluation';
+    readonly completed: number;
+    readonly total: number;
+} | {
+    readonly type: 'rule';
+    readonly name: string;
+    readonly ruleFile: string;
+} | {
+    readonly type: 'gate';
+    readonly name: string;
+    readonly enabled: boolean;
+    readonly applies: boolean;
+    readonly reason?: string;
+} | {
+    readonly type: 'file';
+    readonly evaluationId?: number;
+    readonly name: string;
+    readonly filepath: string;
+    readonly selected: boolean;
+    readonly reason?: string;
+} | {
+    readonly type: 'scope';
+    readonly name: string;
+    readonly subject: ScopeSubject;
+    readonly accepted: boolean;
+    readonly reason?: string;
+} | {
+    readonly type: 'group';
+    readonly name: string;
+    readonly subject: GroupSubject;
+} | {
+    readonly type: 'evaluation';
+    readonly evaluationId: number;
+    readonly name: string;
+    readonly subject: Subject;
+} | {
+    readonly type: 'request';
+    readonly evaluationId: number;
+    readonly name: string;
+    readonly subject: Subject;
+    readonly body: string;
+} | {
+    readonly type: 'response';
+    readonly evaluationId: number;
+    readonly name: string;
+    readonly subject: Subject;
+    readonly status: number;
+    readonly body: string;
+} | {
+    readonly type: 'usage';
+    readonly evaluationId: number;
+    readonly name: string;
+    readonly subject: Subject;
+    readonly usage: AiUsage;
+} | {
+    readonly type: 'result';
+    readonly evaluationId: number;
+    readonly name: string;
+    readonly subject: Subject;
+    readonly result: CheckResult;
+} | {
+    readonly type: 'trace';
+    readonly evaluationId?: number;
+    readonly name: string;
+    readonly message: string;
+    readonly details?: JsonValue;
+} | {
+    readonly type: 'error';
+    readonly evaluationId?: number;
+    readonly name?: string;
+    readonly stage: string;
+    readonly message: string;
+};

package/dist/app/ports.js

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

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

@@ -0,0 +1,20 @@
+import type { JsonValue } from './rule.js';
+export interface RuleTestCase {
+    readonly name: string;
+    readonly files: Readonly<Record<string, JsonValue>>;
+    readonly expected: 'pass' | 'violation' | 'skipped';
+}
+export interface RuleTestResult {
+    readonly ruleName: string;
+    readonly name: string;
+    readonly expected: RuleTestCase['expected'];
+    readonly actual: RuleTestCase['expected'] | 'timeout';
+    readonly durationMs: number;
+}
+export declare function test(name: string): {
+    withFiles(files: RuleTestCase['files']): {
+        passes: () => RuleTestCase;
+        violates: () => RuleTestCase;
+        skips: () => RuleTestCase;
+    };
+};

package/dist/app/rule-tests.js

@@ -0,0 +1,11 @@
+export function test(name) {
+    return {
+        withFiles(files) {
+            return {
+                passes: () => ({ name, files, expected: 'pass' }),
+                violates: () => ({ name, files, expected: 'violation' }),
+                skips: () => ({ name, files, expected: 'skipped' }),
+            };
+        },
+    };
+}

package/dist/app/rule.d.ts

@@ -0,0 +1,121 @@
+import type { Project } from './ports.js';
+export type Awaitable<T> = T | Promise<T>;
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type PredicateResult = boolean | {
+    readonly applies: boolean;
+    readonly reason?: string;
+};
+export interface SourceFile {
+    readonly filepath: string;
+    readonly source: string;
+}
+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;
+    };
+}
+export interface ScopeSubject<T = JsonValue> extends ScopeMatch<T> {
+    readonly kind: 'scope';
+    readonly filepath: string;
+}
+export interface GroupSubject<T = JsonValue> {
+    readonly kind: 'group';
+    readonly group: {
+        readonly type: 'file' | 'folder' | 'project';
+        readonly path: string;
+    };
+    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 Grouping = 'scope' | 'file' | 'folder' | 'project' | {
+    readonly by: 'folder';
+    readonly level: number;
+};
+export interface RuleSettings {
+    readonly backend?: 'jev';
+    readonly model?: string;
+    readonly threshold?: number;
+    readonly inputCostPerMillion?: number;
+    readonly outputCostPerMillion?: number;
+}
+export interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+export interface TokenPricing {
+    readonly inputCostPerMillion: number;
+    readonly outputCostPerMillion: number;
+}
+export interface AiUsage extends TokenUsage {
+    readonly calls: number;
+    readonly unreportedCalls: number;
+    readonly inputCost: number;
+    readonly outputCost: number;
+}
+export interface ViolationLocation {
+    readonly filepath: string;
+    readonly scopeId?: string;
+    readonly lines?: {
+        readonly start: number;
+        readonly end: number;
+    };
+}
+export interface CheckResult {
+    readonly status: 'pass' | 'violation';
+    readonly message?: string;
+    readonly locations?: readonly ViolationLocation[];
+    readonly probability?: number;
+    readonly threshold?: number;
+    readonly model?: string;
+    readonly usage?: AiUsage;
+}
+export interface AiExamples {
+    readonly good?: readonly string[];
+    readonly bad?: readonly string[];
+}
+export interface AiOptions<T = JsonValue> {
+    readonly rule: string;
+    readonly examples?: AiExamples;
+    readonly violationMessage?: string;
+    readonly input?: (subject: Subject<T>, context: ProjectContext) => Awaitable<JsonValue>;
+}
+export type Evaluator<T = JsonValue> = (subject: Subject<T>, context: CheckContext<T>) => Awaitable<CheckResult>;
+export interface ProjectContext {
+    readonly project: Project;
+    trace(message: string, details?: JsonValue): void;
+}
+export interface Selection<T = JsonValue> {
+    readonly files: readonly string[];
+    readonly exclude?: readonly string[];
+    readonly scope?: ScopeSelector<T>;
+}
+export interface SelectionContext extends ProjectContext {
+    select<T>(selection: Selection<T>): Promise<readonly ScopeSubject<T>[]>;
+}
+export interface CheckContext<T = JsonValue> extends SelectionContext {
+    readonly ruleName: string;
+    ai(options: AiOptions<T>): Promise<CheckResult>;
+}
+export declare const RULE_BRAND: symbol;
+export declare abstract class Rule<T = JsonValue> {
+    enabled: boolean;
+    files: readonly string[];
+    exclude: readonly string[];
+    tags?: readonly string[];
+    scope?: ScopeSelector<T>;
+    settings: RuleSettings;
+    group: Grouping;
+    comment?: string;
+    when(_context: ProjectContext): Awaitable<PredicateResult>;
+    filter(_subject: ScopeSubject<T>, _context: ProjectContext): Awaitable<PredicateResult>;
+    select(context: SelectionContext): Awaitable<readonly ScopeSubject<T>[]>;
+    abstract check: Evaluator<T>;
+}

package/dist/app/rule.js

@@ -0,0 +1,24 @@
+export const RULE_BRAND = Symbol.for('coderuler.Rule');
+export class Rule {
+    enabled = true;
+    files = ['**/*'];
+    exclude = [];
+    tags;
+    scope;
+    settings = {};
+    group = 'scope';
+    comment;
+    when(_context) {
+        return true;
+    }
+    filter(_subject, _context) {
+        return true;
+    }
+    select(context) {
+        const { files, exclude, scope } = this;
+        return scope === undefined
+            ? context.select({ files, exclude })
+            : context.select({ files, exclude, scope });
+    }
+}
+Object.defineProperty(Rule.prototype, RULE_BRAND, { value: true, enumerable: false });

package/dist/app/selection.d.ts

@@ -0,0 +1,2 @@
+import type { ScopeMatch, SourceFile } from './rule.js';
+export declare function wholeFileScope(file: SourceFile): readonly ScopeMatch<never>[];

package/dist/app/selection.js

@@ -0,0 +1,23 @@
+function lineCount(source) {
+    let count = 1;
+    let index = 0;
+    while (index < source.length) {
+        const code = source.charCodeAt(index);
+        if (code === 10) {
+            count += 1;
+        }
+        else if (code === 13) {
+            count += 1;
+            if (source.charCodeAt(index + 1) === 10)
+                index += 1;
+        }
+        index += 1;
+    }
+    const last = source.charCodeAt(source.length - 1);
+    if (source.length > 0 && (last === 10 || last === 13))
+        count -= 1;
+    return count;
+}
+export function wholeFileScope(file) {
+    return [{ id: '$', source: file.source, lines: { start: 1, end: lineCount(file.source) } }];
+}

package/dist/app/usage.d.ts

@@ -0,0 +1,2 @@
+import type { AiUsage } from './rule.js';
+export declare function addUsage(current: AiUsage | undefined, usage: AiUsage): AiUsage;

package/dist/app/usage.js

@@ -0,0 +1,13 @@
+import { validateAiUsage } from './validate.js';
+export function addUsage(current, usage) {
+    if (current === undefined)
+        return { ...usage };
+    return validateAiUsage({
+        calls: current.calls + usage.calls,
+        unreportedCalls: current.unreportedCalls + usage.unreportedCalls,
+        inputTokens: current.inputTokens + usage.inputTokens,
+        outputTokens: current.outputTokens + usage.outputTokens,
+        inputCost: current.inputCost + usage.inputCost,
+        outputCost: current.outputCost + usage.outputCost,
+    }, 'Accumulated AI usage');
+}

package/dist/app/validate.d.ts

@@ -0,0 +1,11 @@
+import type { AiUsage, CheckResult, JsonValue, PredicateResult, Rule, ScopeMatch, ScopeSubject, Subject } from './rule.js';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isRuleBranded(value: unknown): boolean;
+export declare function validateRule(value: unknown, ruleFile: string): Rule<unknown>;
+export declare function validateJsonValue(value: unknown, label: string): JsonValue;
+export declare function validateScopeMatch(value: unknown, label: string): ScopeMatch<JsonValue>;
+export declare function validateScopeSubject(value: unknown, label: string): ScopeSubject<JsonValue>;
+export declare function validateScopeSubjects(value: unknown, label: string): readonly ScopeSubject<JsonValue>[];
+export declare function validatePredicateResult(value: unknown, label: string): PredicateResult;
+export declare function validateAiUsage(value: unknown, label: string): AiUsage;
+export declare function validateCheckResult(value: unknown, label: string, subject?: Subject<unknown>): CheckResult;