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

package/dist/infra/fs.js

@@ -0,0 +1,130 @@
+import { createHash } from 'node:crypto';
+import { open, lstat, realpath, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { errorMessage, failed, succeeded } from '../schemas/outcome.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+export const DEFAULT_CONFIG_MAX_BYTES = 1024 * 1024;
+export function sha256Digest(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function filesystemFailure(path, error) {
+    const code = typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : null;
+    if (code === 'ENOENT') {
+        return failed(diagnosticCodes.fileNotFound, `File not found: ${path}`, {
+            nextAction: 'Create the file or correct the path.',
+        });
+    }
+    return failed(diagnosticCodes.fileUnreadable, `Cannot read ${path}: ${errorMessage(error)}`, { nextAction: 'Check file permissions and the path.' });
+}
+/**
+ * Reads at most `maxBytes + 1` bytes from a regular file. The implementation
+ * never loads a larger file into memory just to report that it is too large.
+ */
+export async function readFileBounded(path, maxBytes = DEFAULT_CONFIG_MAX_BYTES) {
+    // Check the type before opening: opening a FIFO for reading can block until
+    // a writer appears. O_NONBLOCK also covers a file replaced after this stat.
+    let pathStats;
+    try {
+        pathStats = await stat(path);
+    }
+    catch (error) {
+        return filesystemFailure(path, error);
+    }
+    if (!pathStats.isFile()) {
+        return failed(diagnosticCodes.fileNotRegular, `Not a regular file: ${path}`, { nextAction: 'Replace it with a regular file.' });
+    }
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY |
+            (process.platform === 'win32' ? 0 : constants.O_NONBLOCK));
+    }
+    catch (error) {
+        return filesystemFailure(path, error);
+    }
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            return failed(diagnosticCodes.fileNotRegular, `Not a regular file: ${path}`, { nextAction: 'Replace it with a regular file.' });
+        }
+        const buffer = Buffer.allocUnsafe(maxBytes + 1);
+        let total = 0;
+        while (total < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+        }
+        if (total > maxBytes) {
+            return failed(diagnosticCodes.fileTooLarge, `File exceeds the ${maxBytes}-byte limit: ${path}`, {
+                nextAction: 'Reduce the file size; Pappra does not truncate configuration.',
+            });
+        }
+        const bytes = buffer.subarray(0, total);
+        return succeeded({
+            bytes,
+            digest: sha256Digest(bytes),
+            size: total,
+        });
+    }
+    catch (error) {
+        return filesystemFailure(path, error);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export async function readTextFileBounded(path, maxBytes = DEFAULT_CONFIG_MAX_BYTES) {
+    const read = await readFileBounded(path, maxBytes);
+    if (!read.ok)
+        return read;
+    let text;
+    try {
+        text = new TextDecoder('utf-8', {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(read.value.bytes);
+    }
+    catch (error) {
+        return failed(diagnosticCodes.fileInvalidEncoding, `File is not valid UTF-8: ${path} (${errorMessage(error)})`, { nextAction: 'Re-save the file as UTF-8 without invalid bytes.' });
+    }
+    return succeeded({ ...read.value, text });
+}
+/** Observes one path segment without following a final symlink. */
+export async function observePath(path) {
+    try {
+        const stats = await lstat(path);
+        const kind = stats.isSymbolicLink()
+            ? 'symlink'
+            : stats.isDirectory()
+                ? 'directory'
+                : stats.isFile()
+                    ? 'file'
+                    : 'other';
+        return { kind, path, stats };
+    }
+    catch (error) {
+        const code = typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            typeof error.code === 'string'
+            ? error.code
+            : null;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return { kind: 'missing', path, stats: null };
+        }
+        throw error;
+    }
+}
+export async function resolveRealpath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/infra/git.d.ts

@@ -0,0 +1,60 @@
+import type { EvidenceRef } from '../schemas/evidence.js';
+import type { Outcome } from '../schemas/outcome.js';
+export declare const DEFAULT_GIT_TIMEOUT_MS = 5000;
+export declare const DEFAULT_GIT_MAX_OUTPUT_BYTES: number;
+export interface RunGitOptions {
+    readonly cwd: string;
+    readonly args: readonly string[];
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+    /** Exit codes that still produce an observable result. Defaults to [0]. */
+    readonly acceptedExitCodes?: readonly number[];
+    /** Bytes written to git stdin, for commands such as check-ignore --stdin. */
+    readonly input?: string;
+    readonly signal?: AbortSignal;
+}
+export interface GitCommandResult {
+    readonly args: readonly string[];
+    readonly stdout: string;
+    readonly stdoutBytes: number;
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly durationMs: number;
+}
+/**
+ * Runs one git command with an argv boundary, a timeout, and bounded output.
+ * Discovery never fetches, checks out, or runs hooks here; every call is a
+ * read-only query.
+ */
+export declare function runGit(options: RunGitOptions): Promise<Outcome<GitCommandResult>>;
+export type GitRepositoryKind = 'regular' | 'linked-worktree' | 'submodule' | 'bare';
+export interface GitRepositoryObservation {
+    readonly kind: GitRepositoryKind;
+    readonly root: string;
+    readonly gitDir: string;
+    readonly commonDir: string;
+    readonly superproject: string | null;
+    readonly head: string | null;
+    readonly branch: string | null;
+    readonly detached: boolean;
+    readonly dirty: boolean | null;
+    readonly limitations: readonly string[];
+    readonly evidence: readonly EvidenceRef[];
+}
+export interface InspectGitRepositoryOptions {
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Observes a repository without modifying the index, refs, or working tree.
+ * The caller supplies the expected checkout root; a subdirectory of a larger
+ * repository is rejected instead of being silently classified as the root.
+ */
+export declare function inspectGitRepository(candidateRoot: string, options?: InspectGitRepositoryOptions): Promise<Outcome<GitRepositoryObservation>>;
+/**
+ * Returns the absolute paths ignored by git for the supplied candidates.
+ * `check-ignore` is read-only; a failure is reported rather than treated as
+ * "nothing is ignored".
+ */
+export declare function filterGitIgnored(repositoryRoot: string, candidates: readonly string[], options?: InspectGitRepositoryOptions): Promise<Outcome<readonly string[]>>;

package/dist/infra/git.js

@@ -0,0 +1,358 @@
+import { spawn } from 'node:child_process';
+import { relative, resolve, sep } from 'node:path';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { errorMessage, failed, succeeded } from '../schemas/outcome.js';
+import { samePath } from '../schemas/paths.js';
+import { sha256Digest, resolveRealpath } from './fs.js';
+export const DEFAULT_GIT_TIMEOUT_MS = 5_000;
+export const DEFAULT_GIT_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+function sanitizedGitEnvironment() {
+    const environment = { ...process.env };
+    for (const key of [
+        'GIT_DIR',
+        'GIT_WORK_TREE',
+        'GIT_COMMON_DIR',
+        'GIT_INDEX_FILE',
+        'GIT_OBJECT_DIRECTORY',
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+        'GIT_NAMESPACE',
+        'GIT_PREFIX',
+        'GIT_CEILING_DIRECTORIES',
+        'GIT_CONFIG_COUNT',
+        'GIT_CONFIG_PARAMETERS',
+    ]) {
+        delete environment[key];
+    }
+    environment.GIT_OPTIONAL_LOCKS = '0';
+    environment.GIT_TERMINAL_PROMPT = '0';
+    environment.GIT_PAGER = 'cat';
+    environment.LC_ALL = 'C';
+    return environment;
+}
+/**
+ * Runs one git command with an argv boundary, a timeout, and bounded output.
+ * Discovery never fetches, checks out, or runs hooks here; every call is a
+ * read-only query.
+ */
+export function runGit(options) {
+    if (options.signal?.aborted === true) {
+        return Promise.resolve(failed(diagnosticCodes.gitAborted, 'Git observation was cancelled.', {
+            nextAction: 'Retry discovery when cancellation is no longer requested.',
+        }));
+    }
+    const cwd = resolve(options.cwd);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_GIT_MAX_OUTPUT_BYTES;
+    const acceptedExitCodes = options.acceptedExitCodes ?? [0];
+    const startedAt = performance.now();
+    return new Promise((resolveResult) => {
+        let settled = false;
+        let timedOut = false;
+        let aborted = false;
+        let outputExceeded = false;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let outputBytes = 0;
+        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;
+            child.kill('SIGKILL');
+        };
+        try {
+            child = spawn('git', ['-c', 'core.fsmonitor=false', ...options.args], {
+                cwd,
+                shell: false,
+                env: sanitizedGitEnvironment(),
+                stdio: [
+                    options.input === undefined ? 'ignore' : 'pipe',
+                    'pipe',
+                    'pipe',
+                ],
+            });
+        }
+        catch (error) {
+            settle(failed(diagnosticCodes.gitUnavailable, `Cannot start git: ${errorMessage(error)}`, { nextAction: 'Install git and ensure it is on PATH.' }));
+            return;
+        }
+        timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        options.signal?.addEventListener('abort', abort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            outputBytes += chunk.byteLength;
+            if (outputBytes > maxOutputBytes) {
+                outputExceeded = true;
+                child.kill('SIGKILL');
+                return;
+            }
+            stdoutChunks.push(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            outputBytes += chunk.byteLength;
+            if (outputBytes > maxOutputBytes) {
+                outputExceeded = true;
+                child.kill('SIGKILL');
+                return;
+            }
+            stderrChunks.push(chunk);
+        });
+        child.on('error', (error) => {
+            settle(failed(diagnosticCodes.gitUnavailable, `Cannot run git ${options.args.join(' ')}: ${errorMessage(error)}`, { nextAction: 'Install git and ensure it is on PATH.' }));
+        });
+        child.on('close', (exitCode, signal) => {
+            const durationMs = Math.round(performance.now() - startedAt);
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            if (timedOut) {
+                settle(failed(diagnosticCodes.gitTimeout, `git ${options.args[0] ?? ''} timed out after ${timeoutMs}ms in ${cwd}.`, {
+                    retryable: true,
+                    nextAction: 'Retry with a healthy repository or a larger timeout.',
+                }));
+                return;
+            }
+            if (aborted) {
+                settle(failed(diagnosticCodes.gitAborted, 'Git observation was cancelled.', {
+                    nextAction: 'Retry discovery when cancellation is no longer requested.',
+                }));
+                return;
+            }
+            if (outputExceeded) {
+                settle(failed(diagnosticCodes.gitOutputLimit, `git ${options.args[0] ?? ''} exceeded the ${maxOutputBytes}-byte output limit in ${cwd}.`, {
+                    nextAction: 'Narrow the repository scope; output was not truncated into a success.',
+                }));
+                return;
+            }
+            if (exitCode === null) {
+                settle(failed(diagnosticCodes.gitCommandFailed, `git ${options.args[0] ?? ''} ended without an exit code (signal ${signal ?? 'unknown'}).`, {
+                    retryable: true,
+                    nextAction: 'Retry and inspect the repository state.',
+                }));
+                return;
+            }
+            if (!acceptedExitCodes.includes(exitCode)) {
+                const detail = stderr.trim().split('\n')[0]?.slice(0, 500) ?? '';
+                settle(failed(diagnosticCodes.gitCommandFailed, `git ${options.args.join(' ')} exited ${exitCode} in ${cwd}${detail === '' ? '' : `: ${detail}`}`, { nextAction: 'Inspect the repository and git installation.' }));
+                return;
+            }
+            settle(succeeded({
+                args: options.args,
+                stdout,
+                stdoutBytes: Buffer.byteLength(stdout, 'utf8'),
+                stderr,
+                exitCode,
+                durationMs,
+            }));
+        });
+        if (options.input !== undefined && child.stdin !== null) {
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(options.input);
+        }
+    });
+}
+function gitEvidence(ref, stdout) {
+    return {
+        kind: 'git',
+        ref,
+        digest: sha256Digest(stdout),
+        observedAt: new Date().toISOString(),
+        scope: 'live-owned',
+    };
+}
+function splitLines(value) {
+    return value
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0);
+}
+/**
+ * Observes a repository without modifying the index, refs, or working tree.
+ * The caller supplies the expected checkout root; a subdirectory of a larger
+ * repository is rejected instead of being silently classified as the root.
+ */
+export async function inspectGitRepository(candidateRoot, options = {}) {
+    const root = (await resolveRealpath(candidateRoot)) ?? resolve(candidateRoot);
+    const evidence = [];
+    const limitations = [];
+    const run = (args) => runGit({
+        cwd: root,
+        args,
+        ...(options.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: options.timeoutMs }),
+        ...(options.maxOutputBytes === undefined
+            ? {}
+            : { maxOutputBytes: options.maxOutputBytes }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const optional = (args) => runGit({
+        cwd: root,
+        args,
+        acceptedExitCodes: [0, 1],
+        ...(options.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: options.timeoutMs }),
+        ...(options.maxOutputBytes === undefined
+            ? {}
+            : { maxOutputBytes: options.maxOutputBytes }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const bareResult = await run(['rev-parse', '--is-bare-repository']);
+    if (!bareResult.ok)
+        return bareResult;
+    evidence.push(gitEvidence('git:rev-parse --is-bare-repository', bareResult.value.stdout));
+    const isBare = bareResult.value.stdout.trim() === 'true';
+    const identity = await run([
+        'rev-parse',
+        '--path-format=absolute',
+        ...(isBare ? [] : ['--show-toplevel']),
+        '--absolute-git-dir',
+        '--git-common-dir',
+    ]);
+    if (!identity.ok)
+        return identity;
+    evidence.push(gitEvidence('git:rev-parse identity', identity.value.stdout));
+    const lines = splitLines(identity.value.stdout);
+    const expectedLines = isBare ? 2 : 3;
+    if (lines.length < expectedLines) {
+        return failed(diagnosticCodes.gitCommandFailed, `git returned an incomplete repository identity for ${root}.`, {
+            nextAction: 'Inspect the repository metadata; no configuration was changed.',
+        });
+    }
+    const observedRoot = isBare ? root : (lines[0] ?? '');
+    const gitDir = lines[isBare ? 0 : 1] ?? '';
+    const commonDir = lines[isBare ? 1 : 2] ?? '';
+    if (!isBare) {
+        const realRoot = root;
+        if (!samePath(resolve(observedRoot), realRoot)) {
+            return failed(diagnosticCodes.repositoryNotGit, `${root} is not a repository root; git resolves it to ${observedRoot}.`, {
+                nextAction: 'Declare the actual repository root, or discover it as part of a scan.',
+            });
+        }
+    }
+    const superprojectResult = await run([
+        'rev-parse',
+        '--show-superproject-working-tree',
+    ]);
+    let superproject = null;
+    if (superprojectResult.ok) {
+        const value = superprojectResult.value.stdout.trim();
+        superproject = value === '' ? null : value;
+    }
+    else {
+        limitations.push('superproject state unavailable');
+    }
+    const headResult = await optional([
+        'rev-parse',
+        '--verify',
+        '--quiet',
+        'HEAD',
+    ]);
+    let head = null;
+    if (headResult.ok) {
+        const value = headResult.value.stdout.trim();
+        head = value === '' ? null : value;
+    }
+    else {
+        limitations.push('HEAD unavailable');
+    }
+    const branchResult = await optional([
+        'symbolic-ref',
+        '--short',
+        '-q',
+        'HEAD',
+    ]);
+    let branch = null;
+    if (branchResult.ok) {
+        const value = branchResult.value.stdout.trim();
+        branch = value === '' ? null : value;
+    }
+    else {
+        limitations.push('branch unavailable');
+    }
+    let dirty = null;
+    const statusResult = await run([
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--untracked-files=normal',
+    ]);
+    if (statusResult.ok) {
+        dirty = statusResult.value.stdout.length > 0;
+    }
+    else {
+        limitations.push(`working tree state unavailable: ${statusResult.message}`);
+    }
+    const kind = isBare
+        ? 'bare'
+        : !samePath(gitDir, commonDir)
+            ? 'linked-worktree'
+            : superproject === null
+                ? 'regular'
+                : 'submodule';
+    return succeeded({
+        kind,
+        root: isBare ? root : resolve(observedRoot),
+        gitDir: resolve(gitDir),
+        commonDir: resolve(commonDir),
+        superproject,
+        head,
+        branch,
+        detached: head !== null && branch === null,
+        dirty,
+        limitations,
+        evidence,
+    });
+}
+/**
+ * Returns the absolute paths ignored by git for the supplied candidates.
+ * `check-ignore` is read-only; a failure is reported rather than treated as
+ * "nothing is ignored".
+ */
+export async function filterGitIgnored(repositoryRoot, candidates, options = {}) {
+    if (candidates.length === 0)
+        return succeeded([]);
+    const root = resolve(repositoryRoot);
+    const relativePaths = [];
+    for (const candidate of candidates) {
+        const path = relative(root, candidate);
+        if (path === '' || path === '..' || path.startsWith(`..${sep}`))
+            continue;
+        relativePaths.push(path.split('\\').join('/'));
+    }
+    if (relativePaths.length === 0)
+        return succeeded([]);
+    const input = `${relativePaths.join('\0')}\0`;
+    const result = await runGit({
+        cwd: root,
+        args: ['check-ignore', '--stdin', '-z'],
+        input,
+        acceptedExitCodes: [0, 1],
+        ...(options.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: options.timeoutMs }),
+        ...(options.maxOutputBytes === undefined
+            ? {}
+            : { maxOutputBytes: options.maxOutputBytes }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!result.ok)
+        return result;
+    const ignored = [];
+    for (const item of result.value.stdout.split('\0')) {
+        if (item === '')
+            continue;
+        ignored.push(resolve(root, ...item.split('/')));
+    }
+    return succeeded(ignored);
+}