feat(openapi3): add fully-dereferenced OpenAPI 3 types and replace custom guards

* Introduce `src/openapi3/dereferencedOpenApiv3.ts`, providing fully-dereferenced
  versions of core OpenAPI 3 objects (Document, OperationObject, SchemaObject,
  etc.).
* Refactor `handleJson.ts` to consume the new types:
  * Remove bespoke type-guard helpers (`isParameter`, `isSchema`, …).
  * Eliminate most explicit `as` casts and manual type-narrowing logic.
  * Simplify enum/array handling through shared helpers (`buildEnumObject`,
    `getArrayType`).

Signed-off-by: J3m5 <5523410+J3m5@users.noreply.github.com>

Author: J3m5

src/openapi3/dereferencedOpenApiv3.ts

@@ -0,0 +1,147 @@
+// oxlint-disable consistent-indexed-object-style
+import type { OpenAPIV3 } from "openapi-types";
+
+export type OpenAPIV3DocumentDereferenced<T extends object = object> = Omit<
+  OpenAPIV3.Document,
+  "paths" | "components"
+> & {
+  paths: PathsObjectDereferenced<T>;
+  components?: ComponentsObjectDereferenced;
+};
+
+interface PathsObjectDereferenced<
+  T extends object = object,
+  P extends object = object,
+> {
+  [pattern: string]: (PathItemObjectDereferenced<T> & P) | undefined;
+}
+
+type PathItemObjectDereferenced<T extends object = object> = Omit<
+  OpenAPIV3.PathItemObject,
+  "parameters" | `${OpenAPIV3.HttpMethods}`
+> & {
+  parameters?: ParameterObjectDereferenced[];
+} & {
+  [method in OpenAPIV3.HttpMethods]?: OperationObjectDereferenced<T>;
+};
+
+export type OperationObjectDereferenced<T extends object = object> = Omit<
+  OpenAPIV3.OperationObject,
+  "parameters" | "requestBody" | "responses" | "callbacks"
+> & {
+  parameters?: ParameterObjectDereferenced[];
+  requestBody?: RequestBodyObjectDereferenced;
+  responses: ResponsesObjectDereferenced;
+  callbacks?: {
+    [callback: string]: CallbackObjectDereferenced;
+  };
+} & T;
+interface ParameterObjectDereferenced extends ParameterBaseObjectDereferenced {
+  name: string;
+  in: string;
+}
+interface HeaderObjectDereferenced extends ParameterBaseObjectDereferenced {}
+type ParameterBaseObjectDereferenced = Omit<
+  OpenAPIV3.ParameterObject,
+  "schema" | "content"
+> & {
+  schema?: SchemaObjectDereferenced;
+  content?: {
+    [media: string]: MediaTypeObjectDereferenced;
+  };
+};
+
+export type SchemaObjectDereferenced =
+  | ArraySchemaObjectDereferenced
+  | NonArraySchemaObjectDereferenced;
+interface ArraySchemaObjectDereferenced extends BaseSchemaObjectDereferenced {
+  type: OpenAPIV3.ArraySchemaObjectType;
+  items: SchemaObjectDereferenced;
+}
+interface NonArraySchemaObjectDereferenced
+  extends BaseSchemaObjectDereferenced {
+  type?: OpenAPIV3.NonArraySchemaObjectType;
+}
+type BaseSchemaObjectDereferenced = Omit<
+  OpenAPIV3.BaseSchemaObject,
+  "additionalProperties" | "properties" | "allOf" | "oneOf" | "anyOf" | "not"
+> & {
+  additionalProperties?: boolean | SchemaObjectDereferenced;
+  properties?: {
+    [name: string]: SchemaObjectDereferenced;
+  };
+  allOf?: SchemaObjectDereferenced[];
+  oneOf?: SchemaObjectDereferenced[];
+  anyOf?: SchemaObjectDereferenced[];
+  not?: SchemaObjectDereferenced;
+};
+
+type MediaTypeObjectDereferenced = Omit<
+  OpenAPIV3.MediaTypeObject,
+  "schema" | "encoding"
+> & {
+  schema?: SchemaObjectDereferenced;
+  encoding?: {
+    [media: string]: EncodingObjectDereferenced;
+  };
+};
+type EncodingObjectDereferenced = Omit<OpenAPIV3.EncodingObject, "headers"> & {
+  headers?: {
+    [header: string]: HeaderObjectDereferenced;
+  };
+};
+type RequestBodyObjectDereferenced = Omit<
+  OpenAPIV3.RequestBodyObject,
+  "content"
+> & {
+  content: {
+    [media: string]: MediaTypeObjectDereferenced;
+  };
+};
+interface ResponsesObjectDereferenced {
+  [code: string]: ResponseObjectDereferenced;
+}
+type ResponseObjectDereferenced = Omit<
+  OpenAPIV3.ResponseObject,
+  "headers" | "content"
+> & {
+  headers?: {
+    [header: string]: HeaderObjectDereferenced;
+  };
+  content?: {
+    [media: string]: MediaTypeObjectDereferenced;
+  };
+};
+
+interface CallbackObjectDereferenced {
+  [url: string]: PathItemObjectDereferenced;
+}
+
+type ComponentsObjectDereferenced = Omit<
+  OpenAPIV3.ComponentsObject,
+  | "schemas"
+  | "responses"
+  | "parameters"
+  | "requestBodies"
+  | "headers"
+  | "callbacks"
+> & {
+  schemas?: {
+    [key: string]: SchemaObjectDereferenced;
+  };
+  responses?: {
+    [key: string]: ResponseObjectDereferenced;
+  };
+  parameters?: {
+    [key: string]: ParameterObjectDereferenced;
+  };
+  requestBodies?: {
+    [key: string]: RequestBodyObjectDereferenced;
+  };
+  headers?: {
+    [key: string]: HeaderObjectDereferenced;
+  };
+  callbacks?: {
+    [key: string]: CallbackObjectDereferenced;
+  };
+};