# Diagnostics

[English](DIAGNOSTICS.md) | [Chinese (Simplified)](zh-CN/DIAGNOSTICS.md)

Configuration, loading, parsing, rendering, and lifecycle issues are reported
as `KoiDiagnostic` values:

```dart
class KoiDiagnostic {
  final String code;
  final DiagnosticSeverity severity; // info | warning | error
  final String message;
  final String? source;
  final String? location;
}
```

`code` is the stable machine-readable identifier. Message wording may improve
between releases. `source` identifies a configuration path, document
URL/file, or generated file. `location` usually contains a JSONPath,
JSON Pointer, or other logical location inside the source.

## Severity behavior

- `info`: a normal decision, such as skipping an unchanged generation.
- `warning`: output remains reliable, but a rename, safe degradation, or
  explicitly omitted non-blocking capability requires attention.
- `error`: continuing could produce an invalid client; generation throws
  `KoiDiagnosticException`.

The CLI prints warnings and errors by default. `--verbose` also prints
informational diagnostics and failure stack traces.

Library callers can inspect diagnostics:

```dart
try {
  final result = await const KoiSwaggerParser().generate();
  for (final item in result.diagnostics) {
    print(item.format());
  }
} on KoiDiagnosticException catch (error) {
  for (final item in error.diagnostics) {
    print(item.format());
  }
}
```

Automation should match `code`, not message text. Assert `source` or
`location` as well when the distinction matters.

## Common codes

### Configuration

| Code | Meaning and remediation |
|---|---|
| `config.missing_sources` | Add at least one enabled `input.swagger_urls` entry. |
| `config.unknown_key` | Correct the spelling or remove a field not recognized by this version; warning. |
| `config.invalid_section` | Replace a scalar/list with the expected YAML map. |
| `config.invalid_string` / `config.invalid_boolean` | Correct the YAML scalar type. |
| `config.invalid_string_list` | Use a list of strings for include/exclude filters. |
| `config.invalid_filter_regex` | Correct the Dart expression after `regex:`. |
| `config.no_outputs_enabled` | API and model generation cannot both be disabled. |
| `config.api_requires_models` | The current API renderer requires generated models. |
| `config.unsupported_api_renderer` | Keep `use_retrofit: true`; no other API renderer is public yet. |
| `config.external_wrapper_import_required` | Add `external_generic.import`. |
| `config.mapping_target_collision` | Give mapping sources distinct target Dart names. |
| `config.import_mapping_conflict` | Use one import for a mapped Dart type. |
| `config.conflicting_schema_mapping` | Do not both rename and externally replace the same schema. |
| `config.ambiguous_enum_mapping` | Use unambiguous typed enum wire values. |

### Documents and references

| Code | Meaning and remediation |
|---|---|
| `openapi.missing_version` / `openapi.unsupported_version` | Supply an OpenAPI 3.0.x or 3.1.x document. |
| `openapi.invalid_info` / `openapi.invalid_paths` | Correct the corresponding core document structure. |
| `openapi.source_load_failed` / `openapi.source_http_error` | Check the file path, URL, access, and response status. |
| `openapi.unresolved_ref` | The local JSON Pointer does not exist. |
| `openapi.unresolved_external_ref` | The external resource or fragment does not exist or cannot be loaded. |
| `openapi.external_ref_not_bundled` | Reference normalization failed; inspect preceding source/resolver diagnostics. |
| `openapi.external_component_renamed` | An external component conflict was renamed deterministically; warning. |
| `openapi.multisource_component_renamed` | A component conflict across roots was renamed deterministically; warning. |
| `openapi.multisource_operation_conflict` | Two roots define the same method/path; remove or separate one definition. |
| `openapi.callbacks_not_supported` / `openapi.webhooks_not_supported` | Reverse-call clients are not generated; warning. |
| `openapi.links_not_supported` | Link Object call relationships are not generated; warning. |

### Parameters, requests, and responses

