fix: preserve parameter order while ensuring path parameters win over same-named query parameters (#151)

## Summary

- Migrated snapshot tests from `toMatchSnapshot` to
`toMatchFileSnapshot` for better diff readability
- Excluded snapshot files from TypeScript type checking to prevent false
errors
- Added Kubernetes v1.28.6 OpenAPI spec as a snapshot test target
- Fixed a bug in `generatePropertySignatures` where same-named
parameters were reordered

## Problem

The previous fix for same-named path/query parameter conflicts (#150)
used `.sort()` to push path parameters to the end of the array before
reducing into a `Record`. This caused all path parameters to appear last
in the generated TypeScript interface, regardless of their position in
the OpenAPI spec.

For example, when the spec defines:
```yaml
parameters:
  - $ref: '#/components/parameters/zone_id'  # path parameter (first)
  - name: bins
    in: query                                 # query parameter (second)
```

The previous output was:
```typescript
export interface Parameter$... {
    bins?: string;    // ← wrong: appeared before zone_id
    zone_id: string;  // ← moved to last by sort
}
```

Additionally, the Kubernetes v1.28.6 spec exposes a second pattern: both
the path parameter and the query parameter with the same name (`path`)
are defined as `$ref` references. The previous sort only resolved `in`
for inline parameters, so both references were treated as non-path and
the query parameter reference (appearing last) won.

## Fix

Replaced the sort + `Record` reduce approach with a `Map`-based
iteration that preserves insertion order:

- Parameters are processed in their original spec order
- When two parameters share the same name, the path parameter's entry
wins by overwriting the existing value at its **original position** in
the Map (JavaScript `Map` preserves insertion order on `set()` of an
existing key)
- `resolveParameterIn` now resolves `$ref` references via
`store.getParameter()` so both inline and referenced path parameters are
correctly identified

```typescript
// Before: sort-based (broke insertion order)
const sorted = [...parameters].sort((a, b) => { /* path last */ });
const typeElementMap = sorted.reduce<Record<string, string>>(...);
return Object.values(typeElementMap);

// After: Map-based (preserves spec order)
const typeElementMap = new Map<string, string>();
for (const parameter of parameters) {
  const { name, typeElement } = generatePropertySignatureObject(...);
  const isPath = resolveParameterIn(store, parameter) === "path";
  if (!typeElementMap.has(name) || isPath) {
    typeElementMap.set(name, typeElement);
  }
}
return [...typeElementMap.values()];
```

## Test plan

- [x] `pnpm test:code:gen:class` — regenerate code passes
- [x] `pnpm test:code:gen:function` — regenerate code passes
- [x] `pnpm test:code:gen:currying-function` — regenerate code passes
- [x] `pnpm test:snapshot` — all 54 snapshot tests pass
- [x] New `$ref`-based path/query conflict scenario added to
`test/path-parameter/index.yml`
- [x] Kubernetes v1.28.6 snapshot added

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Himenon

biome.json

@@ -40,7 +40,7 @@
   },
   "files": {
     "ignoreUnknown": true,
-    "includes": ["**", "!**/dist", "!coverage", "!examples", "!test/code"],
+    "includes": ["**", "!**/dist", "!coverage", "!examples", "!test/code", "!**/__snapshots__"],
     "maxSize": 10485760
   },
   "javascript": {

scripts/testCodeGenWithClass.ts

@@ -40,6 +40,9 @@ const main = () => {
   Writer.generateTypedefWithTemplateCode("test/kubernetes/openapi-v1.18.5.json", "test/code/class/kubernetes/client-v1.18.5.ts", false, {
     sync: false,
   });
+  Writer.generateTypedefWithTemplateCode("test/kubernetes/openapi-v1.28.6.json", "test/code/class/kubernetes/client-v1.28.6.ts", false, {
+    sync: false,
+  });
   Writer.generateTypedefWithTemplateCode("test/argo-rollout/index.json", "test/code/class/argo-rollout/client.ts", false, {
     sync: false,
   });

src/code-templates/class-api-client/ApiClientClass/Method.ts

@@ -1,5 +1,3 @@
-import { EOL } from "node:os";
-
 import type { TsGenerator } from "../../../api";
 import type { CodeGenerator } from "../../../types";
 import * as MethodBody from "../../_shared/MethodBody";
@@ -161,7 +159,7 @@ export const create = (factory: TsGenerator.Factory.Type, params: CodeGenerator.
     comment: option.additionalMethodComment
       ? [params.operationParams.comment, `operationId: ${params.operationId}`, `Request URI: ${params.operationParams.requestUri}`]
           .filter(t => !!t)
-          .join(EOL)
+          .join("\n")
       : params.operationParams.comment,
     deprecated: params.operationParams.deprecated,
     type: returnType,

src/code-templates/currying-functional-api-client/FunctionalApiClient/index.ts

@@ -1,5 +1,3 @@
-import { EOL } from "node:os";
-
 import type { TsGenerator } from "../../../api";
 import type { CodeGenerator } from "../../../types";
 import type { Option } from "../../_shared/types";
@@ -11,7 +9,7 @@ export const create = (factory: TsGenerator.Factory.Type, list: CodeGenerator.Pa
       comment: option.additionalMethodComment
         ? [params.operationParams.comment, `operationId: ${params.operationId}`, `Request URI: ${params.operationParams.requestUri}`]
             .filter(t => !!t)
-            .join(EOL)
+            .join("\n")
         : params.operationParams.comment,
       modifiers: ["export"],
       declarationList: factory.VariableDeclarationList.create({

src/code-templates/functional-api-client/FunctionalApiClient/index.ts

@@ -1,5 +1,3 @@
-import { EOL } from "node:os";
-
 import type { TsGenerator } from "../../../api";
 import type { CodeGenerator } from "../../../types";
 import type { Option } from "../../_shared/types";
@@ -13,7 +11,7 @@ export const create = (factory: TsGenerator.Factory.Type, list: CodeGenerator.Pa
       comment: option.additionalMethodComment
         ? [params.operationParams.comment, `operationId: ${params.operationId}`, `Request URI: ${params.operationParams.requestUri}`]
             .filter(t => !!t)
-            .join(EOL)
+            .join("\n")
         : params.operationParams.comment,
     });
   });

src/index.ts

@@ -1,5 +1,3 @@
-import { EOL } from "node:os";
-
 import * as Api from "./api";
 import { generateValidRootSchema } from "./generateValidRootSchema";
 import type * as Types from "./types";
@@ -63,7 +61,7 @@ export class CodeGenerator {
       });
       return statements;
     };
-    return [Api.OpenApiTools.Comment.generateLeading(this.resolvedReferenceDocument), Api.TsGenerator.generate(create)].join(EOL + EOL + EOL);
+    return [Api.OpenApiTools.Comment.generateLeading(this.resolvedReferenceDocument), Api.TsGenerator.generate(create)].join("\n\n\n");
   }
 
   /**
@@ -79,7 +77,7 @@ export class CodeGenerator {
         return generatorTemplate?.generator(payload, generatorTemplate.option);
       });
     };
-    return [Api.OpenApiTools.Comment.generateLeading(this.resolvedReferenceDocument), Api.TsGenerator.generate(create)].join(EOL + EOL + EOL);
+    return [Api.OpenApiTools.Comment.generateLeading(this.resolvedReferenceDocument), Api.TsGenerator.generate(create)].join("\n\n\n");
   }
 
   /**

src/internal/OpenApiTools/Comment.ts

@@ -1,4 +1,3 @@
-import { EOL } from "node:os";
 import { Name, Version } from "../../meta";
 import type { OpenApi } from "../../types";
 
@@ -22,5 +21,5 @@ export const generateLeading = (schema: OpenApi.Document): string => {
     .map(message => {
       return `// ${message}`;
     })
-    .join(EOL);
+    .join("\n");
 };

src/internal/OpenApiTools/Walker/Operation.ts

@@ -1,5 +1,3 @@
-import { EOL } from "node:os";
-
 import type { CodeGenerator, OpenApi } from "../../../types";
 
 const httpMethodList = ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as const;
@@ -37,7 +35,7 @@ export const create = (rootSchema: OpenApi.Document): State => {
       state[operation.operationId] = {
         httpMethod,
         requestUri,
-        comment: [operation.summary, operation.description].filter(Boolean).join(EOL),
+        comment: [operation.summary, operation.description].filter(Boolean).join("\n"),
         deprecated: !!operation.deprecated,
         requestBody: hasValidMediaType ? requestBody : undefined,
         parameters: uniqParameters(parameters),

src/internal/OpenApiTools/components/ExternalDocumentation.ts

@@ -1,10 +1,8 @@
-import { EOL } from "node:os";
-
 import type { OpenApi } from "../../../types";
 
 export const addComment = (comment?: string, externalDocs?: OpenApi.ExternalDocumentation): string | undefined => {
   if (!externalDocs) {
     return comment;
   }
-  return [comment, "", `@see ${externalDocs.url}`, externalDocs.description].filter(Boolean).join(EOL);
+  return [comment, "", `@see ${externalDocs.url}`, externalDocs.description].filter(Boolean).join("\n");
 };

src/internal/OpenApiTools/components/Operation.ts

@@ -1,4 +1,3 @@
-import { EOL } from "node:os";
 import * as path from "node:path";
 
 import type { OpenApi } from "../../../types";
@@ -26,7 +25,7 @@ const generateComment = (operation: OpenApi.Operation): string => {
   if (operation.tags) {
     comments.push(`tags: ${operation.tags.join(", ")}`);
   }
-  return comments.join(EOL);
+  return comments.join("\n");
 };
 
 export const generateNamespace = (