Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/workflows/build_test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,15 @@ jobs:
# are its tests.
- run: cargo test --verbose -p comline-core --features deps

# The size vectors the sizer is tested against (core/tests/spec) are the
# specification's own, at the rev `comline-catalog` is pinned to.
spec_vectors:
name: Vendored size vectors
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: bash core/tests/spec/vendor.sh --check

# The IR alone (`default-features = false`): what a generator depends on.
# It has no parser, so unlike the default build it compiles for WASI and
# the browser; this keeps tree-sitter (and anything else that can't) out.
Expand Down
2 changes: 1 addition & 1 deletion core/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ comline-core-stdlib = { path = "../core_stdlib", version = "0.1.0" }
# The specification's catalog of shared names: guarantees, facts and their
# values, the official encodings' aliases and frozen spellings. no_std and
# dependency-free, so the IR-only build has it too.
comline-catalog = { git = "https://github.com/ComlineProject/specification", rev = "508f813c259afe07db20cf86bbe2f07028a4fbe0" }
comline-catalog = { git = "https://github.com/ComlineProject/specification", rev = "9a7142c395b2aefb7d4d77e9b36c74187c6f0199" }

# General
eyre = "0.6.8"
Expand Down
192 changes: 192 additions & 0 deletions core/src/doc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ use crate::schema::ir::diff::{
};
use crate::schema::ir::snippet;
use crate::schema::ir::frozen::types::TypeRef;
use crate::schema::ir::size::{self, FrozenLookup};
use crate::schema::ir::frozen::unit::{DeprecatedValue, FrozenUnit};
use crate::settings::{SettingsDict, SettingsValue};

Expand Down Expand Up @@ -157,6 +158,25 @@ pub struct Annotation {
pub value: Option<String>,
}

/// How many bytes a type takes in one data format: at least `min` and at
/// most `max`, from the format's size rules in the specification
/// ([`crate::schema::ir::size`]).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct SizeRange {
/// The format, by its wire name (`packed@1`).
pub format: String,
/// The fewest bytes any value takes.
pub min: u64,
/// The most. Absent where there is no bound: a `string` or a `T[]` with
/// no maximum, or a type that contains itself with no `@max_depth`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max: Option<u64>,
/// `max` is only a bound that no value is known to reach (none of the
/// official formats has one). Absent otherwise.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub upper_bound: bool,
}

