@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/code/exec.js

@@ -0,0 +1,133 @@
+import { spawn } from 'node:child_process';
+import { failed, succeeded } from '../schemas/outcome.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function killGroup(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // The process already exited.
+        }
+    }
+}
+/**
+ * Executes one argv-delimited local command without a shell. Output and time
+ * are bounded; a failure never becomes an empty successful result.
+ */
+export function runCommand(options) {
+    if (options.signal?.aborted === true) {
+        return Promise.resolve(failed(diagnosticCodes.code_engine_failed, 'Command was cancelled.', {
+            nextAction: 'Retry when cancellation is no longer requested.',
+        }));
+    }
+    const startedAt = performance.now();
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const maxOutputBytes = options.maxOutputBytes ?? 2 * 1024 * 1024;
+    return new Promise((resolveResult) => {
+        let settled = false;
+        let timedOut = false;
+        let aborted = false;
+        let outputExceeded = false;
+        let bytes = 0;
+        const stdout = [];
+        const stderr = [];
+        let timer = null;
+        let child;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== null)
+                clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+            resolveResult(result);
+        };
+        const abort = () => {
+            aborted = true;
+            killGroup(child?.pid);
+        };
+        try {
+            child = spawn(options.command, [...options.args], {
+                cwd: options.cwd,
+                shell: false,
+                detached: process.platform !== 'win32',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: {
+                    ...process.env,
+                    NO_COLOR: '1',
+                    FORCE_COLOR: '0',
+                    CI: '1',
+                },
+            });
+        }
+        catch (error) {
+            settle(failed(diagnosticCodes.code_engine_unavailable, `Cannot start ${options.command}: ${errorText(error)}`, {
+                nextAction: 'Install the selected code engine or use text fallback.',
+            }));
+            return;
+        }
+        timer = setTimeout(() => {
+            timedOut = true;
+            killGroup(child.pid);
+        }, timeoutMs);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        const collect = (chunks, chunk) => {
+            bytes += chunk.byteLength;
+            if (bytes > maxOutputBytes) {
+                outputExceeded = true;
+                killGroup(child.pid);
+                return;
+            }
+            chunks.push(chunk);
+        };
+        child.stdout?.on('data', (chunk) => collect(stdout, chunk));
+        child.stderr?.on('data', (chunk) => collect(stderr, chunk));
+        child.on('error', (error) => {
+            settle(failed(diagnosticCodes.code_engine_unavailable, `Cannot run ${options.command}: ${errorText(error)}`, {
+                nextAction: 'Install the selected code engine or use text fallback.',
+            }));
+        });
+        child.on('close', (exitCode, signal) => {
+            const durationMs = Math.round(performance.now() - startedAt);
+            if (timedOut) {
+                settle(failed(diagnosticCodes.code_engine_failed, `${options.command} timed out after ${timeoutMs}ms.`, {
+                    retryable: true,
+                    nextAction: 'Retry with a bounded smaller target.',
+                }));
+                return;
+            }
+            if (aborted) {
+                settle(failed(diagnosticCodes.code_engine_failed, 'Command was cancelled.', {
+                    nextAction: 'Retry when cancellation is no longer requested.',
+                }));
+                return;
+            }
+            if (outputExceeded) {
+                settle(failed(diagnosticCodes.code_output_limit, `${options.command} exceeded the ${maxOutputBytes}-byte output limit.`, { nextAction: 'Narrow the query or selected repository scope.' }));
+                return;
+            }
+            if (exitCode === null) {
+                settle(failed(diagnosticCodes.code_engine_failed, `${options.command} ended without an exit code (signal ${signal ?? 'unknown'}).`, { retryable: true, nextAction: 'Inspect the engine and retry.' }));
+                return;
+            }
+            settle(succeeded({
+                command: options.command,
+                args: [...options.args],
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                exitCode,
+                bytes,
+                durationMs,
+            }));
+        });
+    });
+}

package/dist/code/identity.d.ts

@@ -0,0 +1,13 @@
+import { type Outcome } from '../schemas/outcome.js';
+import { type CodeIdentity } from '../schemas/code.js';
+export interface ComputeCodeIdentityInput {
+    readonly repositoryId: string;
+    readonly root: string;
+    readonly engineVersion: string;
+    readonly configDigest: string;
+    readonly configStatus?: 'default' | 'observed' | 'unknown';
+    readonly excludedRoots?: readonly string[];
+    readonly signal?: AbortSignal;
+}
+export declare function computeCodeIdentity(input: ComputeCodeIdentityInput): Promise<Outcome<CodeIdentity>>;
+export declare function codeIdentityDigest(identity: CodeIdentity): string;

