# Product goal

This is an internal planning record for the 0.2.0 development milestone.
User-facing support commitments are defined by
[Compatibility](../COMPATIBILITY.md).

## Objective

Evolve `koi_swagger_parser` from a Koi/FastAPI happy-path script into a
reliable, diagnosable, and extensible OpenAPI 3.0/3.1 Dart/Flutter client
generator. Preserve the loader -> resolver/merger -> parser/IR ->
preset/renderer -> lifecycle architecture and the Koi-oriented
Retrofit/Freezed output style.

## Definition of done

1. **Diagnostics**: versions, invalid structures, unsupported constructs,
   conflicts, and degradations have stable codes and source/location context.
2. **References**: local, relative-file, and remote references cover component
   groups with caching, cycle detection, multi-source conflict handling, and
   dependency tracking.
3. **Mappings**: enum configuration and vendor extensions have deterministic
   precedence and unknown fallback; model, property, parameter, operation,
   schema, type, and import mappings are validated.
4. **HTTP**: path/query/header/cookie serialization and supported
   style/explode/allowReserved combinations are correct; JSON, multipart,
   form-urlencoded, text, and binary transfers work.
5. **Responses**: multiple 2xx, 204, `2XX`, `default`, error models, headers,
   raw `HttpResponse`, and byte/stream output are represented.
6. **Schemas**: required/nullable/absent, read-only/write-only,
   additional-properties, composition/union, custom-scalar, and constraint
   metadata enter the IR and output within documented boundaries.
7. **Client metadata**: servers/base URLs and security requirements are
   available while remaining compatible with host Dio interceptors.
8. **Lifecycle**: configuration is effective; manifest locking/hashing,
   unchanged skips, safe stale cleanup, filters, and build_runner integration
   are complete.
9. **Quality gate**: layered tests, conflict/error cases, OpenAPI 3.0/3.1
   fixtures, golden output, and a temporary generated-package
   build/analyze/test verification pass.
10. **Documentation**: README, configuration, compatibility, diagnostics, and
    migration documentation match the implementation in English and
    Simplified Chinese.

## Non-goals for this milestone

- Swagger/OpenAPI 2.0.
- Callback, webhook, and Link Object call generation.
- XML, Protobuf, and arbitrary codecs.
- Complete JSON Schema 2020-12.
- Server stubs, mock servers, and non-Dart output.
- Independent generated-SDK publishing.

Non-goals must still produce an explicit warning or error when encountered.

## Evidence

```bash
dart format .
dart analyze
dart test
dart run tool/verify_generated_package.dart
```

The end-to-end verifier must let the generator invoke build_runner and then
run analysis and runtime tests in the generated package. String-fragment checks
alone are insufficient.

## Next horizon

Potential follow-up work includes a larger fixture/fuzz/performance corpus,
versioned IR and renderer interfaces, semantic-diff/CI mode, optional
authentication/error/middleware adapters, and PATCH presence tracking.
JSON Schema or Swagger 2 scope should expand only in response to concrete
consumer fixtures.