@skmtc/core 0.0.983 → 0.16.1

package/esm/context/parseTypes.d.ts

@@ -1,75 +1,174 @@
-import type { OasDocument } from '../oas/document/Document.js';
-import type { StackTrail } from './StackTrail.js';
-import type { IssueType } from './generateTypes.js';
-import type { OpenAPIV3 } from 'openapi-types';
 /**
- * Base type for parse error messages.
+ * Type-only surface for {@link ParseContext}.
+ *
+ * Parser helpers (under `oas/...` and `parsers/graphql/...`) consume
+ * `ParseContextType` as the shape of the context they receive. By
+ * importing from this module — rather than from `ParseContext.ts`
+ * directly — they avoid pulling the runtime class into their import
+ * graph and break the type-level cycle through `toDocumentFieldsV3`.
+ *
+ * Everything here is `import type`-friendly: zero runtime exports.
+ *
+ * Mirror-image: the runtime class and the input transforms live in
+ * `ParseContext.ts`. Adding a new method to `ParseContext` doesn't
+ * require touching this file unless that method is exposed to parser
+ * helpers — `ParseContextType` is `ParseContext` (the whole class)
+ * aliased here.
  */
-export type ParseErrorBase = {
-    /** Issue severity level */
-    level: 'error';
-    /** The error that occurred */
-    error: Error;
-};
+import type { ParseContext } from './ParseContext.js';
+import type { StackTrail } from './StackTrail.js';
+import type { OasIssueType } from './generateTypes.js';
+import type { GqlIssueType } from './ParseIssue.js';
 /**
- * Arguments for logging issues without a specific key.
+ * Public interface parsers write their function signatures against.
+ * Aliased to the unified `ParseContext` class so type-only consumers
+ * compile without depending on the runtime module.
  */
-export type LogIssueNoKeyArgs = ParseIssueBase & {
-    /** The parent object containing the issue */
-    parent: unknown;
-    /** The type of issue for categorization */
-    type: IssueType;
-    /** Stack trail for tracking current parsing context */
-    stackTrail: StackTrail;
-};
+export type ParseContextType = ParseContext;
 /**
- * Base type for parse warning messages.
+ * Unified input variants for `logIssue` / `logIssueNoKey`. Both
+ * variants carry a synthesized `message: string`; the error variant
+ * additionally carries an optional `cause: unknown` for the underlying
+ * thrown value (preserves stack traces without forcing renderers to
+ * know about Error objects). The unified context translates these into
+ * the stored {@link ParseIssue} shape, setting `protocol` to whichever
+ * protocol the current context is parsing.
+ *
+ * Replaces an earlier asymmetric design where the error variant
+ * carried a raw `Error` instance; that shape didn't survive the worker
+ * boundary cleanly (structured clone strips Error prototypes) and
+ * forced GQL parsers to use a separate input shape.
  */
