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

package/dist/workspace/config-file.js

@@ -0,0 +1,237 @@
+import { join, resolve } from 'node:path';
+import { createDiagnostic, hasErrors, pointer, } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { errorMessage } from '../schemas/outcome.js';
+import { isPathInside } from '../schemas/paths.js';
+import { DEFAULT_CONFIG_MAX_BYTES, observePath, readTextFileBounded, resolveRealpath, } from '../infra/fs.js';
+function issuePointer(path) {
+    return pointer(...path.map((segment) => String(segment)));
+}
+function issueDiagnostics(issues, source) {
+    const diagnostics = [];
+    for (const issue of issues) {
+        if (issue.code === 'unrecognized_keys') {
+            const base = issuePointer(issue.path);
+            for (const key of issue.keys) {
+                diagnostics.push(createDiagnostic({
+                    code: diagnosticCodes.configUnknownKey,
+                    severity: 'error',
+                    message: `Unknown key "${key}".`,
+                    source,
+                    pointer: `${base}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`,
+                    hint: 'Remove the key or declare intentional extension data under the existing "extensions" field. A new top-level field requires a schema version change.',
+                }));
+            }
+            continue;
+        }
+        diagnostics.push(createDiagnostic({
+            code: diagnosticCodes.configSchemaInvalid,
+            severity: 'error',
+            message: issue.message,
+            source,
+            pointer: issue.path.length === 0 ? '' : issuePointer(issue.path),
+            hint: 'Correct the value; Pappra does not coerce or silently ignore configuration.',
+        }));
+    }
+    return diagnostics;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads, decodes, validates, and semantically checks one strict JSON
+ * configuration file. Missing configuration is reported instead of defaulted.
+ */
+export async function inspectConfigFile(options) {
+    const source = options.path;
+    let observation;
+    try {
+        observation = await observePath(options.path);
+    }
+    catch (error) {
+        return {
+            path: options.path,
+            exists: true,
+            digest: null,
+            size: null,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.fileUnreadable,
+                    severity: 'error',
+                    message: `Cannot inspect ${options.path}: ${errorMessage(error)}`,
+                    source,
+                    hint: 'Check file permissions and the path.',
+                }),
+            ],
+        };
+    }
+    if (observation.kind === 'missing') {
+        return {
+            path: options.path,
+            exists: false,
+            digest: null,
+            size: null,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.configMissing,
+                    severity: options.missing.severity,
+                    message: options.missing.message,
+                    source,
+                    hint: options.missing.hint,
+                }),
+            ],
+        };
+    }
+    const realPath = await resolveRealpath(options.path);
+    if (realPath !== null &&
+        options.containmentRoot !== undefined &&
+        !isPathInside(options.containmentRoot, realPath)) {
+        return {
+            path: options.path,
+            exists: true,
+            digest: null,
+            size: null,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.configSymlinkEscape,
+                    severity: 'error',
+                    message: `Configuration file resolves outside the workspace: ${realPath}`,
+                    source,
+                    hint: 'Keep the configuration inside .pappra/; external symlinks are not followed.',
+                }),
+            ],
+        };
+    }
+    const read = await readTextFileBounded(options.path, options.maxBytes ?? DEFAULT_CONFIG_MAX_BYTES);
+    if (!read.ok) {
+        return {
+            path: options.path,
+            exists: true,
+            digest: null,
+            size: null,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: read.code,
+                    severity: 'error',
+                    message: read.message,
+                    source,
+                    hint: read.nextAction,
+                }),
+            ],
+        };
+    }
+    const { digest, size, text } = read.value;
+    if (text.startsWith('\uFEFF')) {
+        return {
+            path: options.path,
+            exists: true,
+            digest,
+            size,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.configInvalidJson,
+                    severity: 'error',
+                    message: 'Configuration starts with a UTF-8 BOM.',
+                    source,
+                    hint: 'Remove the BOM; Pappra does not rewrite configuration during inspection.',
+                }),
+            ],
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        return {
+            path: options.path,
+            exists: true,
+            digest,
+            size,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.configInvalidJson,
+                    severity: 'error',
+                    message: `Invalid JSON: ${errorMessage(error)}`,
+                    source,
+                    hint: 'Fix the JSON syntax; the original file was not modified.',
+                }),
+            ],
+        };
+    }
+    if (isRecord(raw) &&
+        typeof raw['schema'] === 'string' &&
+        raw['schema'] !== options.schemaName) {
+        return {
+            path: options.path,
+            exists: true,
+            digest,
+            size,
+            value: null,
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.configUnsupportedSchema,
+                    severity: 'error',
+                    message: `Unsupported schema "${raw['schema']}"; this version reads only "${options.schemaName}".`,
+                    source,
+                    pointer: pointer('schema'),
+                    hint: 'Pappra will not migrate, overwrite, or partially interpret this file. Keep it and use a compatible Pappra version.',
+                }),
+            ],
+        };
+    }
+    const parsed = options.schema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            path: options.path,
+            exists: true,
+            digest,
+            size,
+            value: null,
+            diagnostics: issueDiagnostics(parsed.error.issues, source),
+        };
+    }
+    const diagnostics = options.semantic?.(parsed.data) ?? [];
+    return {
+        path: options.path,
+        exists: true,
+        digest,
+        size,
+        value: hasErrors(diagnostics) ? null : parsed.data,
+        diagnostics,
+    };
+}
+/** Converts an inspection into a convenience result for callers that fail closed. */
+export function requireConfig(inspection) {
+    if (inspection.value !== null) {
+        return { ok: true, value: inspection.value };
+    }
+    const firstError = inspection.diagnostics.find((entry) => entry.severity === 'error') ??
+        inspection.diagnostics[0];
+    if (firstError === undefined) {
+        return {
+            ok: false,
+            code: diagnosticCodes.configSchemaInvalid,
+            message: `Configuration is unavailable: ${inspection.path}`,
+            retryable: false,
+            nextAction: 'Run pappra doctor after correcting the configuration.',
+        };
+    }
+    return {
+        ok: false,
+        code: firstError.code,
+        message: firstError.message,
+        retryable: false,
+        nextAction: firstError.hint,
+    };
+}
+/** Joins a workspace-relative configuration path without normalizing above root. */
+export function workspaceConfigPath(root) {
+    return join(resolve(root), '.pappra', 'workspace.json');
+}