package/dist/code/identity.js

@@ -0,0 +1,214 @@
+import { readlink } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { inspectGitRepository } from '../infra/git.js';
+import { runGit } from '../infra/git.js';
+import { observePath, readFileBounded, sha256Digest } from '../infra/fs.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { failed, succeeded } from '../schemas/outcome.js';
+import { isPathInside } from '../schemas/paths.js';
+import { codeIdentitySchema, } from '../schemas/code.js';
+const MAX_WORKTREE_BYTES = 16 * 1024 * 1024;
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+const GIT_TIMEOUT_MS = 10_000;
+const EXCLUDES = [
+    ':(exclude).codegraph',
+    ':(exclude).pappra/local',
+    ':(exclude).pappra/generated',
+];
+async function observeWorkingTree(root, excludedRoots, signal) {
+    const reasons = [];
+    let completeness = 'complete';
+    const readDiff = async (args) => runGit({
+        cwd: root,
+        args,
+        timeoutMs: GIT_TIMEOUT_MS,
+        maxOutputBytes: MAX_WORKTREE_BYTES,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    const trackedExcludes = [...EXCLUDES];
+    for (const excluded of excludedRoots) {
+        const rel = relative(root, excluded);
+        if (rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`)) {
+            trackedExcludes.push(`:(exclude)${rel.split(sep).join('/')}`);
+        }
+    }
+    const cached = await readDiff([
+        'diff',
+        '--binary',
+        '--cached',
+        '--',
+        '.',
+        ...trackedExcludes,
+    ]);
+    const unstaged = await readDiff([
+        'diff',
+        '--binary',
+        '--',
+        '.',
+        ...trackedExcludes,
+    ]);
+    const cachedBytes = cached.ok
+        ? Buffer.from(cached.value.stdout, 'utf8')
+        : Buffer.alloc(0);
+    const unstagedBytes = unstaged.ok
+        ? Buffer.from(unstaged.value.stdout, 'utf8')
+        : Buffer.alloc(0);
+    if (!cached.ok) {
+        completeness =
+            cached.code === diagnosticCodes.gitOutputLimit ? 'partial' : 'unknown';
+        reasons.push('tracked_staged_diff_unavailable');
+    }
+    if (!unstaged.ok) {
+        completeness =
+            unstaged.code === diagnosticCodes.gitOutputLimit ? 'partial' : 'unknown';
+        reasons.push('tracked_unstaged_diff_unavailable');
+    }
+    const diffBytes = cachedBytes.length + unstagedBytes.length;
+    if (diffBytes > MAX_WORKTREE_BYTES) {
+        completeness = 'partial';
+        reasons.push('tracked_diff_output_limit');
+    }
+    const untracked = await runGit({
+        cwd: root,
+        args: [
+            'ls-files',
+            '--others',
+            '--exclude-standard',
+            '-z',
+            '--',
+            '.',
+            ...trackedExcludes,
+        ],
+        timeoutMs: GIT_TIMEOUT_MS,
+        maxOutputBytes: 2 * 1024 * 1024,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    const parts = [
+        Buffer.from(`PAPPRA-CODE-WORKTREE/2\nD ${cachedBytes.length} ${unstagedBytes.length}\n`, 'utf8'),
+        cachedBytes,
+        unstagedBytes,
+    ];
+    let total = parts.reduce((sum, part) => sum + part.length, 0);
+    let fileCount = 0;
+    if (!untracked.ok) {
+        completeness = 'partial';
+        reasons.push('untracked_list_unavailable');
+    }
+    else {
+        const paths = untracked.value.stdout
+            .split('\0')
+            .filter((path) => path.length > 0);
+        for (const path of paths) {
+            if (total > MAX_WORKTREE_BYTES) {
+                completeness = 'partial';
+                reasons.push('working_tree_output_limit');
+                break;
+            }
+            const absolute = join(root, path);
+            if (!isPathInside(root, absolute)) {
+                completeness = 'partial';
+                reasons.push(`untracked_path_unsafe:${path.slice(0, 200)}`);
+                continue;
+            }
+            if (excludedRoots.some((excluded) => isPathInside(excluded, absolute))) {
+                continue;
+            }
+            const observation = await observePath(absolute).catch(() => null);
+            if (observation === null) {
+                completeness = 'partial';
+                reasons.push(`untracked_unreadable:${path.slice(0, 200)}`);
+                continue;
+            }
+            let body;
+            let kind;
+            if (observation.kind === 'file') {
+                const read = await readFileBounded(absolute, MAX_FILE_BYTES);
+                if (!read.ok) {
+                    completeness = 'partial';
+                    reasons.push(`untracked_file_limit:${path.slice(0, 200)}`);
+                    continue;
+                }
+                body = read.value.bytes;
+                kind = 'F';
+            }
+            else if (observation.kind === 'symlink') {
+                const target = await readlink(absolute).catch(() => null);
+                if (target === null) {
+                    completeness = 'partial';
+                    reasons.push(`untracked_symlink_unreadable:${path.slice(0, 200)}`);
+                    continue;
+                }
+                body = Buffer.from(target, 'utf8');
+                kind = 'L';
+            }
+            else {
+                completeness = 'partial';
+                reasons.push(`untracked_not_regular:${path.slice(0, 200)}`);
+                continue;
+            }
+            const pathBytes = Buffer.from(path, 'utf8');
+            const header = Buffer.from(`${kind} ${pathBytes.length} ${body.length}\n`, 'utf8');
+            if (total + header.length + pathBytes.length + body.length >
+                MAX_WORKTREE_BYTES) {
+                completeness = 'partial';
+                reasons.push('working_tree_output_limit');
+                break;
+            }
+            parts.push(header, pathBytes, body);
+            total += header.length + pathBytes.length + body.length;
+            fileCount += 1;
+        }
+    }
+    const bytes = Buffer.concat(parts);
+    return {
+        observation: {
+            digest: sha256Digest(bytes),
+            completeness,
+            fileCount,
+            byteCount: bytes.length,
+            reasons: [...new Set(reasons)].slice(0, 16),
+        },
+        bytes,
+    };
+}
+export async function computeCodeIdentity(input) {
+    const observed = await inspectGitRepository(input.root, {
+        timeoutMs: GIT_TIMEOUT_MS,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    if (!observed.ok)
+        return observed;
+    const git = observed.value;
+    const working = await observeWorkingTree(input.root, input.excludedRoots ?? [], input.signal);
+    const checkoutId = sha256Digest(JSON.stringify({
+        root: git.root,
+        gitDir: git.gitDir,
+        commonDir: git.commonDir,
+    }));
+    const parsed = codeIdentitySchema.safeParse({
+        schema: 'pappra/code-identity/1',
+        repositoryId: input.repositoryId,
+        checkoutId,
+        root: git.root,
+        gitDir: git.gitDir,
+        gitCommonDir: git.commonDir,
+        head: git.head,
+        branch: git.branch,
+        workingTree: working.observation,
+        engine: {
+            id: 'codegraph',
+            version: input.engineVersion,
+            configDigest: input.configDigest,
+            configStatus: input.configStatus ?? 'observed',
+        },
+    });
+    if (!parsed.success) {
+        return failed(diagnosticCodes.code_identity_changed, `Code identity is invalid: ${parsed.error.issues[0]?.message ?? 'unknown issue'}`, {
+            nextAction: 'Inspect the selected repository and code engine configuration.',
+        });
+    }
+    return succeeded(parsed.data);
+}
+export function codeIdentityDigest(identity) {
+    return sha256Digest(JSON.stringify(identity));
+}

package/dist/code/index.d.ts

@@ -0,0 +1,6 @@
+export { CodeIntelligenceService, codeIdentityDigest } from './service.js';
+export type { CodePrepareInput, CodeQueryInput, CodeQueryOutput, CodeStatusInput, CodeStatusResult, } from './service.js';
+export { CodeGraphProvider, codeGraphConfigDigest, codeGraphIndexPath, codeGraphVersion, } from './providers/codegraph.js';
+export type { CodeProvider } from './providers/codegraph.js';
+export { codeRegistrationPath, readCodeRegistration, registrationMatches, writeCodeRegistration, } from './registration.js';
+export type { CodeEngine, CodeIdentity, CodeIndexCoverage, CodeIndexHealth, CodeIndexRegistration, CodePrepareAction, CodePreparePlan, CodePrepareResult, CodeQueryItem, CodeQueryKind, CodeQueryLimits, CodeQueryRequest, CodeQueryResult, CodeWorkingTree, } from '../schemas/code.js';

package/dist/code/index.js

@@ -0,0 +1,3 @@
+export { CodeIntelligenceService, codeIdentityDigest } from './service.js';
+export { CodeGraphProvider, codeGraphConfigDigest, codeGraphIndexPath, codeGraphVersion, } from './providers/codegraph.js';
+export { codeRegistrationPath, readCodeRegistration, registrationMatches, writeCodeRegistration, } from './registration.js';

package/dist/code/providers/codegraph.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { type Outcome } from '../../schemas/outcome.js';
+import type { EvidenceRef } from '../../schemas/evidence.js';
+import { type CodeIdentity, type CodeIndexHealth, type CodeQueryRequest, type CodeQueryResult, type CodePrepareAction, type CodePreparePlan } from '../../schemas/code.js';
+declare const engineStatusSchema: z.ZodObject<{
+    initialized: z.ZodBoolean;
+    version: z.ZodString;
+    projectPath: z.ZodOptional<z.ZodString>;
+    indexPath: z.ZodOptional<z.ZodString>;
+    lastIndexed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fileCount: z.ZodOptional<z.ZodNumber>;
+    nodeCount: z.ZodOptional<z.ZodNumber>;
+    edgeCount: z.ZodOptional<z.ZodNumber>;
+    dbSizeBytes: z.ZodOptional<z.ZodNumber>;
+    languages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pendingChanges: z.ZodOptional<z.ZodObject<{
+        added: z.ZodNumber;
+        modified: z.ZodNumber;
+        removed: z.ZodNumber;
+    }, z.core.$strip>>;
+    worktreeMismatch: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    index: z.ZodOptional<z.ZodObject<{
+        builtWithVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        builtWithExtractionVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        currentExtractionVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reindexRecommended: z.ZodOptional<z.ZodBoolean>;
+        state: z.ZodOptional<z.ZodString>;
+        pendingRefs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function codeGraphVersion(signal?: AbortSignal): Promise<Outcome<string>>;
+export interface CodeGraphConfigObservation {
+    readonly digest: string;
+    readonly status: 'default' | 'observed' | 'unknown';
+}
+export declare function observeCodeGraphConfig(root: string): Promise<Outcome<CodeGraphConfigObservation>>;
+export declare function codeGraphConfigDigest(root: string): Promise<string>;
+export interface CodeProvider {
+    readonly id: string;
+    detect(root: string, signal?: AbortSignal): Promise<Outcome<readonly EvidenceRef[]>>;
+    status(identity: CodeIdentity, signal?: AbortSignal): Promise<Outcome<CodeIndexHealth>>;
+    prepare(identity: CodeIdentity, plan: CodePreparePlan, signal?: AbortSignal): Promise<Outcome<CodeIndexHealth>>;
+    query(request: CodeQueryRequest, signal?: AbortSignal): Promise<Outcome<CodeQueryResult>>;
+}
+export declare function codeGraphPlanCommand(command: string, action: CodePrepareAction, root: string): string[];
+export declare class CodeGraphProvider implements CodeProvider {
+    private readonly command;
+    readonly id: 'codegraph';
+    constructor(command?: string);
+    detect(root: string, signal?: AbortSignal): Promise<Outcome<readonly EvidenceRef[]>>;
+    status(identity: CodeIdentity, signal?: AbortSignal): Promise<Outcome<CodeIndexHealth>>;
+    plan(identity: CodeIdentity, current: CodeIndexHealth, rebuild: boolean): CodePreparePlan;
+    prepare(identity: CodeIdentity, plan: CodePreparePlan, signal?: AbortSignal): Promise<Outcome<CodeIndexHealth>>;
+    query(request: CodeQueryRequest, signal?: AbortSignal): Promise<Outcome<CodeQueryResult>>;
+}
+export declare function codeGraphIndexPath(root: string): string;
+export declare function codeGraphStatusSchemaForTests(): typeof engineStatusSchema;
+export declare function codeIndexHealthForTests(state: CodeIndexHealth['state'], reasons: readonly string[]): CodeIndexHealth;
+export {};