| Code | Meaning and remediation |
|---|---|
| `openapi.invalid_parameter_style` | Use a style valid for the parameter location. |
| `openapi.deep_object_requires_object` | A deepObject parameter needs an object schema. |
| `openapi.delimited_parameter_requires_array` | A space/pipe-delimited parameter needs an array schema. |
| `openapi.parameter_content_count` | Parameter Object `content` must contain exactly one media type. |
| `openapi.request_body_schema_missing` | Add a schema to the selected request media type. |
| `openapi.unsupported_request_content_type` | Use a supported request codec or map the endpoint manually. |
| `openapi.unsupported_response_content_type` | Use a supported response codec or map the endpoint manually. |
| `openapi.success_response_missing` | Add an explicit 2xx response; `default` is not success. |
| `openapi.multiple_success_response_types` | Multiple successful JSON body types converge on `Object?`; warning. |
| `openapi.mixed_success_media_types` | Binary/stream and JSON successes cannot be decoded safely by one generated method. |
| `openapi.path_parameter_forced_required` | A path parameter declared optional is forced to required; warning. |

### Schemas and names

| Code | Meaning and remediation |
|---|---|
| `openapi.property_read_write_only` | A property cannot be both read-only and write-only. |
| `openapi.invalid_additional_properties` | Use a boolean or Schema Object. |
| `openapi.property_name_collision` | An automatic suffix prevented a Dart field collision; warning. |
| `openapi.operation_name_collision` | An automatic suffix prevented a method collision; warning. |
| `openapi.operation_argument_name_collision` | A parameter conflicts with a body, cancel token, or another argument. |
| `openapi.duplicate_enum_member_name` | Multiple wire values map to one name; a suffix was added. |
| `openapi.enum_member_name_sanitized` | An enum member name was changed into a valid Dart identifier. |
| `filter.required_model_excluded` | A selected API needs an excluded model; include it or exclude its consumers. |
| `filter.model_pattern_unmatched` | An `included_models` pattern matched no schema. |

### Servers and security

| Code | Meaning and remediation |
|---|---|
| `openapi.server_url_missing` | Add a non-empty server URL. |
| `openapi.server_variable_default_missing` | Give every server variable a default value. |
| `openapi.server_variable_default_invalid` | Make the default one of the declared enum values. |
| `openapi.server_variable_unresolved` | Define every variable used by the server URL. |
| `openapi.unknown_security_scheme` | Define the referenced scheme in components. |
| `openapi.unsupported_security_scheme` | The scheme is retained only where documented or rejected. |
| `openapi.http_auth_requires_custom_interceptor` | Implement credential injection in the host Dio layer; warning. |

### Generation lifecycle

| Code | Meaning and remediation |
|---|---|
| `lifecycle.unchanged_skipped` | Hashes and files match; generation was safely skipped. |
| `lifecycle.manifest_invalid` | The old manifest is corrupt; output is rebuilt without trusting its deletion list. |
| `lifecycle.manifest_version_ignored` | The manifest schema is incompatible; its deletion list is ignored. |
| `lifecycle.output_outside_managed_roots` | Renderer output escaped the API/model roots and was rejected. |
| `lifecycle.duplicate_output_path` | Two rendered files target the same path with different content. |
| `lifecycle.stale_path_outside_roots` | A former path is outside current roots and is preserved. |
| `lifecycle.stale_file_modified` | A stale generated file was edited and is preserved for manual review. |
| `lifecycle.generated_file_missing` | A primary generated file disappeared during fix/format/build processing. |
| `lifecycle.control_file_not_stale` | A lifecycle control file is never treated as stale output. |

## Design principles

1. Unresolved references, invalid wire styles, and unsupported codecs do not
   silently become `dynamic`.
2. Safe, compilable automatic renaming can continue with a warning.
3. Unsupported constructs that do not invalidate other output are explicitly
   omitted with a warning.
4. Stale cleanup preserves files whenever containment or hash ownership is
   uncertain.
5. Diagnostics include component, operation, parameter, or file context when
   available.

New codes can be added in minor releases. Existing automation should treat
unknown warning codes as reviewable and unknown error codes as blocking.