package/dist/workspace/config.d.ts

@@ -0,0 +1,28 @@
+import { type MachineConfig } from '../schemas/machine.js';
+import type { Outcome } from '../schemas/outcome.js';
+import { type WorkspaceConfig } from '../schemas/workspace.js';
+import { type ConfigFileInspection } from './config-file.js';
+export interface WorkspaceConfigInspection extends ConfigFileInspection<WorkspaceConfig> {
+    readonly root: string;
+}
+export interface MachineConfigInspection extends ConfigFileInspection<MachineConfig> {
+    readonly root: string;
+}
+export interface InspectWorkspaceConfigOptions {
+    /** Missing workspace configuration is fatal by default; discovery may expect it. */
+    readonly missing?: 'error' | 'info';
+}
+/**
+ * Inspects `.pappra/workspace.json` without changing it. Invalid or unsupported
+ * configuration yields `value: null` and structured diagnostics.
+ */
+export declare function inspectWorkspaceConfig(root: string, options?: InspectWorkspaceConfigOptions): Promise<WorkspaceConfigInspection>;
+/**
+ * Inspects `.pappra/local/machine.json`. The local file is allowed to be absent
+ * on a fresh clone, but a present invalid or mismatched file is never used.
+ */
+export declare function inspectMachineConfig(root: string): Promise<MachineConfigInspection>;
+/** Fails closed when configuration is missing or invalid. */
+export declare function loadWorkspaceConfig(root: string, options?: InspectWorkspaceConfigOptions): Promise<Outcome<WorkspaceConfig>>;
+/** Fails closed when an external mapping or runtime location is required. */
+export declare function loadMachineConfig(root: string): Promise<Outcome<MachineConfig>>;

package/dist/workspace/config.js

