@alex-dbs/coderuler 0.0.0-stage → 1.3.1

package/dist/adapter/scope/protobuf.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue, ScopeSelector } from '../../app/rule.js';
+export interface ProtobufScopeOptions {
+    readonly path?: string;
+}
+export declare function protobuf<T = JsonValue>(options?: ProtobufScopeOptions): ScopeSelector<T>;

package/dist/adapter/scope/protobuf.js

@@ -0,0 +1,53 @@
+import { SourceLines } from './lines.js';
+import { DECLARATION_LISTS, readProtoFile } from './protobuf-parser.js';
+import { pointerSegments, query, validatePath } from './structured.js';
+const DEFAULT_PATH = '$.rpcs[*]';
+function resolvePath(options) {
+    const path = options?.path === undefined ? DEFAULT_PATH : options.path;
+    validatePath(path, 'protobuf scope option path');
+    return path;
+}
+function isDeclarationList(value) {
+    return DECLARATION_LISTS.includes(value);
+}
+function scopeId(document, pointer) {
+    if (pointer === '')
+        return '$';
+    const segments = pointerSegments(pointer);
+    const list = segments[0];
+    if (list === undefined || !isDeclarationList(list))
+        return pointer;
+    const index = Number(segments[1]);
+    const declaration = Number.isInteger(index) ? document[list][index] : undefined;
+    if (declaration === undefined)
+        return pointer;
+    const declarationPointer = `/${segments[0]}/${segments[1]}`;
+    return segments.length === 2 ? declaration.id : `${declaration.id}:${pointer.slice(declarationPointer.length)}`;
+}
+function spanAt(spans, pointer) {
+    let candidate = pointer;
+    while (true) {
+        const span = spans.get(candidate);
+        if (span !== undefined)
+            return span;
+        const slash = candidate.lastIndexOf('/');
+        candidate = slash <= 0 ? '' : candidate.slice(0, slash);
+    }
+}
+export function protobuf(options) {
+    const path = resolvePath(options);
+    return (file) => {
+        const parsed = readProtoFile(file.source);
+        const matches = query(parsed.data, path);
+        const lines = new SourceLines(file.source);
+        return matches.map(({ pointer, value }) => {
+            const span = spanAt(parsed.spans, pointer);
+            return {
+                id: scopeId(parsed.data, pointer),
+                source: file.source.slice(span.start, span.end),
+                data: value,
+                lines: lines.span(span.start, span.end),
+            };
+        });
+    };
+}

package/dist/adapter/scope/structured.d.ts

@@ -0,0 +1,10 @@
+import type { JsonValue } from '../../app/rule.js';
+export interface QueryMatch {
+    readonly pointer: string;
+    readonly value: JsonValue;
+}
+export declare function validatePath(path: string, label: string): void;
+export declare function query(data: JsonValue, path: string): readonly QueryMatch[];
+export declare function pointerSegment(key: string): string;
+export declare function pointerSegments(pointer: string): readonly string[];
+export declare function keyOf(data: JsonValue, path: string): string;

package/dist/adapter/scope/structured.js

