@skmtc/core 0.28.5 → 0.28.7

package/esm/dsl/webhook/types.d.ts

@@ -4,6 +4,7 @@ import type { ContentSettings } from '../ContentSettings.js';
 import type { GenerateContextType } from '../../context/generateTypes.js';
 import type { IdentifierType } from '../IdentifierType.js';
 import type { GeneratedValue } from '../GeneratedValue.js';
+import type { ProjectionOptionsArg } from '../../types/ProjectionOptions.js';
 /**
  * External constructor signature for a webhook projection class.
  *
@@ -14,11 +15,11 @@ import type { GeneratedValue } from '../GeneratedValue.js';
  * `operation` — webhooks are a distinct subject ({@link OasWebhook}),
  * so the field name and type differ even though the shape matches.
  */
-export type WebhookProjectionConstructorArgs<EnrichmentType = undefined> = {
+export type WebhookProjectionConstructorArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     context: GenerateContextType;
     settings: ContentSettings<EnrichmentType>;
     webhook: OasWebhook;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 export type TransformWebhookArgs = {
     context: GenerateContextType;
     webhook: OasWebhook;
@@ -55,33 +56,34 @@ export type ToWebhookMappingArgs = {
     variant: string;
 };
 /**
- * Arguments for a webhook projection's `toIdentifierName` — the pure,
- * cache-key-source half of the old `toIdentifier`.
+ * Arguments for a webhook projection's `toIdentifierName`. Fold `options` into the name when the output
+ * depends on them: definitions are cached by name and export path.
  */
-export type ToWebhookIdentifierNameArgs<EnrichmentType = undefined> = {
+export type ToWebhookIdentifierNameArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     webhook: OasWebhook;
     enrichments: EnrichmentType;
     /** Webhook variant the identifier should disambiguate (see {@link Variant}) */
     variant: string;
-};
-export type ToWebhookExportPathArgs<EnrichmentType = undefined> = {
+} & ProjectionOptionsArg<ProjectionOptions>;
+export type ToWebhookExportPathArgs<EnrichmentType = undefined, ProjectionOptions = undefined> = {
     webhook: OasWebhook;
     enrichments: EnrichmentType;
     /** Webhook variant the export path should disambiguate (see {@link Variant}) */
     variant: string;
-};
+} & ProjectionOptionsArg<ProjectionOptions>;
 /**
  * Static structural type of a webhook projection class.
  *
  * Captures both the instance side (`new(...) => V`) and the static side
  * (`id`, `toIdentifierName`, `toIdentifierType`, `toExportPath`,
  * `toEnrichments`). Passed as a type parameter to
- * `context.insertWebhook(...)`.
+ * `context.insertWebhook(...)`. `ProjectionOptions` is the caller options
+ * the class declares; the Drivers infer it from the constructor and statics.
  */
-export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefined> = {
+export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefined, ProjectionOptions = undefined> = {
     prototype: V;
 } & {
-    new ({ context, settings, webhook }: WebhookProjectionConstructorArgs<EnrichmentType>): V;
+    new ({ context, settings, webhook, options }: WebhookProjectionConstructorArgs<EnrichmentType, ProjectionOptions>): V;
     id: string;
     type: 'webhook';
     /**
@@ -92,7 +94,7 @@ export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefin
      */
     lang: Lang;
     /** Pure: the cache-key name. */
-    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType>) => string;
+    toIdentifierName: (args: ToWebhookIdentifierNameArgs<EnrichmentType, ProjectionOptions>) => string;
     /**
      * Context-aware, overridable: the non-`name` parts of the identifier,
      * derived from the webhook. The engine assembles
@@ -100,7 +102,7 @@ export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefin
      * ...toIdentifierType(webhook, context) })`.
      */
     toIdentifierType: (webhook: OasWebhook, context: GenerateContextType) => IdentifierType;
-    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType>) => string;
+    toExportPath: (args: ToWebhookExportPathArgs<EnrichmentType, ProjectionOptions>) => string;
     toEnrichments: ({ webhook, context }: ToWebhookEnrichmentsArgs) => EnrichmentType;
     /**
      * Family-level capability predicate, surfaced as a static by
@@ -111,4 +113,3 @@ export type WebhookProjection<V extends GeneratedValue, EnrichmentType = undefin
      */
     isSupported?: (args: IsSupportedWebhookArgs) => boolean;
 } & Function;