@@ -0,0 +1,79 @@
+import { join, resolve } from 'node:path';
+import { createDiagnostic, pointer } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { MACHINE_SCHEMA, machineConfigSchema, validateMachineConfigSemantics, } from '../schemas/machine.js';
+import { samePath } from '../schemas/paths.js';
+import { WORKSPACE_SCHEMA, validateWorkspaceConfigSemantics, workspaceConfigSchema, } from '../schemas/workspace.js';
+import { resolveRealpath } from '../infra/fs.js';
+import { inspectConfigFile, requireConfig, } from './config-file.js';
+async function canonicalRoot(root) {
+    const absolute = resolve(root);
+    return (await resolveRealpath(absolute)) ?? absolute;
+}
+/**
+ * Inspects `.pappra/workspace.json` without changing it. Invalid or unsupported
+ * configuration yields `value: null` and structured diagnostics.
+ */
+export async function inspectWorkspaceConfig(root, options = {}) {
+    const canonical = await canonicalRoot(root);
+    const configPath = join(canonical, '.pappra', 'workspace.json');
+    const inspection = await inspectConfigFile({
+        path: configPath,
+        schemaName: WORKSPACE_SCHEMA,
+        schema: workspaceConfigSchema,
+        containmentRoot: canonical,
+        missing: {
+            severity: options.missing ?? 'error',
+            message: `Workspace configuration not found: ${configPath}`,
+            hint: 'Run pappra init in the intended workspace root; Pappra does not guess configuration.',
+        },
+        semantic: (config) => validateWorkspaceConfigSemantics(config, { configPath }),
+    });
+    return { root: canonical, ...inspection };
+}
+/**
+ * Inspects `.pappra/local/machine.json`. The local file is allowed to be absent
+ * on a fresh clone, but a present invalid or mismatched file is never used.
+ */
+export async function inspectMachineConfig(root) {
+    const canonical = await canonicalRoot(root);
+    const configPath = join(canonical, '.pappra', 'local', 'machine.json');
+    const inspection = await inspectConfigFile({
+        path: configPath,
+        schemaName: MACHINE_SCHEMA,
+        schema: machineConfigSchema,
+        containmentRoot: canonical,
+        missing: {
+            severity: 'info',
+            message: `Local machine configuration not found: ${configPath}`,
+            hint: 'Pappra init can create machine.json on this checkout; shared workspace.json does not contain absolute paths.',
+        },
+        semantic: (config) => validateMachineConfigSemantics(config, { configPath }),
+    });
+    const diagnostics = [...inspection.diagnostics];
+    let value = inspection.value;
+    if (value !== null) {
+        const recorded = (await resolveRealpath(value.workspaceRealpath)) ??
+            resolve(value.workspaceRealpath);
+        if (!samePath(recorded, canonical)) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.machineWorkspaceMismatch,
+                severity: 'error',
+                message: `machine.json belongs to ${value.workspaceRealpath}, not ${canonical}.`,
+                source: configPath,
+                pointer: pointer('workspaceRealpath'),
+                hint: 'This checkout was moved or copied. Rebind the local mapping explicitly instead of reusing the old identity.',
+            }));
+            value = null;
+        }
+    }
+    return { root: canonical, ...inspection, value, diagnostics };
+}
+/** Fails closed when configuration is missing or invalid. */
+export async function loadWorkspaceConfig(root, options = {}) {
+    return requireConfig(await inspectWorkspaceConfig(root, options));
+}
+/** Fails closed when an external mapping or runtime location is required. */
+export async function loadMachineConfig(root) {
+    return requireConfig(await inspectMachineConfig(root));
+}

package/dist/workspace/discover.d.ts

