@alex-dbs/coderuler 0.0.0-stage → 1.3.0

package/dist/adapter/filesystem/rule-tests.js

@@ -0,0 +1,264 @@
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { isRecord, validateJsonValue } from '../../app/validate.js';
+import { getRuleDependencies } from './rule-resolution.js';
+// A JavaScript entry lets inherited tsx hooks resolve the source worker's .js import.
+const WORKER_MODULE = new URL('./rule-test-worker.js', import.meta.url);
+const WORKER_ENTRY = new URL(`data:text/javascript,${encodeURIComponent(`import ${JSON.stringify(WORKER_MODULE.href)};`)}`);
+function validateCase(value, label) {
+    if (!isRecord(value))
+        throw new Error(`${label}: expected a test case object`);
+    if (typeof value['name'] !== 'string' || value['name'].trim() === '') {
+        throw new Error(`${label}: name must be a non-blank string`);
+    }
+    const at = `${label} "${value['name']}"`;
+    if (!isRecord(value['files']))
+        throw new Error(`${at}: files must be a fixture path map`);
+    validateJsonValue(value['files'], `${at} files`);
+    const expected = value['expected'];
+    if (expected !== 'pass' && expected !== 'violation' && expected !== 'skipped') {
+        throw new Error(`${at}: expected must be "pass", "violation", or "skipped"`);
+    }
+    return value;
+}
+class RuleTestWorkerSession {
+    worker = new Worker(WORKER_ENTRY);
+    nextId = 0;
+    failure;
+    rejectPending;
+    onFailure;
+    terminating = false;
+    termination;
+    onError = (error) => {
+        if (this.terminating)
+            return;
+        this.failure ??= error;
+        if (this.rejectPending !== undefined)
+            this.rejectPending(error);
+        else
+            this.onFailure?.(error);
+    };
+    onExit = (code) => {
+        if (!this.terminating) {
+            this.onError(new Error(`Rule test worker exited before reporting a result (code ${code})`));
+        }
+    };
+    constructor() {
+        this.worker.on('error', this.onError);
+        this.worker.on('exit', this.onExit);
+    }
+    assertHealthy() {
+        if (this.failure !== undefined)
+            throw this.failure;
+    }
+    async run(request, deadline, onFailure) {
+        this.onFailure = onFailure;
+        this.assertHealthy();
+        const id = this.nextId++;
+        const result = Promise.withResolvers();
+        let timer;
+        const expire = () => {
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                result.resolve('timeout');
+            else
+                timer = setTimeout(expire, Math.min(remaining, 2_147_483_647));
+        };
+        const onMessage = (message) => {
+            if (message.id !== id)
+                return;
+            if (performance.now() >= deadline)
+                result.resolve('timeout');
+            else if ('error' in message)
+                result.reject(new Error(message.error));
+            else
+                result.resolve(message.actual);
+        };
+        this.rejectPending = error => {
+            if (performance.now() >= deadline)
+                result.resolve('timeout');
+            else
+                result.reject(error);
+        };
+        this.worker.on('message', onMessage);
+        try {
+            expire();
+            if (performance.now() < deadline) {
+                this.worker.postMessage({ ...request, id });
+            }
+            return await result.promise;
+        }
+        finally {
+            clearTimeout(timer);
+            this.worker.off('message', onMessage);
+            this.rejectPending = undefined;
+        }
+    }
+    async stop() {
+        if (this.termination === undefined) {
+            this.terminating = true;
+            this.rejectPending?.(new Error('Rule test worker stopped'));
+            this.termination = this.worker.terminate();
+        }
+        await this.termination;
+        this.worker.off('error', this.onError);
+        this.worker.off('exit', this.onExit);
+    }
+}
+async function stopSession(session) {
+    const current = session.current;
+    await current?.stop();
+    if (session.current === current)
+        session.current = undefined;
+}
+async function runCase(entry, example, ai, timeoutMs, session, onFailure) {
+    const started = performance.now();
+    const deadline = started + timeoutMs;
+    let failure;
+    const failCase = (error) => {
+        if (failure !== undefined)
+            return failure;
+        const detail = error instanceof Error ? error.message : String(error);
+        failure = new Error(`Rule "${entry.name}" test "${example.name}" failed: ${detail}`, { cause: error });
+        onFailure(failure);
+        return failure;
+    };
+    try {
+        const root = await mkdtemp(join(await realpath(tmpdir()), 'coderuler-test-'));
+        let actual;
+        let active;
+        try {
+            if (session.cancelled)
+                throw new Error('Rule test run cancelled');
+            if (performance.now() >= deadline)
+                actual = 'timeout';
+            else {
+                active = session.current ??= new RuleTestWorkerSession();
+                const dependencies = getRuleDependencies(entry.ruleFile);
+                actual = await active.run({
+                    root, ruleFile: entry.ruleFile, files: example.files, ai,
+                    ...(dependencies === undefined ? {} : { dependencies }),
+                }, deadline, failCase);
+            }
+        }
+        catch (error) {
+            throw failCase(error);
+        }
+        finally {
+            try {
+                if (actual === undefined || actual === 'timeout')
+                    await stopSession(session);
+            }
+            finally {
+                await rm(root, { recursive: true, force: true });
+            }
+        }
+        if (actual !== 'timeout')
+            active?.assertHealthy();
+        return {
+            ruleName: entry.name,
+            name: example.name,
+            expected: example.expected,
+            actual,
+            durationMs: performance.now() - started,
+        };
+    }
+    catch (error) {
+        const cause = failCase(error);
+        await stopSession(session);
+        throw cause;
+    }
+}
+export async function runRuleTests(rules, onResult, timeoutMs = 10_000, concurrency = 1, includeAI = false) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw new RangeError(`--concurrency must be a positive safe integer, received ${String(concurrency)}`);
+    }
+    const results = [];
+    const sessions = [];
+    let failureObserved = false;
+    let hasExcludedAITests = false;
+    let failure;
+    let cancellation;
+    const fail = (error) => {
+        if (failureObserved)
+            return;
+        failureObserved = true;
+        failure = error;
+        cancellation = Promise.allSettled(sessions.map(session => {
+            session.cancelled = true;
+            return stopSession(session);
+        }));
+    };
+    try {
+        for (const rule of rules) {
+            if (failureObserved)
+                throw failure;
+            // Discovery selects the rule module path at runtime.
+            const { tests, aiTests } = await import(pathToFileURL(rule.ruleFile).href);
+            if (failureObserved)
+                throw failure;
+            if (!includeAI && aiTests !== undefined)
+                hasExcludedAITests = true;
+            const selectedAI = includeAI ? aiTests : undefined;
+            const label = `Rule "${rule.name}"`;
+            if (tests !== undefined && !Array.isArray(tests)) {
+                throw new Error(`${label} tests: expected an array of test cases`);
+            }
+            if (selectedAI !== undefined && !Array.isArray(selectedAI)) {
+                throw new Error(`${label} aiTests: expected an array of test cases`);
+            }
+            const regularCount = tests?.length ?? 0;
+            const count = regularCount + (selectedAI?.length ?? 0);
+            const completed = new Array(count);
+            let nextIndex = 0;
+            let nextResult = 0;
+            const runWorker = async (session) => {
+                while (!failureObserved) {
+                    const index = nextIndex++;
+                    if (index >= count)
+                        return;
+                    try {
+                        const ai = index >= regularCount;
+                        const caseIndex = ai ? index - regularCount : index;
+                        const value = ai ? selectedAI[caseIndex] : tests[caseIndex];
+                        const example = validateCase(value, `${label} ${ai ? 'aiTests' : 'tests'}[${caseIndex}]`);
+                        completed[index] = await runCase(rule, example, ai, timeoutMs, session, fail);
+                        if (failureObserved)
+                            return;
+                        while (completed[nextResult] !== undefined) {
+                            const result = completed[nextResult];
+                            results.push(result);
+                            nextResult += 1;
+                            onResult?.(result, nextResult === count);
+                        }
+                    }
+                    catch (error) {
+                        fail(error);
+                    }
+                }
+            };
+            const workers = [];
+            const workerCount = Math.min(concurrency, count);
+            for (let index = 0; index < workerCount && !failureObserved; index += 1) {
+                const session = sessions[index] ??= { current: undefined, cancelled: false };
+                workers.push(runWorker(session));
+            }
+            await Promise.all(workers);
+            if (failureObserved)
+                throw failure;
+        }
+        if (results.length === 0) {
+            throw new Error(hasExcludedAITests
+                ? 'No ordinary rule test cases found in the selected rules; run with --ai to include aiTests'
+                : 'No rule test cases found in the selected rules');
+        }
+        return results;
+    }
+    finally {
+        await cancellation;
+        await Promise.all(sessions.map(stopSession));
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { RuleLoader } from '../../app/ports.js';
+import type { PreparedRuleDependencies, RuleDependencyManager } from './dependencies.js';
+export interface RuleLoaderOptions {
+    readonly home?: string;
+    readonly dependencies?: RuleDependencyManager;
+    readonly preparedDependencies?: PreparedRuleDependencies;
+}
+export interface ResolvedRuleSelector {
+    readonly explicit?: string;
+    readonly name?: string;
+}
+export declare function resolveRuleSelector(selector: string, invocationCwd: string, allowDirectory?: boolean): Promise<ResolvedRuleSelector>;
+export declare function createRuleLoader(options?: RuleLoaderOptions): RuleLoader;

package/dist/adapter/filesystem/rules.js

@@ -0,0 +1,242 @@
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isRecord, isRuleBranded, validateRule } from '../../app/validate.js';
+import { createRuleDependencyManager, dependencyDirectory } from './dependencies.js';
+import { assertRuleDependenciesCurrent, getRuleDependencies, registerRuleDependencies } from './rule-resolution.js';
+const RULE_DIR = '.coderuler';
+const RULE_MODULE = /\.rule\.(?:ts|mts|js|mjs)$/;
+const PATH_LIKE = /[/\\]|\.rule\.(?:ts|mts|js|mjs)$/;
+const ARCHIVED_DIRECTORY = 'old';
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function ruleNameOf(modulePath) {
+    return basename(modulePath).replace(RULE_MODULE, '');
+}
+async function collectModules(directory, files) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isSymbolicLink())
+            continue;
+        const child = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === ARCHIVED_DIRECTORY || entry.name === 'node_modules'
+                || entry.name === '.coderuler-deps-write'
+                || entry.name.startsWith('.coderuler-deps-stage-')
+                || entry.name.startsWith('.coderuler-sdk-'))
+                continue;
+            await collectModules(child, files);
+        }
+        else if (entry.isFile() && RULE_MODULE.test(entry.name)) {
+            files.push(child);
+        }
+    }
+}
+async function inspectRoot(root) {
+    let stats;
+    try {
+        stats = await lstat(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    if (stats.isSymbolicLink())
+        return undefined;
+    if (!stats.isDirectory()) {
+        throw new Error(`Rule discovery root ${root} is not a directory`);
+    }
+    const physical = await realpath(root);
+    if (physical.split(sep).includes(ARCHIVED_DIRECTORY)) {
+        throw new Error(`Rule path ${physical} is inside an archived "${ARCHIVED_DIRECTORY}" directory`);
+    }
+    const files = [];
+    await collectModules(physical, files);
+    return { physical, files: files.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)) };
+}
+function noRulesError(roots) {
+    return new Error(`No rule files found: expected a .rule.ts, .rule.mts, .rule.js, or .rule.mjs module under ${roots.join(' or ')}`);
+}
+function duplicatedNameError(name, paths) {
+    const listed = paths.map((path) => `  ${path}`).join('\n');
+    return new Error(`Rule name '${name}' matches ${paths.length} rule files:\n${listed}`);
+}
+function assertUniqueNames(entries) {
+    const byName = new Map();
+    for (const entry of entries) {
+        const paths = byName.get(entry.name);
+        if (paths === undefined)
+            byName.set(entry.name, [entry.modulePath]);
+        else
+            paths.push(entry.modulePath);
+    }
+    for (const [name, paths] of byName) {
+        if (paths.length > 1)
+            throw duplicatedNameError(name, paths);
+    }
+}
+async function discover(roots) {
+    const visitedRoots = new Set();
+    const modulePaths = [];
+    for (const root of roots) {
+        const found = await inspectRoot(root);
+        if (found === undefined || visitedRoots.has(found.physical))
+            continue;
+        visitedRoots.add(found.physical);
+        modulePaths.push(...found.files);
+    }
+    const seen = new Set();
+    const entries = [];
+    for (const modulePath of modulePaths) {
+        if (seen.has(modulePath))
+            continue;
+        seen.add(modulePath);
+        entries.push({ name: ruleNameOf(modulePath), modulePath });
+    }
+    if (entries.length === 0)
+        throw noRulesError(roots);
+    return entries;
+}
+async function canonicalRulePath(absolute) {
+    const physical = await realpath(absolute);
+    if (physical.split(sep).includes(ARCHIVED_DIRECTORY)) {
+        throw new Error(`Rule path ${physical} is inside an archived "${ARCHIVED_DIRECTORY}" directory`);
+    }
+    return physical;
+}
+async function collectExplicit(explicit, invocationCwd) {
+    const absolute = resolve(invocationCwd, explicit);
+    if (absolute.split(sep).includes(ARCHIVED_DIRECTORY)) {
+        throw new Error(`Rule path ${absolute} is inside an archived "${ARCHIVED_DIRECTORY}" directory`);
+    }
+    let stats;
+    try {
+        stats = await lstat(absolute);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            throw new Error(`Rule path ${absolute} does not exist`, { cause: error });
+        }
+        throw error;
+    }
+    if (stats.isSymbolicLink()) {
+        throw new Error(`Rule path ${absolute} is a symbolic link; point rule selection at the real file or directory`);
+    }
+    if (stats.isDirectory()) {
+        const files = [];
+        await collectModules(await canonicalRulePath(absolute), files);
+        files.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+        if (files.length === 0)
+            throw noRulesError([absolute]);
+        return files;
+    }
+    if (stats.isFile()) {
+        if (!RULE_MODULE.test(basename(absolute))) {
+            throw new Error(`Unsupported rule module ${absolute}; expected a .rule.ts, .rule.mts, .rule.js, or .rule.mjs file`);
+        }
+        return [await canonicalRulePath(absolute)];
+    }
+    throw new Error(`Rule path ${absolute} is neither a file nor a directory`);
+}
+async function loadRule(modulePath) {
+    let imported;
+    try {
+        imported = await import(pathToFileURL(modulePath).href);
+    }
+    catch (error) {
+        throw new Error(`Rule module ${modulePath} failed to import: ${describe(error)}`, {
+            cause: error,
+        });
+    }
+    const candidate = isRecord(imported) ? imported['default'] : undefined;
+    if (typeof candidate !== 'function' || !isRuleBranded(candidate)) {
+        throw new Error(`Rule module ${modulePath} must default-export a constructible Rule class carrying the shared Rule brand`);
+    }
+    let instance;
+    try {
+        instance = new candidate();
+    }
+    catch (error) {
+        throw new Error(`Rule module ${modulePath} failed to construct: ${describe(error)}`, {
+            cause: error,
+        });
+    }
+    return validateRule(instance, modulePath);
+}
+async function loadEntries(entries, dependencies, preparedDependencies) {
+    const prepared = new Map();
+    for (const entry of entries) {
+        let context = preparedDependencies;
+        if (context === undefined) {
+            const directory = await dependencyDirectory(entry.modulePath);
+            context = prepared.get(directory) ?? await dependencies.prepare(directory);
+            prepared.set(directory, context);
+        }
+        registerRuleDependencies(entry.modulePath, context);
+    }
+    const loaded = [];
+    for (const entry of entries) {
+        const context = getRuleDependencies(entry.modulePath);
+        assertRuleDependenciesCurrent(context);
+        const rule = await loadRule(entry.modulePath);
+        assertRuleDependenciesCurrent(context);
+        loaded.push({ name: entry.name, ruleFile: entry.modulePath, rule });
+    }
+    return loaded;
+}
+export async function resolveRuleSelector(selector, invocationCwd, allowDirectory = false) {
+    const absolute = resolve(invocationCwd, selector);
+    let stats;
+    try {
+        stats = await lstat(absolute);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR')
+            throw error;
+    }
+    if (stats?.isDirectory() === true && !allowDirectory) {
+        throw new Error(`Rule selector ${selector} is a directory; inspecting requires one rule module or an exact rule name`);
+    }
+    if (stats !== undefined || PATH_LIKE.test(selector))
+        return { explicit: absolute };
+    return { name: selector };
+}
+export function createRuleLoader(options = {}) {
+    const home = options.home ?? homedir();
+    const dependencies = options.dependencies ?? createRuleDependencyManager();
+    return {
+        async load(selection) {
+            if (selection.explicit !== undefined && selection.name !== undefined) {
+                throw new Error('Rule selection cannot combine an explicit rule path with a rule name');
+            }
+            const roots = [resolve(selection.root, RULE_DIR), resolve(home, RULE_DIR)];
+            if (selection.explicit !== undefined) {
+                const modulePaths = await collectExplicit(selection.explicit, selection.invocationCwd);
+                const entries = modulePaths.map((modulePath) => ({
+                    name: ruleNameOf(modulePath),
+                    modulePath,
+                }));
+                assertUniqueNames(entries);
+                return loadEntries(entries, dependencies, options.preparedDependencies);
+            }
+            const discovered = await discover(roots);
+            if (selection.name !== undefined) {
+                const matches = discovered.filter((entry) => entry.name === selection.name);
+                if (matches.length === 0) {
+                    throw new Error(`No rule named '${selection.name}' found under ${roots.join(' or ')}`);
+                }
+                if (matches.length > 1) {
+                    throw duplicatedNameError(selection.name, matches.map((match) => match.modulePath));
+                }
+                return loadEntries(matches, dependencies, options.preparedDependencies);
+            }
+            assertUniqueNames(discovered);
+            return loadEntries(discovered, dependencies, options.preparedDependencies);
+        },
+    };
+}