@@ -0,0 +1,84 @@
+import { JSONPath, JSONPathClass } from 'jsonpath-plus';
+import { assertNonExecutable } from '../../app/jsonpath.js';
+class SourcePointerJSONPath extends JSONPathClass {
+    _getPreferredOutput(match) {
+        const pointer = Array.isArray(match.path) && match.parentProperty !== null ? pointerOf(match.path) : undefined;
+        super._getPreferredOutput(match);
+        if (pointer !== undefined)
+            match.pointer = pointer;
+        return match;
+    }
+}
+const PATH_PROBE = { a: { b: { c: 0 } }, items: [{ b: 0 }], list: [0] };
+export function validatePath(path, label) {
+    if (typeof path !== 'string' || path === '') {
+        throw new Error(`The ${label} must be a non-empty string`);
+    }
+    if (!path.startsWith('$'))
+        throw new Error(`The ${label} must start with "$"`);
+    assertNonExecutable(path, label);
+    try {
+        JSONPath({ path, json: PATH_PROBE, eval: false });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`The ${label} "${path}" could not be evaluated: ${reason}`);
+    }
+}
+export function query(data, path) {
+    if (path.trim() === '$')
+        return [{ pointer: '', value: data }];
+    let found;
+    try {
+        const engine = new SourcePointerJSONPath({ autostart: false, resultType: 'all', eval: false });
+        found = engine.evaluate({ path, json: data, wrap: true });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`The scope path "${path}" could not be evaluated: ${reason}`);
+    }
+    if (!Array.isArray(found))
+        return [];
+    return found.map((entry) => {
+        const { value, pointer } = entry;
+        if (typeof pointer !== 'string') {
+            throw new Error(`The scope path "${path}" produced a match without a JSON pointer`);
+        }
+        return { pointer, value: value };
+    });
+}
+export function pointerSegment(key) {
+    return key.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function pointerOf(path) {
+    let pointer = '';
+    for (let index = 1; index < path.length; index += 1) {
+        pointer += `/${pointerSegment(String(path[index]))}`;
+    }
+    return pointer;
+}
+export function pointerSegments(pointer) {
+    if (pointer === '')
+        return [];
+    if (!pointer.startsWith('/'))
+        throw new Error(`Unexpected JSON pointer "${pointer}"`);
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'));
+}
+export function keyOf(data, path) {
+    let value = data;
+    if (path.trim() !== '$') {
+        const matches = query(data, path);
+        if (matches.length !== 1) {
+            throw new Error('The scope "key" selector must match exactly one value');
+        }
+        value = matches[0]?.value;
+    }
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    throw new Error('The scope "key" selector must resolve to a string or finite number');
+}

package/dist/adapter/scope/yaml.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue, ScopeSelector } from '../../app/rule.js';
+export interface YamlScopeOptions {
+    readonly path?: string;
+    readonly key?: string;
+}
+export declare function parseYaml(source: string): readonly JsonValue[];
+export declare function yaml<T = JsonValue>(options?: YamlScopeOptions): ScopeSelector<T>;

package/dist/adapter/scope/yaml.js

