diff --git a/Cargo.lock b/Cargo.lock index 3b24c0c..a90b157 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -714,6 +714,7 @@ dependencies = [ "reqwest", "serde_json", "serde_yaml", + "similar", "tempfile", "thiserror 1.0.69", "tokio", diff --git a/README.md b/README.md index 939647f..71159e0 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Available as both a **Rust library** and a **CLI tool**. - **Swagger 2.0 support** – Swagger 2.0 sources are converted to OpenAPI 3.0.3 automatically; anything that had to be approximated is reported as a warning - **External `$ref`s** – specs split across files or URLs are bundled per source before merging (CLI sandboxed to the config directory) +- **Validation and CI check** – `--check` validates the merged spec and fails the build when it is invalid or when a committed output file is stale - **Multiple source types** – local YAML files, local JSON files, and HTTP endpoints (with custom headers) - **Config-file driven** – define sources and merge options in a single YAML config - **Conflict resolution** – choose between `error`, `overwrite`, or `rename` strategies for duplicate paths and component names @@ -61,6 +62,9 @@ openapi-aggregator -c my-config.yaml -o merged.yaml # Output as JSON openapi-aggregator -c my-config.yaml -f json +# Validate the merged spec and verify that merged.yaml is up to date (writes nothing) +openapi-aggregator -c my-config.yaml -o merged.yaml --check + # Print help openapi-aggregator --help ``` @@ -140,6 +144,51 @@ A source may point at other files or URLs (`$ref: ./schemas/pet.yaml#/Pet`, `$re - **Limit:** at most 100 external documents per source. - **Playground:** referenced files are looked up in the workspace by name, so add each one under exactly the name the `$ref` resolves to (the error message tells you which). Remote refs follow the same "Allow fetching" rule as remote sources. +## Validation and CI + +`--check` merges the sources, validates the result, and exits non-zero on problems, so it can gate a CI job. It never writes anything and prints nothing to stdout; findings go to stderr. + +```sh +openapi-aggregator --check -c openapi-aggregator.yaml -o openapi.yaml +``` + +- **Validation** always runs. It checks what an aggregation can break (it is not a full OpenAPI schema validation). +- **Output comparison** runs when `-o` is given: the file is parsed and compared with the freshly merged spec *as data*, so formatting, YAML vs JSON and key order never count as a difference. On a mismatch a unified diff is printed. A missing or unparseable file counts as out of date. +- **`--deny-warnings`** also fails on warnings (merge warnings, Swagger 2.0 conversion notes and validation warnings). + +| Exit code | Meaning | +|-----------|---------| +| `0` | Passed | +| `1` | Validation errors, denied warnings, or the merge/config itself failed (if the file is also out of date, the diff is still printed) | +| `2` | The output file is missing or out of date. Note that command-line usage errors also exit `2`. | + +Findings look like `error[dangling-ref] /paths/~1pets/get/...: $ref '#/components/schemas/Ghost' does not resolve`, where the location is a JSON pointer into the merged spec. + +| Code | Severity | Meaning | +|------|----------|---------| +| `invalid-openapi-version` | error | `openapi` is missing or not a 3.x version | +| `missing-field` | error | `info`, `info.title`, `info.version` missing; `paths` missing (3.0), or none of `paths`/`webhooks`/`components` (3.1+) | +| `dangling-ref` | error | an internal `$ref` that does not resolve | +| `external-ref` | error | a `$ref` outside the document that was not bundled | +| `duplicate-operation-id` | error | the same `operationId` on two operations | +| `missing-responses` | error | an operation without `responses` | +| `undeclared-path-param` | error | `{name}` in a path with no matching `in: path` parameter | +| `unused-path-param` | warning | a path parameter that is not in the path | +| `duplicate-parameter` | error | the same `name` and `in` declared twice | +| `ambiguous-paths` | error | two paths that differ only in placeholder names | +| `unknown-security-scheme` | error | a `security` requirement naming an undefined scheme | +| `undeclared-tag` | warning | an operation tag missing from the top-level `tags` (only checked when `tags` is non-empty) | +| `invalid-component-name` | error | a component name outside `[a-zA-Z0-9._-]+` | + +Example GitHub Actions step that keeps a committed spec in sync: + +```yaml +- name: Check the aggregated spec + run: openapi-aggregator --check --deny-warnings -c openapi-aggregator.yaml -o openapi.yaml +``` + +The same validator is available as `openapi_aggregator::validate(&spec)`, and the playground shows its findings in the problems panel. + ## Library Usage ```rust diff --git a/crates/openapi-aggregator-core/src/bundle.rs b/crates/openapi-aggregator-core/src/bundle.rs index 4594f4c..256a622 100644 --- a/crates/openapi-aggregator-core/src/bundle.rs +++ b/crates/openapi-aggregator-core/src/bundle.rs @@ -149,10 +149,15 @@ const DATA_KEYS: [&str; 4] = ["example", "default", "enum", "value"]; /// Visit every `$ref` string, skipping example/default/enum data. pub(crate) fn walk_refs(value: &Value, f: &mut dyn FnMut(&str)) { - walk(value, false, f); + walk_refs_at(value, &mut |_, reference| f(reference)); } -fn walk(value: &Value, names: bool, f: &mut dyn FnMut(&str)) { +/// Like [`walk_refs`], also giving the JSON pointer of the object that holds each `$ref`. +pub(crate) fn walk_refs_at(value: &Value, f: &mut dyn FnMut(&str, &str)) { + walk(value, false, &mut String::new(), f); +} + +fn walk(value: &Value, names: bool, pointer: &mut String, f: &mut dyn FnMut(&str, &str)) { match value { Value::Object(map) => { for (key, child) in map { @@ -160,12 +165,30 @@ fn walk(value: &Value, names: bool, f: &mut dyn FnMut(&str)) { continue; } match child { - Value::String(target) if !names && key == "$ref" => f(target), - _ => walk(child, !names && NAME_MAPS.contains(&key.as_str()), f), + Value::String(target) if !names && key == "$ref" => f(pointer, target), + _ => { + let len = pointer.len(); + pointer.push('/'); + pointer.push_str(&crate::validate::pointer_escape(key)); + walk( + child, + !names && NAME_MAPS.contains(&key.as_str()), + pointer, + f, + ); + pointer.truncate(len); + } } } } - Value::Array(items) => items.iter().for_each(|item| walk(item, false, f)), + Value::Array(items) => { + for (index, item) in items.iter().enumerate() { + let len = pointer.len(); + pointer.push_str(&format!("/{index}")); + walk(item, false, pointer, f); + pointer.truncate(len); + } + } _ => {} } } @@ -308,7 +331,7 @@ fn sanitize_name(name: &str) -> String { } } -fn lookup<'v>(document: &'v Value, segments: &[String]) -> Option<&'v Value> { +pub(crate) fn lookup<'v>(document: &'v Value, segments: &[String]) -> Option<&'v Value> { let mut current = document; for segment in segments { current = match current { diff --git a/crates/openapi-aggregator-core/src/lib.rs b/crates/openapi-aggregator-core/src/lib.rs index 7380a8e..7576b61 100644 --- a/crates/openapi-aggregator-core/src/lib.rs +++ b/crates/openapi-aggregator-core/src/lib.rs @@ -41,6 +41,7 @@ pub mod error; pub mod merge; pub mod prepare; pub mod swagger2; +pub mod validate; pub use bundle::{ bundle, check_document_cap, is_url, missing_documents, resolve_location, MissingDocument, @@ -55,3 +56,4 @@ pub use merge::{merge_specs, merge_specs_with_report, MergeReport}; pub use prepare::{ bundle_source, parse_content, prepare_source, prepare_source_with_notes, PreparedSource, }; +pub use validate::{validate, Finding, Severity}; diff --git a/crates/openapi-aggregator-core/src/swagger2.rs b/crates/openapi-aggregator-core/src/swagger2.rs index b65d0af..8b2e6c7 100644 --- a/crates/openapi-aggregator-core/src/swagger2.rs +++ b/crates/openapi-aggregator-core/src/swagger2.rs @@ -82,7 +82,7 @@ pub fn convert(spec: Value) -> (Value, Vec) { (out, notes) } -const METHODS: [&str; 8] = [ +pub(crate) const METHODS: [&str; 8] = [ "get", "put", "post", "delete", "options", "head", "patch", "trace", ]; diff --git a/crates/openapi-aggregator-core/src/validate.rs b/crates/openapi-aggregator-core/src/validate.rs new file mode 100644 index 0000000..32c9d38 --- /dev/null +++ b/crates/openapi-aggregator-core/src/validate.rs @@ -0,0 +1,823 @@ +//! Semantic validation of a merged OpenAPI document: the problems an aggregation can +//! actually introduce (dangling refs, duplicate operation ids, path template mismatches, ...). +//! +//! This is deliberately not a full structural validation against the OpenAPI JSON Schema. + +use std::collections::{HashMap, HashSet}; + +use serde_json::Value; + +/// How serious a [`Finding`] is. +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum Severity { + Error, + Warning, +} + +impl Severity { + pub fn as_str(self) -> &'static str { + match self { + Severity::Error => "error", + Severity::Warning => "warning", + } + } +} + +/// One problem found in a spec. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Finding { + pub severity: Severity, + pub code: &'static str, + pub message: String, + /// JSON pointer into the spec, e.g. `/paths/~1pets/get`. + pub location: String, +} + +/// Escape a key for use as a JSON pointer segment (`~` -> `~0`, `/` -> `~1`). +pub(crate) fn pointer_escape(segment: &str) -> String { + segment.replace('~', "~0").replace('/', "~1") +} + +fn finding( + severity: Severity, + code: &'static str, + message: impl Into, + location: impl Into, +) -> Finding { + Finding { + severity, + code, + message: message.into(), + location: location.into(), + } +} + +fn error(code: &'static str, message: impl Into, location: impl Into) -> Finding { + finding(Severity::Error, code, message, location) +} + +/// Validate `spec`; findings are sorted by `(location, code)`. +pub fn validate(spec: &Value) -> Vec { + let mut out = Vec::new(); + check_document(spec, &mut out); + if spec.is_object() { + check_component_names(spec, &mut out); + check_operations(spec, &mut out); + check_refs(spec, &mut out); + check_operation_ids(spec, &mut out); + check_paths(spec, &mut out); + check_security(spec, &mut out); + check_tags(spec, &mut out); + } + out.sort_by(|a, b| (&a.location, a.code).cmp(&(&b.location, b.code))); + out +} + +fn minor_version(spec: &Value) -> Option { + spec.get("openapi")? + .as_str()? + .strip_prefix("3.")? + .split('.') + .next()? + .parse() + .ok() +} + +fn check_document(spec: &Value, out: &mut Vec) { + let minor = minor_version(spec); + if minor.is_none() { + out.push(error( + "invalid-openapi-version", + "'openapi' must be a 3.x version string", + "/openapi", + )); + } + let Some(root) = spec.as_object() else { return }; + + match root.get("info") { + Some(Value::Object(info)) => { + for field in ["title", "version"] { + if !info.get(field).is_some_and(Value::is_string) { + out.push(error( + "missing-field", + format!("'info.{field}' is required"), + format!("/info/{field}"), + )); + } + } + } + _ => out.push(error("missing-field", "'info' is required", "/info")), + } + + if minor.is_some_and(|m| m >= 1) { + if !["paths", "webhooks", "components"] + .iter() + .any(|k| root.contains_key(*k)) + { + out.push(error( + "missing-field", + "at least one of 'paths', 'webhooks' or 'components' is required", + "", + )); + } + } else if !root.contains_key("paths") { + out.push(error("missing-field", "'paths' is required", "/paths")); + } +} + +fn is_valid_component_name(name: &str) -> bool { + !name.is_empty() + && name + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-')) +} + +fn check_component_names(spec: &Value, out: &mut Vec) { + let Some(Value::Object(components)) = spec.get("components") else { + return; + }; + for (section, entries) in components { + let Value::Object(entries) = entries else { + continue; + }; + for name in entries.keys().filter(|n| !is_valid_component_name(n)) { + out.push(error( + "invalid-component-name", + format!("component name '{name}' must match ^[a-zA-Z0-9._-]+$"), + format!( + "/components/{}/{}", + pointer_escape(section), + pointer_escape(name) + ), + )); + } + } +} + +/// `(path, method, operation)` for every operation in `paths`. +fn operations(spec: &Value) -> Vec<(&str, &str, &Value)> { + let mut ops = Vec::new(); + if let Some(Value::Object(paths)) = spec.get("paths") { + for (path, item) in paths { + for method in crate::swagger2::METHODS { + if let Some(op) = item.get(method) { + ops.push((path.as_str(), method, op)); + } + } + } + } + ops +} + +fn operation_pointer(path: &str, method: &str) -> String { + format!("/paths/{}/{method}", pointer_escape(path)) +} + +fn check_refs(spec: &Value, out: &mut Vec) { + crate::bundle::walk_refs_at(spec, &mut |location, reference| { + let Some(pointer) = reference.strip_prefix('#') else { + out.push(error( + "external-ref", + format!("$ref '{reference}' points outside the document and was not bundled"), + location, + )); + return; + }; + // `#anchor` style refs (3.1) cannot be resolved here; do not guess. + if !pointer.is_empty() && !pointer.starts_with('/') { + return; + } + let segments = crate::bundle::decode_pointer(pointer); + if crate::bundle::lookup(spec, &segments).is_none() { + out.push(error( + "dangling-ref", + format!("$ref '{reference}' does not resolve"), + location, + )); + } + }); +} + +fn check_operation_ids(spec: &Value, out: &mut Vec) { + let mut seen: HashMap<&str, (&str, &str)> = HashMap::new(); + for (path, method, op) in operations(spec) { + let Some(id) = op.get("operationId").and_then(Value::as_str) else { + continue; + }; + match seen.get(id) { + Some((first_path, first_method)) => out.push(error( + "duplicate-operation-id", + format!( + "operationId '{id}' is already used by {} {first_path}", + first_method.to_uppercase() + ), + operation_pointer(path, method), + )), + None => { + seen.insert(id, (path, method)); + } + } + } +} + +/// Names of the `{param}` placeholders in a path template. +fn template_params(path: &str) -> Vec<&str> { + let mut names = Vec::new(); + let mut rest = path; + while let Some(start) = rest.find('{') { + let after = &rest[start + 1..]; + let Some(end) = after.find('}') else { break }; + names.push(&after[..end]); + rest = &after[end + 1..]; + } + names +} + +/// The path template with every placeholder name erased, for ambiguity detection. +fn template_shape(path: &str) -> String { + let mut shape = String::new(); + let mut rest = path; + while let Some(start) = rest.find('{') { + shape.push_str(&rest[..start]); + match rest[start..].find('}') { + Some(end) => { + shape.push_str("{}"); + rest = &rest[start + end + 1..]; + } + None => { + shape.push_str(&rest[start..]); + rest = ""; + } + } + } + shape.push_str(rest); + shape +} + +/// `(name, in)` of each entry of a `parameters` array, resolving internal `$ref`s once. +fn parameter_keys(spec: &Value, parameters: Option<&Value>) -> Vec<(String, String)> { + let Some(Value::Array(list)) = parameters else { + return Vec::new(); + }; + list.iter() + .filter_map(|p| { + let resolved = match p.get("$ref").and_then(Value::as_str) { + Some(reference) => { + let pointer = reference.strip_prefix('#')?; + crate::bundle::lookup(spec, &crate::bundle::decode_pointer(pointer))? + } + None => p, + }; + Some(( + resolved.get("name")?.as_str()?.to_string(), + resolved.get("in")?.as_str()?.to_string(), + )) + }) + .collect() +} + +fn duplicates(keys: &[(String, String)]) -> Vec<&(String, String)> { + let mut seen = HashSet::new(); + keys.iter().filter(|k| !seen.insert(*k)).collect() +} + +fn check_paths(spec: &Value, out: &mut Vec) { + let Some(Value::Object(paths)) = spec.get("paths") else { + return; + }; + let mut shapes: HashMap = HashMap::new(); + for (path, item) in paths { + let item_pointer = format!("/paths/{}", pointer_escape(path)); + match shapes.get(&template_shape(path)) { + Some(other) => out.push(error( + "ambiguous-paths", + format!("path '{path}' is equivalent to '{other}'"), + item_pointer.clone(), + )), + None => { + shapes.insert(template_shape(path), path); + } + } + + // A path item that is a `$ref` takes its operations from elsewhere. + if item.get("$ref").is_some() { + continue; + } + + let template = template_params(path); + let item_params = parameter_keys(spec, item.get("parameters")); + let ops: Vec<(&str, &Value)> = crate::swagger2::METHODS + .iter() + .filter_map(|m| item.get(*m).map(|op| (*m, op))) + .collect(); + + report_duplicates(&item_params, &item_pointer, out); + report_unused(&item_params, &template, path, &item_pointer, out); + if ops.is_empty() { + report_undeclared(&item_params, &template, path, &item_pointer, out); + } + for (method, op) in ops { + let pointer = operation_pointer(path, method); + let op_params = parameter_keys(spec, op.get("parameters")); + report_duplicates(&op_params, &pointer, out); + report_unused(&op_params, &template, path, &pointer, out); + let effective: Vec<(String, String)> = + item_params.iter().chain(&op_params).cloned().collect(); + report_undeclared(&effective, &template, path, &pointer, out); + } + } +} + +fn report_duplicates(keys: &[(String, String)], location: &str, out: &mut Vec) { + for (name, location_in) in duplicates(keys) { + out.push(error( + "duplicate-parameter", + format!("parameter '{name}' (in: {location_in}) is declared more than once"), + location, + )); + } +} + +fn report_unused( + keys: &[(String, String)], + template: &[&str], + path: &str, + location: &str, + out: &mut Vec, +) { + for (name, _) in keys + .iter() + .filter(|(n, i)| i == "path" && !template.contains(&n.as_str())) + { + out.push(finding( + Severity::Warning, + "unused-path-param", + format!("path parameter '{name}' does not appear in '{path}'"), + location, + )); + } +} + +fn report_undeclared( + keys: &[(String, String)], + template: &[&str], + path: &str, + location: &str, + out: &mut Vec, +) { + for name in template { + if !keys.iter().any(|(n, i)| i == "path" && n == name) { + out.push(error( + "undeclared-path-param", + format!("'{{{name}}}' in '{path}' has no matching path parameter"), + location, + )); + } + } +} + +fn check_security(spec: &Value, out: &mut Vec) { + let defined = |name: &str| { + spec.pointer("/components/securitySchemes") + .and_then(Value::as_object) + .is_some_and(|schemes| schemes.contains_key(name)) + }; + let mut check = |requirements: Option<&Value>, location: String| { + let Some(Value::Array(list)) = requirements else { + return; + }; + for (index, requirement) in list.iter().enumerate() { + let Value::Object(requirement) = requirement else { + continue; + }; + for scheme in requirement.keys().filter(|n| !defined(n)) { + out.push(error( + "unknown-security-scheme", + format!("security requirement names '{scheme}', which is not in components.securitySchemes"), + format!("{location}/security/{index}"), + )); + } + } + }; + check(spec.get("security"), String::new()); + for (path, method, op) in operations(spec) { + check(op.get("security"), operation_pointer(path, method)); + } +} + +fn check_tags(spec: &Value, out: &mut Vec) { + let declared: HashSet<&str> = match spec.get("tags") { + Some(Value::Array(tags)) if !tags.is_empty() => tags + .iter() + .filter_map(|t| t.get("name").and_then(Value::as_str)) + .collect(), + _ => return, + }; + for (path, method, op) in operations(spec) { + let Some(Value::Array(tags)) = op.get("tags") else { + continue; + }; + for tag in tags + .iter() + .filter_map(Value::as_str) + .filter(|t| !declared.contains(t)) + { + out.push(finding( + Severity::Warning, + "undeclared-tag", + format!("tag '{tag}' is not declared in the top-level tags"), + operation_pointer(path, method), + )); + } + } +} + +fn check_operations(spec: &Value, out: &mut Vec) { + for (path, method, op) in operations(spec) { + let has_responses = op + .get("responses") + .and_then(Value::as_object) + .is_some_and(|r| !r.is_empty()); + if !has_responses { + out.push(error( + "missing-responses", + format!("{} {path} has no responses", method.to_uppercase()), + operation_pointer(path, method), + )); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn found(spec: &Value) -> Vec<(&'static str, Severity, String)> { + validate(spec) + .into_iter() + .map(|f| (f.code, f.severity, f.location)) + .collect() + } + + fn minimal() -> Value { + json!({"openapi":"3.0.3","info":{"title":"T","version":"1"},"paths":{}}) + } + + #[test] + fn valid_minimal_spec_has_no_findings() { + assert!(validate(&minimal()).is_empty()); + } + + #[test] + fn invalid_openapi_version() { + for bad in [ + json!({"info":{"title":"T","version":"1"},"paths":{}}), + json!({"openapi":"2.0","info":{"title":"T","version":"1"},"paths":{}}), + json!({"openapi":3,"info":{"title":"T","version":"1"},"paths":{}}), + ] { + assert_eq!( + found(&bad), + vec![( + "invalid-openapi-version", + Severity::Error, + "/openapi".to_string() + )], + "{bad}" + ); + } + } + + #[test] + fn missing_info_fields() { + let mut spec = minimal(); + spec.as_object_mut().unwrap().remove("info"); + assert_eq!( + found(&spec), + vec![("missing-field", Severity::Error, "/info".into())] + ); + let mut spec = minimal(); + spec["info"] = json!({"version":"1"}); + assert_eq!( + found(&spec), + vec![("missing-field", Severity::Error, "/info/title".into())] + ); + spec["info"] = json!({"title":"T"}); + assert_eq!( + found(&spec), + vec![("missing-field", Severity::Error, "/info/version".into())] + ); + } + + #[test] + fn paths_required_in_30_only() { + let info = json!({"title":"T","version":"1"}); + let spec = json!({"openapi":"3.0.3","info":info}); + assert_eq!( + found(&spec), + vec![("missing-field", Severity::Error, "/paths".into())] + ); + let spec = json!({"openapi":"3.1.0","info":info,"webhooks":{}}); + assert!(validate(&spec).is_empty()); + let spec = json!({"openapi":"3.1.0","info":info,"components":{}}); + assert!(validate(&spec).is_empty()); + let spec = json!({"openapi":"3.1.0","info":info}); + assert_eq!( + found(&spec), + vec![("missing-field", Severity::Error, "".into())] + ); + } + + #[test] + fn invalid_component_names() { + let mut spec = minimal(); + spec["components"] = json!({ + "schemas": {"bad name": {}, "Good.Name_1-x": {}}, + "parameters": {"a/b": {"name":"a","in":"query"}} + }); + assert_eq!( + found(&spec), + vec![ + ( + "invalid-component-name", + Severity::Error, + "/components/parameters/a~1b".into() + ), + ( + "invalid-component-name", + Severity::Error, + "/components/schemas/bad name".into() + ), + ] + ); + } + + #[test] + fn operations_need_responses() { + let mut spec = minimal(); + spec["paths"] = json!({"/p":{"get":{},"post":{"responses":{}},"put":{"responses":{"200":{"description":"ok"}}},"parameters":[]}}); + assert_eq!( + found(&spec), + vec![ + ( + "missing-responses", + Severity::Error, + "/paths/~1p/get".into() + ), + ( + "missing-responses", + Severity::Error, + "/paths/~1p/post".into() + ), + ] + ); + } + + #[test] + fn escapes_pointer_segments() { + assert_eq!(pointer_escape("/a~b"), "~1a~0b"); + } + + fn with_schema_ref(reference: &str) -> Value { + let mut spec = minimal(); + spec["paths"] = json!({"/p":{"get":{"responses":{"200":{"description":"ok","content":{ + "application/json":{"schema":{"$ref": reference}}}}}}}}); + spec + } + + const SCHEMA_PTR: &str = "/paths/~1p/get/responses/200/content/application~1json/schema"; + + #[test] + fn dangling_ref_is_an_error_at_the_holder() { + let spec = with_schema_ref("#/components/schemas/Missing"); + let f = validate(&spec); + assert_eq!(f.len(), 1); + assert_eq!( + (f[0].code, f[0].severity), + ("dangling-ref", Severity::Error) + ); + assert_eq!(f[0].location, SCHEMA_PTR); + assert!( + f[0].message.contains("#/components/schemas/Missing"), + "{}", + f[0].message + ); + } + + #[test] + fn resolving_refs_are_fine() { + let mut spec = with_schema_ref("#/components/schemas/Pet"); + spec["components"] = json!({"schemas":{"Pet":{"type":"object"}}}); + assert!(validate(&spec).is_empty()); + let spec = with_schema_ref("#/paths/~1p/get/responses/200"); + assert!(validate(&spec).is_empty()); + } + + #[test] + fn external_refs_are_errors() { + let spec = with_schema_ref("./other.yaml#/X"); + assert_eq!( + found(&spec), + vec![("external-ref", Severity::Error, SCHEMA_PTR.to_string())] + ); + } + + #[test] + fn ref_like_data_is_ignored() { + let mut spec = minimal(); + spec["components"] = json!({ + "examples": {"E": {"value": {"$ref": "#/nope"}}}, + "schemas": {"S": {"type":"object","example":{"$ref":"#/nope"},"properties":{"x":{"default":{"$ref":"#/nope"}}}}} + }); + assert!(validate(&spec).is_empty()); + } + + #[test] + fn property_named_default_is_still_checked() { + let mut spec = minimal(); + spec["components"] = json!({"schemas":{"S":{"properties":{"default":{"$ref":"#/components/schemas/Ghost"}}}}}); + assert_eq!( + found(&spec), + vec![( + "dangling-ref", + Severity::Error, + "/components/schemas/S/properties/default".to_string() + )] + ); + } + + fn spec_with_paths(paths: Value) -> Value { + let mut spec = minimal(); + spec["paths"] = paths; + spec + } + + fn ok() -> Value { + json!({"200":{"description":"ok"}}) + } + + #[test] + fn duplicate_operation_id() { + let spec = spec_with_paths(json!({ + "/a":{"get":{"operationId":"list","responses":ok()}}, + "/b":{"get":{"operationId":"list","responses":ok()},"post":{"operationId":"create","responses":ok()}} + })); + let f = validate(&spec); + assert_eq!(f.len(), 1); + assert_eq!( + (f[0].code, f[0].location.as_str()), + ("duplicate-operation-id", "/paths/~1b/get") + ); + assert!( + f[0].message.contains("list") && f[0].message.contains("/a"), + "{}", + f[0].message + ); + } + + #[test] + fn undeclared_path_param() { + let spec = spec_with_paths(json!({"/pets/{id}":{"get":{"responses":ok()}}})); + assert_eq!( + found(&spec), + vec![( + "undeclared-path-param", + Severity::Error, + "/paths/~1pets~1{id}/get".into() + )] + ); + + let at_item = spec_with_paths(json!({"/pets/{id}":{ + "parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}], + "get":{"responses":ok()}}})); + assert!(validate(&at_item).is_empty()); + let at_op = spec_with_paths(json!({"/pets/{id}":{"get":{ + "parameters":[{"name":"id","in":"path","required":true}],"responses":ok()}}})); + assert!(validate(&at_op).is_empty()); + + let mut by_ref = spec_with_paths(json!({"/pets/{id}":{"get":{ + "parameters":[{"$ref":"#/components/parameters/Id"}],"responses":ok()}}})); + by_ref["components"] = + json!({"parameters":{"Id":{"name":"id","in":"path","required":true}}}); + assert!(validate(&by_ref).is_empty()); + + let wrong_in = spec_with_paths(json!({"/pets/{id}":{"get":{ + "parameters":[{"name":"id","in":"query"}],"responses":ok()}}})); + assert_eq!( + found(&wrong_in), + vec![( + "undeclared-path-param", + Severity::Error, + "/paths/~1pets~1{id}/get".into() + )] + ); + } + + #[test] + fn unused_path_param_is_a_warning() { + let spec = spec_with_paths(json!({"/pets":{"get":{ + "parameters":[{"name":"x","in":"path","required":true}],"responses":ok()}}})); + assert_eq!( + found(&spec), + vec![( + "unused-path-param", + Severity::Warning, + "/paths/~1pets/get".into() + )] + ); + } + + #[test] + fn duplicate_parameter() { + let dup = spec_with_paths(json!({"/p":{"get":{"parameters":[ + {"name":"q","in":"query"},{"name":"q","in":"query"}],"responses":ok()}}})); + assert_eq!( + found(&dup), + vec![( + "duplicate-parameter", + Severity::Error, + "/paths/~1p/get".into() + )] + ); + let different_in = spec_with_paths(json!({"/p":{"get":{"parameters":[ + {"name":"q","in":"query"},{"name":"q","in":"header"}],"responses":ok()}}})); + assert!(validate(&different_in).is_empty()); + let overridden = spec_with_paths(json!({"/p":{ + "parameters":[{"name":"q","in":"query"}], + "get":{"parameters":[{"name":"q","in":"query"}],"responses":ok()}}})); + assert!(validate(&overridden).is_empty()); + } + + #[test] + fn ambiguous_paths() { + let spec = spec_with_paths(json!({ + "/a/{id}":{"get":{"parameters":[{"name":"id","in":"path","required":true}],"responses":ok()}}, + "/a/{name}":{"get":{"parameters":[{"name":"name","in":"path","required":true}],"responses":ok()}} + })); + assert_eq!( + found(&spec), + vec![( + "ambiguous-paths", + Severity::Error, + "/paths/~1a~1{name}".into() + )] + ); + let fine = spec_with_paths(json!({ + "/a/{id}":{"get":{"parameters":[{"name":"id","in":"path","required":true}],"responses":ok()}}, + "/b/{id}":{"get":{"parameters":[{"name":"id","in":"path","required":true}],"responses":ok()}} + })); + assert!(validate(&fine).is_empty()); + } + + #[test] + fn unknown_security_scheme() { + let mut spec = spec_with_paths( + json!({"/p":{"get":{"security":[{"ghost":[]},{}, {"real":[]}],"responses":ok()}}}), + ); + spec["security"] = json!([{"ghost": []}]); + spec["components"] = json!({"securitySchemes":{"real":{"type":"http","scheme":"basic"}}}); + assert_eq!( + found(&spec), + vec![ + ( + "unknown-security-scheme", + Severity::Error, + "/paths/~1p/get/security/0".into() + ), + ( + "unknown-security-scheme", + Severity::Error, + "/security/0".into() + ), + ] + ); + spec["security"] = json!([{"real": []}]); + spec["paths"]["/p"]["get"]["security"] = json!([{"real": []}, {}]); + assert!(validate(&spec).is_empty()); + } + + #[test] + fn undeclared_tag_is_a_warning_only_when_tags_are_declared() { + let mut spec = spec_with_paths(json!({"/p":{"get":{"tags":["a","b"],"responses":ok()}}})); + assert!(validate(&spec).is_empty()); + spec["tags"] = json!([]); + assert!(validate(&spec).is_empty()); + spec["tags"] = json!([{"name":"a"}]); + let f = validate(&spec); + assert_eq!(f.len(), 1); + assert_eq!( + (f[0].code, f[0].severity, f[0].location.as_str()), + ("undeclared-tag", Severity::Warning, "/paths/~1p/get") + ); + assert!(f[0].message.contains("'b'"), "{}", f[0].message); + } + + #[test] + fn path_item_refs_are_not_checked_for_path_params() { + let spec = spec_with_paths(json!({ + "/a/{id}":{"get":{"parameters":[{"name":"id","in":"path","required":true}],"responses":ok()}}, + "/b/{id}":{"$ref":"#/paths/~1a~1{id}"} + })); + assert!(validate(&spec).is_empty(), "{:?}", validate(&spec)); + } +} diff --git a/crates/openapi-aggregator-core/tests/validate_real_specs.rs b/crates/openapi-aggregator-core/tests/validate_real_specs.rs new file mode 100644 index 0000000..da9903b --- /dev/null +++ b/crates/openapi-aggregator-core/tests/validate_real_specs.rs @@ -0,0 +1,70 @@ +use openapi_aggregator_core::swagger2::convert; +use openapi_aggregator_core::{parse_content, validate}; +use serde_json::{json, Value}; + +fn assert_clean(name: &str, spec: &Value) { + let findings = validate(spec); + assert!( + findings.is_empty(), + "{name}: unexpected findings: {:#?}", + findings + .iter() + .map(|f| format!("{} {} {}", f.code, f.location, f.message)) + .collect::>() + ); +} + +#[test] +fn petstore_30_fixture_has_no_findings() { + let text = std::fs::read_to_string(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../openapi-aggregator/tests/fixtures/petstore.yaml" + )) + .unwrap(); + assert_clean("petstore.yaml", &parse_content(&text).unwrap()); +} + +#[test] +fn petstore_swagger2_after_conversion_has_no_findings() { + let input: Value = serde_json::from_str(include_str!("fixtures/petstore2.json")).unwrap(); + let (converted, _) = convert(input); + assert_clean("petstore2.json", &converted); +} + +#[test] +fn webhooks_only_31_spec_has_no_findings() { + assert_clean( + "webhooks", + &json!({"openapi":"3.1.0","info":{"title":"T","version":"1"}, + "webhooks":{"newPet":{"post":{"responses":{"200":{"description":"ok"}}}}}}), + ); +} + +#[test] +fn ref_parameters_and_path_item_parameters_have_no_findings() { + assert_clean( + "params", + &json!({"openapi":"3.0.3","info":{"title":"T","version":"1"}, + "paths":{ + "/pets/{petId}":{ + "parameters":[{"$ref":"#/components/parameters/PetId"}], + "get":{"operationId":"getPet","tags":["pets"],"responses":{"200":{"description":"ok","content":{ + "application/json":{"schema":{"$ref":"#/components/schemas/Pet"}}}}}}, + "delete":{"operationId":"deletePet","responses":{"204":{"description":"gone"}}} + }, + "/owners/{ownerId}/pets/{petId}":{ + "get":{"parameters":[ + {"name":"ownerId","in":"path","required":true,"schema":{"type":"string"}}, + {"$ref":"#/components/parameters/PetId"}], + "security":[{"key":[]}], + "responses":{"default":{"$ref":"#/components/responses/Err"}}} + }}, + "tags":[{"name":"pets"}], + "components":{ + "parameters":{"PetId":{"name":"petId","in":"path","required":true,"schema":{"type":"string"}}}, + "schemas":{"Pet":{"type":"object","properties":{"owner":{"$ref":"#/components/schemas/Owner"}}},"Owner":{"type":"object"}}, + "responses":{"Err":{"description":"error"}}, + "securitySchemes":{"key":{"type":"apiKey","name":"k","in":"header"}} + }}), + ); +} diff --git a/crates/openapi-aggregator-wasm/src/lib.rs b/crates/openapi-aggregator-wasm/src/lib.rs index 681a8ef..736bc24 100644 --- a/crates/openapi-aggregator-wasm/src/lib.rs +++ b/crates/openapi-aggregator-wasm/src/lib.rs @@ -5,7 +5,7 @@ use std::collections::{BTreeMap, HashMap}; use openapi_aggregator_core::{ bundle_source, check_document_cap, merge_specs_with_report, missing_documents, parse_content, - prepare_source_with_notes, Config, Error, OutputFormat, PreparedSource, Source, + prepare_source_with_notes, validate, Config, Error, OutputFormat, PreparedSource, Source, }; use serde::Serialize; use wasm_bindgen::prelude::*; @@ -29,6 +29,16 @@ pub struct ConfigSummary { pub struct AggregateOutput { pub text: String, pub warnings: Vec, + /// Validation findings for the merged spec. + pub findings: Vec, +} + +#[derive(Debug, Serialize, PartialEq, Eq)] +pub struct FindingOut { + pub severity: &'static str, + pub code: &'static str, + pub message: String, + pub location: String, } fn format_name(format: &OutputFormat) -> &'static str { @@ -188,9 +198,19 @@ pub fn aggregate_contents( serde_json::to_string_pretty(&report.spec).map_err(|e| e.to_string())? + "\n" } }; + let findings = validate(&report.spec) + .into_iter() + .map(|f| FindingOut { + severity: f.severity.as_str(), + code: f.code, + message: f.message, + location: f.location, + }) + .collect(); Ok(AggregateOutput { text, warnings: report.warnings, + findings, }) } @@ -236,8 +256,8 @@ pub fn aggregate(yaml: &str, contents: Vec, docs: JsValue) -> Result i32 { + match self { + Outcome::Passed => 0, + Outcome::Failed => 1, + Outcome::Stale => 2, + } + } +} + +/// `error[code] /location: message` (or `warning[...]`). +pub fn render_finding(finding: &Finding) -> String { + let location = if finding.location.is_empty() { + "/" + } else { + &finding.location + }; + format!( + "{}[{}] {}: {}", + finding.severity.as_str(), + finding.code, + location, + finding.message + ) +} + +fn plural(count: usize, word: &str) -> String { + if count == 1 { + format!("{count} {word}") + } else { + format!("{count} {word}s") + } +} + +/// The closing line of a check run. +pub fn summary(errors: usize, warnings: usize, passed: bool) -> String { + if passed { + if warnings == 0 { + "check passed".to_string() + } else { + format!("check passed ({})", plural(warnings, "warning")) + } + } else { + format!( + "check failed: {}, {}", + plural(errors, "error"), + plural(warnings, "warning") + ) + } +} + +/// Validate the merged spec, print the findings to stderr, and decide pass/fail. +/// Merge warnings (already printed by the caller) count as warnings. +pub fn run_validation(report: &MergeReport, deny_warnings: bool) -> Outcome { + let findings = validate(&report.spec); + for finding in &findings { + eprintln!("{}", render_finding(finding)); + } + let errors = findings + .iter() + .filter(|f| f.severity == Severity::Error) + .count(); + let warnings = findings.len() - errors + report.warnings.len(); + let passed = errors == 0 && !(deny_warnings && warnings > 0); + eprintln!("{}", summary(errors, warnings, passed)); + if passed { + Outcome::Passed + } else { + Outcome::Failed + } +} + +/// How the existing output file compares with the freshly merged spec. +#[derive(Debug)] +pub enum Comparison { + UpToDate, + Missing, + Stale { + diff: String, + }, + /// The file exists but is not valid JSON/YAML. + Unreadable(String), +} + +fn render(value: &Value, format: &OutputFormat) -> String { + match format { + OutputFormat::Yaml => serde_yaml::to_string(value).unwrap_or_default(), + OutputFormat::Json => serde_json::to_string_pretty(value).unwrap_or_default() + "\n", + } +} + +/// Compare the file at `path` with `merged` as data, so formatting, format (YAML vs JSON) +/// and key order never matter. On a difference, `diff` is a unified diff of both sides +/// rendered in `format`. +pub fn compare_output(path: &Path, merged: &Value, format: &OutputFormat) -> Comparison { + let text = match std::fs::read_to_string(path) { + Ok(text) => text, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Comparison::Missing, + Err(e) => return Comparison::Unreadable(e.to_string()), + }; + let existing = match parse_content(&text) { + Ok(value) => value, + Err(e) => return Comparison::Unreadable(e.to_string()), + }; + if &existing == merged { + return Comparison::UpToDate; + } + let old = render(&existing, format); + let new = render(merged, format); + let diff = similar::TextDiff::from_lines(&old, &new) + .unified_diff() + .context_radius(3) + .header(&path.display().to_string(), "regenerated") + .to_string(); + Comparison::Stale { diff } +} + +/// Check that the output file is up to date, printing what is wrong to stderr. +pub fn check_output(path: &Path, merged: &Value, format: &OutputFormat) -> Outcome { + let shown = path.display(); + match compare_output(path, merged, format) { + Comparison::UpToDate => Outcome::Passed, + Comparison::Missing => { + eprintln!("output file {shown} does not exist; run without --check to create it"); + Outcome::Stale + } + Comparison::Stale { diff } => { + eprint!("{diff}"); + eprintln!("output file {shown} is out of date; regenerate it without --check"); + Outcome::Stale + } + Comparison::Unreadable(reason) => { + eprintln!("output file {shown} could not be read ({reason}); it is out of date; regenerate it without --check"); + Outcome::Stale + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn renders_findings() { + let finding = Finding { + severity: Severity::Error, + code: "dangling-ref", + message: "$ref '#/x' does not resolve".into(), + location: "/paths/~1p".into(), + }; + assert_eq!( + render_finding(&finding), + "error[dangling-ref] /paths/~1p: $ref '#/x' does not resolve" + ); + let root = Finding { + severity: Severity::Warning, + location: String::new(), + ..finding + }; + assert!(render_finding(&root).starts_with("warning[dangling-ref] /: ")); + } + + #[test] + fn summarises_with_plurals() { + assert_eq!(summary(0, 0, true), "check passed"); + assert_eq!(summary(0, 2, true), "check passed (2 warnings)"); + assert_eq!(summary(1, 0, false), "check failed: 1 error, 0 warnings"); + assert_eq!(summary(2, 1, false), "check failed: 2 errors, 1 warning"); + } + + #[test] + fn outcomes_map_to_exit_codes() { + assert_eq!(Outcome::Passed.exit_code(), 0); + assert_eq!(Outcome::Failed.exit_code(), 1); + assert_eq!(Outcome::Stale.exit_code(), 2); + } + + fn merged() -> serde_json::Value { + serde_json::json!({"openapi": "3.0.3", "info": {"title": "T", "version": "1"}, "paths": {}}) + } + + #[test] + fn compares_the_output_file_by_data() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("out.yaml"); + + assert!(matches!( + compare_output(&path, &merged(), &OutputFormat::Yaml), + Comparison::Missing + )); + + std::fs::write( + &path, + "paths: {}\ninfo: {version: '1', title: T}\nopenapi: 3.0.3\n", + ) + .unwrap(); + assert!(matches!( + compare_output(&path, &merged(), &OutputFormat::Yaml), + Comparison::UpToDate + )); + + std::fs::write( + &path, + "openapi: 3.0.3\ninfo: {title: Other, version: '1'}\npaths: {}\n", + ) + .unwrap(); + match compare_output(&path, &merged(), &OutputFormat::Yaml) { + Comparison::Stale { diff } => { + assert!(diff.contains("+++ regenerated"), "{diff}"); + assert!( + diff.contains("- title: Other") && diff.contains("+ title: T"), + "{diff}" + ); + } + other => panic!("expected Stale, got {other:?}"), + } + + std::fs::write(&path, "{: nope").unwrap(); + assert!(matches!( + compare_output(&path, &merged(), &OutputFormat::Yaml), + Comparison::Unreadable(_) + )); + } +} diff --git a/crates/openapi-aggregator/src/lib.rs b/crates/openapi-aggregator/src/lib.rs index 86aba22..3b894ef 100644 --- a/crates/openapi-aggregator/src/lib.rs +++ b/crates/openapi-aggregator/src/lib.rs @@ -14,8 +14,9 @@ pub use error::Error; pub use openapi_aggregator_core::{ bundle_source, check_document_cap, config, is_url, merge, merge_specs, merge_specs_with_report, missing_documents, parse_content, prepare_source, prepare_source_with_notes, resolve_location, - Config, ConflictStrategy, InfoOverride, MergeConfig, MergeReport, MissingDocument, - OutputConfig, OutputFormat, PreparedSource, ServerEntry, Source, TagEntry, TagPrefixStrategy, + validate, Config, ConflictStrategy, Finding, InfoOverride, MergeConfig, MergeReport, + MissingDocument, OutputConfig, OutputFormat, PreparedSource, ServerEntry, Severity, Source, + TagEntry, TagPrefixStrategy, }; pub use source::load_source; diff --git a/crates/openapi-aggregator/src/main.rs b/crates/openapi-aggregator/src/main.rs index 249f447..49d375c 100644 --- a/crates/openapi-aggregator/src/main.rs +++ b/crates/openapi-aggregator/src/main.rs @@ -1,3 +1,5 @@ +mod check; + use std::path::PathBuf; use clap::Parser; @@ -23,6 +25,15 @@ struct Cli { /// Let external `$ref`s read files outside the config directory #[arg(long)] allow_outside_config_dir: bool, + + /// Validate the merged spec and exit non-zero on problems; with --output, also fail + /// when that file is out of date. Writes nothing. + #[arg(long)] + check: bool, + + /// With --check, treat warnings as failures + #[arg(long, requires = "check")] + deny_warnings: bool, } fn parse_format(s: &str) -> Result { @@ -39,13 +50,16 @@ fn parse_format(s: &str) -> Result { async fn main() { let cli = Cli::parse(); - if let Err(e) = run(cli).await { - eprintln!("error: {e}"); - std::process::exit(1); + match run(cli).await { + Ok(outcome) => std::process::exit(outcome.exit_code()), + Err(e) => { + eprintln!("error: {e}"); + std::process::exit(1); + } } } -async fn run(cli: Cli) -> Result<(), Box> { +async fn run(cli: Cli) -> Result> { let config = load_config(&cli.config)?; let options = AggregateOptions { allow_outside_config_dir: cli.allow_outside_config_dir, @@ -56,6 +70,19 @@ async fn run(cli: Cli) -> Result<(), Box> { eprintln!("warning: {warning}"); } + if cli.check { + let mut outcome = check::run_validation(&report, cli.deny_warnings); + if let Some(path) = &cli.output { + let format = cli.format.unwrap_or(config.output.format); + let stale = check::check_output(path, &report.spec, &format); + // A validation failure (exit 1) outranks a stale file (exit 2). + if outcome == check::Outcome::Passed { + outcome = stale; + } + } + return Ok(outcome); + } + let format = cli.format.unwrap_or(config.output.format); let text = match format { OutputFormat::Yaml => serde_yaml::to_string(&report.spec)?, @@ -70,7 +97,7 @@ async fn run(cli: Cli) -> Result<(), Box> { None => print!("{text}"), } - Ok(()) + Ok(check::Outcome::Passed) } #[cfg(test)] diff --git a/crates/openapi-aggregator/tests/check_cli.rs b/crates/openapi-aggregator/tests/check_cli.rs new file mode 100644 index 0000000..c7cf8fe --- /dev/null +++ b/crates/openapi-aggregator/tests/check_cli.rs @@ -0,0 +1,237 @@ +use std::path::Path; +use std::process::Command; + +fn run(dir: &Path, args: &[&str]) -> (i32, String, String) { + let output = Command::new(env!("CARGO_BIN_EXE_openapi-aggregator")) + .args(args) + .current_dir(dir) + .output() + .unwrap(); + ( + output.status.code().unwrap_or(-1), + String::from_utf8_lossy(&output.stdout).into_owned(), + String::from_utf8_lossy(&output.stderr).into_owned(), + ) +} + +fn write(dir: &Path, name: &str, content: &str) { + std::fs::write(dir.join(name), content).unwrap(); +} + +fn spec(title: &str, path: &str, extra: &str) -> String { + format!( + "openapi: 3.0.3\ninfo: {{title: {title}, version: '1'}}\n{extra}paths:\n {path}:\n get:\n operationId: get{title}\n responses:\n '200': {{description: ok}}\n" + ) +} + +fn valid_dir() -> tempfile::TempDir { + let dir = tempfile::tempdir().unwrap(); + write(dir.path(), "a.yaml", &spec("A", "/a", "")); + write(dir.path(), "b.yaml", &spec("B", "/b", "")); + write( + dir.path(), + "cfg.yaml", + "sources:\n - name: a\n path: a.yaml\n - name: b\n path: b.yaml\n", + ); + dir +} + +const DANGLING_CFG: &str = "sources:\n - name: a\n path: a.yaml\n additional_blocks:\n components:\n schemas:\n Bad:\n $ref: '#/components/schemas/Ghost'\n"; + +#[test] +fn valid_config_passes() { + let dir = valid_dir(); + let (code, stdout, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml"]); + assert_eq!(code, 0, "{stderr}"); + assert!(stdout.is_empty(), "{stdout}"); + assert!(stderr.contains("check passed"), "{stderr}"); +} + +#[test] +fn dangling_ref_fails_with_the_finding() { + let dir = valid_dir(); + write(dir.path(), "cfg.yaml", DANGLING_CFG); + let (code, stdout, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml"]); + assert_eq!(code, 1, "{stderr}"); + assert!(stdout.is_empty(), "{stdout}"); + assert!(stderr.contains("error[dangling-ref]"), "{stderr}"); + assert!( + stderr.contains("check failed: 1 error, 0 warnings"), + "{stderr}" + ); +} + +#[test] +fn warnings_pass_unless_denied() { + let dir = valid_dir(); + let tagged = "openapi: 3.0.3\ninfo: {title: T, version: '1'}\ntags: [{name: a}]\npaths:\n /t:\n get:\n tags: [b]\n responses:\n '200': {description: ok}\n"; + write(dir.path(), "a.yaml", tagged); + write(dir.path(), "cfg.yaml", "sources:\n - path: a.yaml\n"); + let (code, _, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml"]); + assert_eq!(code, 0, "{stderr}"); + assert!(stderr.contains("warning[undeclared-tag]"), "{stderr}"); + + let (code, _, stderr) = run( + dir.path(), + &["--check", "--deny-warnings", "-c", "cfg.yaml"], + ); + assert_eq!(code, 1, "{stderr}"); + assert!( + stderr.contains("check failed: 0 errors, 1 warning"), + "{stderr}" + ); +} + +#[test] +fn merge_warnings_are_denied_too() { + let dir = valid_dir(); + write( + dir.path(), + "b.yaml", + &spec("B", "/b", "").replace("3.0.3", "3.1.0"), + ); + let (code, _, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml"]); + assert_eq!(code, 0, "{stderr}"); + let (code, _, stderr) = run( + dir.path(), + &["--check", "--deny-warnings", "-c", "cfg.yaml"], + ); + assert_eq!(code, 1, "{stderr}"); +} + +#[test] +fn merge_failure_exits_1() { + let dir = valid_dir(); + write(dir.path(), "b.yaml", &spec("B", "/a", "")); + let (code, _, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml"]); + assert_eq!(code, 1, "{stderr}"); + assert!( + stderr.contains("conflict") || stderr.contains("error"), + "{stderr}" + ); +} + +#[test] +fn deny_warnings_requires_check() { + let dir = valid_dir(); + let (code, _, stderr) = run(dir.path(), &["--deny-warnings", "-c", "cfg.yaml"]); + assert_eq!(code, 2); + assert!(stderr.contains("--check"), "{stderr}"); +} + +#[test] +fn runs_without_check_are_unchanged() { + let dir = valid_dir(); + write(dir.path(), "cfg.yaml", DANGLING_CFG); + let (code, stdout, stderr) = run(dir.path(), &["-c", "cfg.yaml"]); + assert_eq!(code, 0, "{stderr}"); + assert!(stdout.contains("Ghost"), "{stdout}"); + assert!(!stderr.contains("check"), "{stderr}"); +} + +fn generate(dir: &Path, args: &[&str]) { + let (code, _, stderr) = run(dir, args); + assert_eq!(code, 0, "{stderr}"); +} + +#[test] +fn up_to_date_output_passes() { + let dir = valid_dir(); + generate(dir.path(), &["-c", "cfg.yaml", "-o", "out.yaml"]); + let (code, stdout, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml", "-o", "out.yaml"]); + assert_eq!(code, 0, "{stderr}"); + assert!(stdout.is_empty()); +} + +#[test] +fn stale_output_exits_2_with_a_diff_and_is_not_modified() { + let dir = valid_dir(); + generate(dir.path(), &["-c", "cfg.yaml", "-o", "out.yaml"]); + let original = std::fs::read_to_string(dir.path().join("out.yaml")).unwrap(); + let stale = original.replace("title: A", "title: Z"); + assert_ne!(stale, original); + write(dir.path(), "out.yaml", &stale); + + let (code, stdout, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml", "-o", "out.yaml"]); + assert_eq!(code, 2, "{stderr}"); + assert!(stdout.is_empty()); + assert!( + stderr.contains("--- ") && stderr.contains("+++ regenerated"), + "{stderr}" + ); + assert!( + stderr.contains("- title: Z") && stderr.contains("+ title: A"), + "{stderr}" + ); + assert!(stderr.contains("out of date"), "{stderr}"); + assert_eq!( + std::fs::read_to_string(dir.path().join("out.yaml")).unwrap(), + stale + ); +} + +#[test] +fn missing_output_exits_2_and_is_not_created() { + let dir = valid_dir(); + let (code, _, stderr) = run( + dir.path(), + &["--check", "-c", "cfg.yaml", "-o", "nope.yaml"], + ); + assert_eq!(code, 2, "{stderr}"); + assert!(stderr.contains("does not exist"), "{stderr}"); + assert!(!dir.path().join("nope.yaml").exists()); +} + +#[test] +fn format_and_key_order_do_not_matter() { + let dir = valid_dir(); + generate( + dir.path(), + &["-c", "cfg.yaml", "-f", "json", "-o", "out.json"], + ); + let json: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(dir.path().join("out.json")).unwrap()) + .unwrap(); + let reversed: serde_json::Map = json + .as_object() + .unwrap() + .iter() + .rev() + .map(|(k, v)| (k.clone(), v.clone())) + .collect(); + write( + dir.path(), + "out.yaml", + &serde_yaml::to_string(&reversed).unwrap(), + ); + + let (code, _, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml", "-o", "out.yaml"]); + assert_eq!(code, 0, "{stderr}"); + let (code, _, stderr) = run( + dir.path(), + &["--check", "-c", "cfg.yaml", "-f", "json", "-o", "out.json"], + ); + assert_eq!(code, 0, "{stderr}"); +} + +#[test] +fn invalid_and_stale_exits_1_and_still_prints_the_diff() { + let dir = valid_dir(); + write(dir.path(), "cfg.yaml", DANGLING_CFG); + write(dir.path(), "out.yaml", "openapi: 3.0.3\n"); + let (code, _, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml", "-o", "out.yaml"]); + assert_eq!(code, 1, "{stderr}"); + assert!( + stderr.contains("error[dangling-ref]") && stderr.contains("out of date"), + "{stderr}" + ); +} + +#[test] +fn unparseable_output_file_is_stale() { + let dir = valid_dir(); + write(dir.path(), "out.yaml", "{: nope"); + let (code, _, stderr) = run(dir.path(), &["--check", "-c", "cfg.yaml", "-o", "out.yaml"]); + assert_eq!(code, 2, "{stderr}"); + assert!(stderr.contains("out of date"), "{stderr}"); +} diff --git a/web/src/app.ts b/web/src/app.ts index b2966a7..d1a48f5 100644 --- a/web/src/app.ts +++ b/web/src/app.ts @@ -138,7 +138,7 @@ export async function startApp(): Promise { $('#problems').replaceChildren( ...problems.map((p) => { const li = el('li', `problem ${p.level}`); - li.append(icon('alert'), el('span', 'problem-source', p.source ?? (p.kind === 'config' ? 'config' : 'merge'))); + li.append(icon('alert'), el('span', 'problem-source', p.source ?? (p.kind === 'config' ? 'config' : p.kind === 'validation' ? 'validation' : 'merge'))); li.append(el('span', 'problem-message', p.message)); return li; }), diff --git a/web/src/pipeline.ts b/web/src/pipeline.ts index 98a81d8..e2ae810 100644 --- a/web/src/pipeline.ts +++ b/web/src/pipeline.ts @@ -54,7 +54,12 @@ export async function runPipeline(config: string, files: WorkspaceFile[], deps: try { const out = deps.aggregate(config, contents, docs); const warnings: Problem[] = out.warnings.map((message) => ({ level: 'warning', kind: 'merge', message })); - return { text: out.text, format: summary.format, problems: [...problems, ...warnings] }; + const findings: Problem[] = out.findings.map((f) => ({ + level: f.severity, + kind: 'validation', + message: `${f.message} (${f.location || '/'})`, + })); + return { text: out.text, format: summary.format, problems: [...problems, ...warnings, ...findings] }; } catch (e) { return { text: null, diff --git a/web/src/sources.ts b/web/src/sources.ts index f348cb3..28f6769 100644 --- a/web/src/sources.ts +++ b/web/src/sources.ts @@ -31,6 +31,7 @@ export function statusOf(result: PipelineResult): { state: RunState; label: stri if (result.text === null) { return { state: 'error', label: kinds.has('config') ? 'Config has errors' : 'Merge failed' }; } + if (result.problems.some((p) => p.level === 'error')) return { state: 'error', label: 'Merged with validation errors' }; if (result.problems.length) return { state: 'warning', label: 'Merged with warnings' }; return { state: 'ok', label: 'Merged' }; } diff --git a/web/src/types.ts b/web/src/types.ts index a7c2391..d6bfb89 100644 --- a/web/src/types.ts +++ b/web/src/types.ts @@ -31,12 +31,21 @@ export interface PendingRefs { sources: MissingDocument[][]; } +export interface Finding { + severity: 'error' | 'warning'; + code: string; + message: string; + /** JSON pointer into the merged spec. */ + location: string; +} + export interface AggregateOutput { text: string; warnings: string[]; + findings: Finding[]; } -export type ProblemKind = 'config' | 'missing-file' | 'variable' | 'cors' | 'http' | 'merge' | 'blocked'; +export type ProblemKind = 'config' | 'missing-file' | 'variable' | 'cors' | 'http' | 'merge' | 'validation' | 'blocked'; export interface Problem { level: 'error' | 'warning'; diff --git a/web/tests/examples.test.ts b/web/tests/examples.test.ts index f25011e..fa7a656 100644 --- a/web/tests/examples.test.ts +++ b/web/tests/examples.test.ts @@ -21,6 +21,15 @@ describe('examples', () => { }); for (const example of EXAMPLES) { + const noValidationErrors = async () => { + const result = await runPipeline(example.config, example.files, { parseConfig, aggregate, pendingRefs, load: noNetwork }); + return result.problems.filter((p) => p.kind === 'validation' && p.level === 'error'); + }; + const remote = parseConfigSafe(example.config).some((s) => s.kind === 'url'); + it.skipIf(remote)(`${example.id}: merged output has no validation errors`, async () => { + expect(await noValidationErrors()).toEqual([]); + }); + it(`${example.id}: config parses`, () => { expect(() => parseConfig(example.config)).not.toThrow(); }); diff --git a/web/tests/pipeline.test.ts b/web/tests/pipeline.test.ts index b12bf0a..e9d2ac5 100644 --- a/web/tests/pipeline.test.ts +++ b/web/tests/pipeline.test.ts @@ -7,7 +7,7 @@ import { loadEngineForTests } from './helpers'; beforeAll(loadEngineForTests); const deps = (load: PipelineDeps['load'] = async () => 'unused'): PipelineDeps => ({ parseConfig, aggregate, pendingRefs, load }); -const spec = (title: string, paths = ' /a:\n get: {summary: a}\n') => +const spec = (title: string, paths = ' /a:\n get: {summary: a, responses: {"200": {description: ok}}}\n') => `openapi: 3.0.3\ninfo: {title: ${title}, version: '1'}\npaths:\n${paths}`; describe('runPipeline', () => { @@ -51,7 +51,7 @@ describe('runPipeline', () => { }); it('turns merge warnings into warning problems while keeping output', async () => { - const v31 = spec('B', ' /b:\n get: {summary: b}\n').replace('3.0.3', '3.1.0'); + const v31 = spec('B', ' /b:\n get: {summary: b, responses: {"200": {description: ok}}}\n').replace('3.0.3', '3.1.0'); const result = await runPipeline( 'sources:\n - path: a.yaml\n - path: b.yaml\n', [ @@ -65,7 +65,7 @@ describe('runPipeline', () => { }); it('stays fast for large specs (3,000 paths)', async () => { - const paths = Array.from({ length: 3000 }, (_, i) => ` /r${i}:\n get: {summary: r${i}}\n`).join(''); + const paths = Array.from({ length: 3000 }, (_, i) => ` /r${i}:\n get: {summary: r${i}, responses: {"200": {description: ok}}}\n`).join(''); const started = performance.now(); const result = await runPipeline('sources:\n - path: big.yaml\n', [{ name: 'big.yaml', content: spec('Big', paths) }], deps()); expect(result.problems).toEqual([]); @@ -158,3 +158,21 @@ describe('external refs', () => { expect(calls.find(([u]) => u === 'https://b.test/x.yaml')?.[1]).toEqual({}); }); }); + +describe('validation findings', () => { + const dangling = spec('V', ' /v:\n get:\n responses:\n "200":\n description: ok\n content:\n application/json:\n schema:\n $ref: "#/components/schemas/Missing"\n'); + + it('shows output together with validation problems', async () => { + const result = await runPipeline('sources:\n - path: v.yaml\n', [{ name: 'v.yaml', content: dangling }], deps()); + expect(result.text).not.toBeNull(); + expect(result.problems).toEqual([ + expect.objectContaining({ level: 'error', kind: 'validation', message: expect.stringContaining('Missing') }), + ]); + expect(result.problems[0].message).toContain('/paths/~1v/get/responses/200/content/application~1json/schema'); + }); + + it('reports no validation problems for a clean spec', async () => { + const result = await runPipeline('sources:\n - path: a.yaml\n', [{ name: 'a.yaml', content: spec('A') }], deps()); + expect(result.problems.filter((p) => p.kind === 'validation')).toEqual([]); + }); +}); diff --git a/web/tests/sources.test.ts b/web/tests/sources.test.ts index 6451b9b..349d626 100644 --- a/web/tests/sources.test.ts +++ b/web/tests/sources.test.ts @@ -38,6 +38,14 @@ describe('status', () => { state: 'warning', label: 'Merged with warnings', }); + expect(statusOf(result({ problems: [{ level: 'error', kind: 'validation', message: 'v' }] }))).toEqual({ + state: 'error', + label: 'Merged with validation errors', + }); + expect(statusOf(result({ problems: [{ level: 'warning', kind: 'validation', message: 'v' }] }))).toEqual({ + state: 'warning', + label: 'Merged with warnings', + }); expect(statusOf(result({ text: null, problems: [{ level: 'error', kind: 'config', message: 'c' }] }))).toEqual({ state: 'error', label: 'Config has errors',