-export type ParseWarningBase = {
-    /** Issue severity level */
+export type ParseErrorInput = {
+    level: 'error';
+    message: string;
+    cause?: unknown;
+};
+export type ParseWarningInput = {
     level: 'warning';
-    /** Warning message */
     message: string;
 };
+export type ParseIssueInput = ParseErrorInput | ParseWarningInput;
 /**
- * Base union type for parse issues.
+ * Arguments accepted by `ParseContext.logIssue` (StackTrail-based
+ * location, computed via `stackTrail.trace(key, ...)`).
+ *
+ * `type` accepts either an `OasIssueType` or a `GqlIssueType` — the
+ * `protocol` tag on the stored {@link ParseIssue} is set from
+ * `ParseContext.protocol.type` at log time, so callers don't have to
+ * pass it. Callers are expected to pass a type from the matching
+ * protocol's enum.
+ *
+ * `parent` is the surrounding object (e.g. the whole schema /
+ * AST node) that contains the field at `key`. It is **not** stored on
+ * the persisted `ParseIssue` — it's logged through the standard logger
+ * so log readers see the broader context, not just the leaf address.
  */
-export type ParseIssueBase = ParseErrorBase | ParseWarningBase;
+export type LogIssueArgs = ParseIssueInput & {
+    key: string;
+    stackTrail: StackTrail;
+    parent: unknown;
+    type: OasIssueType | GqlIssueType;
+};
 /**
- * Arguments for logging issues with a specific key.
+ * Arguments accepted by `ParseContext.logIssueNoKey` — same as
+ * {@link LogIssueArgs} without the `key` field (no inner trace).
  */
-export type LogIssueArgs = ParseIssueBase & {
-    /** Stack trail for tracking current parsing context */
+export type LogIssueNoKeyArgs = ParseIssueInput & {
     stackTrail: StackTrail;
-    /** The key where the issue occurred */
-    key: string;
-    /** The parent object containing the issue */
     parent: unknown;
-    /** The type of issue for categorization */
-    type: IssueType;
+    type: OasIssueType | GqlIssueType;
 };
 /**
- * Arguments for logging skipped values during parsing.
+ * Arguments accepted by `ParseContext.logSkippedFields`. The same
+ * shape works for both protocols — callers thread a `stackTrail`
+ * representing the parent (e.g. `[components, schemas, User]` for OAS
+ * or `[User]` for GQL); each skipped key is traced as a child.
+ *
+ * `parent` follows the same role as on {@link LogIssueArgs}: passed
+ * through to the logger so log readers see the surrounding object that
+ * carried the unrecognized fields.
  */
 export type LogSkippedValuesArgs = {
-    /** Stack trail for tracking current parsing context */
     stackTrail: StackTrail;
-    /** Record of skipped key-value pairs */
     skipped: Record<string, unknown>;
-    /** The parent object context */
     parent: unknown;
-    /** String description of the parent type */
     parentType: string;
+    /**
+     * Issue type to record. Defaults to `UNEXPECTED_PROPERTY` (OAS) at
+     * the call site convention, but GQL callers can pass a more
+     * specific category (e.g. `SKIPPED_FIELD_ARGUMENTS`).
+     */
+    type?: OasIssueType | GqlIssueType;
 };
-export type ParseContextType = {
-    oasDocument: OasDocument;
-    documentObject: OpenAPIV3.Document;
-    parse: (stackTrail: StackTrail) => OasDocument;
-    removeErroredItems: () => void;
-    registerRef: (stackTrail: StackTrail, $ref: string) => void;
-    registerRefError: (error: Error, $ref: string | undefined) => void;
-    logSkippedFields: (args: LogSkippedValuesArgs) => void;
-    logIssue: (args: LogIssueArgs) => void;
-    logIssueNoKey: (args: LogIssueNoKeyArgs) => void;
+/**
+ * Arguments accepted by `ParseContext.log` — the thin convenience for
+ * recording an issue at a pre-computed `location` string rather than
+ * threading a {@link StackTrail}.
+ *
+ * Use this for issues whose natural address isn't a tree position:
+ *
+ *   - Schema-level directive definitions (`@auth`, `@cost`) — flat
+ *     namespace, no parent type.
+ *   - Catch-all error paths where the parsed entity doesn't exist
+ *     yet (the parse threw before producing one).
+ *
+ * For tree-position issues (a field of a type, a parameter of an
+ * operation), prefer `logIssueNoKey` so the stack trail composes
+ * naturally with the surrounding traces.
+ *
+ * `location` is split on `:` to reconstruct a `StackTrail` for the
+ * underlying call, matching the protocol-neutral separator used
+ * elsewhere.
+ */
+export type LogAtArgs = ParseIssueInput & {
+    location: string;
+    /**
+     * Surrounding object for log context (optional — synthetic-location
+     * issues often have none). Forwarded to the logger; not stored on
+     * the persisted issue.
+     */
+    parent?: unknown;
+    type: OasIssueType | GqlIssueType;
+};
+/**
+ * Internal "post-protocol" issue input — what `ParseContext.logIssueAt`
+ * accepts. Both protocols funnel here after their surface-specific
+ * adapters compute the location and inject the `protocol` tag.
+ */
+export type LogIssueAtArgs = {
+    protocol: 'oas';
+    level: 'error';
+    type: OasIssueType;
+    location: string;
+    message: string;
+    cause?: unknown;
+} | {
+    protocol: 'oas';
+    level: 'warning';
+    type: OasIssueType;
+    location: string;
+    message: string;
+} | {
+    protocol: 'gql';
+    level: 'error';
+    type: GqlIssueType;
+    location: string;
+    message: string;
+    cause?: unknown;
+} | {
+    protocol: 'gql';
+    level: 'warning';
+    type: GqlIssueType;
+    location: string;
+    message: string;
+};
+/**
+ * Options accepted by the GQL parse phase. Passed through the
+ * `ParseContext` constructor's `options.gql` slot.
+ */
+export type GqlParseOptions = {
+    interfaceUnionSuffix?: string;
+    synthesizeInterfaceUnions?: boolean;
 };
 //# sourceMappingURL=parseTypes.d.ts.map

package/esm/context/parseTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseTypes.d.ts","sourceRoot":"","sources":["../../src/context/parseTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,8BAA8B;IAC9B,KAAK,EAAE,KAAK,CAAA;CACb,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;IACf,uDAAuD;IACvD,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2BAA2B;IAC3B,KAAK,EAAE,SAAS,CAAA;IAChB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,gBAAgB,CAAA;AAE9D;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG;IAC1C,uDAAuD;IACvD,UAAU,EAAE,UAAU,CAAA;IACtB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAA;IACf,2CAA2C;IAC3C,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,uDAAuD;IACvD,UAAU,EAAE,UAAU,CAAA;IACtB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,gCAAgC;IAChC,MAAM,EAAE,OAAO,CAAA;IACf,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,WAAW,CAAA;IACxB,cAAc,EAAE,SAAS,CAAC,QAAQ,CAAA;IAClC,KAAK,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,WAAW,CAAA;IAC9C,kBAAkB,EAAE,MAAM,IAAI,CAAA;IAC9B,WAAW,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3D,gBAAgB,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAA;IAClE,gBAAgB,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAA;IACtD,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAA;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAA;CACjD,CAAA"}
+{"version":3,"file":"parseTypes.d.ts","sourceRoot":"","sources":["../../src/context/parseTypes.ts"],"names":[],"mappings":"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"}

package/esm/context/parseTypes.js

@@ -1 +1,18 @@
+/**
+ * Type-only surface for {@link ParseContext}.
+ *
+ * Parser helpers (under `oas/...` and `parsers/graphql/...`) consume
+ * `ParseContextType` as the shape of the context they receive. By
+ * importing from this module — rather than from `ParseContext.ts`
+ * directly — they avoid pulling the runtime class into their import
+ * graph and break the type-level cycle through `toDocumentFieldsV3`.
+ *
+ * Everything here is `import type`-friendly: zero runtime exports.
+ *
+ * Mirror-image: the runtime class and the input transforms live in
+ * `ParseContext.ts`. Adding a new method to `ParseContext` doesn't
+ * require touching this file unless that method is exposed to parser
+ * helpers — `ParseContextType` is `ParseContext` (the whole class)
+ * aliased here.
+ */
 export {};

package/esm/context/tryParseAt.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared helper for "run a per-item parse inside a stack-trail trace,
+ * isolate failures, log an error issue and continue."
+ *
+ * Both protocols use this pattern at the boundary where a single bad
+ * input shouldn't abort the whole parse phase:
+ *
+ *   - OAS: `toSchemasV3`, `toOperationsV3`, `toResponseV3`,
+ *     `toParameterV3` each iterate a record / map and call the
+ *     per-item parser. A throw inside one item should isolate to that
+ *     item, log an `INVALID_<KIND>` issue, and let the rest of the
+ *     record continue.
+ *
+ *   - GQL: `parseGqlDocument` iterates the GraphQL type map and calls
+ *     `toObjectType` / `toInputType` / etc. per type. Same isolation
+ *     requirement.
+ *
+ * The helper threads the stack trail descent + try/catch + issue
+ * logging into one call so both surfaces share the failure-handling
+ * shape verbatim.
+ */
+import type { ParseContextType } from './parseTypes.js';
+import type { StackTrail } from './StackTrail.js';
+import type { OasIssueType } from './generateTypes.js';
+import type { GqlIssueType } from './ParseIssue.js';
+export type TryParseAtArgs<T> = {
+    /** Stack trail of the parent — child trace is pushed via `key`. */
+    stackTrail: StackTrail;
+    /** Trace key for this item (e.g. the schema name, operation method, type name). */
+    key: string;
+    /** Parse context. */
+    context: ParseContextType;
+    /**
+     * Issue type to log when the per-item parser throws. Use a
+     * protocol-appropriate value from `OasIssueType` (e.g.
+     * `'INVALID_SCHEMA'`) or `GqlIssueType` (e.g.
+     * `'INVALID_TYPE_DEFINITION'`).
+     */
+    type: OasIssueType | GqlIssueType;
+    /**
+     * Optional parent object — forwarded to the logger so log readers
+     * see the surrounding context for the failing item.
+     */
+    parent?: unknown;
+    /**
+     * Optional ref key under which to register a `registerRefError` so
+     * cross-references to this item can be pruned by
+     * `removeErroredItems`. OAS callers usually leave this undefined —
+     * `logIssueNoKey` auto-registers via `stackTrail.toStackRef()` when
+     * the trail is at a components position. GQL callers pass the type
+     * name explicitly.
+     */
+    refKey?: string;
+    /**
+     * The actual parser, invoked inside the child trace.
+     */
+    fn: (childStack: StackTrail) => T;
+};
+/**
+ * Run `fn(childStack)` inside `stackTrail.trace(key, ...)`. On throw:
+ *
+ *   - logs a `level: 'error'` issue at the child location with the
+ *     given `type` and the thrown value as `cause`
+ *   - registers a ref error if `refKey` is provided
+ *   - returns `undefined`
+ *
+ * On success, returns whatever `fn` returned.
+ */
+export declare const tryParseAt: <T>({ stackTrail, key, context, type, parent, refKey, fn }: TryParseAtArgs<T>) => T | undefined;
+//# sourceMappingURL=tryParseAt.d.ts.map

package/esm/context/tryParseAt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tryParseAt.d.ts","sourceRoot":"","sources":["../../src/context/tryParseAt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,mEAAmE;IACnE,UAAU,EAAE,UAAU,CAAA;IACtB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAA;IACX,qBAAqB;IACrB,OAAO,EAAE,gBAAgB,CAAA;IACzB;;;;;OAKG;IACH,IAAI,EAAE,YAAY,GAAG,YAAY,CAAA;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,EAAE,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,CAAC,CAAA;CAClC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,wDAQ3B,cAAc,CAAC,CAAC,CAAC,KAAG,CAAC,GAAG,SAoB1B,CAAA"}

package/esm/context/tryParseAt.js

@@ -0,0 +1,53 @@
+/**
+ * Shared helper for "run a per-item parse inside a stack-trail trace,
+ * isolate failures, log an error issue and continue."
+ *
+ * Both protocols use this pattern at the boundary where a single bad
+ * input shouldn't abort the whole parse phase:
+ *
+ *   - OAS: `toSchemasV3`, `toOperationsV3`, `toResponseV3`,
+ *     `toParameterV3` each iterate a record / map and call the
+ *     per-item parser. A throw inside one item should isolate to that
+ *     item, log an `INVALID_<KIND>` issue, and let the rest of the
+ *     record continue.
+ *
+ *   - GQL: `parseGqlDocument` iterates the GraphQL type map and calls
+ *     `toObjectType` / `toInputType` / etc. per type. Same isolation
+ *     requirement.
+ *
+ * The helper threads the stack trail descent + try/catch + issue
+ * logging into one call so both surfaces share the failure-handling
+ * shape verbatim.
+ */
+/**
+ * Run `fn(childStack)` inside `stackTrail.trace(key, ...)`. On throw:
+ *
+ *   - logs a `level: 'error'` issue at the child location with the
+ *     given `type` and the thrown value as `cause`
+ *   - registers a ref error if `refKey` is provided
+ *   - returns `undefined`
+ *
+ * On success, returns whatever `fn` returned.
+ */
+export const tryParseAt = ({ stackTrail, key, context, type, parent, refKey, fn }) => {
+    try {
+        return stackTrail.trace(key, childStack => fn(childStack));
+    }
+    catch (error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        if (refKey !== undefined) {
+            context.registerRefError(error, refKey);
+        }
+        stackTrail.trace(key, childStack => {
+            context.logIssueNoKey({
+                level: 'error',
+                stackTrail: childStack,
+                parent,
+                message: normalized.message,
+                cause: normalized,
+                type
+            });
+        });
+        return undefined;
+    }
+};