@@ -0,0 +1,224 @@
+import { isAlias, isMap, isNode, isScalar, isSeq, parseAllDocuments, } from 'yaml';
+import { SourceLines } from './lines.js';
+import { keyOf, pointerSegments, query, validatePath } from './structured.js';
+const MAX_ALIAS_COUNT = 100;
+function withGuard(node, active, work) {
+    if (active.has(node))
+        throw new Error('Recursive YAML aliases or merges are not supported');
+    active.add(node);
+    try {
+        return work();
+    }
+    finally {
+        active.delete(node);
+    }
+}
+function resolveAlias(node, document) {
+    if (!isAlias(node))
+        return node;
+    const target = node.resolve(document);
+    if (target === undefined)
+        throw new Error(`YAML alias "*${node.source}" has no matching anchor`);
+    return target;
+}
+function keyString(key) {
+    if (!isScalar(key))
+        throw new Error('A YAML scope requires scalar mapping keys');
+    const value = key.value;
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return String(value);
+    throw new Error('A YAML mapping key must be a string, number, boolean or null');
+}
+function mergeSources(value, document) {
+    const resolved = resolveAlias(value, document);
+    if (isSeq(resolved)) {
+        return resolved.items.map(item => {
+            const source = resolveAlias(item, document);
+            if (!isMap(source))
+                throw new Error('YAML merge sequence entries must be mappings');
+            return source;
+        });
+    }
+    if (!isMap(resolved))
+        throw new Error('A YAML merge value must be a mapping or a sequence of mappings');
+    return [resolved];
+}
+function effectiveEntries(map, document, active, resolved) {
+    const cached = resolved.get(map);
+    if (cached !== undefined)
+        return cached;
+    const entries = withGuard(map, active, () => {
+        const explicit = new Map();
+        const order = [];
+        const merges = [];
+        for (const pair of map.items) {
+            if (isScalar(pair.key) && typeof pair.key.value === 'symbol' && String(pair.key.value) === 'Symbol(<<)') {
+                merges.push(pair.value);
+                continue;
+            }
+            const key = pair.key === null || pair.key === undefined ? '' : keyString(pair.key);
+            if (!explicit.has(key))
+                order.push(key);
+            explicit.set(key, pair.value);
+        }
+        const resolvedEntries = order.map(key => ({ key, value: explicit.get(key) ?? null }));
+        const present = new Set(order);
+        for (const merge of merges) {
+            for (const source of mergeSources(merge, document)) {
+                for (const entry of effectiveEntries(source, document, active, resolved)) {
+                    if (present.has(entry.key))
+                        continue;
+                    present.add(entry.key);
+                    resolvedEntries.push(entry);
+                }
+            }
+        }
+        return resolvedEntries;
+    });
+    resolved.set(map, entries);
+    return entries;
+}
+function assertJsonValue(value, visiting, seen) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('YAML scope data must stay JSON-compatible: non-finite number');
+        return;
+    }
+    if (typeof value !== 'object')
+        throw new Error('YAML scope data must stay JSON-compatible: unsupported value');
+    if (seen.has(value))
+        return;
+    if (visiting.has(value))
+        throw new Error('YAML scope data must stay JSON-compatible: cyclic value');
+    visiting.add(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertJsonValue(item, visiting, seen);
+    }
+    else if (prototype === Object.prototype || prototype === null) {
+        for (const key of Object.keys(value)) {
+            assertJsonValue(value[key], visiting, seen);
+        }
+    }
+    else {
+        throw new Error('YAML scope data must stay JSON-compatible: unsupported value');
+    }
+    visiting.delete(value);
+    seen.add(value);
+}
+function resolveData(document) {
+    let data;
+    try {
+        data = document.toJS({ maxAliasCount: MAX_ALIAS_COUNT });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`YAML scope data could not be resolved: ${reason}`);
+    }
+    assertJsonValue(data, new Set(), new Set());
+    return data;
+}
+function locate(root, segments, document, resolved) {
+    let node = root;
+    const active = new Set();
+    for (const segment of segments) {
+        node = resolveAlias(node, document);
+        if (isMap(node)) {
+            const entry = effectiveEntries(node, document, active, resolved)
+                .find(candidate => candidate.key === segment);
+            if (entry === undefined)
+                return null;
+            node = entry.value;
+        }
+        else if (isSeq(node)) {
+            const index = Number(segment);
+            if (!Number.isInteger(index) || index < 0 || index >= node.items.length)
+                return null;
+            node = node.items[index] ?? null;
+        }
+        else {
+            return null;
+        }
+    }
+    return node;
+}
+function isEmptyDocument(document) {
+    const root = document.contents;
+    if (root === null)
+        return true;
+    if (!isNode(root))
+        return false;
+    const range = root.range;
+    if (range === null || range === undefined || range[0] !== range[1])
+        return false;
+    return !(isScalar(root) && root.tag !== undefined);
+}
+function parseDocuments(source) {
+    if (source === '')
+        return [];
+    const documents = parseAllDocuments(source, { merge: true });
+    const streamError = 'empty' in documents ? documents.errors[0] : undefined;
+    if (streamError !== undefined) {
+        throw new Error(`YAML source could not be parsed: ${streamError.message}`);
+    }
+    const parsed = [];
+    documents.forEach((document, index) => {
+        const firstError = document.errors[0];
+        if (firstError !== undefined) {
+            throw new Error(`YAML source could not be parsed: ${firstError.message}`);
+        }
+        if (isEmptyDocument(document))
+            return;
+        parsed.push({ index, document, data: resolveData(document) });
+    });
+    return parsed;
+}
+export function parseYaml(source) {
+    return parseDocuments(source).map(document => document.data);
+}
+function locationOf(node, source, lines) {
+    const range = isNode(node) ? node.range : undefined;
+    if (!range)
+        throw new Error('The selected YAML node has no source range');
+    return { source: source.slice(range[0], range[1]), lines: lines.span(range[0], range[1]) };
+}
+function selectScopes(source, selector, keySelector) {
+    const lines = new SourceLines(source);
+    const rootOnly = selector.trim() === '$';
+    const scopes = [];
+    for (const { index, document, data } of parseDocuments(source)) {
+        const resolved = new Map();
+        const matches = rootOnly ? [{ pointer: '', value: data }] : query(data, selector);
+        for (const match of matches) {
+            const node = locate(document.contents, pointerSegments(match.pointer), document, resolved);
+            const location = locationOf(node, source, lines);
+            scopes.push({
+                id: keySelector === undefined ? `${index}:${match.pointer}` : `${index}:${keyOf(match.value, keySelector)}`,
+                source: location.source,
+                data: match.value,
+                lines: location.lines,
+            });
+        }
+    }
+    return scopes;
+}
+export function yaml(options) {
+    const selector = options?.path === undefined ? '$' : options.path;
+    if (typeof selector !== 'string')
+        throw new Error('The YAML scope "path" must be a non-empty string');
+    validatePath(selector, 'YAML scope path');
+    const keySelector = options?.key;
+    if (keySelector !== undefined && typeof keySelector !== 'string') {
+        throw new Error('The YAML scope "key" must be a non-empty string');
+    }
+    if (keySelector !== undefined)
+        validatePath(keySelector, 'YAML scope key');
+    return ({ source }) => selectScopes(source, selector, keySelector);
+}

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

