Files
Kigi-CLI/crates/build/kigi-proto-build/src/lib.rs
T
ZacharyZhang-NY a02b555e66 docs(comments): rewrite comments across all crates to the guidelines
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).
2026-07-23 16:55:39 -04:00

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,
}
}