Sweep every first-party crate source (1956 .rs files) to the project comment guidelines: delete redundant restatements, decorative banners, change narration, and end-of-line comments; keep and tighten the crucial ones (invariants, bug rationale, SAFETY blocks, ported-source attribution). No functional code changed. Every edit is proven comment-only against the prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a separate doctest-fence check. Where removing a comment made rustfmt or clippy want to re-lay-out adjacent code, the minimal triggering comment is restored so code tokens stay byte-identical. Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy --workspace --all-targets (0 warnings). Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for these guidelines (flags banners, end-of-line comments, change narration, and commented-out code).
293 lines
10 KiB
Rust
293 lines
10 KiB
Rust
pub mod find_protoc;
|
|
|
|
use anyhow::Context;
|
|
use std::path::{Path, PathBuf};
|
|
use std::process::{Command, Stdio};
|
|
use std::{env, fs, iter};
|
|
|
|
/// Resolve protoc's well-known-types include dir (`../include` next to `bin/protoc`).
|
|
///
|
|
/// Bazel keeps the binary and includes in separate sandbox paths; protoc will
|
|
/// not find them without an explicit `-I`.
|
|
fn find_protoc_include_dir(protoc: Option<&Path>) -> Option<PathBuf> {
|
|
let protoc = protoc?;
|
|
|
|
// Layout: `.../bin/protoc` → sibling `.../include`.
|
|
let parent = protoc.parent()?;
|
|
let grandparent = parent.parent()?;
|
|
let include_dir = grandparent.join("include");
|
|
|
|
if include_dir.is_dir() {
|
|
Some(include_dir)
|
|
} else {
|
|
None
|
|
}
|
|
}
|
|
|
|
pub struct XaiProtoBuilder {
|
|
builder: tonic_prost_build::Builder,
|
|
file_descriptor_set_path: Option<PathBuf>,
|
|
gen_pbjson: bool,
|
|
pbjson_ignore_unknown_fields: bool,
|
|
pbjson_preserve_proto_field_names: bool,
|
|
}
|
|
|
|
impl XaiProtoBuilder {
|
|
fn map_builder(
|
|
self,
|
|
f: impl FnOnce(tonic_prost_build::Builder) -> tonic_prost_build::Builder,
|
|
) -> Self {
|
|
Self {
|
|
builder: f(self.builder),
|
|
..self
|
|
}
|
|
}
|
|
|
|
pub fn bytes<S: AsRef<str>>(self, paths: impl IntoIterator<Item = S>) -> Self {
|
|
self.map_builder(|b| paths.into_iter().fold(b, |b, path| b.bytes(path)))
|
|
}
|
|
|
|
pub fn extern_path(self, proto_path: impl AsRef<str>, rust_path: impl AsRef<str>) -> Self {
|
|
self.map_builder(|b| b.extern_path(proto_path, rust_path))
|
|
}
|
|
|
|
pub fn file_descriptor_set_path(mut self, path: impl AsRef<Path>) -> Self {
|
|
self.file_descriptor_set_path = Some(path.as_ref().to_path_buf());
|
|
self.map_builder(|b| b.file_descriptor_set_path(path))
|
|
}
|
|
|
|
pub fn gen_pbjson(mut self) -> Self {
|
|
self.gen_pbjson = true;
|
|
self
|
|
}
|
|
|
|
pub fn pbjson_ignore_unknown_fields(mut self) -> Self {
|
|
self.pbjson_ignore_unknown_fields = true;
|
|
self
|
|
}
|
|
|
|
/// Emit JSON with original proto field names (snake_case) instead of
|
|
/// proto3-JSON camelCase. Deserialization still accepts both casings.
|
|
pub fn pbjson_preserve_proto_field_names(mut self) -> Self {
|
|
self.pbjson_preserve_proto_field_names = true;
|
|
self
|
|
}
|
|
|
|
pub fn generate_default_stubs(self, enable: bool) -> Self {
|
|
self.map_builder(|b| b.generate_default_stubs(enable))
|
|
}
|
|
|
|
pub fn type_attribute(self, path: impl AsRef<str>, attr: impl AsRef<str>) -> Self {
|
|
self.map_builder(|b| b.type_attribute(path, attr))
|
|
}
|
|
|
|
pub fn field_attribute(self, path: impl AsRef<str>, attr: impl AsRef<str>) -> Self {
|
|
self.map_builder(|b| b.field_attribute(path, attr))
|
|
}
|
|
|
|
// tonic-build's `rerun-if-changed` is lazy and wrong: any include-dir
|
|
// touch invalidates everything, and paths are treated as CWD-relative.
|
|
fn emit_rerun_if_changed<'a>(
|
|
protoc: Option<&Path>,
|
|
protoc_include_dir: Option<&Path>,
|
|
protos: impl IntoIterator<Item = &'a Path>,
|
|
includes: impl IntoIterator<Item = &'a Path>,
|
|
) -> anyhow::Result<()> {
|
|
let includes = Vec::from_iter(includes);
|
|
|
|
if let Some(protoc) = protoc {
|
|
println!(
|
|
"cargo:rerun-if-changed={}",
|
|
protoc.to_str().context("protoc path not UTF-8")?
|
|
);
|
|
}
|
|
|
|
// `--dependency_out` accepts one input per invocation. Write real
|
|
// files (not /dev/stdout|/dev/null — missing on Windows). OUT_DIR
|
|
// names stay stable so reruns overwrite rather than accumulate.
|
|
let scratch_dir = env::var_os("OUT_DIR")
|
|
.map(PathBuf::from)
|
|
.unwrap_or_else(env::temp_dir);
|
|
for proto in protos {
|
|
let stem = proto
|
|
.file_stem()
|
|
.and_then(|s| s.to_str())
|
|
.context("proto file name not UTF-8")?;
|
|
let dep_file = scratch_dir.join(format!("{stem}.protoc-deps.d"));
|
|
let descriptor_file = scratch_dir.join(format!("{stem}.protoc-desc.bin"));
|
|
let mut command = Command::new(protoc.unwrap_or(Path::new("protoc")));
|
|
command
|
|
.arg(format!("--dependency_out={}", dep_file.display()))
|
|
.arg(format!(
|
|
"--descriptor_set_out={}",
|
|
descriptor_file.display()
|
|
));
|
|
|
|
// Well-known types first so Bazel sandboxes resolve them.
|
|
if let Some(include_dir) = protoc_include_dir {
|
|
command.arg(format!(
|
|
"-I{}",
|
|
include_dir.to_str().context("include path not UTF-8")?
|
|
));
|
|
}
|
|
|
|
for include in &includes {
|
|
command.arg(format!("-I{}", include.to_str().context("path not UTF-8")?));
|
|
}
|
|
|
|
command.arg(proto);
|
|
|
|
command.stdin(Stdio::null());
|
|
command.stderr(Stdio::inherit());
|
|
|
|
let output = command.output().context("protoc command failed")?;
|
|
if !output.status.success() {
|
|
return Err(anyhow::anyhow!("protoc command failed"));
|
|
}
|
|
|
|
let output = fs::read_to_string(&dep_file)
|
|
.with_context(|| format!("read protoc dependency file {}", dep_file.display()))?;
|
|
|
|
// Make-style `.d`: `<descriptor path>: dep1 dep2 …`.
|
|
// Normalize separators — protoc may emit `/` even on Windows.
|
|
let mut lines = output.lines();
|
|
let first_line = lines.next().context("protoc dependency output is empty")?;
|
|
let normalized_first = first_line.replace('\\', "/");
|
|
let prefix = format!("{}:", descriptor_file.display()).replace('\\', "/");
|
|
let rem_len = normalized_first
|
|
.strip_prefix(&prefix)
|
|
.with_context(|| {
|
|
format!("protoc dependency output must start with {prefix:?}: {output:?}")
|
|
})?
|
|
.len();
|
|
let rem = &first_line[first_line.len() - rem_len..];
|
|
for line in iter::once(rem).chain(lines) {
|
|
let line = line.trim();
|
|
let line = line.strip_suffix("\\").unwrap_or(line);
|
|
// Skip host-absolute well-known includes so fingerprints stay portable.
|
|
if line.contains("/include/google/protobuf/") {
|
|
continue;
|
|
}
|
|
|
|
if !fs::exists(line)? {
|
|
return Err(anyhow::anyhow!("dependency file not found: {line}"));
|
|
}
|
|
|
|
println!("cargo:rerun-if-changed={line}");
|
|
}
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
|
|
pub fn compile_protos(
|
|
self,
|
|
protos: &[impl AsRef<Path>],
|
|
includes: &[impl AsRef<Path>],
|
|
) -> anyhow::Result<()> {
|
|
for proto in protos {
|
|
let proto = proto.as_ref();
|
|
if proto.is_absolute() {
|
|
return Err(anyhow::anyhow!(
|
|
"Absolute paths are not allowed: {}",
|
|
proto.display()
|
|
));
|
|
}
|
|
}
|
|
|
|
let XaiProtoBuilder {
|
|
builder,
|
|
gen_pbjson,
|
|
file_descriptor_set_path,
|
|
pbjson_ignore_unknown_fields,
|
|
pbjson_preserve_proto_field_names,
|
|
} = self;
|
|
let mut config = prost_build::Config::new();
|
|
config.enable_type_names();
|
|
|
|
let protoc = find_protoc::find_protoc()?;
|
|
|
|
if let Some(protoc) = &protoc {
|
|
config.protoc_executable(protoc);
|
|
}
|
|
|
|
let protoc_include_dir = find_protoc_include_dir(protoc.as_deref());
|
|
|
|
let mut builder = builder.emit_rerun_if_changed(false);
|
|
Self::emit_rerun_if_changed(
|
|
protoc.as_deref(),
|
|
protoc_include_dir.as_deref(),
|
|
protos.iter().map(|p| p.as_ref()),
|
|
includes.iter().map(|i| i.as_ref()),
|
|
)?;
|
|
|
|
let tempfile;
|
|
|
|
let file_descriptor_set_path: Option<PathBuf> =
|
|
if let Some(file_descriptor_set_path) = file_descriptor_set_path {
|
|
Some(file_descriptor_set_path)
|
|
} else if gen_pbjson {
|
|
tempfile = tempfile::TempDir::new()?;
|
|
let file_descriptor_set_path = tempfile.path().join("kigi-proto-build.pbbin");
|
|
builder = builder.file_descriptor_set_path(&file_descriptor_set_path);
|
|
Some(file_descriptor_set_path)
|
|
} else {
|
|
None
|
|
};
|
|
|
|
// Prepend protoc includes so well-known types resolve under Bazel.
|
|
let all_includes: Vec<&Path> = protoc_include_dir
|
|
.as_deref()
|
|
.into_iter()
|
|
.chain(includes.iter().map(|i| i.as_ref()))
|
|
.collect();
|
|
|
|
let protos: Vec<&Path> = protos.iter().map(|p| p.as_ref()).collect();
|
|
|
|
builder
|
|
.compile_with_config(config, &protos, &all_includes)
|
|
.context("tonic_build failed")?;
|
|
|
|
if gen_pbjson {
|
|
let file_descriptor_set_path =
|
|
file_descriptor_set_path.context("fds must be set at this moment")?;
|
|
let descriptor_set = fs::read(&file_descriptor_set_path).with_context(|| {
|
|
format!(
|
|
"Failed to read file descriptor set {}",
|
|
file_descriptor_set_path.display()
|
|
)
|
|
})?;
|
|
let mut builder = pbjson_build::Builder::new();
|
|
builder
|
|
.register_descriptors(&descriptor_set)
|
|
.context("Failed to register descriptors in pbjson_build")?;
|
|
if pbjson_ignore_unknown_fields {
|
|
builder.ignore_unknown_fields();
|
|
}
|
|
if pbjson_preserve_proto_field_names {
|
|
builder.preserve_proto_field_names();
|
|
}
|
|
builder
|
|
.build(&["."])
|
|
.context("Failed to build descriptor set")?;
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
}
|
|
|
|
pub fn configure() -> XaiProtoBuilder {
|
|
let builder = tonic_prost_build::configure()
|
|
.compile_well_known_types(true)
|
|
.extern_path(".google.protobuf", "::pbjson_types")
|
|
.extern_path(".google.protobuf.Empty", "()")
|
|
.protoc_arg("--experimental_allow_proto3_optional");
|
|
XaiProtoBuilder {
|
|
builder,
|
|
gen_pbjson: false,
|
|
pbjson_ignore_unknown_fields: false,
|
|
pbjson_preserve_proto_field_names: false,
|
|
file_descriptor_set_path: None,
|
|
}
|
|
}
|