@@ -0,0 +1,34 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { MachineConfig } from '../schemas/machine.js';
+import type { WorkspaceConfig } from '../schemas/workspace.js';
+import type { DiscoveredDocument, DiscoveredRepository, DiscoveryOptions, MachineConfigState, UnresolvedRepository, ValidationCandidate, WorkspaceConfigState } from './types.js';
+export interface WorkspaceDiscovery {
+    readonly requestedRoot: string;
+    readonly root: string;
+    readonly rootState: 'directory' | 'unavailable';
+    readonly configPath: string;
+    readonly configState: WorkspaceConfigState;
+    readonly config: WorkspaceConfig | null;
+    readonly machinePath: string;
+    readonly machineState: MachineConfigState;
+    readonly machine: MachineConfig | null;
+    readonly repositories: readonly DiscoveredRepository[];
+    readonly unresolvedRepositories: readonly UnresolvedRepository[];
+    /** Nested workspace roots observed and deliberately not entered. */
+    readonly boundaries: readonly string[];
+    readonly documents: readonly DiscoveredDocument[];
+    readonly validationCandidates: readonly ValidationCandidate[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly truncated: boolean;
+    readonly observedAt: string;
+}
+/**
+ * Discovers repositories, rules, documents, and validation candidates under an
+ * explicit workspace root.
+ *
+ * This function is read-only: it never executes package scripts, hooks, git
+ * fetch, or model calls, and never writes configuration. Missing configuration
+ * is reported and discovery continues only with capability-truthful scan data;
+ * invalid configuration is never partially applied.
+ */
+export declare function discoverWorkspace(workspaceRoot: string, options?: DiscoveryOptions): Promise<WorkspaceDiscovery>;

package/dist/workspace/discover.js

@@ -0,0 +1,195 @@
+import { join, resolve } from 'node:path';
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { observePath, resolveRealpath } from '../infra/fs.js';
+import { inspectMachineConfig, inspectWorkspaceConfig } from './config.js';
+import { discoverDocuments } from './documents.js';
+import { discoverRepositories } from './repositories.js';
+import { discoverValidationCandidates } from './validation.js';
+function boundedInteger(name, value, fallback, minimum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new RangeError(`${name} must be an integer >= ${minimum}; received ${String(value)}.`);
+    }
+    return value;
+}
+function normalizeOptions(options) {
+    return {
+        scanDepth: boundedInteger('scanDepth', options.scanDepth, 2, 0),
+        maxDirectories: boundedInteger('maxDirectories', options.maxDirectories, 400, 1),
+        maxDocuments: boundedInteger('maxDocuments', options.maxDocuments, 300, 1),
+        maxEntriesPerDirectory: boundedInteger('maxEntriesPerDirectory', options.maxEntriesPerDirectory, 200, 1),
+        gitTimeoutMs: boundedInteger('gitTimeoutMs', options.gitTimeoutMs, 5_000, 1),
+    };
+}
+function configState(value, exists) {
+    if (value !== null)
+        return 'valid';
+    return exists ? 'invalid' : 'missing';
+}
+function machineState(value, exists) {
+    if (value !== null)
+        return 'valid';
+    return exists ? 'invalid' : 'missing';
+}
+function unavailableDiscovery(requestedRoot, canonicalRoot, diagnostic) {
+    return {
+        requestedRoot,
+        root: canonicalRoot,
+        rootState: 'unavailable',
+        configPath: join(canonicalRoot, '.pappra', 'workspace.json'),
+        configState: 'missing',
+        config: null,
+        machinePath: join(canonicalRoot, '.pappra', 'local', 'machine.json'),
+        machineState: 'missing',
+        machine: null,
+        repositories: [],
+        unresolvedRepositories: [],
+        boundaries: [],
+        documents: [],
+        validationCandidates: [],
+        diagnostics: [diagnostic],
+        truncated: false,
+        observedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Discovers repositories, rules, documents, and validation candidates under an
+ * explicit workspace root.
+ *
+ * This function is read-only: it never executes package scripts, hooks, git
+ * fetch, or model calls, and never writes configuration. Missing configuration
+ * is reported and discovery continues only with capability-truthful scan data;
+ * invalid configuration is never partially applied.
+ */
+export async function discoverWorkspace(workspaceRoot, options = {}) {
+    const normalized = normalizeOptions(options);
+    const requestedRoot = resolve(workspaceRoot);
+    let observation;
+    try {
+        observation = await observePath(requestedRoot);
+    }
+    catch (error) {
+        return unavailableDiscovery(requestedRoot, requestedRoot, createDiagnostic({
+            code: diagnosticCodes.workspaceRootInvalid,
+            severity: 'error',
+            message: `Cannot inspect workspace root: ${requestedRoot} (${error instanceof Error ? error.message : String(error)})`,
+            source: requestedRoot,
+            hint: 'Pass an existing readable directory.',
+        }));
+    }
+    if (observation.kind === 'missing') {
+        return unavailableDiscovery(requestedRoot, requestedRoot, createDiagnostic({
+            code: diagnosticCodes.workspaceRootInvalid,
+            severity: 'error',
+            message: `Workspace root does not exist: ${requestedRoot}`,
+            source: requestedRoot,
+            hint: 'Pass an existing directory; discovery does not create it.',
+        }));
+    }
+    const canonicalRoot = await resolveRealpath(requestedRoot);
+    if (canonicalRoot === null) {
+        return unavailableDiscovery(requestedRoot, requestedRoot, createDiagnostic({
+            code: diagnosticCodes.workspaceRootInvalid,
+            severity: 'error',
+            message: `Cannot resolve workspace root: ${requestedRoot}`,
+            source: requestedRoot,
+            hint: 'Check permissions and the path.',
+        }));
+    }
+    const rootObservation = await observePath(canonicalRoot);
+    if (rootObservation.kind !== 'directory') {
+        return unavailableDiscovery(requestedRoot, canonicalRoot, createDiagnostic({
+            code: diagnosticCodes.workspaceRootInvalid,
+            severity: 'error',
+            message: `Workspace root is not a directory: ${canonicalRoot}`,
+            source: canonicalRoot,
+            hint: 'Pass a directory path.',
+        }));
+    }
+    const [workspaceInspection, machineInspection] = await Promise.all([
+        inspectWorkspaceConfig(canonicalRoot, { missing: 'info' }),
+        inspectMachineConfig(canonicalRoot),
+    ]);
+    const config = workspaceInspection.value;
+    const machine = machineInspection.value;
+    const diagnostics = [
+        ...workspaceInspection.diagnostics,
+        ...machineInspection.diagnostics,
+    ];
+    if (config !== null && machine !== null && machine.runtime !== null) {
+        const runtime = machine.runtime;
+        const executableObservation = await observePath(runtime.executable);
+        if (executableObservation.kind !== 'file' &&
+            executableObservation.kind !== 'symlink') {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.runtimeMissing,
+                severity: 'warning',
+                message: `Recorded runtime does not exist: ${runtime.executable}`,
+                source: machineInspection.path,
+                hint: 'Reinstall or repair the fixed runtime explicitly; discovery never executes it.',
+            }));
+        }
+        if (runtime.version !== config.runtimeVersion) {
+            diagnostics.push(createDiagnostic({
+                code: diagnosticCodes.runtimeVersionMismatch,
+                severity: 'warning',
+                message: `Workspace targets ${config.runtimeVersion}, but the verified local runtime is ${runtime.version}.`,
+                source: machineInspection.path,
+                hint: 'Run an explicit update or repair flow; discovery does not change runtime selection.',
+            }));
+        }
+    }
+    const repositoryDiscovery = await discoverRepositories({
+        root: canonicalRoot,
+        config,
+        machine,
+        configPath: workspaceInspection.path,
+        options: normalized,
+    });
+    const documentDiscovery = await discoverDocuments({
+        root: canonicalRoot,
+        config,
+        configPath: workspaceInspection.path,
+        repositories: repositoryDiscovery.repositories,
+        options: normalized,
+    });
+    const validationDiscovery = await discoverValidationCandidates({
+        root: canonicalRoot,
+        config,
+        configPath: workspaceInspection.path,
+        repositories: repositoryDiscovery.repositories,
+    });
+    const documents = [...documentDiscovery.documents].sort((left, right) => (left.workspaceRelativePath ?? left.path).localeCompare(right.workspaceRelativePath ?? right.path));
+    const boundaries = [
+        ...new Set([
+            ...repositoryDiscovery.boundaries,
+            ...documentDiscovery.boundaries,
+        ]),
+    ];
+    return {
+        requestedRoot,
+        root: canonicalRoot,
+        rootState: 'directory',
+        configPath: workspaceInspection.path,
+        configState: configState(config, workspaceInspection.exists),
+        config,
+        machinePath: machineInspection.path,
+        machineState: machineState(machine, machineInspection.exists),
+        machine,
+        repositories: repositoryDiscovery.repositories,
+        unresolvedRepositories: repositoryDiscovery.unresolved,
+        boundaries,
+        documents,
+        validationCandidates: validationDiscovery.candidates,
+        diagnostics: [
+            ...diagnostics,
+            ...repositoryDiscovery.diagnostics,
+            ...documentDiscovery.diagnostics,
+            ...validationDiscovery.diagnostics,
+        ],
+        truncated: repositoryDiscovery.truncated || documentDiscovery.truncated,
+        observedAt: new Date().toISOString(),
+    };
+}

package/dist/workspace/documents.d.ts

@@ -0,0 +1,21 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import { type WorkspaceConfig } from '../schemas/workspace.js';
+import type { DiscoveredDocument, DiscoveredRepository, NormalizedDiscoveryOptions } from './types.js';
+export interface DocumentDiscoveryInput {
+    readonly root: string;
+    readonly config: WorkspaceConfig | null;
+    readonly configPath: string;
+    readonly repositories: readonly DiscoveredRepository[];
+    readonly options: NormalizedDiscoveryOptions;
+}
+export interface DocumentDiscoveryOutput {
+    readonly documents: readonly DiscoveredDocument[];
+    readonly boundaries: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly truncated: boolean;
+}
+/**
+ * Finds existing rules and documents in place. Content is never read, moved,
+ * or rewritten; only path, kind, provenance and size are reported.
+ */
+export declare function discoverDocuments(input: DocumentDiscoveryInput): Promise<DocumentDiscoveryOutput>;