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

package/dist/code/service.js

@@ -0,0 +1,633 @@
+import { sha256Digest } from '../infra/fs.js';
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { succeeded } from '../schemas/outcome.js';
+import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
+import { discoverRepositories } from '../workspace/repositories.js';
+import { codeIndexHealthSchema, codePreparePlanSchema, codeQueryLimitsSchema, codeQueryRequestSchema, } from '../schemas/code.js';
+import { CodeGraphProvider, observeCodeGraphConfig, codeGraphVersion, codeGraphPlanCommand, } from './providers/codegraph.js';
+import { computeCodeIdentity, codeIdentityDigest } from './identity.js';
+import { codeRegistrationPath, readCodeRegistration, registrationMatches, acquireCodePrepareLock, releaseCodePrepareLock, ensureCodeMutationBoundary, writeCodeRegistration, } from './registration.js';
+import { runTextQuery } from './text.js';
+const discoveryOptions = {
+    scanDepth: 0,
+    maxDirectories: 1,
+    maxDocuments: 1,
+    maxEntriesPerDirectory: 1,
+    gitTimeoutMs: 10_000,
+};
+function outcomeDiagnostic(failure, source) {
+    return createDiagnostic({
+        code: failure.code,
+        severity: 'error',
+        message: failure.message,
+        source,
+        pointer: null,
+        hint: failure.nextAction,
+    });
+}
+function fallbackHealth(state, reason, engineVersion = 'unknown') {
+    return codeIndexHealthSchema.parse({
+        schema: 'pappra/code-index-health/1',
+        state,
+        reasons: [reason],
+        evidence: [],
+        coverage: {
+            scope: 'selected-repository',
+            languages: [],
+            semantic: false,
+            callGraph: false,
+            note: 'No ready code index was established.',
+        },
+        engineVersion,
+        observedAt: new Date().toISOString(),
+    });
+}
+async function loadWorkspace(root) {
+    const config = await inspectWorkspaceConfig(root);
+    const diagnostics = [...config.diagnostics];
+    if (config.value === null) {
+        return { root: config.root, repositories: [], diagnostics };
+    }
+    const machine = await inspectMachineConfig(config.root);
+    diagnostics.push(...machine.diagnostics);
+    const repositories = await discoverRepositories({
+        root: config.root,
+        config: config.value,
+        machine: machine.value,
+        configPath: config.path,
+        options: discoveryOptions,
+    });
+    diagnostics.push(...repositories.diagnostics);
+    return {
+        root: config.root,
+        repositories: repositories.repositories,
+        diagnostics,
+    };
+}
+function selectRepository(view, repositoryId) {
+    return (view.repositories.find((repository) => repository.id === repositoryId && !repository.external) ??
+        view.repositories.find((repository) => repository.id === repositoryId) ??
+        null);
+}
+function overlayRegistration(raw, registration, registrationFailure, identity) {
+    const reasons = [...raw.reasons];
+    if (registrationFailure !== null) {
+        reasons.push(registrationFailure.code);
+        return {
+            ...raw,
+            state: raw.state === 'ready' ? 'partial' : raw.state,
+            reasons: [...new Set(reasons)].slice(0, 32),
+        };
+    }
+    if (raw.state !== 'ready')
+        return raw;
+    if (registration === null) {
+        return {
+            ...raw,
+            state: 'partial',
+            reasons: [...reasons, 'registration_missing'].slice(0, 32),
+        };
+    }
+    if (!registrationMatches(registration, identity)) {
+        return {
+            ...raw,
+            state: 'stale',
+            reasons: [...reasons, 'registration_identity_changed'].slice(0, 32),
+        };
+    }
+    return raw;
+}
+async function observeCode(input) {
+    const view = await loadWorkspace(input.root);
+    const diagnostics = [...view.diagnostics];
+    const repository = selectRepository(view, input.repositoryId);
+    if (repository === null) {
+        return {
+            identity: null,
+            rawHealth: fallbackHealth('unsupported', 'repository_not_found'),
+            health: fallbackHealth('unsupported', 'repository_not_found'),
+            registration: null,
+            registrationPath: null,
+            excludedRoots: [],
+            access: 'read',
+            diagnostics: [
+                ...diagnostics,
+                createDiagnostic({
+                    code: diagnosticCodes.code_repository_unknown,
+                    severity: 'error',
+                    message: `Selected repository is not declared: ${input.repositoryId}`,
+                    source: view.root,
+                    pointer: null,
+                    hint: 'Select an explicit repository id from workspace.json.',
+                }),
+            ],
+        };
+    }
+    const version = await codeGraphVersion(input.signal);
+    const versionValue = version.ok ? version.value : 'unknown';
+    if (!version.ok)
+        diagnostics.push(outcomeDiagnostic(version, repository.root));
+    const configObserved = await observeCodeGraphConfig(repository.root);
+    const configDigest = configObserved.ok
+        ? configObserved.value.digest
+        : sha256Digest('codegraph:unknown');
+    const configStatus = configObserved.ok
+        ? configObserved.value.status
+        : 'unknown';
+    if (configStatus === 'unknown') {
+        diagnostics.push(createDiagnostic({
+            code: diagnosticCodes.code_index_partial,
+            severity: 'warning',
+            message: 'CodeGraph configuration could not be observed as a regular bounded file; ready is not permitted.',
+            source: repository.root,
+            pointer: '.codegraph/config.json',
+            hint: 'Inspect the engine configuration; the default configuration is not assumed.',
+        }));
+    }
+    const excludedRoots = view.repositories
+        .filter((entry) => entry.root !== repository.root)
+        .map((entry) => entry.root);
+    const identity = await computeCodeIdentity({
+        repositoryId: input.repositoryId,
+        root: repository.root,
+        engineVersion: versionValue,
+        configDigest,
+        configStatus,
+        excludedRoots,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    if (!identity.ok) {
+        diagnostics.push(outcomeDiagnostic(identity, repository.root));
+        return {
+            identity: null,
+            rawHealth: fallbackHealth('partial', identity.code, versionValue),
+            health: fallbackHealth('partial', identity.code, versionValue),
+            registration: null,
+            registrationPath: null,
+            excludedRoots,
+            access: repository.access,
+            diagnostics,
+        };
+    }
+    const provider = new CodeGraphProvider();
+    const raw = await provider.status(identity.value, input.signal);
+    const rawHealth = raw.ok
+        ? raw.value
+        : fallbackHealth('unsupported', raw.code, versionValue);
+    if (!raw.ok)
+        diagnostics.push(outcomeDiagnostic(raw, repository.root));
+    const registrationRead = await readCodeRegistration(repository.root, input.repositoryId);
+    let registration = null;
+    let registrationFailure = null;
+    if (registrationRead.ok) {
+        registration = registrationRead.value;
+    }
+    else {
+        registrationFailure = registrationRead;
+        diagnostics.push(outcomeDiagnostic(registrationRead, repository.root));
+    }
+    const health = overlayRegistration(rawHealth, registration, registrationFailure, identity.value);
+    return {
+        identity: identity.value,
+        rawHealth,
+        health,
+        registration,
+        registrationPath: codeRegistrationPath(repository.root, input.repositoryId),
+        excludedRoots,
+        access: repository.access,
+        diagnostics,
+    };
+}
+export class CodeIntelligenceService {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async status(input) {
+        const repositoryId = input?.repositoryId;
+        if (repositoryId === undefined) {
+            const health = fallbackHealth('unsupported', 'repository_required');
+            return {
+                ok: false,
+                identity: null,
+                health,
+                registrationPath: null,
+                registrationPresent: false,
+                diagnostics: [
+                    createDiagnostic({
+                        code: diagnosticCodes.code_repository_required,
+                        severity: 'error',
+                        message: 'code status requires an explicit repository id.',
+                        source: this.root,
+                        pointer: null,
+                        hint: 'Pass --repo <id> from workspace.json.',
+                    }),
+                ],
+            };
+        }
+        const observed = await observeCode({
+            root: this.root,
+            repositoryId,
+            ...(input?.signal === undefined ? {} : { signal: input.signal }),
+        });
+        return {
+            ok: observed.identity !== null && observed.health.state === 'ready',
+            identity: observed.identity,
+            health: observed.health,
+            registrationPath: observed.registrationPath,
+            registrationPresent: observed.registration !== null,
+            diagnostics: observed.diagnostics,
+        };
+    }
+    async planPrepare(input) {
+        const observed = await observeCode(input);
+        if (observed.identity === null) {
+            return {
+                observed,
+                plan: codePreparePlanSchema.parse({
+                    schema: 'pappra/code-prepare-plan/1',
+                    repositoryId: input.repositoryId,
+                    identityDigest: `sha256:${'0'.repeat(64)}`,
+                    action: 'none',
+                    indexPath: this.root,
+                    command: ['codegraph', 'status', '--json', this.root],
+                    mutates: false,
+                    reasons: ['identity_unavailable'],
+                }),
+            };
+        }
+        const provider = new CodeGraphProvider();
+        let plan = provider.plan(observed.identity, observed.rawHealth, input.rebuild);
+        if (observed.registration !== null &&
+            !registrationMatches(observed.registration, observed.identity) &&
+            plan.action === 'none' &&
+            !input.rebuild) {
+            const sameEngineAndCheckout = observed.registration.checkoutId === observed.identity.checkoutId &&
+                observed.registration.engineVersion ===
+                    observed.identity.engine.version &&
+                observed.registration.configDigest ===
+                    observed.identity.engine.configDigest;
+            plan = sameEngineAndCheckout
+                ? {
+                    ...plan,
+                    action: 'sync',
+                    command: codeGraphPlanCommand('codegraph', 'sync', observed.identity.root),
+                    mutates: true,
+                    reasons: [
+                        ...plan.reasons,
+                        'registration_working_tree_changed',
+                    ].slice(0, 16),
+                }
+                : {
+                    ...plan,
+                    action: 'none',
+                    command: codeGraphPlanCommand('codegraph', 'none', observed.identity.root),
+                    mutates: false,
+                    reasons: [
+                        ...plan.reasons,
+                        'registration_identity_changed',
+                        'explicit_rebuild_required',
+                    ].slice(0, 16),
+                };
+        }
+        return { observed, plan };
+    }
+    async prepare(input) {
+        const { observed, plan } = await this.planPrepare(input);
+        if (!input.apply) {
+            return {
+                schema: 'pappra/code-prepare-result/1',
+                ok: observed.identity !== null,
+                status: 'planned',
+                plan,
+                health: observed.health,
+                registrationPath: null,
+                diagnostics: [...observed.diagnostics],
+            };
+        }
+        if (observed.identity === null) {
+            return {
+                schema: 'pappra/code-prepare-result/1',
+                ok: false,
+                status: 'failed',
+                plan,
+                health: observed.health,
+                registrationPath: null,
+                diagnostics: [...observed.diagnostics],
+            };
+        }
+        if (plan.reasons.includes('explicit_rebuild_required')) {
+            return {
+                schema: 'pappra/code-prepare-result/1',
+                ok: false,
+                status: 'conflict',
+                plan,
+                health: observed.health,
+                registrationPath: null,
+                diagnostics: [...observed.diagnostics],
+            };
+        }
+        if (observed.access !== 'write') {
+            return {
+                schema: 'pappra/code-prepare-result/1',
+                ok: false,
+                status: 'conflict',
+                plan: {
+                    ...plan,
+                    action: 'none',
+                    command: codeGraphPlanCommand('codegraph', 'none', observed.identity.root),
+                    mutates: false,
+                    reasons: [...plan.reasons, 'repository_read_only'].slice(0, 16),
+                },
+                health: observed.health,
+                registrationPath: null,
+                diagnostics: [...observed.diagnostics],
+            };
+        }
+        const registrationTarget = codeRegistrationPath(observed.identity.root, observed.identity.repositoryId);
+        for (const target of [plan.indexPath, registrationTarget]) {
+            const boundary = await ensureCodeMutationBoundary(observed.identity.root, target, observed.excludedRoots);
+            if (!boundary.ok) {
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: 'conflict',
+                    plan: {
+                        ...plan,
+                        action: 'none',
+                        command: codeGraphPlanCommand('codegraph', 'none', observed.identity.root),
+                        mutates: false,
+                        reasons: [...plan.reasons, boundary.code].slice(0, 16),
+                    },
+                    health: observed.health,
+                    registrationPath: null,
+                    diagnostics: [
+                        ...observed.diagnostics,
+                        outcomeDiagnostic(boundary, target),
+                    ],
+                };
+            }
+        }
+        const lock = await acquireCodePrepareLock(observed.identity.root, observed.excludedRoots);
+        if (!lock.ok) {
+            return {
+                schema: 'pappra/code-prepare-result/1',
+                ok: false,
+                status: 'conflict',
+                plan: {
+                    ...plan,
+                    action: 'none',
+                    mutates: false,
+                    command: codeGraphPlanCommand('codegraph', 'none', observed.identity.root),
+                },
+                health: observed.health,
+                registrationPath: null,
+                diagnostics: [
+                    ...observed.diagnostics,
+                    outcomeDiagnostic(lock, observed.identity.root),
+                ],
+            };
+        }
+        const perform = async () => {
+            const identity = observed.identity;
+            if (identity === null) {
+                throw new Error('Code identity disappeared before prepare');
+            }
+            const provider = new CodeGraphProvider();
+            const prepared = await provider.prepare(identity, plan, input.signal);
+            if (!prepared.ok) {
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: 'failed',
+                    plan,
+                    health: fallbackHealth('failed', prepared.code),
+                    registrationPath: null,
+                    diagnostics: [
+                        ...observed.diagnostics,
+                        outcomeDiagnostic(prepared, identity.root),
+                    ],
+                };
+            }
+            const afterVersion = await codeGraphVersion(input.signal);
+            const afterConfig = await observeCodeGraphConfig(identity.root);
+            if (!afterVersion.ok ||
+                !afterConfig.ok ||
+                afterConfig.value.status === 'unknown' ||
+                afterVersion.value !== identity.engine.version ||
+                afterConfig.value.digest !== identity.engine.configDigest) {
+                const reasons = [
+                    ...prepared.value.reasons,
+                    ...(afterConfig.ok && afterConfig.value.status === 'unknown'
+                        ? ['engine_config_unknown']
+                        : []),
+                    'engine_identity_changed_after_prepare',
+                ].slice(0, 32);
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: 'partial',
+                    plan,
+                    health: { ...prepared.value, state: 'partial', reasons },
+                    registrationPath: null,
+                    diagnostics: [...observed.diagnostics],
+                };
+            }
+            const afterIdentity = await computeCodeIdentity({
+                repositoryId: identity.repositoryId,
+                root: identity.root,
+                engineVersion: afterVersion.value,
+                configDigest: afterConfig.value.digest,
+                configStatus: afterConfig.value.status,
+                excludedRoots: observed.excludedRoots,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            if (!afterIdentity.ok) {
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: 'partial',
+                    plan,
+                    health: fallbackHealth('partial', afterIdentity.code),
+                    registrationPath: null,
+                    diagnostics: [
+                        ...observed.diagnostics,
+                        outcomeDiagnostic(afterIdentity, identity.root),
+                    ],
+                };
+            }
+            if (codeIdentityDigest(afterIdentity.value) !== codeIdentityDigest(identity)) {
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: 'partial',
+                    plan,
+                    health: {
+                        ...prepared.value,
+                        state: 'partial',
+                        reasons: [
+                            ...prepared.value.reasons,
+                            'source_changed_during_prepare',
+                        ].slice(0, 32),
+                    },
+                    registrationPath: null,
+                    diagnostics: [
+                        ...observed.diagnostics,
+                        createDiagnostic({
+                            code: diagnosticCodes.code_identity_changed,
+                            severity: 'warning',
+                            message: 'Source identity changed while preparing the index; ready registration was not published.',
+                            source: identity.root,
+                            pointer: null,
+                            hint: 'Repeat prepare after the working tree is stable.',
+                        }),
+                    ],
+                };
+            }
+            if (prepared.value.state !== 'ready') {
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: prepared.value.state === 'failed' ? 'failed' : 'partial',
+                    plan,
+                    health: prepared.value,
+                    registrationPath: null,
+                    diagnostics: [...observed.diagnostics],
+                };
+            }
+            const registration = {
+                schema: 'pappra/code-index-registration/1',
+                repositoryId: afterIdentity.value.repositoryId,
+                identityDigest: codeIdentityDigest(afterIdentity.value),
+                checkoutId: afterIdentity.value.checkoutId,
+                root: afterIdentity.value.root,
+                engineVersion: afterIdentity.value.engine.version,
+                configDigest: afterIdentity.value.engine.configDigest,
+                preparedAt: new Date().toISOString(),
+                coverage: prepared.value.coverage,
+            };
+            const written = await writeCodeRegistration(afterIdentity.value.root, registration, observed.excludedRoots);
+            if (!written.ok) {
+                return {
+                    schema: 'pappra/code-prepare-result/1',
+                    ok: false,
+                    status: 'partial',
+                    plan,
+                    health: {
+                        ...prepared.value,
+                        state: 'partial',
+                        reasons: [
+                            ...prepared.value.reasons,
+                            'registration_write_failed',
+                        ].slice(0, 32),
+                    },
+                    registrationPath: null,
+                    diagnostics: [
+                        ...observed.diagnostics,
+                        outcomeDiagnostic(written, identity.root),
+                    ],
+                };
+            }
+            return {
+                schema: 'pappra/code-prepare-result/1',
+                ok: true,
+                status: 'ready',
+                plan,
+                health: prepared.value,
+                registrationPath: written.value,
+                diagnostics: [...observed.diagnostics],
+            };
+        };
+        let result;
+        try {
+            result = await perform();
+        }
+        catch (error) {
+            await releaseCodePrepareLock(lock.value);
+            throw error;
+        }
+        const released = await releaseCodePrepareLock(lock.value);
+        if (released.ok)
+            return result;
+        return {
+            ...result,
+            ok: false,
+            status: result.ok ? 'partial' : result.status,
+            diagnostics: [
+                ...result.diagnostics,
+                outcomeDiagnostic(released, lock.value),
+            ],
+        };
+    }
+    async query(input) {
+        const limits = codeQueryLimitsSchema.parse({
+            maxResults: input.limits?.maxResults ?? 20,
+            maxBytes: input.limits?.maxBytes ?? 1024 * 1024,
+            maxFiles: input.limits?.maxFiles ?? 1000,
+        });
+        const observed = await observeCode(input);
+        if (observed.identity === null) {
+            return {
+                ok: false,
+                result: null,
+                health: observed.health,
+                diagnostics: [...observed.diagnostics],
+            };
+        }
+        const request = codeQueryRequestSchema.parse({
+            schema: 'pappra/code-query/1',
+            kind: input.kind,
+            query: input.query,
+            identity: observed.identity,
+            limits,
+            excludedRoots: observed.excludedRoots,
+        });
+        const provider = new CodeGraphProvider();
+        let result;
+        if (input.kind === 'text') {
+            result = await runTextQuery(request, 'text', input.signal);
+        }
+        else if (observed.health.state === 'ready') {
+            result = await provider.query(request, input.signal);
+        }
+        else if (input.kind === 'symbol') {
+            result = await runTextQuery(request, 'structure', input.signal);
+        }
+        else {
+            result = succeeded({
+                schema: 'pappra/code-query-result/1',
+                provider: 'text',
+                kind: input.kind,
+                query: input.query,
+                identityDigest: codeIdentityDigest(observed.identity),
+                observedIdentity: observed.identity,
+                coverage: 'unsupported',
+                items: [],
+                bytes: 0,
+                truncated: false,
+                reasons: [...observed.health.reasons, 'index_not_ready'],
+                evidence: observed.health.evidence,
+                unsupportedReason: 'The selected code index is not ready; only text or structure fallback is available.',
+            });
+        }
+        if (!result.ok) {
+            return {
+                ok: false,
+                result: null,
+                health: observed.health,
+                diagnostics: [
+                    ...observed.diagnostics,
+                    outcomeDiagnostic(result, observed.identity.root),
+                ],
+            };
+        }
+        return {
+            ok: result.value.coverage !== 'unsupported',
+            result: result.value,
+            health: observed.health,
+            diagnostics: [...observed.diagnostics],
+        };
+    }
+}
+export { codeIdentityDigest };

package/dist/code/text.d.ts

@@ -0,0 +1,3 @@
+import { type Outcome } from '../schemas/outcome.js';
+import type { CodeQueryRequest, CodeQueryResult } from '../schemas/code.js';
+export declare function runTextQuery(request: CodeQueryRequest, mode: 'text' | 'structure', signal?: AbortSignal): Promise<Outcome<CodeQueryResult>>;