Files
crank/crates/crank-import/tests/preview.rs
T

960 lines
33 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
mod unit {
use crank_core::HttpMethod;
use crank_import::rest::{
ImportParseError, NormalizationConfig, SourceDigest, normalize_verified_document,
preview_document, preview_document_legacy_v1,
};
use crank_schema::SchemaKind;
use serde_json::json;
const OPENAPI3: &str = r#"
openapi: 3.0.3
info:
title: Frankfurter API
servers:
- url: https://api.frankfurter.dev
paths:
/v2/latest:
get:
operationId: getLatestRates
summary: Получить последние курсы
description: Возвращает последние курсы валют для базовой валюты.
tags: [currency]
parameters:
- name: base
in: query
required: true
schema:
type: string
- name: symbols
in: query
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required: [amount, base]
properties:
amount:
type: number
base:
type: string
"#;
const SWAGGER2: &str = r#"
swagger: "2.0"
info:
title: Pet API
host: petstore.example.com
basePath: /api
schemes: [https]
paths:
/pets/{id}:
get:
operationId: getPet
summary: Получить питомца
tags: [pets]
parameters:
- name: id
in: path
required: true
type: string
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Pet'
definitions:
Pet:
type: object
required: [id, name]
properties:
id:
type: string
name:
type: string
"#;
#[test]
fn previews_openapi3_rest_operations_grouped_by_tag() {
let preview = preview_document(OPENAPI3).unwrap();
assert_eq!(preview.source.format, "openapi");
assert_eq!(preview.source.servers, vec!["https://api.frankfurter.dev"]);
assert_eq!(preview.groups.len(), 1);
assert_eq!(preview.groups[0].key, "currency");
let operation = &preview.groups[0].operations[0];
assert_eq!(operation.method, HttpMethod::Get);
assert_eq!(operation.suggested_name, "get_latest_rates");
assert_eq!(operation.input_fields, 2);
assert_eq!(operation.output_fields, 2);
assert_eq!(operation.draft.target.path_template, "/v2/latest");
assert_eq!(operation.draft.input_mapping.rules.len(), 2);
}
#[test]
fn previews_swagger2_and_resolves_local_definitions() {
let preview = preview_document(SWAGGER2).unwrap();
assert_eq!(preview.source.format, "swagger");
assert_eq!(
preview.source.servers,
vec!["https://petstore.example.com/api"]
);
let operation = &preview.groups[0].operations[0];
assert_eq!(operation.suggested_name, "get_pet");
assert_eq!(operation.input_fields, 1);
assert_eq!(operation.output_fields, 2);
assert_eq!(operation.draft.target.path_template, "/pets/{id}");
assert_eq!(
operation.draft.input_mapping.rules[0].target,
"$.request.path.id"
);
}
#[test]
fn normalized_schema_descriptions_round_trip_to_draft_fields_and_arrays_default_to_string_items()
{
let document = r#"
openapi: 3.1.0
info: { title: Schema descriptions }
paths:
/items:
post:
operationId: createItem
parameters:
- name: filter
in: query
schema:
type: object
description: Filter input
properties:
nested:
type: object
description: Nested filter
properties:
labels:
type: array
description: Labels without item schema
requestBody:
content:
application/json:
schema:
type: object
description: Request root
properties:
payload:
type: object
description: Request payload
properties:
enabled: { type: boolean, description: Enable the item }
responses:
'201':
description: created
content:
application/json:
schema:
type: object
description: Created item response
properties:
id: { type: string, description: New item identifier }
"#;
let preview = preview_document(document).unwrap();
let operation = &preview.groups[0].operations[0];
let filter = operation.draft.input_schema.field("filter").unwrap();
assert_eq!(filter.description.as_deref(), Some("Filter input"));
let nested = filter.field("nested").unwrap();
assert_eq!(nested.description.as_deref(), Some("Nested filter"));
let labels = nested.field("labels").unwrap();
assert_eq!(
labels.description.as_deref(),
Some("Labels without item schema")
);
assert_eq!(labels.kind, SchemaKind::Array);
assert_eq!(labels.items.as_ref().unwrap().kind, SchemaKind::String);
let body = operation.draft.input_schema.field("body").unwrap();
let payload = body.field("payload").unwrap();
assert_eq!(payload.description.as_deref(), Some("Request payload"));
assert_eq!(
payload.field("enabled").unwrap().description.as_deref(),
Some("Enable the item")
);
assert_eq!(
operation.draft.output_schema.description.as_deref(),
Some("Ответ API")
);
assert_eq!(
operation
.draft
.output_schema
.field("id")
.unwrap()
.description
.as_deref(),
Some("New item identifier")
);
}
#[test]
fn legacy_v1_keeps_frozen_response_priority_when_v2_selects_later_success_code() {
let document = r#"
openapi: 3.1.0
info: { title: Response replay priority }
paths:
/items:
get:
operationId: listItems
responses:
'200': { description: no schema }
'203': { description: selected by v2, content: { application/json: { schema: { type: string } } } }
'206': { description: later success, content: { application/json: { schema: { type: integer } } } }
default: { description: legacy fallback, content: { application/json: { schema: { type: boolean } } } }
"#;
let v2 = preview_document(document).unwrap();
assert_eq!(
v2.groups[0].operations[0].draft.output_schema.kind,
SchemaKind::Oneof
);
let legacy = preview_document_legacy_v1(document).unwrap();
assert_eq!(
legacy.groups[0].operations[0].draft.output_schema.kind,
SchemaKind::Boolean
);
}
#[test]
fn legacy_v1_projection_matches_baseline_local_ref_and_composition_behavior() {
let document = r#"
swagger: '2.0'
info: { title: Legacy }
paths:
/pets:
get:
responses:
'200': { description: OK, schema: { $ref: '#/definitions/Pet' } }
definitions:
Pet:
allOf:
- type: object
properties: { id: { type: string }, name: { type: string } }
"#;
let preview = preview_document_legacy_v1(document).unwrap();
assert_eq!(preview.groups[0].operations[0].output_fields, 2);
}
#[test]
fn legacy_v1_resolves_object_level_local_refs_before_projection() {
let document = r#"
openapi: 3.0.3
info: { title: Legacy object refs }
paths:
/items:
get:
operationId: getItem
parameters: [{ $ref: '#/components/parameters/Id' }]
requestBody: { $ref: '#/components/requestBodies/Body' }
responses:
'200': { $ref: '#/components/responses/Ok' }
components:
parameters:
Id:
name: id
in: query
schema: { type: string }
requestBodies:
Body:
content:
application/json:
schema: { $ref: '#/components/schemas/Input' }
responses:
Ok:
description: ok
content:
application/json:
schema: { $ref: '#/components/schemas/Output' }
schemas:
Input:
type: object
properties: { name: { type: string } }
Output:
type: object
properties: { result: { type: string } }
"#;
let preview = preview_document_legacy_v1(document).unwrap();
let operation = &preview.groups[0].operations[0];
assert_eq!(operation.input_fields, 2);
assert_eq!(operation.output_fields, 1);
assert!(operation.draft.input_schema.fields.contains_key("id"));
assert!(operation.draft.input_schema.fields.contains_key("name"));
assert!(operation.draft.output_schema.fields.contains_key("result"));
}
#[test]
fn legacy_v1_rejects_hostile_alias_input_before_decode() {
let document = format!(
"openapi: 3.0.3\ninfo: {{ title: aliases }}\npaths: {{}}\nitems: [{}]",
std::iter::repeat_n("*bomb", 129)
.collect::<Vec<_>>()
.join(", ")
);
assert_eq!(
preview_document_legacy_v1(&document),
Err(ImportParseError::LimitExceeded)
);
}
#[test]
fn legacy_v1_keeps_baseline_version_dispatch_and_does_not_expand_path_item_refs() {
let document = r#"
openapi: 9.9.0
info: { title: Legacy dispatch }
paths:
/valid:
get:
operationId: valid
responses: { '200': { description: ok } }
/referenced:
$ref: '#/x-path-items/referenced'
x-path-items:
referenced:
post:
operationId: mustNotAppear
responses: { '201': { description: ok } }
"#;
let preview = preview_document_legacy_v1(document).unwrap();
assert_eq!(preview.source.version.as_deref(), Some("9.9.0"));
let keys = preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
.map(|operation| operation.key.as_str())
.collect::<Vec<_>>();
assert_eq!(keys, vec!["GET /valid"]);
}
#[test]
fn legacy_v1_preview_exactly_matches_baseline_for_path_refs_servers_and_malformed_operations() {
let document = r#"
openapi: 3.0.3
info: { title: Legacy parity }
servers: [{ url: https://document.test }]
paths:
/items:
parameters:
- { $ref: '#/components/parameters/Query' }
- { name: session, in: cookie }
servers: [{ url: https://path.test }]
head: { responses: {} }
get: false
components:
parameters:
Query: { name: q, in: query, schema: { type: string } }
"#;
let preview = preview_document_legacy_v1(document).unwrap();
assert_eq!(
serde_json::to_value(preview).unwrap(),
json!({
"source": {
"format": "openapi",
"version": "3.0.3",
"title": "Legacy parity",
"servers": ["https://document.test"]
},
"groups": [{
"key": "imported_operation",
"title": "Без группы",
"operations": [{
"key": "GET /items",
"method": "GET",
"path": "/items",
"suggested_name": "g_e_t_items",
"suggested_display_name": "G E T Items",
"description": "Выполняет GET /items",
"category": "imported",
"input_fields": 1,
"output_fields": 0,
"server_urls": ["https://document.test"],
"findings": [
{
"code": "missing_operation_id",
"severity": "warning",
"message": "У метода нет operationId, имя инструмента будет сгенерировано из метода и пути.",
"operation_key": "GET /items"
},
{
"code": "missing_summary",
"severity": "warning",
"message": "У метода нет summary, отображаемое имя будет сгенерировано автоматически.",
"operation_key": "GET /items"
},
{
"code": "missing_description",
"severity": "warning",
"message": "У метода нет description. Перед публикацией лучше описать, когда агенту стоит вызывать этот инструмент.",
"operation_key": "GET /items"
},
{
"code": "missing_response_schema",
"severity": "warning",
"message": "У метода не найдена схема успешного ответа, результат будет описан как общий объект.",
"operation_key": "GET /items"
},
{
"code": "parameter_descriptions_missing",
"severity": "warning",
"message": "У 1 входных параметров нет описания. Модели будет сложнее понять, какие значения туда передавать.",
"operation_key": "GET /items"
},
{
"code": "empty_output_schema",
"severity": "warning",
"message": "В ответе не найдено отдельных полей. Перед публикацией проверьте схему ответа и маппинг результата.",
"operation_key": "GET /items"
},
{
"code": "weak_tool_description",
"severity": "warning",
"message": "Описание инструмента слишком короткое или техническое. Перед публикацией добавьте, когда агент должен вызывать инструмент и что будет в успешном ответе.",
"operation_key": "GET /items"
},
{
"code": "weak_tool_name",
"severity": "warning",
"message": "Имя инструмента `g_e_t_items` выглядит слишком общим. Лучше использовать имя с конкретным действием и объектом.",
"operation_key": "GET /items"
}
],
"draft": {
"name": "g_e_t_items",
"display_name": "G E T Items",
"category": "imported",
"target": {
"base_url": "https://document.test",
"method": "GET",
"path_template": "/items"
},
"input_schema": {
"type": "object",
"description": "Входные параметры MCP-инструмента",
"required": true,
"nullable": false,
"fields": {
"q": {
"type": "string",
"required": false,
"nullable": false
}
}
},
"output_schema": {
"type": "object",
"description": "Ответ API",
"required": true,
"nullable": false
},
"input_mapping": {
"rules": [{
"source": "$.mcp.q",
"target": "$.request.query.q",
"required": false
}]
},
"output_mapping": {
"rules": [{
"source": "$.response.body",
"target": "$.output",
"required": true
}]
},
"tool_description": {
"title": "G E T Items",
"description": "Выполняет GET /items",
"examples": [{ "input": {} }]
},
"wizard_state": {}
}
}]
}],
"findings": []
})
);
}
#[test]
fn reports_missing_descriptions_as_recommendations() {
let document = r#"
openapi: 3.0.3
info: { title: Minimal API }
paths:
/items:
get:
responses:
'204': { description: Empty }
"#;
let preview = preview_document(document).unwrap();
let operation = &preview.groups[0].operations[0];
let codes = operation
.findings
.iter()
.map(|finding| finding.code.as_str())
.collect::<Vec<_>>();
assert!(codes.contains(&"missing_operation_id"));
assert!(codes.contains(&"missing_summary"));
assert!(codes.contains(&"missing_description"));
assert!(codes.contains(&"missing_response_schema"));
}
#[test]
fn expands_json_request_body_object_into_tool_inputs() {
let document = r#"
openapi: 3.0.3
info: { title: CRM API }
servers:
- url: https://crm.example.test
paths:
/leads:
post:
operationId: createLead
summary: Создать лид
description: Создает лид в CRM.
tags: [crm]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email]
properties:
email: { type: string }
name: { type: string }
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id: { type: string }
"#;
let preview = preview_document(document).unwrap();
let operation = &preview.groups[0].operations[0];
let input_fields = &operation.draft.input_schema.fields;
let targets = operation
.draft
.input_mapping
.rules
.iter()
.map(|rule| rule.target.as_str())
.collect::<Vec<_>>();
assert!(input_fields.contains_key("body"));
assert!(input_fields["body"].fields.contains_key("email"));
assert!(input_fields["body"].fields.contains_key("name"));
assert!(targets.contains(&"$.request.body"));
}
#[test]
fn reports_tool_quality_recommendations_for_imported_operations() {
let document = r#"
openapi: 3.0.3
info: { title: Wide API }
paths:
/items:
get:
operationId: getItems
summary: Get items
description: Get items.
parameters:
- name: page
in: query
schema: { type: integer }
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
field01: { type: string }
field02: { type: string }
field03: { type: string }
field04: { type: string }
field05: { type: string }
field06: { type: string }
field07: { type: string }
field08: { type: string }
field09: { type: string }
field10: { type: string }
field11: { type: string }
field12: { type: string }
field13: { type: string }
"#;
let preview = preview_document(document).unwrap();
let operation = &preview.groups[0].operations[0];
let codes = operation
.findings
.iter()
.map(|finding| finding.code.as_str())
.collect::<Vec<_>>();
assert!(codes.contains(&"parameter_descriptions_missing"));
assert!(codes.contains(&"weak_tool_description"));
assert!(codes.contains(&"weak_tool_name"));
assert!(codes.contains(&"too_many_output_fields"));
}
#[test]
fn previews_head_and_options_operations_and_rejects_trace_connect() {
let document = r#"
openapi: 3.0.3
info: { title: Method coverage }
paths:
/health:
head:
operationId: healthHead
responses: { '204': { description: Empty } }
options:
operationId: healthOptions
responses: { '204': { description: Empty } }
trace:
responses: { '200': { description: Unsupported } }
connect:
responses: { '200': { description: Unsupported } }
"#;
let preview = preview_document(document).unwrap();
let operations = preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
.collect::<Vec<_>>();
assert_eq!(operations.len(), 2);
assert!(operations.iter().any(|operation| {
operation.key == "HEAD /health" && operation.method == HttpMethod::Head
}));
assert!(operations.iter().any(|operation| {
operation.key == "OPTIONS /health" && operation.method == HttpMethod::Options
}));
let unsupported = preview
.findings
.iter()
.filter(|finding| finding.code == "unsupported_http_method")
.count();
assert_eq!(unsupported, 2);
}
#[test]
fn preserves_cookie_location_and_does_not_collapse_same_name_parameters() {
let document = r#"
openapi: 3.0.3
info: { title: Cookie parameters }
paths:
/sessions:
get:
operationId: listSessions
parameters:
- name: token
in: query
schema: { type: string }
- name: token
in: cookie
required: true
schema: { type: string }
responses:
'200': { description: OK }
"#;
let preview = preview_document(document).unwrap();
let candidate = &preview.groups[0].operations[0];
let cookie_and_query_rules = candidate
.draft
.input_mapping
.rules
.iter()
.filter(|rule| {
rule.target == "$.request.query.token" || rule.target == "$.request.cookies.token"
})
.collect::<Vec<_>>();
assert_eq!(cookie_and_query_rules.len(), 2);
assert_ne!(
cookie_and_query_rules[0].source,
cookie_and_query_rules[1].source
);
let ir = normalize_verified_document(
document,
SourceDigest::parse("0".repeat(64)).unwrap(),
&NormalizationConfig::default(),
)
.unwrap();
let operation = &ir.operations[0];
assert_eq!(operation.parameters.len(), 2);
assert!(operation.parameters.iter().any(|parameter| {
parameter.name == "token"
&& parameter.location == crank_import::rest::RestParameterLocation::Query
}));
assert!(operation.parameters.iter().any(|parameter| {
parameter.name == "token"
&& parameter.location == crank_import::rest::RestParameterLocation::Cookie
&& parameter.required
}));
}
#[test]
fn preserves_all_supported_request_media_variants() {
let document = r#"
openapi: 3.0.3
info: { title: Request media variants }
paths:
/imports:
post:
operationId: importPayload
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [json_name]
properties: { json_name: { type: string } }
application/x-www-form-urlencoded:
schema:
type: object
required: [form_name]
properties: { form_name: { type: string } }
multipart/form-data:
schema:
type: object
required: [file]
properties: { file: { type: string, format: binary } }
encoding:
file: { contentType: "image/png, image/jpeg" }
responses:
'202': { description: Accepted }
"#;
let ir = normalize_verified_document(
document,
SourceDigest::parse("0".repeat(64)).unwrap(),
&NormalizationConfig::default(),
)
.unwrap();
let variants = &ir.operations[0].request_body_variants;
let content_types = variants
.iter()
.map(|variant| variant.content_type.as_str())
.collect::<Vec<_>>();
assert_eq!(
content_types,
vec![
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
]
);
assert!(variants.iter().all(|variant| variant.required));
assert!(variants.iter().all(|variant| variant.schema.is_some()));
assert_eq!(
variants[2].multipart_field_mime_types.get("file"),
Some(&vec!["image/png".to_owned(), "image/jpeg".to_owned()])
);
let preview = preview_document(document).unwrap();
let input_schema = &preview.groups[0].operations[0].draft.input_schema;
assert_eq!(input_schema.kind, SchemaKind::Oneof);
assert_eq!(input_schema.variants.len(), 3);
assert!(
input_schema
.validate_shape(&json!({
"content_type": "application/json",
"body": {"json_name": "Ada"}
}))
.is_ok()
);
assert!(
input_schema
.validate_shape(&json!({
"content_type": "application/json",
"body": {"form_name": "Ada"}
}))
.is_err()
);
assert!(
input_schema
.validate_shape(&json!({
"content_type": "multipart/form-data",
"body": {"file": {"data_base64": "SGVsbG8="}}
}))
.is_ok()
);
assert!(
input_schema
.validate_shape(&json!({
"content_type": "multipart/form-data",
"body": {"file": {"data_base64": "SGVsbG8=", "extra": true}}
}))
.is_err()
);
assert!(
input_schema
.validate_shape(&json!({
"content_type": "multipart/form-data",
"body": {}
}))
.is_err()
);
assert_eq!(
preview.groups[0].operations[0]
.draft
.target
.multipart_field_mime_types
.get("multipart/form-data")
.and_then(|fields| fields.get("file")),
Some(&vec!["image/png".to_owned(), "image/jpeg".to_owned()])
);
}
#[test]
fn optional_variant_pair_preserves_omission_and_nullable_null_in_mapping() {
let document = r#"
openapi: 3.0.3
info: { title: Optional variants }
paths:
/events:
post:
operationId: createEvent
requestBody:
required: false
content:
application/json:
schema: { type: object, nullable: true, properties: { name: { type: string } } }
application/x-www-form-urlencoded:
schema: { type: object, properties: { title: { type: string } } }
responses: { '204': { description: Empty } }
"#;
let preview = preview_document(document).unwrap();
let draft = &preview.groups[0].operations[0].draft;
assert!(draft.input_schema.validate_shape(&json!({})).is_ok());
assert!(
draft
.input_schema
.validate_shape(&json!({"content_type": "application/json", "body": null}))
.is_ok()
);
assert!(
draft
.input_schema
.validate_shape(
&json!({"content_type": "application/x-www-form-urlencoded", "body": null})
)
.is_err()
);
// Omission is represented by its own closed branch, so an incomplete
// selector/body pair is rejected by the portable schema as well.
assert!(
draft
.input_schema
.validate_shape(&json!({"content_type": "application/json"}))
.is_err()
);
let mapped = draft
.input_mapping
.apply(&json!({"mcp": {"content_type": "application/json", "body": null}}))
.unwrap();
assert_eq!(mapped["request"]["body"], json!(null));
assert_eq!(mapped["request"]["body_content_type"], "application/json");
}
#[test]
fn preserves_multiple_success_responses_and_explicit_no_content() {
let document = r#"
openapi: 3.0.3
info: { title: Response variants }
paths:
/items:
get:
operationId: getItems
responses:
'200':
description: JSON result
content:
application/json:
schema: { type: object, properties: { id: { type: string } } }
'204': { description: No content }
'206':
description: Partial result
content:
application/json:
schema: { type: array, items: { type: string } }
"#;
let preview = preview_document(document).unwrap();
let output_schema = &preview.groups[0].operations[0].draft.output_schema;
let response_contract = &preview.groups[0].operations[0]
.draft
.target
.response_contract;
assert_eq!(output_schema.kind, SchemaKind::Oneof);
assert_eq!(output_schema.variants.len(), 3);
assert_eq!(
response_contract
.iter()
.map(|descriptor| (descriptor.status_code, descriptor.media_type.as_deref()))
.collect::<Vec<_>>(),
vec![
(200, Some("application/json")),
(204, None),
(206, Some("application/json")),
]
);
assert!(
output_schema
.variants
.iter()
.any(|variant| variant.kind == SchemaKind::Null)
);
let ir = normalize_verified_document(
document,
SourceDigest::parse("0".repeat(64)).unwrap(),
&NormalizationConfig::default(),
)
.unwrap();
let variants = &ir.operations[0].response_variants;
assert_eq!(
variants
.iter()
.map(|variant| variant.status_code)
.collect::<Vec<_>>(),
vec![200, 204, 206]
);
assert_eq!(
variants[0].content_type.as_deref(),
Some("application/json")
);
assert!(variants[0].schema.is_some());
assert_eq!(variants[1].content_type, None);
assert!(variants[1].schema.is_none());
assert_eq!(
variants[2].content_type.as_deref(),
Some("application/json")
);
assert!(variants[2].schema.is_some());
}
}