package/dist/adapter/git/changes.d.ts

@@ -0,0 +1 @@
+export declare function changedFiles(root: string, base: string, env?: Readonly<Record<string, string | undefined>>): Promise<ReadonlySet<string>>;

package/dist/adapter/git/changes.js

@@ -0,0 +1,54 @@
+import { spawn } from 'node:child_process';
+import { traversablePath } from '../filesystem/project.js';
+async function git(root, args, consume, env) {
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', [...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', consume);
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', error => reject(new Error(`Cannot run Git: ${error.message}`, { cause: error })));
+        child.on('close', (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Git ${args[0]} failed: ${stderr.trim() || signal || `exit ${code}`}`));
+        });
+    });
+}
+export async function changedFiles(root, base, env) {
+    let tree = '';
+    try {
+        await git(root, ['rev-parse', '--verify', '--end-of-options', `${base}^{tree}`], chunk => {
+            tree += chunk;
+        }, env);
+    }
+    catch (error) {
+        throw new Error(`Cannot resolve Git base ${base}: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: error,
+        });
+    }
+    const paths = new Set();
+    const collectPaths = async (args) => {
+        let pending = '';
+        await git(root, args, chunk => {
+            const records = (pending + chunk).split('\0');
+            pending = records.pop();
+            for (const path of records)
+                paths.add(path);
+        }, env);
+    };
+    await collectPaths([
+        'diff', '--relative', '--name-only', '-z', '--no-renames', '--no-ext-diff', '--no-textconv',
+        tree.trim(), '--', '.',
+    ]);
+    await collectPaths(['ls-files', '--others', '--exclude-standard', '-z', '--', '.']);
+    const changed = new Set();
+    for (const path of paths) {
+        const physical = await traversablePath(root, path);
+        if (physical !== undefined)
+            changed.add(physical);
+    }
+    return changed;
+}

