claude_code_settings/merge.rs
1//! The layer merge: [`merge_values`].
2
3use alloc::vec::Vec;
4
5use serde_json::Value;
6
7/// Layers the settings document `higher` over `lower`, in place, the way
8/// Claude Code merges settings sources (checked against 2.1.322's
9/// merge, a lodash `mergeWith`):
10///
11/// - Objects merge key by key, recursively: a key only one side sets
12/// keeps its value (so `env`, `permissions`, `sandbox` and `hooks`
13/// combine).
14/// - Arrays concatenate, `lower`'s entries first, and repeated scalars
15/// are dropped (so `permissions.allow`/`deny`/`ask` and each hook
16/// event's matcher groups combine). Two keys are whole values instead:
17/// `fallbackModel` (an ordered chain) and `modelPicker`, where
18/// `higher`'s wins.
19/// - `extraKnownMarketplaces` merges one level deep: a marketplace
20/// `higher` names replaces `lower`'s whole.
21/// - Anything else (scalars, `null`, a type change): `higher` wins.
22///
23/// Merging decides what each key holds, not what it means: a `deny` rule
24/// beats an `allow` rule however the layers were ordered, and Claude Code
25/// reads some keys only from some sources (managed-only keys, keys it
26/// ignores in project settings), which this doesn't model.
27pub fn merge_values(lower: &mut Value, higher: Value) {
28 merge_at(lower, higher, None);
29}
30
31fn merge_at(lower: &mut Value, higher: Value, key: Option<&str>) {
32 if key == Some("modelPicker") {
33 *lower = higher;
34 return;
35 }
36 match (lower, higher) {
37 (Value::Array(lo), Value::Array(hi)) => {
38 if key == Some("fallbackModel") {
39 *lo = hi;
40 return;
41 }
42 lo.extend(hi);
43 dedup_scalars(lo);
44 }
45 (Value::Object(lo), Value::Object(hi)) if key == Some("extraKnownMarketplaces") => {
46 lo.extend(hi);
47 }
48 (Value::Object(lo), Value::Object(hi)) => {
49 for (k, v) in hi {
50 match lo.get_mut(&k) {
51 Some(slot) => merge_at(slot, v, Some(&k)),
52 None => {
53 lo.insert(k, v);
54 }
55 }
56 }
57 }
58 (lo, hi) => *lo = hi,
59 }
60}
61
62/// Drops a scalar that repeats an earlier one (lodash `uniq`, which keeps
63/// every object and array: they are compared by reference).
64fn dedup_scalars(values: &mut Vec<Value>) {
65 let mut seen: Vec<Value> = Vec::new();
66 values.retain(|v| {
67 if matches!(v, Value::Array(_) | Value::Object(_)) {
68 return true;
69 }
70 if seen.contains(v) {
71 return false;
72 }
73 seen.push(v.clone());
74 true
75 });
76}