feat(openapi-mock): add package for generating OpenAPI-shaped fake responses

[odinr]

Why is this change needed?
Extracted from the poc/framework-testability branch cleanup. @equinor/fusion-openapi-mock is a standalone, framework-agnostic utility and deserves its own history/PR rather than being entangled with the HTTP-mock-module and MSAL/service-discovery mock work. It also has its own tracked user story: equinor/fusion-core-tasks#1660.

What is the current behavior?
No package exists for generating fake responses from an OpenAPI document. Testing an API-shaped client currently requires hand-written fixtures for every endpoint.

What is the new behavior?
Adds @equinor/fusion-openapi-mock:

• createOpenApiMock(document, options?) fakes every operation with an operationId from its declared success response schema ($refs resolved against the document).
• overrides (at construction) and .register(operationId, handler) (afterwards) replace faked output for specific operations.
• seed makes faked output repeatable across runs.
• fetchOpenApiDocument(url, options?) fetches/parses a JSON or YAML spec from a URL.
• fields (a FieldFakerMap) fakes specific fields with a @faker-js/faker path string or function; loadFakerMap(source) loads one from a sidecar file.
• No dependency on any HTTP or routing framework — resolve({ method, path, query }) returns a plain { status, mock }.

What is the intended behavior or invariant?
resolve() returns undefined for any request that matches no operation in the document, so callers (e.g. @equinor/fusion-framework-module-http's mock router via fromOpenApiMock) can compose it with other registrations covering endpoints outside the spec. The package has zero runtime dependency on any HTTP module — consumers duck-type against OpenApiMockLike.

Does this PR introduce a breaking change?
No — this is a new package.

Impact assessment:

• Breaking changes: No
• Version bump: Minor (initial release, see changeset)
• Consumer impact: New opt-in package; no existing packages depend on it yet
• Downstream impact: None yet — @equinor/fusion-framework-module-http's fromOpenApiMock adapter is duck-typed against this package's shape but has no hard dependency

Review guidance:
Focus on the public API surface (createOpenApiMock, fetchOpenApiDocument, loadFakerMap) and TSDoc. Tests cover schema dereferencing, field-faker application, and mock generation from schema.

Additional context
Extracted cleanly from poc/framework-testability — verified pnpm --filter @equinor/fusion-openapi-mock test run, build, biome check, and fusion-lint lint packages/utils/openapi-mock all pass with no issues.

Related issues
closes: equinor/fusion-core-tasks#1660
ref: equinor/fusion-core-tasks#1654

Checklist

• Confirm completion of the self-review checklist
• Confirm TSDoc captures intent for functions, hooks, components, classes, and named arrow functions
• Confirm iterator blocks, decision gates, RxJS chains, and complex decisions explain why they exist
• Confirm React logic and derived values are resolved before markup when applicable (N/A — no React in this package)
• Confirm README/docs are updated for user-facing changes
• Confirm changes to target branch validation
  • Included files validated
  • No new linting warnings
  • Not a duplicate PR
• Confirm adherence to code of conduct

[changeset-bot]

🦋 Changeset detected

Latest commit: 1f7b278

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@equinor/fusion-openapi-mock	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds a new published utility package, @equinor/fusion-openapi-mock, for generating OpenAPI-shaped fake responses (with overrides, seeding, and field-level faker mapping), plus accompanying tests, docs, and a changeset for the initial release.

Changes:

• Introduce @equinor/fusion-openapi-mock public API (createOpenApiMock, fetchOpenApiDocument, loadFakerMap) and supporting internals for $ref dereferencing and schema-based mock generation.
• Add Vitest coverage for dereferencing, document fetching/parsing, sidecar faker maps, and resolve/override behavior.
• Add package metadata/docs + changeset, and update CODEMAP/lockfile to include the new package and dependencies.

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds the new package importer and locks new deps (json-schema-faker, yaml, etc.).
packages/utils/openapi-mock/vitest.config.ts	Vitest project config for the new package.
packages/utils/openapi-mock/tsconfig.json	TS build configuration for the new package (project references, output dirs).
packages/utils/openapi-mock/package.json	New published package manifest, scripts, and dependencies.
packages/utils/openapi-mock/README.md	Consumer-facing docs and usage examples for the new mock generator.
packages/utils/openapi-mock/src/index.ts	Public export surface for the package.
packages/utils/openapi-mock/src/types.ts	Public types for documents, mocks, overrides, and field faker mappings.
packages/utils/openapi-mock/src/load-faker-map.ts	Sidecar loader for FieldFakerMap (JSON/YAML/script via importConfig).
packages/utils/openapi-mock/src/fetch-open-api-document.ts	Fetch + parse helper for JSON/YAML OpenAPI docs.
packages/utils/openapi-mock/src/dereference-schema.ts	$ref inlining helper with cycle protection.
packages/utils/openapi-mock/src/generate-mock-from-schema.ts	Schema-to-value generation using json-schema-faker + @faker-js/faker.
packages/utils/openapi-mock/src/create-open-api-mock.ts	Core routing + operation indexing + override/resolve implementation.
packages/utils/openapi-mock/src/apply-field-fakers.ts	Field-level faker-map application by annotating schemas before generation.
packages/utils/openapi-mock/tests/load-faker-map.test.ts	Tests for sidecar parsing/loading behavior.
packages/utils/openapi-mock/tests/fetch-open-api-document.test.ts	Tests for JSON/YAML parsing and non-OK fetch handling.
packages/utils/openapi-mock/tests/dereference-schema.test.ts	Tests for $ref resolution, arrays, and cycle breaking.
packages/utils/openapi-mock/tests/create-open-api-mock.test.ts	Tests for routing, schema-based mocking, overrides, and seeding.
packages/utils/openapi-mock/tests/fixtures/fields-yaml.faker.yaml	YAML fixture for loadFakerMap.
packages/utils/openapi-mock/tests/fixtures/fields-ts.faker.ts	TS sidecar fixture (default export with real function).
packages/utils/openapi-mock/tests/fixtures/fields-json.faker.json	JSON fixture for loadFakerMap.
CODEMAP.md	Updates published package count and adds the new package to the map.
.changeset/openapi-mock_initial-release.md	Changeset for initial minor release of the new package.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	67.44%	3327 / 4933
🔵	Statements	66.66%	3977 / 5966
🔵	Functions	52.6%	1151 / 2188
🔵	Branches	57.21%	1855 / 3242

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/utils/openapi-mock/src/apply-field-fakers.ts	91.83%	84.84%	100%	100%	42, 46, 114, 141
packages/utils/openapi-mock/src/create-open-api-mock.ts	88.75%	76.66%	96.42%	90.14%	72, 83-93
packages/utils/openapi-mock/src/dereference-schema.ts	95.83%	94.73%	100%	100%	11
packages/utils/openapi-mock/src/fetch-open-api-document.ts	91.66%	80%	100%	91.66%	65
packages/utils/openapi-mock/src/generate-mock-from-schema.ts	100%	100%	100%	100%
packages/utils/openapi-mock/src/load-faker-map.ts	87.5%	77.77%	100%	86.66%	22, 28-30

Generated in workflow #15082 for commit 1f7b278 by the Vitest Coverage Report Action

[Copilot]

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (4)

packages/utils/openapi-mock/src/create-open-api-mock.ts:256

• options.overrides entries are never validated against the operations in the document, so a misspelled operationId in overrides is silently ignored (contradicting the @throws doc and the intent of failing fast on typos). Validate the keys eagerly and throw the same error message used elsewhere.

  const operations = buildOperations(document);
  const overrides = new Map<string, OpenApiMockOverride>(Object.entries(options.overrides ?? {}));

packages/utils/openapi-mock/src/index.ts:14

• The package-level TSDoc says resolve() returns { status, mock }, but the actual return type/value includes operationId and params as well. This mismatch can mislead consumers reading the generated docs.

 * This package has no opinion on HTTP or routing frameworks: {@link OpenApiMock.resolve}
 * takes a plain `{ method, path, query }` and returns a plain
 * `{ status, mock }`, so it drops into `@equinor/fusion-framework-module-http`'s

.changeset/openapi-mock_initial-release.md:24

• The changeset claims resolve({ method, path, query }) returns { status, mock }, but the public API actually returns { status, mock, operationId, params }. Aligning this text avoids publishing misleading release notes for consumers.

- No dependency on any HTTP or routing framework: `resolve({ method, path, query })` returns a plain `{ status, mock }`, so it drops into `@equinor/fusion-framework-module-http`'s mock router, `openapi-backend`, Express, or a hand-rolled server equally easily.

packages/utils/openapi-mock/src/load-faker-map.ts:92

• loadFakerMap validates YAML sidecars, but .json (and .ts/.js) sidecars loaded via importConfig are returned without runtime shape validation. A malformed .json map (non-string values) will fail later in less obvious ways; validate the resolved config immediately and throw an error that names the resolved file.

  // .json, .ts, .js, .mjs (or no extension) resolve through `importConfig`'s own
  // extension probing, so a sidecar can be authored in whichever of those formats
  // (real functions require .ts/.js/.mjs, since JSON can't hold one)
  const basename = source.replace(/\.(json|ts|mjs|js)$/i, '');
  const { config } = await importConfig<FieldFakerMap>(basename, { baseDir: options.baseDir });
  return config;