From 67ea13ba9a4f74f4cbec2eaca320aa0dd3a8c252 Mon Sep 17 00:00:00 2001 From: Kinflou <149606337+Kinflou@users.noreply.github.com> Date: Fri, 13 Nov 2026 08:51:58 +0800 Subject: [PATCH 1/3] Bump core, generation and the generators to the docs-links revs comline-core 35ab4b8 -> 263e583; comline-codegen, comline-doc-markdown and comline-doc-html -> generation 3ad2c79; comline-codegen-rust and comline-codegen-typescript to the heads that pin them. The test generator fixtures pin the same revs. core's changelog now takes the encodings each version sees alongside its schemas and config, so `doc` carries each version's stored configs (own and its dependencies') and reads the encodings from them. --- Cargo.lock | 14 +++---- Cargo.toml | 12 +++--- src/commands/doc.rs | 63 ++++++++++++++++++++-------- src/history.rs | 14 ++++++- tests/fixtures/generators/Cargo.lock | 12 +++--- tests/fixtures/generators/Cargo.toml | 8 ++-- 6 files changed, 82 insertions(+), 41 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 1af253f..ff060e0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -515,7 +515,7 @@ source = "git+https://github.com/ComlineProject/runtime?rev=3b9cc9dc53a83fb2830d [[package]] name = "comline-codegen" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=0977d7a339e92ced0ebaac477a0f6b3c1104c680#0977d7a339e92ced0ebaac477a0f6b3c1104c680" +source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" dependencies = [ "comline-core", "eyre", @@ -529,7 +529,7 @@ dependencies = [ [[package]] name = "comline-codegen-rust" version = "0.1.0" -source = "git+https://github.com/ComlineProject/comline-rust?rev=6405b44d1b49d5926ba6519c46eac84bd5467962#6405b44d1b49d5926ba6519c46eac84bd5467962" +source = "git+https://github.com/ComlineProject/comline-rust?rev=349763589f16fcee43a9b8bc3e2d9af8674fef00#349763589f16fcee43a9b8bc3e2d9af8674fef00" dependencies = [ "comline-codegen", "comline-core", @@ -539,7 +539,7 @@ dependencies = [ [[package]] name = "comline-codegen-typescript" version = "0.1.0" -source = "git+https://github.com/ComlineProject/comline-typescript?rev=9496b1e9f158029a18e4db9435f5944f501b30cb#9496b1e9f158029a18e4db9435f5944f501b30cb" +source = "git+https://github.com/ComlineProject/comline-typescript?rev=20bad456df0334b0197ddefdc1460f96c7ff33ae#20bad456df0334b0197ddefdc1460f96c7ff33ae" dependencies = [ "comline-codegen", "comline-core", @@ -549,7 +549,7 @@ dependencies = [ [[package]] name = "comline-core" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=35ab4b801c9b35af591fb48972407468c8e8af24#35ab4b801c9b35af591fb48972407468c8e8af24" +source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" dependencies = [ "ariadne", "blake3", @@ -579,12 +579,12 @@ dependencies = [ [[package]] name = "comline-core-stdlib" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=35ab4b801c9b35af591fb48972407468c8e8af24#35ab4b801c9b35af591fb48972407468c8e8af24" +source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" [[package]] name = "comline-doc-html" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=0977d7a339e92ced0ebaac477a0f6b3c1104c680#0977d7a339e92ced0ebaac477a0f6b3c1104c680" +source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" dependencies = [ "comline-codegen", "eyre", @@ -595,7 +595,7 @@ dependencies = [ [[package]] name = "comline-doc-markdown" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=0977d7a339e92ced0ebaac477a0f6b3c1104c680#0977d7a339e92ced0ebaac477a0f6b3c1104c680" +source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" dependencies = [ "comline-codegen", "eyre", diff --git a/Cargo.toml b/Cargo.toml index 53ed580..e918b8c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -32,20 +32,20 @@ eyre = "0.6.8" # needs real I/O (git fetch, filesystem), so it's off by default for # `comline-core`'s wasm32 consumers (the playground editor, the language # server); the CLI is the one consumer that actually runs `comline build`. -comline-core = { git = "https://github.com/ComlineProject/core", rev = "35ab4b801c9b35af591fb48972407468c8e8af24", features = ["deps"] } +comline-core = { git = "https://github.com/ComlineProject/core", rev = "263e58378bb7efcaa466542ca644228ad14e2884", features = ["deps"] } # All three pinned to revs that agree on one `comline-codegen`, and bumped # together: comline-rust and comline-typescript's codegen crates consume # `comline-codegen`'s types, so the rev below must be byte-identical to the # one *they* pin - Cargo only unifies a git dependency across identical rev # strings, and two copies of `GenRequest` are two incompatible types. -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } # The official Markdown and HTML documentation renderers (`comline doc`), # linked in like the official generators. Same generation rev as # `comline-codegen`. -comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } -comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } -comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "6405b44d1b49d5926ba6519c46eac84bd5467962", optional = true } -comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "9496b1e9f158029a18e4db9435f5944f501b30cb", optional = true } +comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } +comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } +comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "349763589f16fcee43a9b8bc3e2d9af8674fef00", optional = true } +comline-codegen-typescript = { git = "https://github.com/ComlineProject/comline-typescript", rev = "20bad456df0334b0197ddefdc1460f96c7ff33ae", optional = true } # `comline conformance`: the conformance runner (corpus loading, judging, # profile proofs) and its case format, a public spec. Pinned by git rev. comline-runtime-conformance = { git = "https://github.com/ComlineProject/runtime", rev = "3b9cc9dc53a83fb2830d91b267bd5f477f0a1e51" } diff --git a/src/commands/doc.rs b/src/commands/doc.rs index 7ba6886..e266a72 100644 --- a/src/commands/doc.rs +++ b/src/commands/doc.rs @@ -52,7 +52,8 @@ use comline_core::doc::{self, ChangelogSpan, DocModel, FrozenDocs, DOC_MODEL_VER use comline_core::package::build::cas::objects::{Commit, Tree}; use comline_core::package::build::cas::refs; use comline_core::package::build::cas::storage::Hash; -use comline_core::package::config::ir::frozen::FrozenUnit as ConfigUnit; +use comline_core::package::config::ir::context::ProjectContext; +use comline_core::package::config::ir::frozen::cas::blob::StoredConfigs; use comline_core::schema::ir::frozen::unit::FrozenUnit; use miette::{miette, IntoDiagnostic, Result, WrapErr}; use serde::{Deserialize, Serialize}; @@ -96,8 +97,9 @@ struct Version { model: DocModel, /// Its own frozen schemas: not its dependencies' or `std`'s. schemas: Vec>, - /// Its frozen config, whose `wire` its changelogs are measured under. - config: Vec, + /// Its frozen configs, own and its dependencies': the `wire` and the + /// encodings its changelogs are measured under. + configs: StoredConfigs, /// The commits its changelogs are computed from, for the cache key. changelog_from: Vec, /// What its documentation lacks. @@ -217,12 +219,12 @@ pub fn run(work_dir: &Path, flags: Flags) -> Result<()> { let commit = history::resolve(&history, from)?; let store = history::open_store(work_dir)?; let old = history::load_schemas(&store, commit)?; - let old_config = history::load_config(&store, commit)?; - version.model.changelog.push(doc::changelog( + let old_configs = history::load_stored_configs(&store, commit)?; + version.model.changelog.push(changelog( &commit.version, - (&old, &old_config), + (&old, &old_configs), &version.id, - (&version.schemas, &version.config), + (&version.schemas, &version.configs), )); } let first = document_one(&out, &formats, &renderers, &cfg, version)?; @@ -616,7 +618,7 @@ fn every_version(work_dir: &Path, select: Option<&DocVersions>) -> Result) -> Result) -> Result = Vec::with_capacity(versions.len()); for (mut version, since) in versions { if let Some(previous) = out.last() { - let step = doc::changelog( + let step = changelog( &previous.id, - (&previous.schemas, &previous.config), + (&previous.schemas, &previous.configs), &version.id, - (&version.schemas, &version.config), + (&version.schemas, &version.configs), ); version.model.changelog = vec![step]; version.changelog_from.extend(previous.commit); @@ -707,6 +709,33 @@ fn kind_of(version: &str) -> (VersionKind, String) { } } +/// What a compiled package's changelogs are measured under: its own config and +/// its dependencies', all of which a compile has. +fn compiled_configs(context: &ProjectContext) -> StoredConfigs { + StoredConfigs { + own: doc::frozen_config(context), + own_stored: true, + dependencies: context.dependency_configs.clone(), + unstored: vec![], + } +} + +/// What changed from one version to the next, each given as its frozen schemas +/// and configs, the encodings read from the configs. +fn changelog( + from: &str, + old: (&[Vec], &StoredConfigs), + to: &str, + new: (&[Vec], &StoredConfigs), +) -> doc::Changelog { + doc::changelog( + from, + (old.0, &old.1.own, &old.1.encodings()), + to, + (new.0, &new.1.own, &new.1.encodings()), + ) +} + /// `--version`'s one built version. fn frozen_version(work_dir: &Path, spec: &str) -> Result { let history = history::load(work_dir)?; @@ -726,10 +755,10 @@ fn frozen(work_dir: &Path, hash: Hash, commit: &Commit) -> Result<(Version, Froz let store = history::open_store(work_dir)?; // Every compiled schema: the package's own, its dependencies' and std's. let all_schemas = history::load_schemas(&store, commit)?; - let config = history::load_config(&store, commit)?; + let configs = history::load_stored_configs(&store, commit)?; // A built version's config doesn't always freeze the package's name; // the working tree's is the same unless the package was renamed. - let name = comline_core::package::config::ir::frozen::namespace(&config) + let name = comline_core::package::config::ir::frozen::namespace(&configs.own) .map(str::to_string) .or_else(|| { comline_core::package::build::compile_package_without_fetching(work_dir) @@ -791,7 +820,7 @@ fn frozen(work_dir: &Path, hash: Hash, commit: &Commit) -> Result<(Version, Froz commit: Some(hash), model, schemas, - config, + configs, changelog_from: vec![], notes, }, diff --git a/src/history.rs b/src/history.rs index 1f892fa..f3ef602 100644 --- a/src/history.rs +++ b/src/history.rs @@ -9,7 +9,7 @@ use comline_core::package::build::cas::object_store::CURRENT_IR_FORMAT_VERSION; use comline_core::package::build::cas::objects::{Commit, EntryMode, Tree}; use comline_core::package::build::cas::storage::Hash; use comline_core::package::build::cas::{refs, ObjectStore}; -use comline_core::package::config::ir::frozen::cas::blob::read_config; +use comline_core::package::config::ir::frozen::cas::blob::{read_config, StoredConfigs}; use comline_core::package::config::ir::frozen::FrozenUnit as ConfigUnit; use comline_core::schema::ir::frozen::cas::blob::load_schema_from_tree; use comline_core::schema::ir::frozen::unit::FrozenUnit; @@ -136,6 +136,18 @@ pub fn load_config(store: &ObjectStore, commit: &Commit) -> Result Result { + let root_bytes = store + .read(&commit.tree) + .map_err(|e| miette::miette!("failed to read root tree: {e:#}"))?; + let root = + Tree::from_bytes(&root_bytes).map_err(|e| miette::miette!("corrupt root tree: {e:#}"))?; + StoredConfigs::read(store, &root) + .map_err(|e| miette::miette!("failed to read the package's configs: {e:#}")) +} + /// Load every local schema's frozen units from a commit's root tree, in tree /// order. Vendored dependencies (`dep_` trees) aren't this package's /// schemas and are skipped. diff --git a/tests/fixtures/generators/Cargo.lock b/tests/fixtures/generators/Cargo.lock index 39c1247..97faf86 100644 --- a/tests/fixtures/generators/Cargo.lock +++ b/tests/fixtures/generators/Cargo.lock @@ -84,7 +84,7 @@ source = "git+https://github.com/ComlineProject/specification?rev=068500670debad [[package]] name = "comline-codegen" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=0977d7a339e92ced0ebaac477a0f6b3c1104c680#0977d7a339e92ced0ebaac477a0f6b3c1104c680" +source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" dependencies = [ "comline-core", "eyre", @@ -98,7 +98,7 @@ dependencies = [ [[package]] name = "comline-codegen-rust" version = "0.1.0" -source = "git+https://github.com/ComlineProject/comline-rust?rev=6405b44d1b49d5926ba6519c46eac84bd5467962#6405b44d1b49d5926ba6519c46eac84bd5467962" +source = "git+https://github.com/ComlineProject/comline-rust?rev=349763589f16fcee43a9b8bc3e2d9af8674fef00#349763589f16fcee43a9b8bc3e2d9af8674fef00" dependencies = [ "comline-codegen", "comline-core", @@ -108,7 +108,7 @@ dependencies = [ [[package]] name = "comline-core" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=35ab4b801c9b35af591fb48972407468c8e8af24#35ab4b801c9b35af591fb48972407468c8e8af24" +source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" dependencies = [ "blake3", "ciborium", @@ -126,12 +126,12 @@ dependencies = [ [[package]] name = "comline-core-stdlib" version = "0.1.0" -source = "git+https://github.com/ComlineProject/core?rev=35ab4b801c9b35af591fb48972407468c8e8af24#35ab4b801c9b35af591fb48972407468c8e8af24" +source = "git+https://github.com/ComlineProject/core?rev=263e58378bb7efcaa466542ca644228ad14e2884#263e58378bb7efcaa466542ca644228ad14e2884" [[package]] name = "comline-doc-html" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=0977d7a339e92ced0ebaac477a0f6b3c1104c680#0977d7a339e92ced0ebaac477a0f6b3c1104c680" +source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" dependencies = [ "comline-codegen", "eyre", @@ -142,7 +142,7 @@ dependencies = [ [[package]] name = "comline-doc-markdown" version = "0.1.0" -source = "git+https://github.com/ComlineProject/generation?rev=0977d7a339e92ced0ebaac477a0f6b3c1104c680#0977d7a339e92ced0ebaac477a0f6b3c1104c680" +source = "git+https://github.com/ComlineProject/generation?rev=3ad2c79f48242f7de4bed3e8bc23c5673a381a2e#3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" dependencies = [ "comline-codegen", "eyre", diff --git a/tests/fixtures/generators/Cargo.toml b/tests/fixtures/generators/Cargo.toml index 9a30f9e..8bdd403 100644 --- a/tests/fixtures/generators/Cargo.toml +++ b/tests/fixtures/generators/Cargo.toml @@ -12,7 +12,7 @@ publish = false [dependencies] # The same revs the CLI pins, so the real generator's output is comparable # byte for byte with the CLI's built-in one. -comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } -comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } -comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "0977d7a339e92ced0ebaac477a0f6b3c1104c680" } -comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "6405b44d1b49d5926ba6519c46eac84bd5467962" } +comline-codegen = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } +comline-doc-markdown = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } +comline-doc-html = { git = "https://github.com/ComlineProject/generation", rev = "3ad2c79f48242f7de4bed3e8bc23c5673a381a2e" } +comline-codegen-rust = { git = "https://github.com/ComlineProject/comline-rust", rev = "349763589f16fcee43a9b8bc3e2d9af8674fef00" } From 91d4a9828dd44b1a892c1dd854d1eafc2e2085ce Mon Sep 17 00:00:00 2001 From: Kinflou <149606337+Kinflou@users.noreply.github.com> Date: Fri, 13 Nov 2026 08:52:32 +0800 Subject: [PATCH 2/3] Rename the generate module to generation; fold in the in-progress formatting commands/generate.rs -> commands/generation.rs and tests/cli/generate.rs -> tests/cli/generation.rs, to match the `generation` command. The formatting is the owner's in-progress work: blank lines between logical steps, struct fields and enum variants, the crate's own imports grouped before the external ones in generation.rs and history.rs, and a blank line after the consts in external.rs. --- src/commands/build.rs | 2 +- src/commands/clean.rs | 2 +- src/commands/{generate.rs => generation.rs} | 41 ++++++++++++++++----- src/commands/mod.rs | 2 +- src/commands/new.rs | 2 +- src/commands/targets.rs | 2 +- src/external.rs | 4 ++ src/history.rs | 5 ++- src/main.rs | 2 +- tests/cli/{generate.rs => generation.rs} | 0 tests/cli/main.rs | 4 +- 11 files changed, 47 insertions(+), 19 deletions(-) rename src/commands/{generate.rs => generation.rs} (99%) rename tests/cli/{generate.rs => generation.rs} (100%) diff --git a/src/commands/build.rs b/src/commands/build.rs index bbbbab2..186876d 100644 --- a/src/commands/build.rs +++ b/src/commands/build.rs @@ -15,7 +15,7 @@ use miette::Result; use crate::bounds_migration; use crate::changes; -use crate::commands::generate::generator_registry; +use crate::commands::generation::generator_registry; use crate::commands::{core_err, ensure_project}; use crate::lang_targets; use crate::ui; diff --git a/src/commands/clean.rs b/src/commands/clean.rs index 08f1249..99619ce 100644 --- a/src/commands/clean.rs +++ b/src/commands/clean.rs @@ -116,7 +116,7 @@ fn generated_files_for(work_dir: &Path, target: Option<&str>) -> Result Vec::new(), }; - let registry = super::generate::generator_registry(); + let registry = super::generation::generator_registry(); let mut files = Vec::new(); for t in &targets { // A dedicated output directory: remove it wholesale (stale files too). diff --git a/src/commands/generate.rs b/src/commands/generation.rs similarity index 99% rename from src/commands/generate.rs rename to src/commands/generation.rs index 63d4455..dc4d8f0 100644 --- a/src/commands/generate.rs +++ b/src/commands/generation.rs @@ -13,6 +13,15 @@ use std::collections::BTreeMap; use std::path::{Path, PathBuf}; use std::time::Duration; +use crate::commands::{core_err, ensure_project}; +use crate::external::{self, External}; +use crate::gen_config::Destination; +use crate::lang_targets::{self, TargetError}; +use crate::{history, ui, watch}; + +use comline_codegen::config::{ + self as gen_config, ComlineToml, DeclaredLang, Overrides, VersionSpec, +}; use comline_codegen::protocol::{Description, TargetLanguage}; use comline_codegen::versions::LangVersion; use comline_codegen::{ @@ -24,15 +33,6 @@ use comline_core::schema::idl::constants::SCHEMA_EXTENSION; use comline_core::schema::ir::frozen::unit::{schema_namespace_as_path, FrozenUnit}; use miette::{miette, IntoDiagnostic, Result, WrapErr}; -use crate::commands::{core_err, ensure_project}; -use crate::external::{self, External}; -use crate::gen_config::Destination; -use crate::lang_targets::{self, TargetError}; -use crate::{history, ui, watch}; -use comline_codegen::config::{ - self as gen_config, ComlineToml, DeclaredLang, Overrides, VersionSpec, -}; - /// The generator registry, composed from the per-language `comline-codegen-*` /// crates this CLI was built with — one `register()` per crate, each behind its /// `gen-` cargo feature (both on by default). A build without a feature @@ -40,10 +40,13 @@ use comline_codegen::config::{ pub(crate) fn generator_registry() -> Registry { #[allow(unused_mut)] let mut registry = Registry::new(); + #[cfg(feature = "gen-rust")] comline_codegen_rust::register(&mut registry); + #[cfg(feature = "gen-typescript")] comline_codegen_typescript::register(&mut registry); + registry } @@ -69,9 +72,11 @@ pub fn run( struct GenVersion { package_version: String, schemas: Vec<(String, Vec)>, // (namespace path, frozen units) + /// The version's own `wire.format`: a built version keeps the format it /// was built with. wire_format: String, + /// Where its facts come from (`comline_core::compat`), for a package that /// needs them: a built version's, or the working tree's. facts: FactsSource, @@ -81,6 +86,7 @@ struct GenVersion { enum FactsSource { /// This commit's. Commit(comline_core::package::build::cas::storage::Hash), + /// The working tree's, as its next build would record them. WorkingTree, } @@ -101,7 +107,9 @@ fn generate_once(work_dir: &Path, overrides: &Overrides, dry_run: bool, list: bo let spinner = ui::spinner("validating schemas"); let context = build::compile_package(work_dir); + ui::finish_spinner(spinner); + let context = context.map_err(|e| core_err("code generation failed", e))?; for warning in context.rendered_warnings() { ui::warn(warning); @@ -566,6 +574,7 @@ fn gen_version_from_commit( (ns, units) }) .collect(); + let config = history::load_config(store, commit)?; Ok(GenVersion { package_version: version.to_owned(), @@ -603,10 +612,12 @@ fn facts_for( } .map_err(|e| miette!("working out the package's facts: {e:#}"))?; // The same fields under the same names: the generator protocol's mirror. + let facts = serde_json::to_value(&facts) .and_then(serde_json::from_value) .into_diagnostic() .wrap_err("the package's facts")?; + Ok(Some(facts)) } @@ -619,10 +630,12 @@ fn warn_async_unused(language: &str, request: &GenerateRequest) { if !request.async_api { return; } + let uses = features::used(&request.schemas, &features::Options::of(request)); if uses.iter().any(|u| u.feature == features::Feature::Async) { return; } + ui::warn(format!( "`{language}`: `async = true`, but no protocol runs on a connection, so the output \ is the same as without it - every protocol here is lockstep: on the `datagram` \ @@ -657,9 +670,11 @@ fn note_no_connection_protocols(language: &str, request: &GenerateRequest) { } } } + if framings.is_empty() { return; } + let framings: Vec = framings .into_iter() .map(|f| match f.as_str() { @@ -669,6 +684,7 @@ fn note_no_connection_protocols(language: &str, request: &GenerateRequest) { _ => format!("`{f}`"), }) .collect(); + let page = match language { "rust" => " (https://comlineproject.github.io/docs/languages/rust/connections/#when-theyre-generated)", "typescript" => { @@ -676,6 +692,7 @@ fn note_no_connection_protocols(language: &str, request: &GenerateRequest) { } _ => "", }; + ui::note(format!( "`{language}`: no package `Services` / `serve` / `connect` - every protocol is \ server-provided on {}, and none is on a connection{page}", @@ -695,24 +712,30 @@ fn warn_ignored(language: &str, request: &GenerateRequest, resolved: &Resolved) ignored.entry(u.feature).or_default().push(u); } } + for (feature, uses) in ignored { let s = resolved.support(feature); let mut message = format!("`{language}` ignores {}", feature.title()); + if let Some(note) = s.note { message.push_str(&format!(": {note}")); } + if let Some(tracking) = s.tracking { message.push_str(&format!(" ({tracking})")); } + let first = uses[0]; let place = match first.namespace.is_empty() { true => first.owner.clone(), false => format!("schema '{}', {}", first.namespace, first.owner), }; + message.push_str(&format!(" - used by {place}")); if uses.len() > 1 { message.push_str(&format!(" and {} more", uses.len() - 1)); } + ui::warn(message); } } diff --git a/src/commands/mod.rs b/src/commands/mod.rs index 94b489f..9fddde6 100644 --- a/src/commands/mod.rs +++ b/src/commands/mod.rs @@ -11,7 +11,7 @@ pub mod conformance; pub mod diff; pub mod doc; pub mod fix; -pub mod generate; +pub mod generation; pub mod inspect; pub mod list; pub mod new; diff --git a/src/commands/new.rs b/src/commands/new.rs index 011b7b4..523ba74 100644 --- a/src/commands/new.rs +++ b/src/commands/new.rs @@ -5,7 +5,7 @@ use std::process::Command; use miette::{IntoDiagnostic, Result, WrapErr}; -use crate::commands::generate::generator_registry; +use crate::commands::generation::generator_registry; use crate::ui; const GREETING_IDS: &str = "\ diff --git a/src/commands/targets.rs b/src/commands/targets.rs index 9fc2f25..3a2677c 100644 --- a/src/commands/targets.rs +++ b/src/commands/targets.rs @@ -14,7 +14,7 @@ use comline_codegen::features::{self, Column, Feature}; use comline_codegen::versions::Versions; use miette::{IntoDiagnostic, Result}; -use crate::commands::generate::generator_registry; +use crate::commands::generation::generator_registry; pub fn run(with_features: bool, json: bool) -> Result<()> { let registry = generator_registry(); diff --git a/src/external.rs b/src/external.rs index be1a3cb..335576c 100644 --- a/src/external.rs +++ b/src/external.rs @@ -36,13 +36,17 @@ use miette::{miette, Result}; /// How long one call to a generator may take, unless the target sets /// `timeout` (in seconds). pub const DEFAULT_TIMEOUT: Duration = comline_codegen::config::DEFAULT_TIMEOUT; + /// The most a generator may write to stdout: one encoded response. pub const STDOUT_CAP: usize = 256 * 1024 * 1024; + /// The most generated file contents one response may carry, all files /// together. pub const GENERATED_CAP: usize = 256 * 1024 * 1024; + /// The most of a generator's stderr that's shown; the rest is dropped. pub const STDERR_CAP: usize = 64 * 1024; + /// The most linear memory a `.wasm` generator may grow to. #[cfg(feature = "gen-wasm")] pub const WASM_MEMORY: usize = 1024 * 1024 * 1024; diff --git a/src/history.rs b/src/history.rs index f3ef602..8b0efb9 100644 --- a/src/history.rs +++ b/src/history.rs @@ -5,6 +5,8 @@ use std::path::Path; +use crate::error::CliError; + use comline_core::package::build::cas::object_store::CURRENT_IR_FORMAT_VERSION; use comline_core::package::build::cas::objects::{Commit, EntryMode, Tree}; use comline_core::package::build::cas::storage::Hash; @@ -15,8 +17,6 @@ use comline_core::schema::ir::frozen::cas::blob::load_schema_from_tree; use comline_core::schema::ir::frozen::unit::FrozenUnit; use miette::Result; -use crate::error::CliError; - /// One commit in the chain, with its object hash. pub struct Entry { pub hash: Hash, @@ -172,5 +172,6 @@ pub fn load_schemas(store: &ObjectStore, commit: &Commit) -> Result Result<()> { .or(no_external_std.then_some(false)), validate_on_decode: validate_on_decode.as_deref(), }; - commands::generate::run(&work_dir, &overrides, dry_run, list, watch) + commands::generation::run(&work_dir, &overrides, dry_run, list, watch) } Commands::Diff { old, new } => commands::diff::run(&work_dir, &old, &new), Commands::Reset { force, dry_run } => commands::reset::run(&work_dir, force, dry_run), diff --git a/tests/cli/generate.rs b/tests/cli/generation.rs similarity index 100% rename from tests/cli/generate.rs rename to tests/cli/generation.rs diff --git a/tests/cli/main.rs b/tests/cli/main.rs index a7f77f9..4888682 100644 --- a/tests/cli/main.rs +++ b/tests/cli/main.rs @@ -2,7 +2,7 @@ //! //! Shared helpers live in [`util`]. Cargo compiles this directory as a single //! test target (`tests/cli/main.rs`), so `cargo test` runs the whole suite and -//! `cargo test ::` scopes to one area (e.g. `cargo test generate::`). +//! `cargo test ::` scopes to one area (e.g. `cargo test generation::`). mod util; @@ -16,7 +16,7 @@ mod diff; mod doc; mod end_to_end; mod external; -mod generate; +mod generation; mod global; mod inspect; mod list; From a66d5f2e9a36a54ba2557492c741586487d55478 Mon Sep 17 00:00:00 2001 From: Kinflou <149606337+Kinflou@users.noreply.github.com> Date: Fri, 13 Nov 2026 08:58:14 +0800 Subject: [PATCH 3/3] Take each generator's docs link from the generator The note that a package has no `Services` / `serve` / `connect` linked to a page chosen by matching the language's name. It now links to the page the generator names for `Topic::Connections`: a built-in generator's `docs` table, or the `docs` of the `LanguageInfo` an external generator's description offers for the target's language. A generator that names none gets the note without a link. The `hostile` fixture generator gets `docs` and `plain` modes, which generate a file with and without a connections page. --- src/commands/generation.rs | 40 ++++++++++------ tests/cli/external.rs | 49 ++++++++++++++++++++ tests/cli/generation.rs | 49 ++++++++++++++------ tests/cli/util.rs | 20 ++++++++ tests/fixtures/generators/src/bin/hostile.rs | 16 ++++++- 5 files changed, 143 insertions(+), 31 deletions(-) diff --git a/src/commands/generation.rs b/src/commands/generation.rs index dc4d8f0..74611a9 100644 --- a/src/commands/generation.rs +++ b/src/commands/generation.rs @@ -22,6 +22,7 @@ use crate::{history, ui, watch}; use comline_codegen::config::{ self as gen_config, ComlineToml, DeclaredLang, Overrides, VersionSpec, }; +use comline_codegen::docs::{self, Topic}; use comline_codegen::protocol::{Description, TargetLanguage}; use comline_codegen::versions::LangVersion; use comline_codegen::{ @@ -212,7 +213,7 @@ fn generate_once(work_dir: &Path, overrides: &Overrides, dry_run: bool, list: bo )); } - let (source, ext) = match &t.generator { + let (source, ext, connections_doc) = match &t.generator { Some(path) => { let (generator, description) = externals.get(path, t.timeout)?; let info = @@ -232,7 +233,9 @@ fn generate_once(work_dir: &Path, overrides: &Overrides, dry_run: bool, list: bo } } let ext = info.ext.clone(); - (Source::External(generator), ext) + // The page the generator itself names for its connections. + let connections_doc = info.doc(Topic::Connections).map(str::to_owned); + (Source::External(generator), ext, connections_doc) } None => { // Reached for every language the congregation declares now, not only @@ -266,7 +269,9 @@ fn generate_once(work_dir: &Path, overrides: &Overrides, dry_run: bool, list: bo Err(error) => return Err(miette!("target `{}`: {error}", t.language)), } let ext = resolved.generator.ext.to_string(); - (Source::Builtin(resolved), ext) + let connections_doc = + docs::link(resolved.generator.docs, Topic::Connections).map(str::to_owned); + (Source::Builtin(resolved), ext, connections_doc) } }; @@ -368,7 +373,7 @@ fn generate_once(work_dir: &Path, overrides: &Overrides, dry_run: bool, list: bo warn_ignored(&t.language, &request, resolved); } warn_async_unused(&t.language, &request); - warn_no_package_connection(&t.language, &request); + warn_no_package_connection(&t.language, &request, connections_doc.as_deref()); // Both kinds answer the same protocol request, and either // response is checked whole - every path, the total size - // before anything below writes a file. @@ -647,21 +652,30 @@ fn warn_async_unused(language: &str, request: &GenerateRequest) { /// The package's `serve` / `connect` need its protocols on one connection; /// when they disagree on the framing or handshake, the generators leave them /// out, which would otherwise look like they forgot. -fn warn_no_package_connection(language: &str, request: &GenerateRequest) { +fn warn_no_package_connection( + language: &str, + request: &GenerateRequest, + connections_doc: Option<&str>, +) { match connections::package_connection(&request.schemas) { Err(reason) => ui::warn(format!( "`{language}`: no package `serve` / `connect` - {reason}; each protocol still has \ its own" )), - Ok(None) => note_no_connection_protocols(language, request), + Ok(None) => note_no_connection_protocols(language, request, connections_doc), Ok(Some(_)) => {} } } /// The silent case: protocols are declared, but none is on a connection, so /// there is no `Services` / `serve` to look for. A package with no protocols -/// has nothing to serve and gets no note. -fn note_no_connection_protocols(language: &str, request: &GenerateRequest) { +/// has nothing to serve and gets no note. `connections_doc` is the generator's +/// own page on connections, which the note links to when it has one. +fn note_no_connection_protocols( + language: &str, + request: &GenerateRequest, + connections_doc: Option<&str>, +) { let mut framings = std::collections::BTreeSet::new(); for (_, units) in &request.schemas { for unit in units { @@ -685,13 +699,9 @@ fn note_no_connection_protocols(language: &str, request: &GenerateRequest) { }) .collect(); - let page = match language { - "rust" => " (https://comlineproject.github.io/docs/languages/rust/connections/#when-theyre-generated)", - "typescript" => { - " (https://comlineproject.github.io/docs/languages/typescript/connections/#when-theyre-generated)" - } - _ => "", - }; + let page = connections_doc + .map(|url| format!(" ({url})")) + .unwrap_or_default(); ui::note(format!( "`{language}`: no package `Services` / `serve` / `connect` - every protocol is \ diff --git a/tests/cli/external.rs b/tests/cli/external.rs index c707a8d..63ea7cb 100644 --- a/tests/cli/external.rs +++ b/tests/cli/external.rs @@ -361,3 +361,52 @@ fn a_generator_that_offers_no_renderer_is_refused_as_one() { "doesn't render `markdown`; it offers none", )); } + +/// The note that a package has no connection links to the page the external +/// generator's own description names for connections. +#[test] +fn an_external_generators_connections_link_is_shown() { + let temp = tempfile::tempdir().unwrap(); + let project = lockstep_project(temp.path()); + let file = install(&project, Kind::Native, "hostile", "docs"); + fs::write( + project.join("comline.toml"), + format!("[[generate.target]]\nlanguage = \"rust\"\ngenerator = \"{file}\"\n"), + ) + .unwrap(); + comline_cmd() + .current_dir(&project) + .arg("generation") + .assert() + .success() + .stderr(predicate::str::contains( + "no package `Services` / `serve` / `connect`", + )) + .stderr(predicate::str::contains( + "(https://hostile.example/connections#generated)", + )); +} + +/// A generator that names no connections page gets the note without a link, +/// whatever its language is called. +#[test] +fn an_external_generator_without_a_connections_link_gets_none() { + let temp = tempfile::tempdir().unwrap(); + let project = lockstep_project(temp.path()); + let file = install(&project, Kind::Native, "hostile", "plain"); + fs::write( + project.join("comline.toml"), + format!("[[generate.target]]\nlanguage = \"rust\"\ngenerator = \"{file}\"\n"), + ) + .unwrap(); + let output = comline_cmd() + .current_dir(&project) + .arg("generation") + .assert() + .success() + .stderr(predicate::str::contains("and none is on a connection")) + .get_output() + .clone(); + let stderr = String::from_utf8_lossy(&output.stderr); + assert!(!stderr.contains("http"), "{stderr}"); +} diff --git a/tests/cli/generation.rs b/tests/cli/generation.rs index e5dbc85..f265846 100644 --- a/tests/cli/generation.rs +++ b/tests/cli/generation.rs @@ -203,13 +203,6 @@ fn rejects_an_unconfigured_target() { // -------- lib mode -------- -/// Appends `line` to the project's `config.idp`. -fn add_to_config(project: &std::path::Path, line: &str) { - let path = project.join("config.idp"); - let config = fs::read_to_string(&path).unwrap(); - fs::write(&path, format!("{config}\n{line}\n")).unwrap(); -} - #[test] fn config_idp_wire_framing_reaches_the_rust_generator() { let temp = tempfile::tempdir().unwrap(); @@ -314,13 +307,7 @@ fn protocols_on_different_framings_get_no_package_serve() { #[test] fn protocols_on_no_connection_say_why_there_is_no_package_serve() { let temp = tempfile::tempdir().unwrap(); - let project = fixture_project(temp.path()); - add_to_config(&project, "wire = { framing = \"datagram\" }"); - fs::write( - project.join("src/link.ids"), - "protocol Link {\n function send(n: u32) -> u32;\n}\n", - ) - .unwrap(); + let project = lockstep_project(temp.path()); comline_cmd() .current_dir(&project) @@ -333,10 +320,42 @@ fn protocols_on_no_connection_say_why_there_is_no_package_serve() { .stderr(predicate::str::contains( "every protocol is server-provided on `datagram@1`", )) - .stderr(predicate::str::contains("#when-theyre-generated")); + .stderr(predicate::str::contains( + "(https://comlineproject.github.io/docs/languages/rust/connections/#when-theyre-generated)", + )); assert!(!project.join("generated/rust/connection.rs").exists()); } +/// The TypeScript generator names its own page too: the link comes from the +/// generator, not from the language's name. +#[test] +fn the_typescript_generator_links_its_own_connections_page() { + let temp = tempfile::tempdir().unwrap(); + let project = lockstep_project(temp.path()); + let config = project.join("config.idp"); + let idp = fs::read_to_string(&config).unwrap(); + fs::write( + &config, + idp.replace( + "rust#1.85.0 = {}", + "rust#1.85.0 = {}\n typescript#5.0 = {}", + ), + ) + .unwrap(); + + comline_cmd() + .current_dir(&project) + .args(["generation", "--target", "typescript"]) + .assert() + .success() + .stderr(predicate::str::contains( + "no package `Services` / `serve` / `connect`", + )) + .stderr(predicate::str::contains( + "(https://comlineproject.github.io/docs/languages/typescript/connections/#when-theyre-generated)", + )); +} + /// No protocols at all: nothing to serve, so nothing is said. #[test] fn a_package_without_protocols_gets_no_serve_note() { diff --git a/tests/cli/util.rs b/tests/cli/util.rs index bfa3eca..310cc05 100644 --- a/tests/cli/util.rs +++ b/tests/cli/util.rs @@ -24,6 +24,26 @@ pub fn fixture_project(temp: &Path) -> PathBuf { copy_fixture("simple_project", temp) } +/// Appends `line` to the project's `config.idp`. +pub fn add_to_config(project: &Path, line: &str) { + let path = project.join("config.idp"); + let config = fs::read_to_string(&path).unwrap(); + fs::write(&path, format!("{config}\n{line}\n")).unwrap(); +} + +/// The fixture with a protocol that is on no connection (lockstep on the +/// `datagram` framing), so the package has no `serve` and generating says why. +pub fn lockstep_project(temp: &Path) -> PathBuf { + let project = fixture_project(temp); + add_to_config(&project, "wire = { framing = \"datagram\" }"); + fs::write( + project.join("src/link.ids"), + "protocol Link {\n function send(n: u32) -> u32;\n}\n", + ) + .unwrap(); + project +} + /// Like [`fixture_project`] for an arbitrary fixture under `tests/fixtures/`. pub fn copy_fixture(name: &str, temp: &Path) -> PathBuf { let dest = temp.join("proj"); diff --git a/tests/fixtures/generators/src/bin/hostile.rs b/tests/fixtures/generators/src/bin/hostile.rs index 8ed611b..29366a2 100644 --- a/tests/fixtures/generators/src/bin/hostile.rs +++ b/tests/fixtures/generators/src/bin/hostile.rs @@ -1,9 +1,11 @@ -//! A generator that misbehaves, one way per name: the tests copy it to +//! A generator that misbehaves, one way per name (`docs` and `plain` behave): the tests copy it to //! `.wasm` or `` and the mode is `argv[0]`'s file stem, since a //! generator gets no other arguments and no environment. +use std::collections::BTreeMap; use std::io::{Read, Write}; +use comline_codegen::docs::Topic; use comline_codegen::protocol::{ decode, encode, Description, FileOut, Generated, LanguageInfo, Request, RequestBody, Response, VersionsInfo, IR_FORMAT, PROTOCOL_VERSION, @@ -44,6 +46,15 @@ fn describe(mode: &str) -> Response { forward_compatible: true, }, support: vec![], + // `docs` names a page for the topics the CLI links to. + docs: if mode == "docs" { + BTreeMap::from([( + Topic::Connections.id().to_string(), + "https://hostile.example/connections#generated".to_string(), + )]) + } else { + BTreeMap::new() + }, }], protocols: (protocol, protocol), ir_formats: vec![IR_FORMAT], @@ -67,6 +78,9 @@ fn files(paths: &[&str]) -> Response { fn generate(mode: &str) -> Response { match mode { // A good file first: nothing at all may be written. + // Well-behaved: the same one file, with a docs entry (`docs`) or + // without (`plain`). + "docs" | "plain" => files(&["api.rs"]), "dotdot" => files(&["api.rs", "../escape.rs"]), "absolute" => files(&["api.rs", "/tmp/comline-hostile-absolute.rs"]), "oversized" => {