Skip to main content

tuwunel_core/config/
regenerate.rs

1use std::{
2	cmp::Ordering,
3	fmt::Write as _,
4	iter::once,
5	path::{Path, PathBuf},
6	sync::LazyLock,
7};
8
9mod overlay;
10#[cfg(test)]
11mod tests;
12mod tree;
13mod write;
14
15use figment::{
16	Figment,
17	providers::{Data, Format as _},
18	value::{Dict, Value},
19};
20use itertools::Itertools as _;
21use link_section::TypedSection;
22use serde::Serialize as _;
23use smallvec::SmallVec;
24use toml::{Value as TomlValue, ser::ValueSerializer};
25use toml_writer::TomlWrite as _;
26
27use self::{
28	overlay::{filter_nonconfig_environment, is_file_value, validate_file_overlay},
29	tree::{
30		ConfigPath, Instance, PathPart, find_path, normalize_aliases, remove_path,
31		resolve_instances,
32	},
33	write::write_atomic,
34};
35use super::{Config, DEPRECATED_KEYS, Sources, format::Toml, normalize::validate_registry};
36use crate::{Err, Result, err, implement, utils::BoolExt};
37
38const NEVER_EMIT: [&str; 2] = ["database_restore_backup", "force_migration"];
39
40#[derive(Clone, Copy, Debug, Eq, PartialEq)]
41pub(super) enum FieldClass {
42	Documented,
43	Structural,
44	Hidden,
45	Forbidden,
46}
47
48#[derive(Clone, Copy, Debug)]
49pub(super) struct FieldSpec {
50	pub(super) name: &'static str,
51	pub(super) path: &'static str,
52	pub(super) legacy: &'static [&'static str],
53	pub(super) aliases: &'static [&'static str],
54	pub(super) example: &'static str,
55	pub(super) class: FieldClass,
56	pub(super) sensitive: bool,
57}
58
59#[derive(Clone, Copy, Debug)]
60pub(super) struct SectionSpec {
61	pub(super) section: &'static str,
62	pub(super) aliases: &'static [&'static str],
63	pub(super) about: &'static str,
64	pub(super) example: &'static str,
65	pub(super) fields: &'static [FieldSpec],
66	pub(super) group: bool,
67}
68
69/// Selects how an existing configuration is regenerated.
70///
71/// The output path is optional so a single input can use its adjacent `.new`
72/// destination. The remaining flags control replacement and value selection.
73#[derive(Clone, Copy, Debug, Default)]
74pub struct RegenerateOptions<'a> {
75	/// Selects the output path.
76	///
77	/// When omitted, regeneration writes beside its sole input with a `.new`
78	/// suffix. Layered inputs require an explicit destination.
79	pub output: Option<&'a Path>,
80
81	/// Allows replacement of an existing output.
82	///
83	/// The previous contents are retained beside the output with a `.bak`
84	/// suffix before the atomic replacement is installed.
85	pub force: bool,
86
87	/// Materializes configuration values supplied through the environment.
88	///
89	/// The default keeps file values active and annotates environment overrides
90	/// without copying them into the regenerated document.
91	pub include_env: bool,
92
93	/// Comments out deprecated and unknown residue keys.
94	///
95	/// Hidden but valid configuration remains active. Forbidden migration
96	/// controls are always removed regardless of this setting.
97	pub strip_unknown: bool,
98}
99
100/// Selects whether an existing output may be replaced.
101///
102/// Replacement preserves the previous file beside the output as a `.bak`
103/// backup before installing the regenerated contents.
104#[derive(Clone, Copy, Debug, Eq, PartialEq)]
105pub enum Overwrite {
106	/// Refuses to replace an existing output.
107	///
108	/// A preexisting destination is left untouched and causes an error.
109	Deny,
110
111	/// Replaces an existing output after retaining a backup.
112	///
113	/// The previous regular file is preserved at the adjacent backup path.
114	Allow,
115}
116
117/// Summarizes a completed configuration regeneration.
118///
119/// Counts distinguish input layers, schema fields, and preserved residue.
120/// Intentionally removed migration controls are available through
121/// [`Self::dropped_keys`].
122#[derive(Debug)]
123pub struct RegenerationSummary {
124	output: PathBuf,
125	input_count: usize,
126	configured: usize,
127	residue: usize,
128	dropped: [bool; NEVER_EMIT.len()],
129}
130
131#[derive(Default)]
132struct RenderStats {
133	configured: usize,
134	residue: usize,
135	dropped: [bool; NEVER_EMIT.len()],
136}
137
138struct RenderContext<'a> {
139	environment: Option<(&'a Figment, &'a Dict)>,
140	strip_unknown: bool,
141	expected: &'a mut Dict,
142	stats: &'a mut RenderStats,
143}
144
145#[derive(Clone, Copy)]
146enum Block<'a, 'v> {
147	Instance(&'a Instance<'v>),
148	Environment(&'a Instance<'v>, (&'a Figment, &'a Dict)),
149	Template,
150}
151
152#[derive(Clone, Copy)]
153enum ResidueKind {
154	Deprecated,
155	Hidden,
156	Unknown,
157}
158
159#[derive(Clone, Copy)]
160enum ResidueDisposition {
161	Active,
162	Commented,
163}
164
165#[link_section::section(typed)]
166pub(super) static REGISTERED_SECTIONS: TypedSection<SectionSpec>;
167
168type MetadataKeys<'a> = SmallVec<[&'a str; 4]>;
169
170type OrderedSections = SmallVec<[&'static SectionSpec; 16]>;
171
172static ORDERED_SECTIONS: LazyLock<OrderedSections> = LazyLock::new(ordered_sections);
173
174#[inline]
175pub(super) fn schema() -> &'static [&'static SectionSpec] { ORDERED_SECTIONS.as_slice() }
176
177fn ordered_sections() -> OrderedSections {
178	let mut sections = REGISTERED_SECTIONS
179		.as_slice()
180		.iter()
181		.collect::<OrderedSections>();
182
183	// Section paths put each parent before its alphabetically ordered children.
184	sections.sort_unstable_by_key(|section| section.section.trim_matches(['[', ']']));
185	validate_schema(&sections);
186
187	sections
188}
189
190fn validate_schema(sections: &[&SectionSpec]) {
191	validate_registry(sections);
192	let first = sections
193		.first()
194		.expect("configuration schema must contain the global section");
195
196	assert_eq!(first.section, "global", "global must be the first configuration section");
197
198	for (index, section) in sections.iter().enumerate() {
199		assert!(
200			sections[..index]
201				.iter()
202				.all(|previous| previous.section != section.section),
203			"configuration section {:?} is registered more than once",
204			section.section,
205		);
206	}
207}
208
209/// Renders the example configuration carried by this binary.
210///
211/// The returned document is generated from the same runtime schema that
212/// produces the checked-in example file.
213pub fn example_config() -> Result<String> {
214	let values = Dict::new();
215	let mut expected = Dict::new();
216	let mut stats = RenderStats::default();
217	let rendered = {
218		let mut context = RenderContext {
219			environment: None,
220			strip_unknown: false,
221			expected: &mut expected,
222			stats: &mut stats,
223		};
224
225		render_schema(&values, &mut context)?
226	};
227
228	Ok(rendered)
229}
230
231/// Writes the example configuration to a filesystem path.
232///
233/// New files use private permissions. [`Overwrite::Allow`] retains an existing
234/// file beside the replacement with a `.bak` suffix.
235pub fn write_example_config(path: &Path, overwrite: Overwrite) -> Result {
236	let rendered = example_config()?;
237
238	write_atomic(path, rendered.as_bytes(), matches!(overwrite, Overwrite::Allow))
239}
240
241/// Regenerates the file-backed configuration retained by `sources`.
242///
243/// Command-line overrides are never consulted. Environment values are either
244/// annotated or explicitly materialized according to `options`.
245pub fn regenerate_config(
246	sources: &Sources,
247	options: RegenerateOptions<'_>,
248) -> Result<RegenerationSummary> {
249	let paths = sources.file_paths().collect_vec();
250	let input_count = paths.iter().sorted_unstable().dedup().count();
251
252	if paths.is_empty() {
253		return Err!("Configuration regeneration requires at least one input file.");
254	}
255
256	if input_count > 1 && options.output.is_none() {
257		return Err!(
258			"Layered configuration files require an explicit output path because they are \
259			 collapsed into one document."
260		);
261	}
262
263	let output = options
264		.output
265		.map(Path::to_path_buf)
266		.unwrap_or_else(|| adjacent_new_path(&paths[0]));
267
268	let files = Config::load_files(paths.iter().map(PathBuf::as_path))?;
269	validate_file_overlay(&files)?;
270
271	let file_values = options
272		.include_env
273		.is_false()
274		.then(|| files.extract::<Dict>())
275		.transpose()?;
276
277	let effective = Config::merge_environment(files)?;
278
279	Config::new(&effective)?;
280
281	let mut values = match file_values {
282		| Some(values) => values,
283		| None => {
284			let mut values = effective.extract::<Dict>()?;
285
286			filter_nonconfig_environment(&effective, &mut values)?;
287			values
288		},
289	};
290
291	normalize_aliases(&mut values, schema());
292
293	let effective_values = options
294		.include_env
295		.is_false()
296		.then(|| effective.extract::<Dict>())
297		.transpose()?
298		.map(|mut values| {
299			normalize_aliases(&mut values, schema());
300
301			values
302		});
303
304	let mut expected = values.clone();
305	let mut stats = RenderStats::default();
306	let rendered = {
307		let mut context = RenderContext {
308			environment: Some((&effective, effective_values.as_ref().unwrap_or(&values))),
309			strip_unknown: options.strip_unknown,
310			expected: &mut expected,
311			stats: &mut stats,
312		};
313
314		render_schema(&values, &mut context)?
315	};
316
317	verify_rendered(&rendered, &expected)?;
318	write_atomic(&output, rendered.as_bytes(), options.force)?;
319	verify_file(&output, &expected).map_err(|error| {
320		err!(
321			"Configuration was written to {} but post-write verification failed. Inspect the \
322			 written file and restore its adjacent `.bak` backup if present before retrying: \
323			 {error}",
324			output.display(),
325		)
326	})?;
327
328	let summary = RegenerationSummary {
329		output,
330		input_count,
331		configured: stats.configured,
332		residue: stats.residue,
333		dropped: stats.dropped,
334	};
335
336	Ok(summary)
337}
338
339/// Returns the path written by regeneration.
340///
341/// The path is absolute or relative according to the caller's selected
342/// destination.
343#[implement(RegenerationSummary)]
344#[inline]
345#[must_use]
346pub fn output(&self) -> &Path { &self.output }
347
348/// Returns the number of unique input files collapsed into the output.
349///
350/// A value greater than one means the result combines layered configuration
351/// sources in their normal precedence order.
352#[implement(RegenerationSummary)]
353#[inline]
354#[must_use]
355pub fn input_count(&self) -> usize { self.input_count }
356
357/// Returns the number of configured schema fields written.
358///
359/// Residue keys are counted separately by [`Self::residue`].
360#[implement(RegenerationSummary)]
361#[inline]
362#[must_use]
363pub fn configured(&self) -> usize { self.configured }
364
365/// Returns the number of encountered hidden, deprecated, or unknown keys.
366///
367/// The count includes commented residue when stripping was requested.
368#[implement(RegenerationSummary)]
369#[inline]
370#[must_use]
371pub fn residue(&self) -> usize { self.residue }
372
373/// Iterates over migration controls intentionally removed from the output.
374///
375/// The iterator is empty when neither control appeared in the selected
376/// configuration values.
377#[implement(RegenerationSummary)]
378pub fn dropped_keys(&self) -> impl Iterator<Item = &'static str> + '_ {
379	NEVER_EMIT
380		.into_iter()
381		.zip(self.dropped)
382		.filter_map(|(key, dropped)| dropped.then_some(key))
383}
384
385fn render_schema(values: &Dict, context: &mut RenderContext<'_>) -> Result<String> {
386	let schema = schema();
387	let capacity = schema
388		.iter()
389		.flat_map(|spec| [spec.about, spec.example])
390		.map(str::len)
391		.sum();
392
393	schema
394		.iter()
395		.try_fold(String::with_capacity(capacity), |output, &spec| {
396			render_section(output, spec, values, context)
397		})
398}
399
400fn render_section(
401	output: String,
402	spec: &SectionSpec,
403	values: &Dict,
404	context: &mut RenderContext<'_>,
405) -> Result<String> {
406	let environment = context.environment;
407	let instances = resolve_instances(spec, values);
408	let environment_instances = environment
409		.map(|(_, environment_values)| resolve_instances(spec, environment_values))
410		.unwrap_or_default();
411
412	let rendered = instances.is_empty().is_false()
413		|| environment_instances
414			.iter()
415			.any(|candidate| is_unrendered(&instances, candidate));
416
417	let templated = is_dynamic(spec.section) || rendered.is_false();
418	let environment_blocks = environment_instances
419		.iter()
420		.filter(|candidate| is_unrendered(&instances, candidate))
421		.filter_map(|candidate| {
422			environment.map(|environment| Block::Environment(candidate, environment))
423		});
424
425	instances
426		.iter()
427		.map(Block::Instance)
428		.chain(environment_blocks)
429		.chain(templated.then_some(Block::Template))
430		.enumerate()
431		.try_fold(output, |output, (index, block)| {
432			render_block(output, index, spec, block, context)
433		})
434}
435
436fn is_unrendered<'v>(instances: &[Instance<'v>], candidate: &Instance<'v>) -> bool {
437	instances
438		.iter()
439		.all(|instance| instance.path != candidate.path)
440}
441
442fn render_block(
443	mut output: String,
444	index: usize,
445	spec: &SectionSpec,
446	block: Block<'_, '_>,
447	context: &mut RenderContext<'_>,
448) -> Result<String> {
449	let lead = if index == 0 { spec.about } else { "\n\n" };
450
451	output.push_str(lead);
452	match block {
453		| Block::Instance(instance) => render_instance(&mut output, spec, instance, context)?,
454		| Block::Environment(instance, environment) =>
455			render_environment_instance(&mut output, spec, instance, environment)?,
456		| Block::Template => output.push_str(spec.example),
457	}
458
459	Ok(output)
460}
461
462fn render_instance(
463	output: &mut String,
464	spec: &SectionSpec,
465	instance: &Instance<'_>,
466	context: &mut RenderContext<'_>,
467) -> Result {
468	for line in spec.example.split_inclusive('\n') {
469		let body = line.strip_suffix('\n').unwrap_or(line);
470
471		if is_template_header(body, spec.section) {
472			write_active_header(output, spec.section, &instance.section);
473			if line.ends_with('\n') {
474				output.push('\n');
475			}
476
477			continue;
478		}
479
480		let Some(name) = assignment_name(body) else {
481			output.push_str(line);
482			continue;
483		};
484
485		let Some(field) = spec
486			.fields
487			.iter()
488			.find(|field| field.class == FieldClass::Documented && field.name == name)
489		else {
490			output.push_str(line);
491			continue;
492		};
493
494		let path = field_path(&instance.path, field.name);
495		annotate_environment(
496			output,
497			context.environment,
498			&path,
499			instance.values.get(field.name),
500		)?;
501
502		match instance.values.get(field.name) {
503			| None => output.push_str(line),
504			| Some(value) => {
505				write_assignment(output, field.name, value)?;
506				context.stats.configured = context.stats.configured.saturating_add(1);
507			},
508		}
509	}
510
511	render_unlisted_fields(output, spec, instance, context)
512}
513
514#[cfg(test)]
515pub(super) fn render_fixture(spec: &SectionSpec, values: &Dict) -> Result<String> {
516	let mut output = String::new();
517	let mut expected = Dict::new();
518	let mut stats = RenderStats::default();
519	let mut context = RenderContext {
520		environment: None,
521		strip_unknown: false,
522		expected: &mut expected,
523		stats: &mut stats,
524	};
525
526	for instance in resolve_instances(spec, values) {
527		render_instance(&mut output, spec, &instance, &mut context)?;
528	}
529
530	Ok(output)
531}
532
533fn render_environment_instance(
534	output: &mut String,
535	spec: &SectionSpec,
536	instance: &Instance<'_>,
537	environment: (&Figment, &Dict),
538) -> Result {
539	for line in spec.example.split_inclusive('\n') {
540		let body = line.strip_suffix('\n').unwrap_or(line);
541
542		if is_template_header(body, spec.section) {
543			output.push('#');
544			write_active_header(output, spec.section, &instance.section);
545			if line.ends_with('\n') {
546				output.push('\n');
547			}
548
549			continue;
550		}
551
552		if let Some(field) = assignment_name(body).and_then(|name| {
553			spec.fields
554				.iter()
555				.find(|field| field.class == FieldClass::Documented && field.name == name)
556		}) {
557			let path = field_path(&instance.path, field.name);
558
559			annotate_environment(output, Some(environment), &path, None)?;
560		}
561
562		output.push_str(line);
563	}
564
565	for field in spec
566		.fields
567		.iter()
568		.filter(|field| field.class == FieldClass::Hidden)
569	{
570		let path = field_path(&instance.path, field.name);
571
572		render_hidden_environment(output, field, Some(environment), &path)?;
573	}
574
575	Ok(())
576}
577
578fn render_unlisted_fields(
579	output: &mut String,
580	spec: &SectionSpec,
581	instance: &Instance<'_>,
582	context: &mut RenderContext<'_>,
583) -> Result {
584	for field in spec.fields {
585		let Some(value) = instance.values.get(field.name) else {
586			if field.class == FieldClass::Hidden {
587				let path = field_path(&instance.path, field.name);
588
589				render_hidden_environment(output, field, context.environment, &path)?;
590			}
591
592			continue;
593		};
594
595		let path = field_path(&instance.path, field.name);
596
597		match field.class {
598			| FieldClass::Documented | FieldClass::Structural => {},
599			| FieldClass::Hidden => {
600				annotate_environment(output, context.environment, &path, Some(value))?;
601				render_residue(
602					output,
603					field.name,
604					value,
605					ResidueKind::Hidden,
606					ResidueDisposition::Active,
607				)?;
608
609				context.stats.residue = context.stats.residue.saturating_add(1);
610			},
611			| FieldClass::Forbidden => {
612				remove_path(context.expected, &path);
613				mark_dropped(context.stats, field.name);
614			},
615		}
616	}
617
618	for (name, value) in instance.values {
619		if spec.fields.iter().any(|field| field.name == name) {
620			continue;
621		}
622
623		let path = field_path(&instance.path, name);
624		let kind = is_deprecated(&path)
625			.then_some(ResidueKind::Deprecated)
626			.unwrap_or(ResidueKind::Unknown);
627
628		let disposition = if context.strip_unknown {
629			ResidueDisposition::Commented
630		} else {
631			ResidueDisposition::Active
632		};
633
634		annotate_environment(output, context.environment, &path, Some(value))?;
635		render_residue(output, name, value, kind, disposition)?;
636		context.stats.residue = context.stats.residue.saturating_add(1);
637
638		if context.strip_unknown {
639			remove_path(context.expected, &path);
640		}
641	}
642
643	Ok(())
644}
645
646fn render_hidden_environment(
647	output: &mut String,
648	field: &FieldSpec,
649	environment: Option<(&Figment, &Dict)>,
650	path: &[PathPart<'_>],
651) -> Result {
652	let Some((figment, value)) = environment_value(environment, path) else {
653		return Ok(());
654	};
655
656	writeln!(
657		output,
658		"\n# UNDOCUMENTED: `{}` is valid but omitted from the example configuration.",
659		field.name
660	)
661	.expect("written to configuration buffer");
662
663	output.push_str("# currently set by ");
664	write_environment_name(output, figment, value, path);
665	output.push_str(".\n");
666
667	match field.example {
668		| "" => writeln!(output, "#{} =", field.name),
669		| example => writeln!(output, "#{} = {example}", field.name),
670	}
671	.expect("written to configuration buffer");
672
673	Ok(())
674}
675
676fn render_residue(
677	output: &mut String,
678	name: &str,
679	value: &Value,
680	kind: ResidueKind,
681	disposition: ResidueDisposition,
682) -> Result {
683	match kind {
684		| ResidueKind::Hidden => writeln!(
685			output,
686			"\n# UNDOCUMENTED: `{name}` is valid but omitted from the example configuration."
687		)
688		.expect("written to configuration buffer"),
689		| ResidueKind::Deprecated => {
690			writeln!(
691				output,
692				"\n# DEPRECATED: `{name}` is no longer used by tuwunel and is ignored."
693			)
694			.expect("written to configuration buffer");
695
696			writeln!(output, "# Preserved from the previous configuration; it can be deleted.")
697				.expect("written to configuration buffer");
698		},
699		| ResidueKind::Unknown => {
700			writeln!(output, "\n# UNKNOWN: `{name}` is not a tuwunel configuration option.")
701				.expect("written to configuration buffer");
702
703			writeln!(output, "# Preserved from the previous configuration.")
704				.expect("written to configuration buffer");
705		},
706	}
707
708	if matches!(disposition, ResidueDisposition::Commented) {
709		output.push('#');
710	}
711
712	write_assignment(output, name, value)?;
713
714	Ok(())
715}
716
717fn annotate_environment(
718	output: &mut String,
719	environment: Option<(&Figment, &Dict)>,
720	path: &[PathPart<'_>],
721	file_value: Option<&Value>,
722) -> Result {
723	let Some((figment, value)) = environment_value(environment, path) else {
724		return Ok(());
725	};
726
727	let action = match file_value {
728		| None => "currently set by",
729		| Some(value) if is_file_value(figment, value) => "currently overridden by",
730		| Some(_) => "materialized from",
731	};
732
733	write!(output, "# {action} ").expect("written to configuration buffer");
734	write_environment_name(output, figment, value, path);
735	output.push_str(".\n");
736
737	Ok(())
738}
739
740fn environment_value<'a>(
741	environment: Option<(&'a Figment, &'a Dict)>,
742	path: &[PathPart<'_>],
743) -> Option<(&'a Figment, &'a Value)> {
744	let (figment, values) = environment?;
745
746	find_path(values, path)
747		.filter(|value| !is_file_value(figment, value))
748		.map(|value| (figment, value))
749}
750
751fn write_assignment(output: &mut String, name: &str, value: &Value) -> Result {
752	output
753		.key(name)
754		.expect("written to configuration buffer");
755
756	output.push_str(" = ");
757	write_value(output, value)?;
758	output.push('\n');
759
760	Ok(())
761}
762
763fn write_value(output: &mut String, value: &Value) -> Result {
764	value
765		.serialize(ValueSerializer::new(output))
766		.map_err(|error| err!("Failed to serialize a configuration value: {error}"))?;
767
768	Ok(())
769}
770
771fn assignment_name(line: &str) -> Option<&str> {
772	let (name, _) = line.strip_prefix('#')?.split_once(" =")?;
773
774	name.chars()
775		.all(|character| {
776			character.is_ascii_lowercase() || character.is_ascii_digit() || character == '_'
777		})
778		.then_some(name)
779}
780
781fn is_template_header(line: &str, section: &str) -> bool {
782	match section == "global" {
783		| true => line == "[global]",
784		| false => line
785			.strip_prefix("#[")
786			.and_then(|line| line.strip_suffix(']'))
787			.is_some_and(|line| line == section),
788	}
789}
790
791fn write_active_header(output: &mut String, section: &str, resolved: &str) {
792	if section.starts_with('[') {
793		write!(output, "[[{resolved}]]").expect("written to configuration buffer");
794	} else {
795		write!(output, "[{resolved}]").expect("written to configuration buffer");
796	}
797}
798
799fn is_dynamic(section: &str) -> bool { section.contains('<') || section.starts_with('[') }
800
801fn field_path<'a>(base: &ConfigPath<'a>, field: &'a str) -> ConfigPath<'a> {
802	base.iter()
803		.copied()
804		.chain(once(PathPart::Key(field)))
805		.collect()
806}
807
808fn is_deprecated(path: &[PathPart<'_>]) -> bool {
809	DEPRECATED_KEYS.iter().any(|deprecated| {
810		deprecated
811			.split('.')
812			.eq(path.iter().filter_map(|part| match part {
813				| PathPart::Key(key) => Some(*key),
814				| PathPart::Index(_) => None,
815			}))
816	})
817}
818
819fn mark_dropped(stats: &mut RenderStats, name: &str) {
820	if let Some(index) = NEVER_EMIT.iter().position(|key| *key == name) {
821		stats.dropped[index] = true;
822	}
823}
824
825fn write_environment_name(
826	output: &mut String,
827	figment: &Figment,
828	value: &Value,
829	path: &[PathPart<'_>],
830) {
831	if let Some(metadata) = figment.get_metadata(value.tag()) {
832		let keys = path
833			.iter()
834			.filter_map(|part| match part {
835				| PathPart::Key(key) => Some(*key),
836				| PathPart::Index(_) => None,
837			})
838			.collect::<MetadataKeys<'_>>();
839
840		let profile = value
841			.tag()
842			.profile()
843			.unwrap_or_else(|| figment.profile().clone());
844
845		output.push_str(&metadata.interpolate(&profile, &keys));
846	}
847}
848
849fn verify_rendered(rendered: &str, expected: &Dict) -> Result {
850	let output = Figment::new().merge(Data::nested(Toml::string(rendered)));
851	let actual = output.extract::<Dict>()?;
852
853	if !toml_equivalent(&actual, expected)? {
854		return Err!("Regenerated configuration failed its semantic round-trip check.");
855	}
856
857	Ok(())
858}
859
860fn verify_file(path: &Path, expected: &Dict) -> Result {
861	let output = Config::load_files([path].into_iter())?;
862	let actual = output.extract::<Dict>()?;
863
864	if !toml_equivalent(&actual, expected)? {
865		return Err!("Written configuration failed its semantic round-trip check.");
866	}
867
868	Ok(())
869}
870
871fn toml_equivalent(left: &Dict, right: &Dict) -> Result<bool> {
872	let left = TomlValue::try_from(left)
873		.map_err(|error| err!("Failed to normalize regenerated values: {error}"))?;
874
875	let right = TomlValue::try_from(right)
876		.map_err(|error| err!("Failed to normalize expected values: {error}"))?;
877
878	Ok(toml_values_equivalent(&left, &right))
879}
880
881fn toml_values_equivalent(left: &TomlValue, right: &TomlValue) -> bool {
882	match (left, right) {
883		| (TomlValue::Float(left), TomlValue::Float(right)) =>
884			left.is_nan() && right.is_nan()
885				|| left
886					.partial_cmp(right)
887					.is_some_and(Ordering::is_eq),
888		| (TomlValue::Array(left), TomlValue::Array(right)) =>
889			left.len() == right.len()
890				&& left
891					.iter()
892					.zip(right)
893					.all(|(left, right)| toml_values_equivalent(left, right)),
894		| (TomlValue::Table(left), TomlValue::Table(right)) =>
895			left.len() == right.len()
896				&& left.iter().all(|(key, left)| {
897					right
898						.get(key)
899						.is_some_and(|right| toml_values_equivalent(left, right))
900				}),
901		| _ => left == right,
902	}
903}
904
905fn adjacent_new_path(input: &Path) -> PathBuf {
906	let mut output = input.as_os_str().to_owned();
907
908	output.push(".new");
909
910	output.into()
911}