sourcey 3.6.0 → 3.6.2

package/dist/core/sourcey-rustdoc/src/main.rs

@@ -0,0 +1,256 @@
+use std::fs;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::process::ExitCode;
+
+use anyhow::{anyhow, Context, Result};
+use clap::Parser;
+use flate2::write::GzEncoder;
+use flate2::Compression;
+use rustdoc_json::Builder;
+use rustdoc_types::Crate;
+use time::OffsetDateTime;
+
+use sourcey_rustdoc::diagnostics::{self, codes};
+use sourcey_rustdoc::extract::{extract_crate, ExtractOptions};
+use sourcey_rustdoc::spec::{Diagnostic, RustdocSpec, SOURCEY_RUSTDOC_VERSION, SPEC_VERSION};
+
+const EXPECTED_FORMAT_VERSION: u32 = rustdoc_types::FORMAT_VERSION;
+
+#[derive(Parser, Debug)]
+#[command(version, about = "Convert nightly rustdoc JSON into a sourcey RustdocSpec snapshot.", long_about = None)]
+struct Args {
+    /// Path to a Cargo manifest (Cargo.toml) or a workspace directory.
+    #[arg(long)]
+    manifest: PathBuf,
+
+    /// Crate names to include. Repeat to include multiple. If omitted, the
+    /// manifest's own package is used.
+    #[arg(long = "crate", value_name = "NAME")]
+    crates: Vec<String>,
+
+    /// Enable a feature. Repeat for multiple.
+    #[arg(long = "features", value_name = "NAME")]
+    features: Vec<String>,
+
+    /// Enable all features.
+    #[arg(long)]
+    all_features: bool,
+
+    /// Disable default features.
+    #[arg(long)]
+    no_default_features: bool,
+
+    /// Include `pub(crate)` and private items.
+    #[arg(long)]
+    include_private: bool,
+
+    /// Include items marked `#[doc(hidden)]`.
+    #[arg(long)]
+    include_hidden: bool,
+
+    /// Target triple to build docs for.
+    #[arg(long)]
+    target: Option<String>,
+
+    /// rustup toolchain name (default: nightly).
+    #[arg(long, default_value = "nightly")]
+    toolchain: String,
+
+    /// rustc cap-lints level (default: warn).
+    #[arg(long, default_value = "warn")]
+    cap_lints: String,
+
+    /// Output path; "-" for stdout.
+    #[arg(long, default_value = "-")]
+    output: String,
+
+    /// Fail (exit code 2) on any blocking diagnostic.
+    #[arg(long)]
+    strict: bool,
+}
+
+fn main() -> ExitCode {
+    let args = Args::parse();
+    match run(args) {
+        Ok(exit) => exit,
+        Err(err) => {
+            eprintln!("sourcey-rustdoc: {err:#}");
+            ExitCode::from(2)
+        }
+    }
+}
+
+fn run(args: Args) -> Result<ExitCode> {
+    let crate_names = resolve_crate_names(&args)?;
+    let mut crates = Vec::new();
+    let mut diagnostics: Vec<Diagnostic> = Vec::new();
+
+    for crate_name in &crate_names {
+        let json_path = build_rustdoc_json(&args, crate_name)
+            .with_context(|| format!("building rustdoc JSON for {crate_name}"))?;
+        let krate = load_rustdoc_json(&json_path)
+            .with_context(|| format!("loading rustdoc JSON for {crate_name}"))?;
+        if krate.format_version != EXPECTED_FORMAT_VERSION {
+            let msg = format!(
+                "rustdoc JSON format v{} produced by toolchain `{}`; this helper was built against v{}. Install `rustup toolchain install nightly-YYYY-MM-DD` to match.",
+                krate.format_version, args.toolchain, EXPECTED_FORMAT_VERSION
+            );
+            diagnostics.push(diagnostics::error(codes::FORMAT_VERSION_MISMATCH, msg));
+            if args.strict {
+                return Ok(ExitCode::from(2));
+            }
+            continue;
+        }
+        let opts = ExtractOptions {
+            include_private: args.include_private,
+            include_hidden: args.include_hidden,
+            crate_name_hint: crate_name.clone(),
+        };
+        let result = extract_crate(&krate, &opts);
+        diagnostics.extend(result.diagnostics);
+        crates.push(result.crate_spec);
+    }
+
+    let has_error_diagnostic = diagnostics
+        .iter()
+        .any(|d| matches!(d.severity, sourcey_rustdoc::spec::DiagnosticSeverity::Error));
+    let snapshot = RustdocSpec {
+        version: SPEC_VERSION,
+        sourcey_rustdoc_version: SOURCEY_RUSTDOC_VERSION.to_string(),
+        rustdoc_format_version: EXPECTED_FORMAT_VERSION,
+        rust_toolchain: args.toolchain.clone(),
+        generated_at: now_rfc3339(),
+        crates,
+        diagnostics,
+    };
+
+    // Compact JSON: large snapshots (multi-crate workspaces) benefit from
+    // dropping pretty-print whitespace. Gzip is layered on top when the
+    // output path ends in `.gz`.
+    let serialized =
+        serde_json::to_vec(&snapshot).context("serializing RustdocSpec to JSON")?;
+    write_output(&args.output, &serialized)?;
+
+    if args.strict && has_error_diagnostic {
+        return Ok(ExitCode::from(2));
+    }
+    Ok(ExitCode::SUCCESS)
+}
+
+fn resolve_crate_names(args: &Args) -> Result<Vec<String>> {
+    if !args.crates.is_empty() {
+        return Ok(args.crates.clone());
+    }
+    // Read the package name from the manifest as a fallback.
+    let manifest = manifest_toml_path(&args.manifest)?;
+    let text = fs::read_to_string(&manifest)
+        .with_context(|| format!("reading {}", manifest.display()))?;
+    let parsed: toml::Value = toml::from_str(&text).context("parsing Cargo.toml")?;
+    if let Some(name) = parsed
+        .get("package")
+        .and_then(|p| p.get("name"))
+        .and_then(|n| n.as_str())
+    {
+        return Ok(vec![name.to_string()]);
+    }
+    Err(anyhow!(
+        "no --crate provided and no [package].name in {}",
+        manifest.display()
+    ))
+}
+
+fn manifest_toml_path(input: &PathBuf) -> Result<PathBuf> {
+    if input.is_file() {
+        return Ok(input.clone());
+    }
+    let joined = input.join("Cargo.toml");
+    if joined.is_file() {
+        return Ok(joined);
+    }
+    Err(anyhow!("no Cargo.toml at {}", input.display()))
+}
+
+fn build_rustdoc_json(args: &Args, crate_name: &str) -> Result<PathBuf> {
+    let manifest = manifest_toml_path(&args.manifest)?;
+    let mut builder = Builder::default()
+        .toolchain(&args.toolchain)
+        .manifest_path(&manifest)
+        .package(crate_name)
+        .cap_lints(Some(&args.cap_lints))
+        .document_private_items(args.include_private)
+        .quiet(true);
+    if args.all_features {
+        builder = builder.all_features(true);
+    }
+    if args.no_default_features {
+        builder = builder.no_default_features(true);
+    }
+    if !args.features.is_empty() {
+        builder = builder.features(args.features.iter().map(String::as_str));
+    }
+    if let Some(target) = &args.target {
+        builder = builder.target(target.clone());
+    }
+    let path = builder
+        .build()
+        .map_err(|err| anyhow!("rustdoc-json builder failed: {err}"))?;
+    Ok(path)
+}
+
+fn load_rustdoc_json(path: &PathBuf) -> Result<Crate> {
+    let bytes =
+        fs::read(path).with_context(|| format!("reading rustdoc JSON at {}", path.display()))?;
+    let krate: Crate = serde_json::from_slice(&bytes).context("parsing rustdoc JSON")?;
+    Ok(krate)
+}
+
+fn write_output(target: &str, contents: &[u8]) -> Result<()> {
+    if target == "-" {
+        let stdout = std::io::stdout();
+        let mut handle = stdout.lock();
+        handle.write_all(contents)?;
+        handle.write_all(b"\n")?;
+        return Ok(());
+    }
+    let path = PathBuf::from(target);
+    if let Some(parent) = path.parent() {
+        if !parent.as_os_str().is_empty() {
+            fs::create_dir_all(parent).with_context(|| format!("creating {}", parent.display()))?;
+        }
+    }
+    if is_gz_path(&path) {
+        let file = fs::File::create(&path)
+            .with_context(|| format!("creating {}", path.display()))?;
+        let mut encoder = GzEncoder::new(file, Compression::default());
+        encoder
+            .write_all(contents)
+            .with_context(|| format!("writing gzip stream to {}", path.display()))?;
+        encoder.finish().with_context(|| format!("finalising {}", path.display()))?;
+    } else {
+        fs::write(&path, contents).with_context(|| format!("writing {}", path.display()))?;
+    }
+    Ok(())
+}
+
+fn is_gz_path(path: &Path) -> bool {
+    path.extension()
+        .and_then(|e| e.to_str())
+        .is_some_and(|ext| ext.eq_ignore_ascii_case("gz"))
+}
+
+fn now_rfc3339() -> String {
+    OffsetDateTime::now_utc()
+        .format(&time::format_description::well_known::Rfc3339)
+        .unwrap_or_else(|_| "0".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn format_version_constant_present() {
+        // Sentinel: confirms the helper's expected format version matches
+        // the pinned rustdoc-types dependency at compile time.
+        assert_eq!(super::EXPECTED_FORMAT_VERSION, rustdoc_types::FORMAT_VERSION);
+    }
+}

package/dist/core/sourcey-rustdoc/src/signature.rs

@@ -0,0 +1,415 @@
+use rustdoc_types::{
+    DynTrait, FunctionSignature, GenericArg, GenericArgs, GenericBound, Generics as RdGenerics,
+    Path as RdPath, PreciseCapturingArg, Type, WherePredicate,
+};
+
+use crate::links::LinkContext;
+use crate::spec::{
+    GenericParam, GenericParamKind, Generics, SigInput, SigToken, Signature, TypePath,
+};
+use rustdoc_types::Type as RdType;
+
+pub fn lower_signature(
+    sig: &FunctionSignature,
+    name: &str,
+    is_const: bool,
+    is_async: bool,
+    is_unsafe: bool,
+    links: &LinkContext<'_>,
+) -> Signature {
+    let inputs: Vec<SigInput> = sig
+        .inputs
+        .iter()
+        .map(|(name, ty)| SigInput {
+            name: name.clone(),
+            type_display: render_type(ty),
+        })
+        .collect();
+
+    let output_display = sig.output.as_ref().map(render_type);
+
+    let mut tokens: Vec<SigToken> = Vec::new();
+    let kw = |text: &str| SigToken::Keyword { text: text.to_string() };
+    let punct = |text: &str| SigToken::Punct { text: text.to_string() };
+    if is_const {
+        tokens.push(kw("const"));
+        tokens.push(SigToken::Whitespace);
+    }
+    if is_async {
+        tokens.push(kw("async"));
+        tokens.push(SigToken::Whitespace);
+    }
+    if is_unsafe {
+        tokens.push(kw("unsafe"));
+        tokens.push(SigToken::Whitespace);
+    }
+    tokens.push(kw("fn"));
+    tokens.push(SigToken::Whitespace);
+    tokens.push(SigToken::Type {
+        text: name.to_string(),
+        target: None,
+    });
+    tokens.push(punct("("));
+    for (idx, ((input_name, input_ty), input)) in sig.inputs.iter().zip(inputs.iter()).enumerate() {
+        let _ = input_name;
+        if idx > 0 {
+            tokens.push(punct(","));
+            tokens.push(SigToken::Whitespace);
+        }
+        tokens.push(SigToken::Punct { text: input.name.clone() });
+        tokens.push(punct(":"));
+        tokens.push(SigToken::Whitespace);
+        push_type_tokens(&mut tokens, &resolve_type_path(input_ty, links));
+    }
+    if sig.is_c_variadic {
+        if !inputs.is_empty() {
+            tokens.push(punct(","));
+            tokens.push(SigToken::Whitespace);
+        }
+        tokens.push(punct("..."));
+    }
+    tokens.push(punct(")"));
+
+    if let Some(output_ty) = &sig.output {
+        tokens.push(SigToken::Whitespace);
+        tokens.push(punct("->"));
+        tokens.push(SigToken::Whitespace);
+        push_type_tokens(&mut tokens, &resolve_type_path(output_ty, links));
+    }
+    let _ = output_display;
+
+    let mut display = String::new();
+    for token in &tokens {
+        match token {
+            SigToken::Keyword { text }
+            | SigToken::Punct { text }
+            | SigToken::Generic { text } => display.push_str(text),
+            SigToken::Lifetime { text } => {
+                display.push('\'');
+                display.push_str(text);
+            }
+            SigToken::Type { text, .. } => display.push_str(text),
+            SigToken::Whitespace => display.push(' '),
+            SigToken::Newline => display.push('\n'),
+        }
+    }
+
+    Signature {
+        display,
+        tokens,
+        inputs,
+        output_display,
+        is_c_variadic: sig.is_c_variadic,
+    }
+}
+
+fn push_type_tokens(out: &mut Vec<SigToken>, resolved: &ResolvedTypeDisplay) {
+    out.push(SigToken::Type {
+        text: resolved.text.clone(),
+        target: resolved.target.clone(),
+    });
+}
+
+struct ResolvedTypeDisplay {
+    text: String,
+    target: Option<TypePath>,
+}
+
+fn resolve_type_path(ty: &RdType, links: &LinkContext<'_>) -> ResolvedTypeDisplay {
+    let text = render_type(ty);
+    let target = type_path_target(ty, links);
+    ResolvedTypeDisplay { text, target }
+}
+
+fn type_path_target(ty: &RdType, links: &LinkContext<'_>) -> Option<TypePath> {
+    match ty {
+        RdType::ResolvedPath(p) => {
+            let resolved = links.resolve_id(&p.id);
+            let display = p.path.clone();
+            match resolved {
+                Some(r) => Some(TypePath {
+                    crate_id: r.crate_id,
+                    path: r.path,
+                    display,
+                    external: r.external,
+                    html_root_url: r.html_root_url,
+                }),
+                None => Some(TypePath {
+                    crate_id: 0,
+                    path: vec![p.path.clone()],
+                    display,
+                    external: false,
+                    html_root_url: None,
+                }),
+            }
+        }
+        RdType::BorrowedRef { type_, .. } | RdType::RawPointer { type_, .. } => {
+            type_path_target(type_, links)
+        }
+        _ => None,
+    }
+}
+
+pub fn lower_generics(generics: &RdGenerics) -> Generics {
+    let params = generics
+        .params
+        .iter()
+        .map(|p| GenericParam {
+            name: p.name.clone(),
+            kind: match p.kind {
+                rustdoc_types::GenericParamDefKind::Lifetime { .. } => GenericParamKind::Lifetime,
+                rustdoc_types::GenericParamDefKind::Type { .. } => GenericParamKind::Type,
+                rustdoc_types::GenericParamDefKind::Const { .. } => GenericParamKind::Const,
+            },
+            default_display: generic_param_default(&p.kind),
+            bounds: generic_param_bounds(&p.kind),
+        })
+        .collect();
+    let where_predicates = generics
+        .where_predicates
+        .iter()
+        .map(render_where_predicate)
+        .collect();
+    Generics {
+        params,
+        where_predicates,
+    }
+}
+
+fn generic_param_default(kind: &rustdoc_types::GenericParamDefKind) -> Option<String> {
+    match kind {
+        rustdoc_types::GenericParamDefKind::Type { default, .. } => default.as_ref().map(render_type),
+        rustdoc_types::GenericParamDefKind::Const { default, .. } => default.clone(),
+        rustdoc_types::GenericParamDefKind::Lifetime { .. } => None,
+    }
+}
+
+fn generic_param_bounds(kind: &rustdoc_types::GenericParamDefKind) -> Vec<String> {
+    match kind {
+        rustdoc_types::GenericParamDefKind::Type { bounds, .. } => {
+            bounds.iter().map(render_bound).collect()
+        }
+        rustdoc_types::GenericParamDefKind::Lifetime { outlives, .. } => outlives.clone(),
+        rustdoc_types::GenericParamDefKind::Const { .. } => Vec::new(),
+    }
+}
+
+fn render_where_predicate(pred: &WherePredicate) -> String {
+    match pred {
+        WherePredicate::BoundPredicate {
+            type_, bounds, generic_params, ..
+        } => {
+            let mut s = String::new();
+            if !generic_params.is_empty() {
+                s.push_str("for<");
+                let parts: Vec<String> = generic_params.iter().map(|p| p.name.clone()).collect();
+                s.push_str(&parts.join(", "));
+                s.push_str("> ");
+            }
+            s.push_str(&render_type(type_));
+            if !bounds.is_empty() {
+                s.push_str(": ");
+                let parts: Vec<String> = bounds.iter().map(render_bound).collect();
+                s.push_str(&parts.join(" + "));
+            }
+            s
+        }
+        WherePredicate::LifetimePredicate { lifetime, outlives } => {
+            let mut s = lifetime.clone();
+            if !outlives.is_empty() {
+                s.push_str(": ");
+                s.push_str(&outlives.join(" + "));
+            }
+            s
+        }
+        WherePredicate::EqPredicate { lhs, rhs } => {
+            format!("{} = {}", render_type(lhs), render_term(rhs))
+        }
+    }
+}
+
+pub fn render_bound(bound: &GenericBound) -> String {
+    match bound {
+        GenericBound::TraitBound {
+            trait_,
+            generic_params,
+            modifier,
+        } => {
+            let mut s = String::new();
+            if !generic_params.is_empty() {
+                s.push_str("for<");
+                let parts: Vec<String> = generic_params.iter().map(|p| p.name.clone()).collect();
+                s.push_str(&parts.join(", "));
+                s.push_str("> ");
+            }
+            match modifier {
+                rustdoc_types::TraitBoundModifier::None => {}
+                rustdoc_types::TraitBoundModifier::Maybe => s.push('?'),
+                rustdoc_types::TraitBoundModifier::MaybeConst => s.push_str("~const "),
+            }
+            s.push_str(&render_path(trait_));
+            s
+        }
+        GenericBound::Outlives(lifetime) => lifetime.clone(),
+        GenericBound::Use(captures) => {
+            let parts: Vec<String> = captures
+                .iter()
+                .map(|c| match c {
+                    PreciseCapturingArg::Lifetime(s) | PreciseCapturingArg::Param(s) => s.clone(),
+                })
+                .collect();
+            format!("use<{}>", parts.join(", "))
+        }
+    }
+}
+
+fn render_term(term: &rustdoc_types::Term) -> String {
+    match term {
+        rustdoc_types::Term::Type(t) => render_type(t),
+        rustdoc_types::Term::Constant(c) => c.expr.clone(),
+    }
+}
+
+pub fn render_type(ty: &Type) -> String {
+    match ty {
+        Type::ResolvedPath(p) => render_path(p),
+        Type::DynTrait(d) => render_dyn(d),
+        Type::Generic(s) => s.clone(),
+        Type::Primitive(s) => s.clone(),
+        Type::FunctionPointer(f) => format!(
+            "fn({}){}",
+            f.sig
+                .inputs
+                .iter()
+                .map(|(_, t)| render_type(t))
+                .collect::<Vec<_>>()
+                .join(", "),
+            f.sig
+                .output
+                .as_ref()
+                .map(|t| format!(" -> {}", render_type(t)))
+                .unwrap_or_default()
+        ),
+        Type::Tuple(parts) => {
+            let inner: Vec<String> = parts.iter().map(render_type).collect();
+            format!("({})", inner.join(", "))
+        }
+        Type::Slice(inner) => format!("[{}]", render_type(inner)),
+        Type::Array { type_, len } => format!("[{}; {}]", render_type(type_), len),
+        Type::Pat { type_, .. } => render_type(type_),
+        Type::ImplTrait(bounds) => {
+            let parts: Vec<String> = bounds.iter().map(render_bound).collect();
+            format!("impl {}", parts.join(" + "))
+        }
+        Type::Infer => "_".to_string(),
+        Type::RawPointer { is_mutable, type_ } => {
+            let m = if *is_mutable { "*mut " } else { "*const " };
+            format!("{}{}", m, render_type(type_))
+        }
+        Type::BorrowedRef {
+            lifetime,
+            is_mutable,
+            type_,
+        } => {
+            let lt = lifetime
+                .as_ref()
+                .map(|l| format!("{} ", l))
+                .unwrap_or_default();
+            let m = if *is_mutable { "mut " } else { "" };
+            format!("&{}{}{}", lt, m, render_type(type_))
+        }
+        Type::QualifiedPath {
+            name,
+            args,
+            self_type,
+            trait_,
+            ..
+        } => {
+            let self_render = render_type(self_type);
+            let trait_render = trait_
+                .as_ref()
+                .map(|p| format!(" as {}", render_path(p)))
+                .unwrap_or_default();
+            let args_render = match args.as_ref() {
+                Some(a) => render_generic_args(a),
+                None => String::new(),
+            };
+            format!("<{}{}>::{}{}", self_render, trait_render, name, args_render)
+        }
+    }
+}
+
+fn render_path(path: &RdPath) -> String {
+    let mut s = path.path.clone();
+    if let Some(args) = &path.args {
+        s.push_str(&render_generic_args(args));
+    }
+    s
+}
+
+fn render_generic_args(args: &GenericArgs) -> String {
+    match args {
+        GenericArgs::AngleBracketed { args, constraints } => {
+            let mut parts: Vec<String> = args
+                .iter()
+                .map(|a| match a {
+                    GenericArg::Lifetime(s) => s.clone(),
+                    GenericArg::Type(t) => render_type(t),
+                    GenericArg::Const(c) => c.expr.clone(),
+                    GenericArg::Infer => "_".to_string(),
+                })
+                .collect();
+            for c in constraints {
+                let term = match &c.binding {
+                    rustdoc_types::AssocItemConstraintKind::Equality(t) => render_term(t),
+                    rustdoc_types::AssocItemConstraintKind::Constraint(bounds) => {
+                        let bs: Vec<String> = bounds.iter().map(render_bound).collect();
+                        bs.join(" + ")
+                    }
+                };
+                let sep = matches!(
+                    c.binding,
+                    rustdoc_types::AssocItemConstraintKind::Equality(_)
+                )
+                .then(|| "=".to_string())
+                .unwrap_or_else(|| ":".to_string());
+                parts.push(format!("{}{}{}", c.name, sep, term));
+            }
+            if parts.is_empty() {
+                String::new()
+            } else {
+                format!("<{}>", parts.join(", "))
+            }
+        }
+        GenericArgs::Parenthesized { inputs, output } => {
+            let in_render: Vec<String> = inputs.iter().map(render_type).collect();
+            let out_render = output
+                .as_ref()
+                .map(|t| format!(" -> {}", render_type(t)))
+                .unwrap_or_default();
+            format!("({}){}", in_render.join(", "), out_render)
+        }
+        GenericArgs::ReturnTypeNotation => "(..)".to_string(),
+    }
+}
+
+fn render_dyn(d: &DynTrait) -> String {
+    let parts: Vec<String> = d
+        .traits
+        .iter()
+        .map(|t| {
+            let mut s = render_path(&t.trait_);
+            if !t.generic_params.is_empty() {
+                let lts: Vec<String> = t.generic_params.iter().map(|p| p.name.clone()).collect();
+                s.push_str(&format!(" + for<{}>", lts.join(", ")));
+            }
+            s
+        })
+        .collect();
+    let lt = d
+        .lifetime
+        .as_ref()
+        .map(|l| format!(" + {}", l))
+        .unwrap_or_default();
+    format!("dyn {}{}", parts.join(" + "), lt)
+}