# strictness

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`strictness` resolves the host's missing-schema policy for the OpenAPI
emitter and applies it consistently across every route. It encodes the
two-mode contract from the spec: `warn` (emit + warn + count) and
`refuse-install` (raise before the plugin is installed). The same
helper is wired into both the emitter and the host's plugin-install
gate so missing schemas behave identically wherever they're detected.

The module also owns the `api.openapi.missing_schema_total` OTel
counter — without an OTel meter exporter wired into the host, missing
schemas silently accumulate. Surfacing them as a per-plugin per-route
labelled metric makes drift visible to anyone watching the
observability stack.

## Features

- `resolveStrictness({ configured, environment })` — typed precedence
  resolver. Configured value wins; otherwise `"production"` → refuse,
  `"development"`/anything else → warn.
- `reportMissingSchema(input)` — single chokepoint that either throws
  or logs+counts. Accepts an injectable logger and counter so test
  setups can assert exact behaviour with a real `MeterProvider`.
- `getMissingSchemaCounter()` — lazy accessor over the package meter so
  production callers do not need to thread the counter through.

## Usage: Basic

```ts
import {
    reportMissingSchema,
    resolveStrictness,
} from "@suaveplan/api-openapi/strictness";

const mode = resolveStrictness({ environment: "production" });
// "refuse-install"

reportMissingSchema({
    mode,
    plugin: "billing",
    method: "GET",
    path: "/invoices/:id",
    slot: "response",
});
// throws OpenAPIError(OPENAPI.MISSING_SCHEMA)
```

## Usage: Advanced

```ts
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";
import {
    __resetMissingSchemaCounter,
    reportMissingSchema,
} from "@suaveplan/api-openapi/strictness";

const provider = new MeterProvider();
metrics.setGlobalMeterProvider(provider);
__resetMissingSchemaCounter();

const logger = { warn: (msg: string) => console.warn(msg) } as const;
reportMissingSchema({
    mode: "warn",
    plugin: "billing",
    method: "POST",
    path: "/invoices",
    slot: "request",
    logger,
});
// → counter increments, logger.warn called
```

## API Reference

- `StrictnessMode` — `"warn" | "refuse-install"`.
- `HostEnvironment` — `"development" | "production"`.
- `resolveStrictness(input) → StrictnessMode`.
- `reportMissingSchema(input) → void` (throws on `refuse-install`).
- `getMissingSchemaCounter() → Counter`.
- `__resetMissingSchemaCounter()` — test-only seam.
- Constants: `MISSING_SCHEMA_COUNTER_NAME`, `OPENAPI_METER_NAME`.

## Implementation Notes

- The counter is acquired lazily so registering the package side-effect
  does not require an OTel SDK at import time. Tests reset the cache
  via `__resetMissingSchemaCounter()` before binding a fresh
  `MeterProvider`.
- The counter labels — `plugin`, `route`, `slot` — match the spec's
  scenario assertion (`{ plugin, route }`) and add `slot` so request
  vs response misses can be distinguished without a second metric.
- `LoggerLike.warn` is optional in the contract (`@suaveplan/types`);
  the call is guarded with optional chaining so structured loggers that
  only ship `info` + `error` still work.