Release 0.2.0

Complete OpenAPI 3.0/3.1 generation, diagnostics, lifecycle safety, enum and naming mappings, bilingual documentation, examples, and pub.dev release validation.

doc/internal/GOAL.md

@@ -0,0 +1,75 @@
+# 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.