@simplysf/simply-gitlab-core 0.2.0 → 0.3.0

package/lib/baseline-apply.d.ts

@@ -0,0 +1,35 @@
+import type { BaselinePlan, TargetPlan } from './baseline-plan.js';
+import { type RunOptions } from './baseline-run.js';
+import type { GitLabClient } from './gitlab-client.js';
+/** What executing one target's plan amounted to. */
+export interface TargetResult {
+    readonly path: string;
+    readonly kind: 'project' | 'group';
+    readonly applied: number;
+    /** Set when execution stopped part-way; the actions before it are already applied. */
+    readonly error?: string;
+    /** The section that failed, so a partial application can be described precisely. */
+    readonly failedSection?: string;
+}
+export interface ApplyResult {
+    readonly targets: readonly TargetResult[];
+}
+/**
+ * Executes one target's plan, in the order the sections were planned.
+ *
+ * There is no transaction across GitLab endpoints and this does not pretend otherwise: a failure
+ * part-way leaves the earlier sections applied, and the result says which section stopped it so a
+ * following `plan` can be read against that.
+ */
+export declare function applyTarget(client: GitLabClient, target: TargetPlan): Promise<TargetResult>;
+/**
+ * Executes a whole plan.
+ *
+ * One target failing does not abandon the other forty-nine — that is the default, because a run
+ * that stopped at the twelfth project would leave the operator worse off than one that reported
+ * twelve successes and one failure. `--fail-fast` is there for the systematic problem where the
+ * rest are pointless.
+ */
+export declare function applyPlan(client: GitLabClient, plan: BaselinePlan, options?: RunOptions): Promise<ApplyResult>;
+/** How many targets an apply failed on, for the exit code. */
+export declare function applyFailures(result: ApplyResult): readonly TargetResult[];

package/lib/baseline-apply.js