-//# sourceMappingURL=types.d.ts.map

package/esm/enrichments/EnrichmentAudit.d.ts

@@ -76,4 +76,3 @@ export declare class EnrichmentAudit {
  */
 export declare const hasVariantEnrichment: (block: unknown, variant: string) => boolean;
 export {};
-//# sourceMappingURL=EnrichmentAudit.d.ts.map

package/esm/enrichments/EnrichmentWarning.d.ts

@@ -69,4 +69,3 @@ export declare const enrichmentWarning: v.GenericSchema<EnrichmentWarning>;
  * segments visually distinct even when they contain dots or slashes.
  */
 export declare const formatEnrichmentPath: (path: readonly string[]) => string;
-//# sourceMappingURL=EnrichmentWarning.d.ts.map

package/esm/enrichments/findUnknownKeys.d.ts

@@ -37,4 +37,3 @@ export type UnknownKey = {
  * the subsequent `v.parse` throws on those as before.
  */
 export declare const findUnknownKeys: (schema: unknown, value: unknown) => UnknownKey[];
-//# sourceMappingURL=findUnknownKeys.d.ts.map

package/esm/enrichments/parseEnrichmentUmbrella.d.ts

@@ -60,4 +60,3 @@ type ParseEnrichmentUmbrellaArgs<EnrichmentType> = {
  */
 export declare const parseEnrichmentUmbrella: <EnrichmentType>({ context, generatorId, subjectSegments, schema }: ParseEnrichmentUmbrellaArgs<EnrichmentType>) => EnrichmentType;
 export {};
-//# sourceMappingURL=parseEnrichmentUmbrella.d.ts.map

package/esm/enrichments/readEnrichments.d.ts

@@ -66,4 +66,3 @@ export declare const toGeneratorEnrichment: <EnrichmentType>(context: Enrichment
  */
 export declare const toStackEnrichment: <EnrichmentType>(context: EnrichmentReadContext, schema: v.GenericSchema<EnrichmentType>) => EnrichmentType;
 export {};
-//# sourceMappingURL=readEnrichments.d.ts.map

package/esm/enrichments/toEnrichmentDescriptor.d.ts

@@ -139,4 +139,3 @@ export declare const toEnrichmentFields: (schema: v.GenericSchema | undefined) =
  * sits above it in the editor UI, since the variant axis is core-owned.
  */
 export declare const toEnrichmentDescriptor: (entry: EnrichmentSource) => EnrichmentDescriptor;
-//# sourceMappingURL=toEnrichmentDescriptor.d.ts.map

package/esm/enrichments/valibotShape.d.ts

@@ -48,4 +48,3 @@ export declare const unwrap: (schema: ValibotSchemaShape) => {
  * would silently break the lookup.
  */
 export declare const baseOf: (schema: ValibotSchemaShape) => ValibotSchemaShape;
-//# sourceMappingURL=valibotShape.d.ts.map

package/esm/enrichments/validateConfig.d.ts

@@ -57,4 +57,3 @@ export type EnrichmentValidationIssue = {
  * entry-like objects.
  */
 export declare const validateConfig: (enrichments: GeneratorEnrichments | undefined, sources: readonly EnrichmentSource[]) => EnrichmentValidationIssue[];
-//# sourceMappingURL=validateConfig.d.ts.map

package/esm/gql/_helpers/recordAppliedDirectives.d.ts

@@ -22,4 +22,3 @@ export type RecordAppliedDirectivesArgs = {
  * pure-runtime constructions, so we guard.
  */
 export declare const recordAppliedDirectives: ({ astNode, stackTrail, context }: RecordAppliedDirectivesArgs) => void;
-//# sourceMappingURL=recordAppliedDirectives.d.ts.map

package/esm/gql/_helpers/unwrapType.d.ts

@@ -36,4 +36,3 @@ export type UnwrappedType = {
  * peeled outermost first. This walks the chain and records the bookkeeping.
  */
 export declare const unwrapType: (type: GraphQLType) => UnwrappedType;
-//# sourceMappingURL=unwrapType.d.ts.map

package/esm/gql/argument/GqlArgument.d.ts

@@ -52,4 +52,3 @@ export declare class GqlArgument extends OasBase {
     readonly deprecationReason: string | undefined;
     constructor(fields: GqlArgumentFields, context?: ParseContextType);
 }
-//# sourceMappingURL=GqlArgument.d.ts.map

package/esm/gql/document/GqlDocument.d.ts

@@ -90,4 +90,3 @@ export declare class GqlDocument {
      */
     removeItem(stackTrail: StackTrail): unknown;
 }
-//# sourceMappingURL=GqlDocument.d.ts.map

package/esm/gql/document/parseGqlDocument.d.ts

@@ -30,4 +30,3 @@ export type ParseGqlDocumentArgs = {
 export declare const parseGqlDocument: ({ options, context, stackTrail }: ParseGqlDocumentArgs) => {
     fields: GqlDocumentFields;
 };
-//# sourceMappingURL=parseGqlDocument.d.ts.map

package/esm/gql/enum/toEnumType.d.ts

@@ -26,4 +26,3 @@ export type ToEnumTypeArgs = {
  * threaded for future diagnostic reporting; today the function is pure.
  */
 export declare const toEnumType: ({ enumType, nullable, context, stackTrail }: ToEnumTypeArgs) => OasString;
-//# sourceMappingURL=toEnumType.d.ts.map

package/esm/gql/field/toFieldSchema.d.ts

@@ -35,4 +35,3 @@ export type ToFieldSchemaArgs = {
  * `OasArray.nullable` and the inner schema's nullability.
  */
 export declare const toFieldSchema: ({ type, context, stackTrail }: ToFieldSchemaArgs) => OasSchema | OasRef<"schema">;
-//# sourceMappingURL=toFieldSchema.d.ts.map

package/esm/gql/input/toInputType.d.ts

@@ -25,4 +25,3 @@ export type ToInputTypeArgs = {
  * `default` slot when present.
  */
 export declare const toInputType: ({ inputType, context, stackTrail }: ToInputTypeArgs) => OasObject;
-//# sourceMappingURL=toInputType.d.ts.map

package/esm/gql/interface/toInterfaceUnion.d.ts

@@ -25,4 +25,3 @@ export type ToInterfaceUnionArgs = {
  * generators select whichever they prefer.
  */
 export declare const toInterfaceUnion: ({ interfaceType, context, stackTrail }: ToInterfaceUnionArgs) => OasUnion;
-//# sourceMappingURL=toInterfaceUnion.d.ts.map

package/esm/gql/object/toObjectType.d.ts

@@ -20,4 +20,3 @@ export type ToObjectTypeArgs = {
  * model so the user would otherwise have no signal that they exist.
  */
 export declare const toObjectType: ({ objectType, context, stackTrail }: ToObjectTypeArgs) => OasObject;
-//# sourceMappingURL=toObjectType.d.ts.map

package/esm/gql/operation/GqlOperation.d.ts

@@ -60,4 +60,3 @@ export declare class GqlOperation extends OasBase {
      */
     get identifier(): string;
 }
-//# sourceMappingURL=GqlOperation.d.ts.map

package/esm/gql/operation/synthesizeArgsObject.d.ts

@@ -19,4 +19,3 @@ import { OasObject } from '../../oas/object/Object.js';
  * generator-specific output assumptions.
  */
 export declare const synthesizeArgsObject: (operation: GqlOperation) => OasObject | undefined;
-//# sourceMappingURL=synthesizeArgsObject.d.ts.map

package/esm/gql/operation/toRootField.d.ts

@@ -23,4 +23,3 @@ export type ToRootFieldArgs = {
  * runs through {@link toFieldSchema} like any other field type.
  */
 export declare const toRootField: ({ rootKind, field, context, stackTrail }: ToRootFieldArgs) => GqlOperation;
-//# sourceMappingURL=toRootField.d.ts.map

package/esm/gql/registry/GqlRegistry.d.ts

@@ -67,4 +67,3 @@ export declare class GqlRegistry {
      */
     removeSchema(refName: RefName): boolean;
 }
-//# sourceMappingURL=GqlRegistry.d.ts.map

package/esm/gql/rootType/GqlRootTypes.d.ts

@@ -12,4 +12,3 @@ export type GqlRootTypes = {
     mutation?: RefName;
     subscription?: RefName;
 };
-//# sourceMappingURL=GqlRootTypes.d.ts.map

package/esm/gql/scalar/toScalarType.d.ts

@@ -30,4 +30,3 @@ export type ToScalarTypeArgs = {
  * without an API change.
  */
 export declare const toScalarType: ({ scalar, nullable, context, stackTrail }: ToScalarTypeArgs) => OasSchema;
-//# sourceMappingURL=toScalarType.d.ts.map

package/esm/gql/union/toUnionType.d.ts

@@ -21,4 +21,3 @@ export type ToUnionTypeArgs = {
  * pruned at the end of parsing.
  */
 export declare const toUnionType: ({ unionType, context, stackTrail }: ToUnionTypeArgs) => OasUnion;
-//# sourceMappingURL=toUnionType.d.ts.map

package/esm/helpers/ResultsLog.d.ts

@@ -198,4 +198,3 @@ export declare class ResultsLog {
      */
     toTree(): ResultsItem;
 }
-//# sourceMappingURL=ResultsLog.d.ts.map

package/esm/helpers/applyGeneratedSuffix.d.ts

@@ -40,4 +40,3 @@ export declare const applyGeneratedSuffix: (path: string, suffix: string) => str
  * flow to compute the owned name of a generated file.
  */
 export declare const removeGeneratedSuffix: (path: string, suffix: string) => string;
-//# sourceMappingURL=applyGeneratedSuffix.d.ts.map

package/esm/helpers/collateExamples.d.ts

@@ -167,4 +167,3 @@ type CollatedExampleArgs = {
  */
 export declare const collateExamples: ({ objectSchema, depth, seen }: CollatedExampleArgs) => unknown;
 export {};
-//# sourceMappingURL=collateExamples.d.ts.map

package/esm/helpers/formatNumber.d.ts

@@ -95,4 +95,3 @@
  */
 import "../_dnt.polyfills.js";
 export declare const formatNumber: (value: number, locales?: Intl.LocalesArgument) => string;
-//# sourceMappingURL=formatNumber.d.ts.map

package/esm/helpers/isEmpty.d.ts

@@ -3,4 +3,3 @@
  */
 import "../_dnt.polyfills.js";
 export declare const isEmpty: (value: object) => boolean;
-//# sourceMappingURL=isEmpty.d.ts.map

package/esm/helpers/isGeneratorName.d.ts

@@ -1,2 +1 @@
 export declare const isGeneratorName: (name: string) => boolean;
-//# sourceMappingURL=isGeneratorName.d.ts.map

package/esm/helpers/isImported.d.ts

@@ -79,4 +79,3 @@
  * ```
  */
 export declare const isImported: (pathOne: string, pathTwo: string) => boolean;
-//# sourceMappingURL=isImported.d.ts.map

package/esm/helpers/matchPackage.d.ts

@@ -0,0 +1,54 @@
+import type { ModulePackage } from '../types/Settings.js';
+/**
+ * Arguments for {@link matchPackage}.
+ */
+export type MatchPackageArgs = {
+    /** The artifact path to locate, in any spelling — see {@link toWorkspacePath} */
+    path: string;
+    /** `settings.packages`; roots may nest and may be listed in any order */
+    packages: ModulePackage[] | undefined;
+};
+/**
+ * The packages a path belongs to. Both carry a canonical `rootPath`.
+ *
+ * Package roots may nest — a nested root is a subpath export of the package
+ * around it — so one path can sit under several roots. They nest as a chain
+ * (each is an ancestor of the next), and the two ends of the chain answer the
+ * two questions a language package asks.
+ */
+export type PackageMatch = {
+    /**
+     * The widest root containing the path — the package. Decides whether an
+     * import is intra-package: every file in the package shares one alias,
+     * rooted here.
+     */
+    outermost: ModulePackage;
+    /**
+     * The narrowest root containing the path — the subpath. Its `moduleName` is
+     * what a file outside the package imports (`@acme/sdk/models`); its folders
+     * are what a Kotlin `package` directive starts after.
+     */
+    innermost: ModulePackage;
+};
+/**
+ * Finds the package roots containing `path`, or `undefined` when no root does.
+ *
+ * Roots are compared as folders in canonical spelling, so `./packages/sdk/`,
+ * `@/packages/sdk` and `packages/sdk` are one root, and the order of
+ * `packages` never matters. A root contains itself, so a directory import
+ * of a root (`packages/sdk/src/models`, its barrel) belongs to that root.
+ * `packages` is expected to have passed the {@link clientSettings} schema,
+ * which rejects duplicate roots and the workspace root.
+ *
+ * @example
+ * ```typescript
+ * const packages = [
+ *   { rootPath: 'packages/sdk/src', moduleName: '@acme/sdk' },
+ *   { rootPath: 'packages/sdk/src/models', moduleName: '@acme/sdk/models' }
+ * ]
+ * matchPackage({ path: '@/packages/sdk/src/models/User.ts', packages })
+ * // { outermost: { rootPath: 'packages/sdk/src', … }, innermost: { rootPath: 'packages/sdk/src/models', … } }
+ * matchPackage({ path: 'zod', packages }) // undefined
+ * ```
+ */
+export declare const matchPackage: ({ path, packages }: MatchPackageArgs) => PackageMatch | undefined;

package/esm/helpers/matchPackage.js

@@ -0,0 +1,35 @@
+import { isUnderRoot, toWorkspacePath } from './toWorkspacePath.js';
+/**
+ * Finds the package roots containing `path`, or `undefined` when no root does.
+ *
+ * Roots are compared as folders in canonical spelling, so `./packages/sdk/`,
+ * `@/packages/sdk` and `packages/sdk` are one root, and the order of
+ * `packages` never matters. A root contains itself, so a directory import
+ * of a root (`packages/sdk/src/models`, its barrel) belongs to that root.
+ * `packages` is expected to have passed the {@link clientSettings} schema,
+ * which rejects duplicate roots and the workspace root.
+ *
+ * @example
+ * ```typescript
+ * const packages = [
+ *   { rootPath: 'packages/sdk/src', moduleName: '@acme/sdk' },
+ *   { rootPath: 'packages/sdk/src/models', moduleName: '@acme/sdk/models' }
+ * ]
+ * matchPackage({ path: '@/packages/sdk/src/models/User.ts', packages })
+ * // { outermost: { rootPath: 'packages/sdk/src', … }, innermost: { rootPath: 'packages/sdk/src/models', … } }
+ * matchPackage({ path: 'zod', packages }) // undefined
+ * ```
+ */
+export const matchPackage = ({ path, packages = [] }) => {
+    // Every root here contains the same path, so the roots nest: each is a
+    // prefix of the next. Ordering by length is therefore ordering by depth,
+    // outermost first.
+    const containing = packages
+        .map(({ rootPath, moduleName }) => ({ rootPath: toWorkspacePath(rootPath), moduleName }))
+        .filter(modulePackage => isUnderRoot({ path, rootPath: modulePackage.rootPath }))
+        .sort((a, b) => a.rootPath.length - b.rootPath.length);
+    if (containing.length === 0) {
+        return undefined;
+    }
+    return { outermost: containing[0], innermost: containing[containing.length - 1] };
+};

package/esm/helpers/naming.d.ts

@@ -70,4 +70,3 @@ export declare const toArgsName: (operation: OasOperation) => string;
  * ```
  */
 export declare const toMethodVerb: (method: Method) => string;
-//# sourceMappingURL=naming.d.ts.map

package/esm/helpers/nearestKey.d.ts

@@ -15,4 +15,3 @@
  * `undefined` — a key that exists needs no suggestion.
  */
 export declare const nearestKey: (target: string, candidates: Iterable<string>) => string | undefined;
-//# sourceMappingURL=nearestKey.d.ts.map

package/esm/helpers/parseModuleName.d.ts

@@ -180,4 +180,3 @@ export type ParsedModuleName = {
  * ```
  */
 export declare const parseModuleName: (moduleName: string) => ParsedModuleName;
-//# sourceMappingURL=parseModuleName.d.ts.map

package/esm/helpers/refFns.d.ts

@@ -169,4 +169,3 @@ export declare const isRef: (value: unknown) => value is Ref;
  */
 export declare const toGetRef: (oasDocument: OpenAPIV3.Document) => ({ $ref }: ReferenceObject) => OpenAPIV3.SchemaObject;
 export {};
-//# sourceMappingURL=refFns.d.ts.map

package/esm/helpers/strings.d.ts

@@ -124,4 +124,3 @@ type CamelCaseOptions = {
  */
 export declare const camelCase: (str: string, { upperFirst, retainUnderscores }?: CamelCaseOptions) => string;
 export {};
-//# sourceMappingURL=strings.d.ts.map

package/esm/helpers/toResolvedArtifactPath.d.ts

@@ -1,61 +1,10 @@
 /**
- * @fileoverview Artifact Path Resolution Utilities for SKMTC Core
+ * Resolves an artifact's destination path onto `basePath`.
  *
- * This module provides utilities for resolving file paths for generated artifacts
- * within the SKMTC code generation pipeline. It handles the complexities of path
- * resolution, ensuring that generated files are placed in the correct locations
- * relative to base directories and project structures.
- *
- * The path resolution system supports both absolute and relative paths,
- * cross-platform compatibility, and proper handling of nested directory
- * structures for organized code generation output.
- *
- * ## Key Features
- *
- * - **Cross-Platform Compatibility**: Works correctly on Windows, macOS, and Linux
- * - **Relative Path Resolution**: Proper handling of relative paths with base directories
- * - **Absolute Path Support**: Direct support for absolute destination paths
- * - **Directory Creation**: Safe directory creation for nested path structures
- * - **Path Normalization**: Consistent path formatting across different systems
- *
- * @example Basic path resolution
- * ```typescript
- * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
- *
- * // Resolve relative path with base directory
- * const resolvedPath = toResolvedArtifactPath({
- *   basePath: '/project/src',
- *   destinationPath: './generated/UserApi.ts'
- * });
- *
- * console.log(resolvedPath); // '/project/src/generated/UserApi.ts'
- * ```
- *
- * @example Absolute path handling
- * ```typescript
- * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
- *
- * // Absolute paths are returned as-is
- * const absolutePath = toResolvedArtifactPath({
- *   basePath: '/project/src',
- *   destinationPath: '/absolute/path/to/UserApi.ts'
- * });
- *
- * console.log(absolutePath); // '/absolute/path/to/UserApi.ts'
- * ```
- *
- * @example Working without base path
- * ```typescript
- * import { toResolvedArtifactPath } from '@skmtc/core/toResolvedArtifactPath';
- *
- * // When basePath is undefined, returns the destination path
- * const path = toResolvedArtifactPath({
- *   basePath: undefined,
- *   destinationPath: './UserApi.ts'
- * });
- *
- * console.log(path); // './UserApi.ts'
- * ```
+ * `destinationPath` is a workspace path in any spelling
+ * ({@link toWorkspacePath}) — `@/models/User.ts` as a generator wrote it,
+ * or `./models/User.ts` — and is always joined onto `basePath`; there is no
+ * absolute-path escape.
  *
  * @module toResolvedArtifactPath
  */
@@ -73,145 +22,16 @@ type ToResolvedArtifactPathArgs = {
     destinationPath: string;
 };
 /**
- * Resolves artifact destination paths relative to a base directory.
- *
- * This utility function combines a base path with a destination path to create
- * the final resolved file path for generated artifacts. It handles special path
- * prefixes (like '@/') and provides sensible defaults when no base path is specified.
- *
- * The function is used throughout the rendering pipeline to determine the final
- * file system locations for generated code artifacts, ensuring consistent path
- * resolution across different operating systems and deployment scenarios.
- *
- * @param args - Path resolution configuration
- * @param args.basePath - Base directory path (defaults to './' if undefined)
- * @param args.destinationPath - Destination path for the artifact
- * @returns The resolved absolute or relative path for the artifact
- *
- * @example Basic path resolution
- * ```typescript
- * import { toResolvedArtifactPath } from '@skmtc/core';
- *
- * // With explicit base path
- * const resolved1 = toResolvedArtifactPath({
- *   basePath: './src/generated',
- *   destinationPath: 'models/User.ts'
- * });
- * console.log(resolved1); // './src/generated/models/User.ts'
+ * Joins `destinationPath` (canonicalized) onto `basePath`, or onto `./` when
+ * `basePath` is undefined.
  *
- * // With undefined base path (uses default)
- * const resolved2 = toResolvedArtifactPath({
- *   basePath: undefined,
- *   destinationPath: 'types.ts'
- * });
- * console.log(resolved2); // './types.ts'
- * ```
- *
- * @example Special path prefix handling
- * ```typescript
- * // '@/' prefix gets stripped and resolved relative to base
- * const resolved = toResolvedArtifactPath({
- *   basePath: './output',
- *   destinationPath: '@/api/models.ts'
- * });
- * console.log(resolved); // './output/api/models.ts'
- *
- * // Regular paths work normally
- * const normal = toResolvedArtifactPath({
- *   basePath: './build',
- *   destinationPath: 'components/Button.tsx'
- * });
- * console.log(normal); // './build/components/Button.tsx'
- * ```
- *
- * @example Cross-platform path resolution
- * ```typescript
- * // Works consistently across platforms
- * const windowsPath = toResolvedArtifactPath({
- *   basePath: 'C:\\projects\\app\\dist',
- *   destinationPath: 'utils/helpers.js'
- * });
- *
- * const unixPath = toResolvedArtifactPath({
- *   basePath: '/home/user/projects/app/dist',
- *   destinationPath: 'utils/helpers.js'
- * });
- * ```
- *
- * @example Usage in file generation
- * ```typescript
- * class ArtifactWriter {
- *   writeArtifact(
- *     content: string,
- *     destination: string,
- *     baseDir?: string
- *   ) {
- *     const resolvedPath = toResolvedArtifactPath({
- *       basePath: baseDir,
- *       destinationPath: destination
- *     });
- *
- *     console.log(`Writing to: ${resolvedPath}`);
- *     return Deno.writeTextFile(resolvedPath, content);
- *   }
- * }
- *
- * const writer = new ArtifactWriter();
- * await writer.writeArtifact(
- *   'export const greeting = "Hello";',
- *   '@/constants.ts',
- *   './src/generated'
- * );
- * // Writes to: ./src/generated/constants.ts
- * ```
- *
- * @example Integration with rendering pipeline
- * ```typescript
- * class FileRenderer {
- *   renderFiles(
- *     files: Map<string, File>,
- *     outputDir: string
- *   ): Record<string, string> {
- *     const artifacts: Record<string, string> = {};
- *
- *     for (const [destPath, file] of files) {
- *       const resolvedPath = toResolvedArtifactPath({
- *         basePath: outputDir,
- *         destinationPath: destPath
- *       });
- *
- *       artifacts[resolvedPath] = file.toString();
- *     }
- *
- *     return artifacts;
- *   }
- * }
- * ```
- *
- * @example Dynamic base path resolution
+ * @example
  * ```typescript
- * function resolveForEnvironment(
- *   destination: string,
- *   env: 'development' | 'production'
- * ): string {
- *   const basePaths = {
- *     development: './dev-output',
- *     production: './dist'
- *   };
- *
- *   return toResolvedArtifactPath({
- *     basePath: basePaths[env],
- *     destinationPath: destination
- *   });
- * }
- *
- * const devPath = resolveForEnvironment('api.ts', 'development');
- * const prodPath = resolveForEnvironment('api.ts', 'production');
- *
- * console.log(devPath);  // './dev-output/api.ts'
- * console.log(prodPath); // './dist/api.ts'
+ * toResolvedArtifactPath({ basePath: './output', destinationPath: '@/api/models.ts' })
+ * // 'output/api/models.ts'
+ * toResolvedArtifactPath({ basePath: undefined, destinationPath: 'types.ts' })
+ * // 'types.ts'
  * ```
  */
 export declare const toResolvedArtifactPath: ({ basePath, destinationPath }: ToResolvedArtifactPathArgs) => string;
 export {};
-//# sourceMappingURL=toResolvedArtifactPath.d.ts.map