/// A declared unit.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "snake_case")]
Expand All @@ -166,11 +186,20 @@ pub enum Unit {
docs: Option<Doc>,
annotations: Vec<Annotation>,
fields: Vec<Field>,
/// What it takes in each format its package's protocols use, those
/// with size rules (the official ones). Absent where it can't be told
/// (a `union` in it) and in a model of a built version, which keeps no
/// protocol to say which formats.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
sizes: Vec<SizeRange>,
},
Enum {
name: String,
docs: Option<Doc>,
variants: Vec<String>,
/// As for a struct.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
sizes: Vec<SizeRange>,
},
Protocol {
name: String,
Expand Down Expand Up @@ -213,6 +242,9 @@ pub enum Unit {
docs: Option<Doc>,
annotations: Vec<Annotation>,
target: Type,
/// What the type it names takes; as for a struct.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
sizes: Vec<SizeRange>,
},
Settings {
/// `None` for the schema's unnamed block.
Expand Down Expand Up @@ -243,6 +275,9 @@ pub struct Function {
pub arguments: Vec<Argument>,
/// `None` when the function has no reply at all; [`Type::Unit`] for `()`.
pub returns: Option<Type>,
/// What the reply takes, as a struct's `sizes`.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub returns_sizes: Vec<SizeRange>,
/// The errors it declares with `!`, each a reference to the error.
pub throws: Vec<Type>,
}
Expand All @@ -252,6 +287,9 @@ pub struct Argument {
pub name: String,
#[serde(rename = "type")]
pub ty: Type,
/// What it takes, as a struct's `sizes`.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub sizes: Vec<SizeRange>,
}

/// One `assert(condition, message)` of a validator.
Expand Down Expand Up @@ -520,6 +558,18 @@ pub fn model(context: &ProjectContext, version: Option<String>) -> DocModel {
.filter(|p| !p.dependency)
.collect::<Vec<_>>();

// Every compiled schema, the package's and what it reaches: a type's
// names resolve into a dependency's or `std`'s.
let compiled: Vec<Vec<FrozenUnit>> = context
.schema_contexts
.iter()
.filter_map(|schema| schema.borrow().frozen_schema.borrow().clone())
.collect();
let sizing = Sizing {
formats: size_formats(context, &protocols),
lookup: FrozenLookup::new(compiled.iter().map(Vec::as_slice)),
};

let mut modules = vec![];
for schema in &context.schema_contexts {
let schema = schema.borrow();
Expand All @@ -533,6 +583,7 @@ pub fn model(context: &ProjectContext, version: Option<String>) -> DocModel {
index: &index,
namespace: path.clone(),
units,
sizing: Some(&sizing),
};
let units = units
.iter()
Expand Down Expand Up @@ -602,6 +653,7 @@ fn dependencies(
index,
namespace: namespace.join("::"),
units,
sizing: None,
};
let units: Vec<Unit> = units.iter().filter_map(|u| scope.unit(u)).collect();
if units.is_empty() {
Expand Down Expand Up @@ -711,6 +763,7 @@ pub fn model_frozen(
index: &index,
namespace: path.clone(),
units,
sizing: None,
};
Some(Module {
docs: headers.modules.remove(&path),
Expand Down Expand Up @@ -875,9 +928,71 @@ struct Scope<'a> {
/// The schema's namespace, `::`-joined.
namespace: String,
units: &'a [FrozenUnit],
/// What the package's types take in its formats, where the model has it:
/// not for a dependency's modules or a built version's.
sizing: Option<&'a Sizing<'a>>,
}

/// The formats the documented package's protocols use that have size rules,
/// and the names its types resolve through, for [`SizeRange`].
struct Sizing<'a> {
formats: Vec<(&'static str, &'static size::Sizes)>,
lookup: FrozenLookup<'a>,
}

impl Sizing<'_> {
/// What `ty`, written in the schema `namespace`, takes in each format.
fn of(&self, ty: &TypeRef, namespace: &str) -> Vec<SizeRange> {
let Some(scope) = self.lookup.scope_of(namespace) else {
return vec![];
};
self.formats
.iter()
.filter_map(|(format, rules)| {
let range = size::range(ty, rules, &self.lookup, scope)?;
Some(SizeRange {
format: format.to_string(),
min: range.min,
max: range.max,
upper_bound: range.upper_bound,
})
})
.collect()
}
}

/// The official formats with size rules that the package's own protocols use,
/// in the order they are first used; the package's default format where it
/// has no protocol.
fn size_formats(
context: &ProjectContext,
protocols: &[ProtocolSummary],
) -> Vec<(&'static str, &'static size::Sizes)> {
let mut names: Vec<&str> = protocols.iter().map(|p| p.format.value.as_str()).collect();
if names.is_empty() {
let config = context.config_frozen.as_deref().unwrap_or(&[]);
names.push(crate::package::config::ir::frozen::wire_format(config));
}
let mut formats: Vec<(&'static str, &'static size::Sizes)> = vec![];
for name in names {
let Some(encoding) = comline_catalog::resolve(name) else {
continue;
};
if let Some(rules) = encoding.sizes {
if !formats.iter().any(|(id, _)| *id == encoding.id) {
formats.push((encoding.id, rules));
}
}
}
formats
}

impl Scope<'_> {
/// What `ty` takes in each of the package's formats.
fn sizes(&self, ty: &TypeRef) -> Vec<SizeRange> {
self.sizing.map(|s| s.of(ty, &self.namespace)).unwrap_or_default()
}

/// What `name`, written in this schema, names.
fn resolve(&self, name: &str) -> Option<UnitRef> {
if name.contains("::") {
Expand Down Expand Up @@ -992,6 +1107,7 @@ impl Scope<'_> {
docs: doc(docstring),
annotations: annotations(parameters),
fields: self.fields(fields),
sizes: self.sizes(&TypeRef::Named(name.clone())),
},
FrozenUnit::Enum {
docstring,
Expand All @@ -1008,6 +1124,7 @@ impl Scope<'_> {
_ => None,
})
.collect(),
sizes: self.sizes(&TypeRef::Named(name.clone())),
},
FrozenUnit::Protocol {
docstring,
Expand Down Expand Up @@ -1043,9 +1160,11 @@ impl Scope<'_> {
.map(|a| Argument {
name: a.name.clone(),
ty: self.ty(&a.ty),
sizes: self.sizes(&a.ty),
})
.collect(),
returns: _return.as_ref().map(|t| self.ty(t)),
returns_sizes: _return.as_ref().map(|t| self.sizes(t)).unwrap_or_default(),
throws: throws.iter().map(|o| self.thrown(*o)).collect(),
})
})
Expand Down Expand Up @@ -1121,6 +1240,7 @@ impl Scope<'_> {
docs: doc(docstring),
annotations: annotations(parameters),
target: self.ty(target),
sizes: self.sizes(&TypeRef::Named(name.clone())),
},
FrozenUnit::Settings {
docstring,
Expand Down Expand Up @@ -1388,6 +1508,78 @@ mod tests {
assert_eq!(back, model);
}

fn range(format: &str, min: u64, max: u64) -> Vec<SizeRange> {
vec![SizeRange {
format: format.into(),
min,
max: Some(max),
upper_bound: false,
}]
}

fn sizes_of<'a>(model: &'a DocModel, module: &str, name: &str) -> &'a [SizeRange] {
match unit(model, module, name) {
Unit::Struct { sizes, .. }
| Unit::Enum { sizes, .. }
| Unit::TypeAlias { sizes, .. } => sizes,
other => panic!("{other:?} has no sizes"),
}
}

