feat: introduce expander for easier debugging

[drahnr]

Attempt to address #760

[ahl]

1. this doesn't seem to work if there are multiple invocations to generate_api! transitively in the compiled artifact; in fact, the results seem pathological.
2. I don't know what expander is; let's just use prettyplease (not prettier-please which I can't find the source for).
3. Let's not change the behavior to include the generated source file.

So:

Suggested change

	let output = if let Some(dest) = std::env::var("PROGENITOR_OUTPUT_DEBUG")
	.map(std::path::PathBuf::from_str)
	{
	eprintln!("Writing generated output to {}", path.display());
	expander::Expander::new(dest.filename().expect("Environment var `PROGENITOR_OUTPUT_DEBUG` must contain path with filename"))
	.fmt(expander::Edition::_2021)
	.verbose(true)
	.write_to(output, dest.parent().expect("If path has filename, parent must be root / drive at least. qed"))
	.write_to_out_dir(output)
	.expect("Writing file works. qed")
	} else {
	output
	};
	if let Some(dest) = std::env::var("PROGENITOR_OUTPUT_LOG") {
	eprintln!("Logging generated output for {} to {}", path_str, dest);
	let heading = format!("generated code from {}", path_str);
	let output = output.clone();
	let file = syn::parse_quote! {
	#[doc = "vvvvvvvvvvvvvvvvvvvvvvvvv"]
	#[doc = #heading]
	#[doc = "^^^^^^^^^^^^^^^^^^^^^"]
	#output
	};
	let text = prettyplease::unparse(&file);
	let mut outfile = OpenOptions::new()
	.append(true) // Open in append mode
	.open("dest")
	.map_err(|_| eprintln!("something"));
	outfile.write_all(text);
	}

[drahnr]

1. that's correct, there is the option to use a hash derived from the generated content (see https://docs.rs/expander/latest/src/expander/lib.rs.html#186 ). The proposed solution using PROGENITOR_OUTPUT_LOG suffers the same aliasing issue. Let me re-test, I am pretty sure this already works, other projects use expander that way already.
2. expander is a solution for rustc not generating good error messages for proc macro generated code, this is the motivation for the indirection. https://github.com/drahnr/expander?tab=readme-ov-file#advantages
3. The behaviour would only change IFF the user would enable it via an environment variable. I don't see the issue doing the inclusion? Could you elaborate where you see an issue?

[ahl]

1. The proposed solution using PROGENITOR_OUTPUT_LOG suffers the same aliasing issue. Let me re-test, I am pretty sure this already works, other projects use expander that way already.

I apologize but I haven't looked at expander and can't prioritize its inclusion to our SBOM.

2. expander is a solution for rustc not generating good error messages for proc macro generated code, this is the motivation for the indirection. https://github.com/drahnr/expander?tab=readme-ov-file#advantages

Do you have examples of the improved error messages?

3. The behaviour would only change IFF the user would enable it via an environment variable. I don't see the issue doing the inclusion? Could you elaborate where you see an issue?

When using a debugging facility, I have found that it's a good principle to minimally change the process being debugged. As a concrete example: use of this as-is causes our omicron repo build to fail--much worse than merely imperfect debugging output!

[ahl]

If you're still interested in moving forward with this without expander, what do you think about having the user specify a directory for generated output rather than a file? We could name the files within that directory based on the input file names.