package/dist/adapter/git/environment.d.ts

@@ -0,0 +1 @@
+export declare function isolatedGitEnvironment(env: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;

package/dist/adapter/git/environment.js

@@ -0,0 +1,10 @@
+export function isolatedGitEnvironment(env) {
+    const isolated = { ...env };
+    for (const key of [
+        'GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY',
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_SHALLOW_FILE', 'GIT_GRAFT_FILE', 'GIT_IMPLICIT_WORK_TREE',
+        'GIT_PREFIX', 'GIT_REPLACE_REF_BASE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_NAMESPACE', 'GIT_CONFIG',
+    ])
+        delete isolated[key];
+    return isolated;
+}

package/dist/adapter/github/api.d.ts

@@ -0,0 +1,5 @@
+export declare function mapping(value: unknown): Record<string, unknown> | undefined;
+export declare function createGithubApi(token?: string): {
+    request(path: string, method: 'GET' | 'POST', payload?: object): Promise<Response>;
+    json(path: string): Promise<unknown>;
+};

package/dist/adapter/github/api.js

@@ -0,0 +1,40 @@
+export function mapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value : undefined;
+}
+export function createGithubApi(token) {
+    const request = async (path, method, payload) => {
+        let response;
+        try {
+            response = await fetch(`https://api.github.com${path}`, {
+                method,
+                redirect: 'manual',
+                headers: {
+                    ...(token === undefined ? {} : { Authorization: `Bearer ${token}` }),
+                    Accept: 'application/vnd.github+json',
+                    'X-GitHub-Api-Version': '2022-11-28',
+                    ...(payload === undefined ? {} : { 'Content-Type': 'application/json' }),
+                },
+                ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
+            });
+        }
+        catch {
+            throw new Error('GitHub API request failed; check network connectivity to api.github.com.');
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error(`GitHub API returned HTTP ${response.status}; check GITHUB_TOKEN permissions and pull request access.`);
+        }
+        return response;
+    };
+    const json = async (path) => {
+        const response = await request(path, 'GET');
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new Error('GitHub API returned an invalid response.');
+        }
+    };
+    return { request, json };
+}

package/dist/adapter/github/comments.d.ts

@@ -0,0 +1,3 @@
+import type { ViolationComment } from '../../app/violation-comments.js';
+import { type PullRequest } from './pull-request.js';
+export declare function createGithubCommenter(env: Readonly<Record<string, string | undefined>>): (root: string, comments: readonly ViolationComment[], pullRequest?: PullRequest) => Promise<void>;