#[test]
fn documents_what_each_type_takes_in_the_packages_format() {
let tmp = tempfile::tempdir().unwrap();
let dir = package(&tmp.path().join("shop"), TYPES);
let context = crate::package::build::compile_package(&dir).unwrap();
let packed = model(&context, None);

// `packed@1`, the default: `Customer` is a `u64`, a string of at most
// 256 characters (1 to 1026 bytes) and an optional one (1 to 1027).
assert_eq!(sizes_of(&packed, "types", "Customer"), range("packed@1", 10, 2061));
assert_eq!(sizes_of(&packed, "types", "Payment"), range("packed@1", 1, 1));
assert_eq!(sizes_of(&packed, "types", "CustomerId"), range("packed@1", 8, 8));
// An order holds a `union`, which no format says the size of.
assert!(sizes_of(&packed, "api", "Order").is_empty());

let Unit::Protocol { functions, .. } = unit(&packed, "api", "Orders") else {
panic!()
};
let [place, ping] = functions.as_slice() else {
panic!()
};
assert!(place.arguments[0].sizes.is_empty());
assert_eq!(place.returns_sizes, range("packed@1", 8, 8));
assert!(ping.returns_sizes.is_empty());

// The format the package's protocols use is the one shown.
let config = format!("{CONFIG}wire = {{ format = \"json@1\" }}\n");
let json = tmp.path().join("json").join("shop");
std::fs::create_dir_all(json.join("src")).unwrap();
std::fs::write(json.join("config.idp"), config).unwrap();
std::fs::write(json.join("src/types.ids"), TYPES).unwrap();
std::fs::write(json.join("src/api.ids"), API).unwrap();
let context = crate::package::build::compile_package(&json).unwrap();
let json_model = model(&context, None);
assert_eq!(sizes_of(&json_model, "types", "Customer"), range("json@1", 29, 3120));

// In the JSON, a size has its format, least and most; a type with none
// has no `sizes` at all.
let value = serde_json::to_value(&json_model).unwrap();
let customer = &value["modules"]
.as_array()
.unwrap()
.iter()
.find(|m| m["path"] == "types")
.unwrap()["units"][0];
assert_eq!(customer["sizes"][0], serde_json::json!({ "format": "json@1", "min": 29, "max": 3120 }));
let order = &value["modules"].as_array().unwrap().iter().find(|m| m["path"] == "api").unwrap()["units"];
assert!(order
.as_array()
.unwrap()
.iter()
.any(|u| u["name"] == "Order" && u.get("sizes").is_none()));
}

#[test]
fn a_changelog_between_two_versions() {
let tmp = tempfile::tempdir().unwrap();
Expand Down
2 changes: 1 addition & 1 deletion core/src/schema/idl/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ pub mod grammar; // Rust-sitter generated parser
#[cfg(feature = "compiler")]
pub mod parse; // Parsing with the checks that keep it from panicking or overflowing
#[cfg(feature = "compiler")]
pub mod size; // Static wire-size estimate (hover)
pub mod size; // Byte ranges per format, over the grammar (hover)
#[cfg(feature = "compiler")]
pub mod vocabulary; // Primitive types & keywords, for editors/highlighters/docs
pub mod annotations; // Known @key=value metadata, for editors/hover
Expand Down
Loading
Loading