@@ -0,0 +1,10 @@
+export declare const SKILL_NAME = "coderuler-new-rule";
+export declare const SKILL_SOURCE: string;
+export interface SkillOptions {
+    readonly global?: boolean;
+    readonly project?: boolean;
+    readonly agent?: readonly string[];
+    readonly yes?: boolean;
+    readonly copy?: boolean;
+}
+export declare function createSkillManager(cwd: string, env: NodeJS.ProcessEnv, executable?: string): (operation: 'install' | 'update', options: SkillOptions) => Promise<number>;

package/dist/adapter/skills/cli.js

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { constants, homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const SKILL_NAME = 'coderuler-new-rule';
+export const SKILL_SOURCE = fileURLToPath(new URL(`../../../skills/${SKILL_NAME}`, import.meta.url));
+function skillsExecutable() {
+    const manifestPath = createRequire(import.meta.url).resolve('skills/package.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    return resolve(dirname(manifestPath), manifest.bin.skills);
+}
+function runSkills(executable, args, cwd, env, capture) {
+    const { promise, resolve: resolveResult, 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', (chunk) => { stdout += chunk; });
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+        resolveResult({ status: code ?? 128 + (signal === null ? 0 : constants.signals[signal]), stdout });
+    });
+    return promise;
+}
+export function createSkillManager(cwd, env, executable) {
+    return async (operation, options) => {
+        const cli = executable ?? skillsExecutable();
+        const scope = options.global === true ? ['--global'] : [];
+        // Never let environment detection choose a different destination during a refresh.
+        const targets = options.agent ?? ['universal'];
+        const agents = ['--agent', ...targets];
+        if (operation === 'update') {
+            const allAgents = targets.includes('*');
+            const filter = allAgents ? [] : agents;
+            const listed = await runSkills(cli, ['list', '--json', ...scope, ...filter], cwd, env, true);
+            if (listed.status !== 0)
+                return listed.status;
+            const installed = JSON.parse(listed.stdout);
+            const selectedScope = options.global === true ? 'global' : 'project';
+            const matching = installed.filter(skill => skill.name === SKILL_NAME && skill.scope === selectedScope);
+            if (matching.length === 0) {
+                throw new Error(`${SKILL_NAME} is not installed in this scope; run coderuler skill install first`);
+            }
+            // List filters also scan other agents. Universal has no agent label in JSON,
+            // so verify its canonical path; ordinary targets must match display labels.
+            // An explicit '*' deliberately opts into installing for every upstream agent.
+            const home = env[process.platform === 'win32' ? 'USERPROFILE' : 'HOME'] ?? homedir();
+            const universalPath = targets.includes('universal')
+                ? resolve(options.global === true ? home : cwd, '.agents', 'skills', SKILL_NAME)
+                : undefined;
+            if (!allAgents) {
+                for (const target of targets) {
+                    const normalized = target.toLowerCase().replace(/[^a-z0-9]/g, '');
+                    const verified = target === 'universal'
+                        ? matching.some(skill => skill.path === universalPath)
+                        : normalized !== '' && matching.some(skill => Array.isArray(skill.agents)
+                            && skill.agents.some((agent) => typeof agent === 'string' && agent.toLowerCase().replace(/[^a-z0-9]/g, '') === normalized));
+                    if (!verified) {
+                        throw new Error(`${SKILL_NAME} is not installed for agent "${target}" in this scope, or its installation cannot be verified; `
+                            + 'use a supported installed --agent target or universal, or run coderuler skill install first');
+                    }
+                }
+            }
+        }
+        const args = ['add', SKILL_SOURCE, '--skill', SKILL_NAME, ...scope, ...agents];
+        if (operation === 'update' || options.yes === true)
+            args.push('--yes');
+        if (options.copy === true)
+            args.push('--copy');
+        return (await runSkills(cli, args, cwd, env, false)).status;
+    };
+}

package/dist/app/concurrency.d.ts

@@ -0,0 +1 @@
+export declare function mapConcurrent<T, R>(items: readonly T[], concurrency: number, mapper: (item: T, index: number, reportFailure: (error: unknown) => void) => Promise<R>): Promise<R[]>;

package/dist/app/concurrency.js

@@ -0,0 +1,44 @@
+function invalidConcurrency(received) {
+    return new RangeError(`--concurrency must be a positive safe integer, received ${received}`);
+}
+function requirePositiveSafeInteger(concurrency) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw invalidConcurrency(String(concurrency));
+    }
+}
+export async function mapConcurrent(items, concurrency, mapper) {
+    requirePositiveSafeInteger(concurrency);
+    const results = new Array(items.length);
+    if (items.length === 0)
+        return results;
+    const workerCount = Math.min(items.length, concurrency);
+    let nextIndex = 0;
+    let failureObserved = false;
+    let failure;
+    // A mapper may need to drain started work after it has already failed.
+    const reportFailure = (error) => {
+        if (!failureObserved) {
+            failureObserved = true;
+            failure = error;
+        }
+    };
+    const runWorker = async () => {
+        while (!failureObserved) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= items.length)
+                return;
+            try {
+                results[index] = await mapper(items[index], index, reportFailure);
+            }
+            catch (error) {
+                reportFailure(error);
+            }
+        }
+    };
+    const workers = Array.from({ length: workerCount }, () => runWorker());
+    await Promise.all(workers);
+    if (failureObserved)
+        throw failure;
+    return results;
+}

package/dist/app/evaluators.d.ts

@@ -0,0 +1,14 @@
+import type { AiOptions, Awaitable, CheckResult, Evaluator, JsonValue, ProjectContext, ScopeSubject, Subject, ViolationLocation } from './rule.js';
+import type { DecisionObserver, DecisionRuntime } from './ports.js';
+export declare function pass(): CheckResult;
+export declare function violation(message: string, locations?: readonly ViolationLocation[]): CheckResult;
+export declare function ai<T = JsonValue>(options: AiOptions<T>): Evaluator<T>;
+export declare function evaluateAi<T = JsonValue>(subject: Subject<T>, options: AiOptions<T>, context: ProjectContext & {
+    readonly ruleName: string;
+}, runtime: DecisionRuntime, observer?: DecisionObserver): Promise<CheckResult>;
+export interface RegexOptions<T = JsonValue> {
+    readonly pattern: RegExp;
+    readonly violationMessage?: string;
+    readonly input?: (subject: ScopeSubject<T>, context: ProjectContext) => Awaitable<string>;
+}
+export declare function regex<T = JsonValue>(options: RegexOptions<T>): Evaluator<T>;