@akira-tl/forgerelay 1.1.2 → 1.2.0

package/dist/runtime/config/resolution/resolver.js

@@ -0,0 +1,485 @@
+import { createHash } from "node:crypto";
+import * as z from "zod/v4";
+import { configSourceSchema, normalizeConfigSourceShape, resolveExecutionEffect, } from "../definition/definition.js";
+import { configSchemaId } from "../definition/schema.js";
+const SCOPE_RANK = {
+    "built-in": 0,
+    user: 1,
+    project: 2,
+    "project-local": 3,
+    runtime: 4,
+};
+class MissingEnvironmentError extends Error {
+    name;
+    constructor(name) {
+        super(`Required environment variable ${name} is not available.`);
+        this.name = name;
+    }
+}
+export function resolveConfigDomain(input) {
+    const environment = input.environment ?? process.env;
+    const diagnostics = [];
+    const prepared = [];
+    for (const source of input.sources) {
+        const reference = sourceReference(source);
+        const schemaDiagnostic = sourceSchemaDiagnostic(input.definition, source, reference);
+        if (schemaDiagnostic)
+            diagnostics.push(schemaDiagnostic);
+        if (source.deprecation)
+            diagnostics.push(sourceDeprecationDiagnostic(reference, source.deprecation));
+        if (source.error) {
+            diagnostics.push({
+                severity: "error",
+                code: source.error.code,
+                source: reference,
+                message: source.error.message,
+            });
+            continue;
+        }
+        try {
+            const configured = sourceObject(source.normalized
+                ? source.value
+                : normalizeConfigSourceShape(input.definition, source.scope, source.value, source.entryKey));
+            const interpolated = interpolateSource(input.definition, source.scope, configured, environment);
+            const parsed = parseSource(input.definition, source.scope, interpolated);
+            prepared.push({
+                input: source,
+                reference,
+                values: stripSchemaMetadata(parsed),
+                configuredValues: stripSchemaMetadata(configured),
+            });
+        }
+        catch (error) {
+            diagnostics.push(diagnosticForSourceError(reference, error));
+        }
+    }
+    const builtInReference = {
+        id: `built-in:${input.definition.domain}`,
+        scope: "built-in",
+        kind: "built-in",
+        priority: 0,
+    };
+    const shadowBarriers = sourceShadowBarriers(input.sources);
+    const entries = {};
+    const values = {};
+    for (const [name, field] of Object.entries(input.definition.fields)) {
+        if (field.merge === "keyed") {
+            resolveKeyedField({
+                definition: input.definition,
+                name,
+                field,
+                prepared,
+                builtInReference,
+                shadowBarriers,
+                entries,
+                values,
+                diagnostics,
+            });
+            continue;
+        }
+        resolveReplaceField({
+            definition: input.definition,
+            name,
+            field,
+            prepared,
+            builtInReference,
+            shadowBarriers,
+            entries,
+            values,
+            diagnostics,
+        });
+    }
+    const sources = [
+        ...input.sources.map(sourceReference),
+        builtInReference,
+    ].sort(compareSourceReferences);
+    return {
+        domain: input.definition.domain,
+        values,
+        entries,
+        sources,
+        diagnostics,
+    };
+}
+export function assertConfigResolutionValid(resolution) {
+    const errors = resolution.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length === 0)
+        return;
+    const details = errors.map((diagnostic) => {
+        const location = diagnostic.source.location ?? diagnostic.source.id;
+        return `${location}: ${diagnostic.message}`;
+    });
+    throw new Error(`Invalid ForgeRelay ${resolution.domain} configuration: ${details.join("; ")}`);
+}
+function resolveReplaceField(input) {
+    const logicalPath = `${input.definition.domain}.${input.name}`;
+    const candidates = input.prepared
+        .filter((source) => Object.prototype.hasOwnProperty.call(source.values, input.name))
+        .map((source) => ({
+        source: source.reference,
+        value: source.values[input.name],
+        hasValue: true,
+        configuredValue: source.configuredValues[input.name],
+    }));
+    appendBuiltInCandidate(candidates, input.field, input.builtInReference);
+    candidates.sort(compareCandidates);
+    const winner = candidates.find((candidate) => !candidateIsSourceShadowed(candidate, input.shadowBarriers, input.name));
+    if (!winner)
+        return;
+    input.entries[input.name] = {
+        logicalPath,
+        effective: provenanceFor(input.field, winner, logicalPath),
+        shadowed: candidates
+            .filter((candidate) => candidate !== winner)
+            .map((candidate) => ({
+            ...provenanceFor(input.field, candidate, logicalPath),
+            reason: candidateIsSourceShadowed(candidate, input.shadowBarriers, input.name)
+                ? "source-shadowed"
+                : shadowReason(winner, candidate),
+        })),
+    };
+    if (winner.hasValue)
+        input.values[input.name] = winner.value;
+    appendFieldDeprecations(input.diagnostics, input.field, candidates, logicalPath);
+}
+function resolveKeyedField(input) {
+    const sourceValues = input.prepared
+        .filter((source) => Object.prototype.hasOwnProperty.call(source.values, input.name))
+        .map((source) => ({
+        source,
+        value: keyedObject(source.values[input.name], `${input.definition.domain}.${input.name}`),
+        configured: keyedObject(source.configuredValues[input.name], `${input.definition.domain}.${input.name}`),
+    }));
+    let fieldPresent = sourceValues.length > 0;
+    let builtInValue;
+    if (input.field.builtIn.kind === "literal") {
+        builtInValue = keyedObject(input.field.builtIn.value, `${input.definition.domain}.${input.name}`);
+        fieldPresent = true;
+    }
+    const keys = new Set();
+    for (const source of sourceValues)
+        for (const key of Object.keys(source.value))
+            keys.add(key);
+    for (const key of Object.keys(builtInValue ?? {}))
+        keys.add(key);
+    const merged = {};
+    for (const key of [...keys].sort()) {
+        const logicalPath = `${input.definition.domain}.${input.name}.${key}`;
+        const candidates = sourceValues
+            .filter(({ value }) => Object.prototype.hasOwnProperty.call(value, key))
+            .map(({ source, value, configured }) => ({
+            source: source.reference,
+            value: value[key],
+            hasValue: true,
+            configuredValue: configured[key],
+        }));
+        if (builtInValue && Object.prototype.hasOwnProperty.call(builtInValue, key)) {
+            candidates.push({
+                source: input.builtInReference,
+                value: builtInValue[key],
+                hasValue: true,
+                configuredValue: builtInValue[key],
+            });
+        }
+        candidates.sort(compareCandidates);
+        const entryPath = `${input.name}.${key}`;
+        const winner = candidates.find((candidate) => !candidateIsSourceShadowed(candidate, input.shadowBarriers, entryPath));
+        if (!winner)
+            continue;
+        const tombstone = isDisabledTombstone(winner.value);
+        input.entries[`${input.name}.${key}`] = {
+            logicalPath,
+            effective: provenanceFor(input.field, winner, logicalPath),
+            shadowed: candidates
+                .filter((candidate) => candidate !== winner)
+                .map((candidate) => ({
+                ...provenanceFor(input.field, candidate, logicalPath),
+                reason: candidateIsSourceShadowed(candidate, input.shadowBarriers, entryPath)
+                    ? "source-shadowed"
+                    : shadowReason(winner, candidate),
+            })),
+            ...(tombstone ? { tombstone: true } : {}),
+        };
+        if (!tombstone)
+            merged[key] = winner.value;
+        appendFieldDeprecations(input.diagnostics, input.field, candidates, logicalPath);
+    }
+    if (fieldPresent)
+        input.values[input.name] = merged;
+}
+function appendBuiltInCandidate(candidates, field, builtInReference) {
+    if (field.builtIn.kind === "literal") {
+        candidates.push({
+            source: builtInReference,
+            value: field.builtIn.value,
+            hasValue: true,
+            configuredValue: field.builtIn.value,
+        });
+    }
+    else if (field.builtIn.kind === "computed") {
+        candidates.push({
+            source: builtInReference,
+            value: undefined,
+            hasValue: false,
+            configuredValue: `<computed: ${field.builtIn.description}>`,
+        });
+    }
+}
+function sourceShadowBarriers(sources) {
+    const scope = new Map();
+    const entries = new Map();
+    for (const source of sources) {
+        if (source.shadowsLowerPriority) {
+            scope.set(source.scope, Math.max(scope.get(source.scope) ?? Number.NEGATIVE_INFINITY, source.priority));
+        }
+        for (const entryPath of source.shadowsLowerPriorityKeys ?? []) {
+            const key = shadowBarrierKey(source.scope, entryPath);
+            entries.set(key, Math.max(entries.get(key) ?? Number.NEGATIVE_INFINITY, source.priority));
+        }
+    }
+    return { scope, entries };
+}
+function candidateIsSourceShadowed(candidate, barriers, entryPath) {
+    const scopeBarrier = barriers.scope.get(candidate.source.scope);
+    const entryBarrier = barriers.entries.get(shadowBarrierKey(candidate.source.scope, entryPath));
+    const barrier = Math.max(scopeBarrier ?? Number.NEGATIVE_INFINITY, entryBarrier ?? Number.NEGATIVE_INFINITY);
+    return candidate.source.priority < barrier;
+}
+function shadowBarrierKey(scope, entryPath) {
+    return `${scope}\0${entryPath}`;
+}
+function parseSource(definition, scope, value) {
+    if (scope === "user" || scope === "project" || scope === "project-local") {
+        return configSourceSchema(definition, scope).parse(value);
+    }
+    if (scope !== "runtime") {
+        throw new Error("Built-in configuration is synthesized from Config Definition metadata.");
+    }
+    const shape = {};
+    for (const [name, field] of Object.entries(definition.fields)) {
+        if (!field.legalScopes.includes("runtime"))
+            continue;
+        shape[name] = field.required ? field.schema : field.schema.optional();
+    }
+    return z.object(shape).strict().parse(value);
+}
+function interpolateSource(definition, scope, configured, environment) {
+    const interpolated = { ...configured };
+    for (const [name, field] of Object.entries(definition.fields)) {
+        if (!field.legalScopes.includes(scope) || field.interpolation !== "env")
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(interpolated, name))
+            continue;
+        interpolated[name] = field.interpolateValue
+            ? field.interpolateValue(interpolated[name], environment)
+            : interpolateValue(interpolated[name], environment);
+    }
+    return interpolated;
+}
+function interpolateValue(value, environment) {
+    if (typeof value === "string") {
+        return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+            const resolved = environment[name];
+            if (resolved === undefined)
+                throw new MissingEnvironmentError(name);
+            return resolved;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => interpolateValue(entry, environment));
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, interpolateValue(entry, environment)]));
+    }
+    return value;
+}
+function provenanceFor(field, candidate, logicalPath) {
+    const executionEffect = candidate.hasValue
+        ? resolveExecutionEffect(field, candidate.value, logicalPath.split("."))
+        : typeof field.executionEffect === "string"
+            ? field.executionEffect
+            : "none";
+    const provenance = {
+        source: candidate.source,
+        configuredValue: safeConfiguredValue(field, candidate.configuredValue),
+        effectiveValue: candidate.hasValue
+            ? safeValue(field, candidate.value)
+            : candidate.configuredValue,
+        reload: field.reload,
+        sensitivity: field.sensitivity,
+        executionEffect,
+    };
+    if (executionEffect === "process" && candidate.hasValue) {
+        Object.defineProperty(provenance, "executionFingerprint", {
+            value: valueFingerprint({ logicalPath, value: candidate.value }),
+            enumerable: false,
+        });
+    }
+    return provenance;
+}
+function safeConfiguredValue(field, value) {
+    if (field.sensitivity !== "sensitive")
+        return structuredClone(value);
+    if (field.interpolation === "env")
+        return preserveEnvironmentReferences(value);
+    return "<redacted>";
+}
+function safeValue(field, value) {
+    if (field.sensitivity === "sensitive")
+        return "<redacted>";
+    return structuredClone(value);
+}
+function valueFingerprint(value) {
+    return createHash("sha256").update(stableJson(value)).digest("base64url");
+}
+function stableJson(value) {
+    return JSON.stringify(normalizeForFingerprint(value)) ?? "undefined";
+}
+function normalizeForFingerprint(value) {
+    if (Array.isArray(value))
+        return value.map(normalizeForFingerprint);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, normalizeForFingerprint(entry)]));
+}
+function preserveEnvironmentReferences(value) {
+    if (typeof value === "string") {
+        return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(value) ? value : "<redacted>";
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => preserveEnvironmentReferences(entry));
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, preserveEnvironmentReferences(entry)]));
+    }
+    return "<redacted>";
+}
+function appendFieldDeprecations(diagnostics, field, candidates, logicalPath) {
+    if (!field.deprecation)
+        return;
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (candidate.source.scope === "built-in" || seen.has(candidate.source.id))
+            continue;
+        seen.add(candidate.source.id);
+        diagnostics.push({
+            severity: "warning",
+            code: "deprecated_source",
+            source: candidate.source,
+            logicalPath,
+            message: `${logicalPath} is deprecated since ForgeRelay ${field.deprecation.since}` +
+                (field.deprecation.replacement ? `; use ${field.deprecation.replacement}.` : "."),
+        });
+    }
+}
+function sourceSchemaDiagnostic(definition, source, reference) {
+    if (source.kind !== "file" || definition.schemaOutput === "none")
+        return undefined;
+    if (source.scope !== "user" && source.scope !== "project" && source.scope !== "project-local")
+        return undefined;
+    if (!isRecord(source.value) || typeof source.value.$schema !== "string")
+        return undefined;
+    const expected = configSchemaId(definition, source.scope);
+    if (source.value.$schema === expected)
+        return undefined;
+    return {
+        severity: "warning",
+        code: "schema_mismatch",
+        source: reference,
+        message: `Configuration $schema does not match the current ${definition.domain} ${source.scope} schema; expected ${expected}.`,
+    };
+}
+function sourceDeprecationDiagnostic(source, deprecation) {
+    return {
+        severity: "warning",
+        code: "deprecated_source",
+        source,
+        message: `Configuration source ${source.location ?? source.id} is deprecated since ForgeRelay ${deprecation.since}` +
+            (deprecation.replacement ? `; use ${deprecation.replacement}.` : "."),
+    };
+}
+function diagnosticForSourceError(source, error) {
+    const missingEnvironment = missingEnvironmentName(error);
+    if (missingEnvironment) {
+        return {
+            severity: "error",
+            code: "missing_environment",
+            source,
+            message: `Required environment variable ${missingEnvironment} is not available.`,
+        };
+    }
+    if (error instanceof z.ZodError) {
+        return {
+            severity: "error",
+            code: "invalid_source",
+            source,
+            message: error.issues.map((issue) => {
+                const path = issue.path.length > 0 ? issue.path.join(".") : "config";
+                return `${path}: ${issue.message}`;
+            }).join("; "),
+        };
+    }
+    return {
+        severity: "error",
+        code: "invalid_source",
+        source,
+        message: error instanceof Error ? error.message : "Configuration source is invalid.",
+    };
+}
+function missingEnvironmentName(error) {
+    if (error instanceof MissingEnvironmentError)
+        return error.name;
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "missing_environment" &&
+        "variable" in error &&
+        typeof error.variable === "string") {
+        return error.variable;
+    }
+    return undefined;
+}
+function sourceObject(value) {
+    if (!isRecord(value))
+        throw new Error("Configuration source must be a JSON object.");
+    return value;
+}
+function keyedObject(value, logicalPath) {
+    if (!isRecord(value))
+        throw new Error(`${logicalPath} must resolve to a keyed object.`);
+    return value;
+}
+function isDisabledTombstone(value) {
+    return isRecord(value) && value.disabled === true;
+}
+function stripSchemaMetadata(value) {
+    const { $schema: _schema, ...rest } = value;
+    return rest;
+}
+function sourceReference(source) {
+    return {
+        id: source.id,
+        scope: source.scope,
+        kind: source.kind,
+        ...(source.location ? { location: source.location } : {}),
+        priority: source.priority,
+    };
+}
+function compareCandidates(left, right) {
+    return compareSourceReferences(left.source, right.source);
+}
+function compareSourceReferences(left, right) {
+    const scope = SCOPE_RANK[right.scope] - SCOPE_RANK[left.scope];
+    if (scope !== 0)
+        return scope;
+    const priority = right.priority - left.priority;
+    if (priority !== 0)
+        return priority;
+    return left.id.localeCompare(right.id);
+}
+function shadowReason(winner, candidate) {
+    return winner.source.scope === candidate.source.scope ? "higher-priority" : "higher-scope";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/runtime/config/resolution/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/config/runtime/config-runtime.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { ConfigSourceRuntime } from "./source-refresh.js";
+export class ConfigRuntime {
+    sources = new ConfigSourceRuntime();
+    applied = new Map();
+    resolutionInputs = new Map();
+    captureResolutionInputs(domain, inputs) {
+        this.resolutionInputs.set(domain, {
+            environment: { ...inputs.environment },
+            ...(inputs.cli ? { cli: structuredClone(inputs.cli) } : {}),
+        });
+    }
+    resolutionInputsFor(domain) {
+        const inputs = this.resolutionInputs.get(domain);
+        if (!inputs)
+            throw new Error(`No runtime resolution inputs are available for ${domain}.`);
+        return {
+            environment: { ...inputs.environment },
+            ...(inputs.cli ? { cli: structuredClone(inputs.cli) } : {}),
+        };
+    }
+    captureApplied(definition, values) {
+        const domain = new Map();
+        for (const [name, field] of Object.entries(definition.fields)) {
+            if (field.reload !== "restart-required")
+                continue;
+            domain.set(name, structuredClone(values[name]));
+        }
+        this.applied.set(definition.domain, domain);
+    }
+    snapshotApplied(definition, configuredValues) {
+        const startup = this.applied.get(definition.domain);
+        if (!startup) {
+            throw new Error(`No applied configuration snapshot is available for ${definition.domain}.`);
+        }
+        const fields = {};
+        let restartRequired = false;
+        for (const [name, field] of Object.entries(definition.fields)) {
+            if (field.reload !== "restart-required")
+                continue;
+            const appliedValue = startup.get(name);
+            const configuredValue = configuredValues[name];
+            const changed = valueFingerprint(appliedValue) !== valueFingerprint(configuredValue);
+            restartRequired ||= changed;
+            fields[name] = {
+                logicalPath: `${definition.domain}.${name}`,
+                configuredValue: safeValue(field.sensitivity, configuredValue),
+                appliedValue: safeValue(field.sensitivity, appliedValue),
+                restartRequired: changed,
+            };
+        }
+        return { domain: definition.domain, restartRequired, fields };
+    }
+}
+function safeValue(sensitivity, value) {
+    if (sensitivity === "sensitive" && value !== undefined)
+        return "<redacted>";
+    return structuredClone(value);
+}
+function valueFingerprint(value) {
+    return createHash("sha256").update(stableJson(value)).digest("base64url");
+}
+function stableJson(value) {
+    return JSON.stringify(normalize(value)) ?? "undefined";
+}
+function normalize(value) {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, normalize(entry)]));
+}