@@ -0,0 +1,177 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { mapPool, DEFAULT_CONCURRENCY } from './baseline-run.js';
+import { ConfigError } from './errors.js';
+function asRecord(value) {
+    return (typeof value === 'object' && value !== null ? value : {});
+}
+/**
+ * Resolves the name-based references an approval rule carries into the ids the API demands.
+ *
+ * This has to happen here rather than at plan time. A rule scoped to `main` needs that branch's
+ * protection id, and the protected-branches section that creates it runs moments earlier in this
+ * same apply — so at plan time the id does not exist yet.
+ */
+async function resolveRuleReferences(client, ref, body, branches, groups) {
+    const resolved = { ...body };
+    if (branches !== undefined && branches.length > 0) {
+        const protectedBranches = (await client.listProtectedBranches(ref)).items.map(asRecord);
+        const byName = new Map(protectedBranches.map((branch) => [String(branch.name), branch.id]));
+        const ids = [];
+        for (const name of branches) {
+            const id = byName.get(name);
+            if (typeof id !== 'number') {
+                throw new ConfigError(`Approval rule references protected branch "${name}", which is not protected on this project. ` +
+                    'Declare it under protectedBranches so it exists before the rule is written.');
+            }
+            ids.push(id);
+        }
+        resolved.protected_branch_ids = ids;
+    }
+    if (groups !== undefined && groups.length > 0) {
+        const ids = [];
+        /* Each group is one lookup; there are rarely more than a couple on a rule. */
+        /* eslint-disable no-await-in-loop */
+        for (const path of groups) {
+            const group = asRecord(await client.getGroup(path));
+            if (typeof group.id !== 'number') {
+                throw new ConfigError(`Approval rule references group "${path}", which could not be resolved to an id.`);
+            }
+            ids.push(group.id);
+        }
+        /* eslint-enable no-await-in-loop */
+        resolved.group_ids = ids;
+    }
+    return resolved;
+}
+/** Executes one action. Split out so the switch stays exhaustive as actions are added. */
+async function execute(client, target, action) {
+    const ref = target.path;
+    switch (action.kind) {
+        case 'updateProject':
+            await client.updateProject(ref, action.body);
+            return;
+        case 'updateGroup':
+            await client.updateGroup(ref, action.body);
+            return;
+        case 'protectBranch':
+            await client.protectBranch(ref, action.body);
+            return;
+        case 'patchProtectedBranch':
+            await client.patchProtectedBranch(ref, action.name, action.body);
+            return;
+        case 'unprotectBranch':
+            await client.unprotectBranch(ref, action.name);
+            return;
+        case 'protectTag':
+            await client.protectTag(ref, action.body);
+            return;
+        case 'unprotectTag':
+            await client.unprotectTag(ref, action.name);
+            return;
+        case 'updateApprovalSettings':
+            await client.updateApprovalSettings(ref, action.body);
+            return;
+        case 'createApprovalRule': {
+            const groups = Array.isArray(action.body.groups) ? action.body.groups : undefined;
+            const body = await resolveRuleReferences(client, ref, action.body, action.branches, groups);
+            await client.createApprovalRule(ref, body);
+            return;
+        }
+        case 'updateApprovalRule': {
+            const groups = Array.isArray(action.body.groups) ? action.body.groups : undefined;
+            const body = await resolveRuleReferences(client, ref, action.body, action.branches, groups);
+            await client.updateApprovalRule(ref, action.ruleId, body);
+            return;
+        }
+        case 'deleteApprovalRule':
+            await client.deleteApprovalRule(ref, action.ruleId);
+            return;
+        case 'setPushRules':
+            // POST creates the rule set, PUT edits it. Which one applies was decided at plan time from
+            // whether the project already had push rules.
+            if (action.exists)
+                await client.updatePushRules(ref, action.body);
+            else
+                await client.createPushRules(ref, action.body);
+            return;
+        default: {
+            const exhaustive = action;
+            throw new ConfigError(`Unknown action ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Executes one target's plan, in the order the sections were planned.
+ *
+ * There is no transaction across GitLab endpoints and this does not pretend otherwise: a failure
+ * part-way leaves the earlier sections applied, and the result says which section stopped it so a
+ * following `plan` can be read against that.
+ */
+export async function applyTarget(client, target) {
+    let applied = 0;
+    for (const section of target.sections) {
+        for (const action of section.actions) {
+            try {
+                // eslint-disable-next-line no-await-in-loop -- order across sections is the contract
+                await execute(client, target, action);
+                applied += 1;
+            }
+            catch (error) {
+                return {
+                    path: target.path,
+                    kind: target.kind,
+                    applied,
+                    failedSection: section.section,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+    }
+    return { path: target.path, kind: target.kind, applied };
+}
+/**
+ * Executes a whole plan.
+ *
+ * One target failing does not abandon the other forty-nine — that is the default, because a run
+ * that stopped at the twelfth project would leave the operator worse off than one that reported
+ * twelve successes and one failure. `--fail-fast` is there for the systematic problem where the
+ * rest are pointless.
+ */
+export async function applyPlan(client, plan, options = {}) {
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    // A target that failed to plan is not applied: acting on a half-read project is how a baseline
+    // makes things worse than it found them.
+    const runnable = plan.targets.filter((target) => target.error === undefined);
+    const unplanned = plan.targets
+        .filter((target) => target.error !== undefined)
+        .map((target) => ({ path: target.path, kind: target.kind, applied: 0, error: target.error }));
+    const groups = runnable.filter((target) => target.kind === 'group');
+    const projects = runnable.filter((target) => target.kind === 'project');
+    const stopAfter = options.failFast === true ? (result) => result.error !== undefined : undefined;
+    // Groups first: a group setting that projects inherit should be in place before the projects are
+    // reconciled against it.
+    const groupResults = await mapPool(groups, concurrency, (target) => applyTarget(client, target), stopAfter);
+    const projectResults = options.failFast === true && groupResults.some((result) => result.error !== undefined)
+        ? []
+        : await mapPool(projects, concurrency, (target) => applyTarget(client, target), stopAfter);
+    return { targets: [...unplanned, ...groupResults, ...projectResults] };
+}
+/** How many targets an apply failed on, for the exit code. */
+export function applyFailures(result) {
+    return result.targets.filter((target) => target.error !== undefined);
+}
+//# sourceMappingURL=baseline-apply.js.map

package/lib/baseline-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-apply.js","sourceRoot":"","sources":["../src/baseline-apply.ts"],"names":[],"mappings":"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"}

package/lib/baseline-config.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The baseline configuration file: what a set of projects should have in common.
+ *
+ * Everything here is data. Reading it, diffing against an instance, and converging are three other
+ * modules; this one only turns a file into a validated, merged description of intent — which is
+ * what makes the merge semantics below testable without a server.
+ *
+ * See docs/design/0007-configuration-baselines.md.
+ */
+export interface BaselineConfig {
+    readonly version: 1;
+    readonly targets?: BaselineTargets;
+    readonly group?: GroupDesired;
+    readonly project?: ProjectDesired;
+    readonly overrides?: Readonly<Record<string, TargetOverride>>;
+}
+export interface BaselineTargets {
+    /** Group paths or ids. Expands to every project in the group and its subgroups. */
+    readonly groups?: readonly string[];
+    /** Individual project paths or ids, added to whatever the groups expanded to. */
+    readonly projects?: readonly string[];
+    /** Removed from the union. A trailing `*` drops a whole subtree. */
+    readonly exclude?: readonly string[];
+}
+export interface TargetOverride {
+    readonly project?: ProjectDesired;
+    readonly group?: GroupDesired;
+}
+export interface GroupDesired {
+    readonly settings?: Readonly<Record<string, unknown>>;
+}
+export interface ProjectDesired {
+    readonly settings?: Readonly<Record<string, unknown>>;
+    readonly protectedBranches?: Section;
+    readonly protectedTags?: Section;
+    readonly approvals?: Readonly<Record<string, unknown>>;
+    readonly approvalRules?: Section;
+    readonly pushRules?: Readonly<Record<string, unknown>>;
+    readonly variables?: Section;
+}
+/** An entry in a keyed section. Fields are GitLab's own, so this stays deliberately open. */
+export type Entry = Readonly<Record<string, unknown>>;
+/**
+ * A list section, in either of the two shapes the file accepts: a bare array, or an object that
+ * can also turn on pruning or wholesale replacement.
+ */
+export type Section = readonly Entry[] | SectionObject;
+export interface SectionObject {
+    /** Delete entries that exist on the instance but are not declared here. Off by default. */
+    readonly prune?: boolean;
+    /** Replace the baseline's entries entirely instead of merging into them, in an override. */
+    readonly $replace?: boolean;
+    readonly entries: readonly Entry[];
+}
+/** A section reduced to the three things every consumer needs. */
+export interface NormalizedSection {
+    readonly prune: boolean;
+    readonly replace: boolean;
+    readonly entries: readonly Entry[];
+}
+/** The list sections, in the order `apply` reconciles them. */
+export declare const LIST_SECTIONS: readonly ["protectedBranches", "protectedTags", "approvalRules", "variables"];
+export type ListSection = (typeof LIST_SECTIONS)[number];
+/** The object sections, which merge key by key rather than by entry. */
+export declare const OBJECT_SECTIONS: readonly ["settings", "approvals", "pushRules"];
+/** The identity of one entry, as a string, for keying a map. */
+export declare function entryKey(section: ListSection, entry: Entry): string;
+/** The human-readable identity of one entry, for plan output. */
+export declare function entryLabel(section: ListSection, entry: Entry): string;
+export declare function normalizeSection(section: Section | undefined): NormalizedSection | undefined;
+/**
+ * Validates the parsed file, reporting the JSON path of whatever is wrong.
+ *
+ * Hand-written rather than schema-driven because the error is the product: a caller who wrote
+ * `"targets": {"group": "x"}` needs to be told that the key is `groups` and that it takes an array,
+ * at that path, not that the document failed to match a schema. The published JSON Schema gives an
+ * editor completion and hover text; this is what runs.
+ */
+export declare function validateBaselineConfig(value: unknown, label?: string): BaselineConfig;
+/**
+ * The effective configuration for one project: the baseline with its override merged over it.
+ *
+ * Objects merge key by key. Lists merge by the section's natural key, so an override adjusts one
+ * entry rather than restating the array — unless it sets `$replace`, which swaps the list wholesale
+ * for the project that genuinely needs different rules rather than adjusted ones.
+ */
+export declare function mergeProjectDesired(base?: ProjectDesired, override?: ProjectDesired): ProjectDesired;
+export declare function mergeGroupDesired(base?: GroupDesired, override?: GroupDesired): GroupDesired;
+/** The effective project configuration for one path, baseline merged with any override for it. */
+export declare function effectiveProject(config: BaselineConfig, path: string): ProjectDesired;
+/** The effective group configuration for one path. */
+export declare function effectiveGroup(config: BaselineConfig, path: string): GroupDesired;
+/**
+ * Reads and validates a baseline config file.
+ *
+ * A parse failure reports only the position, never the parser's snippet of the content — the same
+ * rule the rest of this package follows, because a caller can name any path and the snippet would
+ * echo the first bytes of whatever file that was.
+ */
+export declare function loadBaselineConfig(path: string): BaselineConfig;

package/lib/baseline-config.js

@@ -0,0 +1,342 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ConfigError } from './errors.js';
+import { readTextFile } from './json-input.js';
+/** The list sections, in the order `apply` reconciles them. */
+export const LIST_SECTIONS = ['protectedBranches', 'protectedTags', 'approvalRules', 'variables'];
+/** The object sections, which merge key by key rather than by entry. */
+export const OBJECT_SECTIONS = ['settings', 'approvals', 'pushRules'];
+/**
+ * What identifies an entry within its section, for merging an override onto a baseline and for
+ * matching a declared entry against one that already exists on the instance.
+ *
+ * Every section has a natural key, which is what makes a two-line override possible: restating a
+ * whole array to change one number is how these files rot.
+ */
+const SECTION_KEYS = {
+    protectedBranches: ['name'],
+    protectedTags: ['name'],
+    approvalRules: ['name'],
+    variables: ['key', 'environment_scope'],
+};
+/** GitLab treats an unset environment scope as `*`, so the merge key has to agree with it. */
+const SCOPE_DEFAULTS = { environment_scope: '*' };
+/**
+ * Renders a key field as text.
+ *
+ * Key fields come out of parsed JSON, so they are `unknown` until proven otherwise. Coercing an
+ * object with `String()` would key every such entry as `[object Object]` and silently collide
+ * entries that are not the same thing at all.
+ */
+function keyText(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value) ?? '';
+}
+/** The identity of one entry, as a string, for keying a map. */
+export function entryKey(section, entry) {
+    return SECTION_KEYS[section].map((field) => keyText(entry[field] ?? SCOPE_DEFAULTS[field])).join(' ');
+}
+/** The human-readable identity of one entry, for plan output. */
+export function entryLabel(section, entry) {
+    return SECTION_KEYS[section]
+        .map((field) => keyText(entry[field] ?? SCOPE_DEFAULTS[field]))
+        .filter((part) => part !== '')
+        .join(' @ ');
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function normalizeSection(section) {
+    if (section === undefined)
+        return undefined;
+    if (Array.isArray(section))
+        return { prune: false, replace: false, entries: section };
+    const object = section;
+    return { prune: object.prune === true, replace: object.$replace === true, entries: object.entries };
+}
+// --- Validation ---------------------------------------------------------------------------------
+/**
+ * Validates the parsed file, reporting the JSON path of whatever is wrong.
+ *
+ * Hand-written rather than schema-driven because the error is the product: a caller who wrote
+ * `"targets": {"group": "x"}` needs to be told that the key is `groups` and that it takes an array,
+ * at that path, not that the document failed to match a schema. The published JSON Schema gives an
+ * editor completion and hover text; this is what runs.
+ */
+export function validateBaselineConfig(value, label = 'config') {
+    const problems = [];
+    const at = (path, message) => {
+        problems.push(`${path}: ${message}`);
+    };
+    if (!isPlainObject(value)) {
+        throw new ConfigError(`${label} must be a JSON object.`);
+    }
+    if (value.version !== 1) {
+        at('version', `must be 1, got ${JSON.stringify(value.version)}`);
+    }
+    const known = new Set(['$schema', 'version', 'targets', 'group', 'project', 'overrides']);
+    for (const key of Object.keys(value)) {
+        if (!known.has(key))
+            at(key, `is not a known top-level key (expected one of ${[...known].join(', ')})`);
+    }
+    if (value.targets !== undefined)
+        validateTargets(value.targets, 'targets', at);
+    if (value.group !== undefined)
+        validateGroupDesired(value.group, 'group', at);
+    if (value.project !== undefined)
+        validateProjectDesired(value.project, 'project', at);
+    if (value.overrides !== undefined) {
+        if (!isPlainObject(value.overrides)) {
+            at('overrides', 'must be an object keyed by project or group path');
+        }
+        else {
+            for (const [path, override] of Object.entries(value.overrides)) {
+                const where = `overrides["${path}"]`;
+                if (!isPlainObject(override)) {
+                    at(where, 'must be an object');
+                    continue;
+                }
+                for (const key of Object.keys(override)) {
+                    if (key !== 'project' && key !== 'group')
+                        at(`${where}.${key}`, 'must be "project" or "group"');
+                }
+                if (override.project !== undefined)
+                    validateProjectDesired(override.project, `${where}.project`, at);
+                if (override.group !== undefined)
+                    validateGroupDesired(override.group, `${where}.group`, at);
+            }
+        }
+    }
+    if (problems.length > 0) {
+        // Every problem at once. Fixing a config one error per run, fifty projects into a change, is
+        // the kind of loop that makes people stop using the tool.
+        throw new ConfigError(`${label} is not valid:\n  ${problems.join('\n  ')}`);
+    }
+    return value;
+}
+function validateStringArray(value, path, at) {
+    if (!Array.isArray(value)) {
+        at(path, 'must be an array of strings');
+        return;
+    }
+    for (const [index, item] of value.entries()) {
+        if (typeof item !== 'string' || item.trim() === '') {
+            at(`${path}[${index}]`, `must be a non-empty string, got ${JSON.stringify(item)}`);
+        }
+    }
+}
+function validateTargets(value, path, at) {
+    if (!isPlainObject(value)) {
+        at(path, 'must be an object');
+        return;
+    }
+    const known = new Set(['groups', 'projects', 'exclude']);
+    for (const key of Object.keys(value)) {
+        if (!known.has(key))
+            at(`${path}.${key}`, `is not a known key (expected ${[...known].join(', ')})`);
+    }
+    for (const key of known) {
+        if (value[key] !== undefined)
+            validateStringArray(value[key], `${path}.${key}`, at);
+    }
+    if (value.groups === undefined && value.projects === undefined) {
+        at(path, 'must name at least one of "groups" or "projects"');
+    }
+}
+function validateGroupDesired(value, path, at) {
+    if (!isPlainObject(value)) {
+        at(path, 'must be an object');
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== 'settings')
+            at(`${path}.${key}`, 'is not a known key (expected "settings")');
+    }
+    if (value.settings !== undefined && !isPlainObject(value.settings)) {
+        at(`${path}.settings`, 'must be an object of GitLab group attributes');
+    }
+}
+function validateProjectDesired(value, path, at) {
+    if (!isPlainObject(value)) {
+        at(path, 'must be an object');
+        return;
+    }
+    const known = new Set([...OBJECT_SECTIONS, ...LIST_SECTIONS]);
+    for (const key of Object.keys(value)) {
+        if (!known.has(key))
+            at(`${path}.${key}`, `is not a known section (expected ${[...known].join(', ')})`);
+    }
+    for (const section of OBJECT_SECTIONS) {
+        const entry = value[section];
+        if (entry !== undefined && !isPlainObject(entry)) {
+            at(`${path}.${section}`, 'must be an object of GitLab attributes');
+        }
+    }
+    for (const section of LIST_SECTIONS) {
+        if (value[section] !== undefined)
+            validateListSection(value[section], `${path}.${section}`, section, at);
+    }
+}
+function validateListSection(value, path, section, at) {
+    let entries;
+    if (Array.isArray(value)) {
+        entries = value;
+    }
+    else if (isPlainObject(value)) {
+        const known = new Set(['prune', '$replace', 'entries']);
+        for (const key of Object.keys(value)) {
+            if (!known.has(key))
+                at(`${path}.${key}`, `is not a known key (expected ${[...known].join(', ')})`);
+        }
+        for (const flag of ['prune', '$replace']) {
+            if (value[flag] !== undefined && typeof value[flag] !== 'boolean')
+                at(`${path}.${flag}`, 'must be a boolean');
+        }
+        if (value.entries === undefined) {
+            at(`${path}.entries`, 'is required when the section is written as an object');
+            return;
+        }
+        entries = value.entries;
+    }
+    else {
+        at(path, 'must be an array of entries, or an object with an "entries" array');
+        return;
+    }
+    if (!Array.isArray(entries)) {
+        at(Array.isArray(value) ? path : `${path}.entries`, 'must be an array');
+        return;
+    }
+    const base = Array.isArray(value) ? path : `${path}.entries`;
+    const seen = new Map();
+    for (const [index, entry] of entries.entries()) {
+        const where = `${base}[${index}]`;
+        if (!isPlainObject(entry)) {
+            at(where, 'must be an object');
+            continue;
+        }
+        for (const field of SECTION_KEYS[section]) {
+            // Only the first key field is required; `environment_scope` defaults to `*`, as GitLab does.
+            if (field !== SECTION_KEYS[section][0])
+                continue;
+            if (typeof entry[field] !== 'string' || entry[field].trim() === '') {
+                at(`${where}.${field}`, `is required and must be a non-empty string`);
+            }
+        }
+        const key = entryKey(section, entry);
+        const first = seen.get(key);
+        if (first !== undefined) {
+            // Two entries with the same identity would silently reconcile against each other.
+            at(where, `duplicates ${base}[${first}] (same ${SECTION_KEYS[section].join(' + ')})`);
+        }
+        else {
+            seen.set(key, index);
+        }
+    }
+}
+// --- Merging ------------------------------------------------------------------------------------
+/**
+ * The effective configuration for one project: the baseline with its override merged over it.
+ *
+ * Objects merge key by key. Lists merge by the section's natural key, so an override adjusts one
+ * entry rather than restating the array — unless it sets `$replace`, which swaps the list wholesale
+ * for the project that genuinely needs different rules rather than adjusted ones.
+ */
+export function mergeProjectDesired(base = {}, override = {}) {
+    const merged = {};
+    for (const section of OBJECT_SECTIONS) {
+        const value = mergeObjects(base[section], override[section]);
+        if (value !== undefined)
+            merged[section] = value;
+    }
+    for (const section of LIST_SECTIONS) {
+        const value = mergeSections(section, base[section], override[section]);
+        if (value !== undefined)
+            merged[section] = value;
+    }
+    return merged;
+}
+export function mergeGroupDesired(base = {}, override = {}) {
+    const settings = mergeObjects(base.settings, override.settings);
+    return settings === undefined ? {} : { settings };
+}
+function mergeObjects(base, override) {
+    if (base === undefined && override === undefined)
+        return undefined;
+    return { ...(base ?? {}), ...(override ?? {}) };
+}
+function mergeSections(section, base, override) {
+    const left = normalizeSection(base);
+    const right = normalizeSection(override);
+    if (left === undefined && right === undefined)
+        return undefined;
+    if (left === undefined)
+        return { prune: right.prune, entries: right.entries };
+    if (right === undefined)
+        return { prune: left.prune, entries: left.entries };
+    // Pruning is a property of the section as configured, so an override can turn it on for one
+    // project without the baseline turning it on for all fifty.
+    if (right.replace)
+        return { prune: right.prune, entries: right.entries };
+    const byKey = new Map();
+    const order = [];
+    for (const entry of left.entries) {
+        const key = entryKey(section, entry);
+        if (!byKey.has(key))
+            order.push(key);
+        byKey.set(key, entry);
+    }
+    for (const entry of right.entries) {
+        const key = entryKey(section, entry);
+        const existing = byKey.get(key);
+        if (existing === undefined)
+            order.push(key);
+        byKey.set(key, existing === undefined ? entry : { ...existing, ...entry });
+    }
+    return { prune: right.prune || left.prune, entries: order.map((key) => byKey.get(key)) };
+}
+/** The effective project configuration for one path, baseline merged with any override for it. */
+export function effectiveProject(config, path) {
+    return mergeProjectDesired(config.project, config.overrides?.[path]?.project);
+}
+/** The effective group configuration for one path. */
+export function effectiveGroup(config, path) {
+    return mergeGroupDesired(config.group, config.overrides?.[path]?.group);
+}
+/**
+ * Reads and validates a baseline config file.
+ *
+ * A parse failure reports only the position, never the parser's snippet of the content — the same
+ * rule the rest of this package follows, because a caller can name any path and the snippet would
+ * echo the first bytes of whatever file that was.
+ */
+export function loadBaselineConfig(path) {
+    const source = readTextFile(path, 'Config file');
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        const position = error instanceof Error ? /position \d+(?::? line \d+ column \d+)?/.exec(error.message)?.[0] : undefined;
+        throw new ConfigError(`${path} is not valid JSON${position === undefined ? '' : ` at ${position}`}.`);
+    }
+    return validateBaselineConfig(parsed, path);
+}
+//# sourceMappingURL=baseline-config.js.map