@skmtc/core 0.28.6 → 0.29.0

package/esm/helpers/normalizeWorkspacePath.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Options for {@link normalizeWorkspacePath} and {@link toNormalizedWorkspacePath}.
+ */
+export type NormalizeWorkspacePathOptions = {
+    /** Names the generator in the error when the path is rejected. */
+    generatorId?: string;
+};
+/**
+ * Whether a path contains a `..` parent-reference segment. `..` is a parent
+ * reference only as a whole segment — a directory name that merely contains
+ * dots is not flagged.
+ */
+export declare const hasParentSegment: (path: string) => boolean;
+/**
+ * Whether a path is absolute on either host: a POSIX root, a Windows drive
+ * (`C:\`, `C:/`) or a UNC share. Checked on every host, so a client.json
+ * written on Windows is rejected the same way on Linux.
+ */
+export declare const isAbsolutePath: (path: string) => boolean;
+/**
+ * Whether `path` is spelled from the workspace root — `@/`, `./`, a bare
+ * leading `/`, or their Windows forms. An artifact path, never a bare
+ * module specifier such as `zod` or `@tanstack/query`.
+ */
+export declare const hasWorkspaceAnchor: (path: string) => boolean;
+/**
+ * Whether `path` can name a file below `basePath`: not a Windows drive or
+ * UNC path, no `..` segment, and not `basePath` itself. The non-throwing
+ * form of {@link normalizeWorkspacePath}'s checks, for schema validation
+ * and for comparing a module specifier against a file path.
+ */
+export declare const isValidWorkspacePath: (path: string) => boolean;
+/**
+ * The path relative to `basePath`, normalized and with no anchor:
+ * what {@link normalizeWorkspacePath} writes after `@/`, and what
+ * {@link toResolvedArtifactPath} joins onto `basePath`.
+ *
+ * Throws when the path cannot name a file below `basePath`: a Windows
+ * drive or UNC path, a `..` segment (checked as a whole segment before
+ * normalization, so it is never resolved), or a path naming `basePath`
+ * itself (`@/`, `@`, `./`, `.`, `/`, ``).
+ */
+export declare const toNormalizedWorkspacePath: (path: string, { generatorId }?: NormalizeWorkspacePathOptions) => string;
+/**
+ * The one spelling of a workspace path — an export path or a destination
+ * path: `@/` followed by a POSIX path relative to `basePath`.
+ *
+ * A workspace path is a logical path inside the workspace, never a
+ * filesystem path, so it reads the same on every host. A generator may
+ * return one as `@/types/User.ts`, `./types/User.ts`, `/types/User.ts`,
+ * `types/User.ts`, or with Windows separators; the engine stores this form
+ * and nothing else, so file-map keys, import modules and the ejected lookup
+ * always agree. The result is a fixed point.
+ *
+ * Throws in the cases {@link toNormalizedWorkspacePath} throws.
+ *
+ * @example
+ * ```typescript
+ * normalizeWorkspacePath('@\\types\\User.ts') // '@/types/User.ts'
+ * normalizeWorkspacePath('./types/User.ts')   // '@/types/User.ts'
+ * normalizeWorkspacePath('../User.ts')        // throws
+ * ```
+ */
+export declare const normalizeWorkspacePath: (path: string, options?: NormalizeWorkspacePathOptions) => string;

package/esm/helpers/normalizeWorkspacePath.js

@@ -0,0 +1,98 @@
+import { normalize } from '../deps/jsr.io/@std/path/1.1.6/posix/normalize.js';
+import { isAbsolute as isPosixAbsolute } from '../deps/jsr.io/@std/path/1.1.6/posix/is_absolute.js';
+import { isAbsolute as isWindowsAbsolute } from '../deps/jsr.io/@std/path/1.1.6/windows/is_absolute.js';
+import { toWorkspacePath } from './toWorkspacePath.js';
+/**
+ * Whether a path contains a `..` parent-reference segment. `..` is a parent
+ * reference only as a whole segment — a directory name that merely contains
+ * dots is not flagged.
+ */
+export const hasParentSegment = (path) => path.split(/[/\\]/).some(segment => segment === '..');
+/**
+ * Whether a path is absolute on either host: a POSIX root, a Windows drive
+ * (`C:\`, `C:/`) or a UNC share. Checked on every host, so a client.json
+ * written on Windows is rejected the same way on Linux.
+ */
+export const isAbsolutePath = (path) => isPosixAbsolute(path.replaceAll('\\', '/')) || isWindowsAbsolute(path);
+/**
+ * A Windows drive path (`C:\`, `C:/`) or a UNC path (`\\server\share`):
+ * the two absolute forms that can never be relative to `basePath`. A bare
+ * leading `/` is not one — it is an anchor spelling of the workspace root.
+ */
+const isDriveOrUncPath = (path) => /^[A-Za-z]:[\\/]/.test(path) || path.startsWith('\\\\');
+/**
+ * Whether `path` is spelled from the workspace root — `@/`, `./`, a bare
+ * leading `/`, or their Windows forms. An artifact path, never a bare
+ * module specifier such as `zod` or `@tanstack/query`.
+ */
+export const hasWorkspaceAnchor = (path) => /^(@[\\/]|\.[\\/]|[\\/])/.test(path);
+/**
+ * Whether `path` can name a file below `basePath`: not a Windows drive or
+ * UNC path, no `..` segment, and not `basePath` itself. The non-throwing
+ * form of {@link normalizeWorkspacePath}'s checks, for schema validation
+ * and for comparing a module specifier against a file path.
+ */
+export const isValidWorkspacePath = (path) => !isDriveOrUncPath(path) && !hasParentSegment(path) && toBody(path) !== '';
+/**
+ * The path relative to `basePath`, normalized and with no anchor:
+ * what {@link normalizeWorkspacePath} writes after `@/`, and what
+ * {@link toResolvedArtifactPath} joins onto `basePath`.
+ *
+ * Throws when the path cannot name a file below `basePath`: a Windows
+ * drive or UNC path, a `..` segment (checked as a whole segment before
+ * normalization, so it is never resolved), or a path naming `basePath`
+ * itself (`@/`, `@`, `./`, `.`, `/`, ``).
+ */
+export const toNormalizedWorkspacePath = (path, { generatorId } = {}) => {
+    const reject = (reason) => {
+        const source = generatorId ? ` returned by generator '${generatorId}'` : '';
+        throw new Error(`Path '${path}'${source} ${reason}`);
+    };
+    if (isDriveOrUncPath(path)) {
+        return reject('is a Windows drive or UNC path; a workspace path is relative to basePath');
+    }
+    if (hasParentSegment(path)) {
+        return reject('contains a ".." segment; a workspace path is a forward path below basePath');
+    }
+    const body = toBody(path);
+    if (body === '') {
+        return reject('names basePath itself; a workspace path names a file below it');
+    }
+    return body;
+};
+/**
+ * The one spelling of a workspace path — an export path or a destination
+ * path: `@/` followed by a POSIX path relative to `basePath`.
+ *
+ * A workspace path is a logical path inside the workspace, never a
+ * filesystem path, so it reads the same on every host. A generator may
+ * return one as `@/types/User.ts`, `./types/User.ts`, `/types/User.ts`,
+ * `types/User.ts`, or with Windows separators; the engine stores this form
+ * and nothing else, so file-map keys, import modules and the ejected lookup
+ * always agree. The result is a fixed point.
+ *
+ * Throws in the cases {@link toNormalizedWorkspacePath} throws.
+ *
+ * @example
+ * ```typescript
+ * normalizeWorkspacePath('@\\types\\User.ts') // '@/types/User.ts'
+ * normalizeWorkspacePath('./types/User.ts')   // '@/types/User.ts'
+ * normalizeWorkspacePath('../User.ts')        // throws
+ * ```
+ */
+export const normalizeWorkspacePath = (path, options = {}) => `@/${toNormalizedWorkspacePath(path, options)}`;
+/**
+ * Separator swap, then every anchor spelling goes (`@/`, `./`, a leading
+ * `/` — {@link toWorkspacePath}), then POSIX normalize of what is left so
+ * `@//x` and `@/./x` collapse. The anchor goes first so normalize can
+ * never fold it into a name (`@/.` is the root, not a file called `@`).
+ * The root in any spelling is the empty string.
+ */
+const toBody = (path) => {
+    const stripped = toWorkspacePath(path.replaceAll('\\', '/'));
+    if (stripped === '') {
+        return '';
+    }
+    const normalized = normalize(stripped);
+    return normalized === '.' ? '' : normalized;
+};

package/esm/helpers/toResolvedArtifactPath.d.ts

@@ -2,9 +2,11 @@
  * Resolves an artifact's destination path onto `basePath`.
  *
  * `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.
+ * ({@link toNormalizedWorkspacePath}) — `@/models/User.ts` as a generator
+ * wrote it, `./models/User.ts`, or with Windows separators — and is always
+ * joined onto `basePath` with forward slashes, so the artifact key reads
+ * the same on every host. A `..` segment or an absolute path is refused:
+ * every artifact lands below `basePath`, whoever writes it.
  *
  * @module toResolvedArtifactPath
  */
@@ -22,8 +24,9 @@ type ToResolvedArtifactPathArgs = {
     destinationPath: string;
 };
 /**
- * Joins `destinationPath` (canonicalized) onto `basePath`, or onto `./` when
- * `basePath` is undefined.
+ * Joins `destinationPath` (canonicalized) onto `basePath`, or onto the
+ * workspace root when `basePath` is undefined. Throws when
+ * `destinationPath` cannot name a file below `basePath`.
  *
  * @example
  * ```typescript

package/esm/helpers/toResolvedArtifactPath.js

@@ -2,18 +2,22 @@
  * Resolves an artifact's destination path onto `basePath`.
  *
  * `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.
+ * ({@link toNormalizedWorkspacePath}) — `@/models/User.ts` as a generator
+ * wrote it, `./models/User.ts`, or with Windows separators — and is always
+ * joined onto `basePath` with forward slashes, so the artifact key reads
+ * the same on every host. A `..` segment or an absolute path is refused:
+ * every artifact lands below `basePath`, whoever writes it.
  *
  * @module toResolvedArtifactPath
  */
 import "../_dnt.polyfills.js";
-import { join } from '../deps/jsr.io/@std/path/1.1.6/join.js';
+import { join } from '../deps/jsr.io/@std/path/1.1.6/posix/join.js';
+import { toNormalizedWorkspacePath } from './normalizeWorkspacePath.js';
 import { toWorkspacePath } from './toWorkspacePath.js';
 /**
- * Joins `destinationPath` (canonicalized) onto `basePath`, or onto `./` when
- * `basePath` is undefined.
+ * Joins `destinationPath` (canonicalized) onto `basePath`, or onto the
+ * workspace root when `basePath` is undefined. Throws when
+ * `destinationPath` cannot name a file below `basePath`.
  *
  * @example
  * ```typescript
@@ -24,5 +28,5 @@ import { toWorkspacePath } from './toWorkspacePath.js';
  * ```
  */
 export const toResolvedArtifactPath = ({ basePath, destinationPath }) => {
-    return join(basePath ?? './', toWorkspacePath(destinationPath));
+    return join(toWorkspacePath(basePath ?? ''), toNormalizedWorkspacePath(destinationPath));
 };

package/esm/helpers/toWorkspacePath.d.ts

@@ -7,9 +7,9 @@
  * config and examples write it as `./`, and std `normalize` — applied to
  * `File.path` by the drivers — strips `./` but leaves `@/` alone. Anything
  * that compares paths from more than one of those sources (package matching,
- * on-disk resolution) must see all spellings as equal: every leading `@/` or
- * `./` goes, a trailing `/` goes, a Windows `\` is a `/`, and the workspace
- * root itself (`@/`, `./`, `.`, ``) is the empty string. The result is a fixed
+ * on-disk resolution) must see all spellings as equal: every leading `@/`,
+ * `./` or bare `/` goes, a trailing `/` goes, a Windows `\` is a `/`, and the
+ * workspace root itself (`@/`, `@`, `./`, `.`, `/`, ``) is the empty string. The result is a fixed
  * point: canonicalizing it again changes nothing.
  *
  * The `@/` stripped here is Skmtc's **workspace root** — the prefix

package/esm/helpers/toWorkspacePath.js

@@ -7,9 +7,9 @@
  * config and examples write it as `./`, and std `normalize` — applied to
  * `File.path` by the drivers — strips `./` but leaves `@/` alone. Anything
  * that compares paths from more than one of those sources (package matching,
- * on-disk resolution) must see all spellings as equal: every leading `@/` or
- * `./` goes, a trailing `/` goes, a Windows `\` is a `/`, and the workspace
- * root itself (`@/`, `./`, `.`, ``) is the empty string. The result is a fixed
+ * on-disk resolution) must see all spellings as equal: every leading `@/`,
+ * `./` or bare `/` goes, a trailing `/` goes, a Windows `\` is a `/`, and the
+ * workspace root itself (`@/`, `@`, `./`, `.`, `/`, ``) is the empty string. The result is a fixed
  * point: canonicalizing it again changes nothing.
  *
  * The `@/` stripped here is Skmtc's **workspace root** — the prefix
@@ -29,9 +29,9 @@
 export const toWorkspacePath = (path) => {
     const withoutAnchor = path
         .replaceAll('\\', '/')
-        .replace(/^(?:@\/|\.\/)+/, '')
+        .replace(/^(?:@\/|\.\/|\/)+/, '')
         .replace(/\/+$/, '');
-    return withoutAnchor === '.' ? '' : withoutAnchor;
+    return withoutAnchor === '.' || withoutAnchor === '@' ? '' : withoutAnchor;
 };
 /**
  * `path` is `rootPath` itself or a file or folder below it. A root is a

package/esm/mod.d.ts

@@ -118,6 +118,7 @@ export * from './helpers/strings.js';
 export * from './helpers/parseModuleName.js';
 export * from './helpers/toResolvedArtifactPath.js';
 export * from './helpers/toWorkspacePath.js';
+export * from './helpers/normalizeWorkspacePath.js';
 export * from './helpers/matchPackage.js';
 export * from './helpers/withVariant.js';
 export * from './helpers/toVariantList.js';

package/esm/mod.js

@@ -118,6 +118,7 @@ export * from './helpers/strings.js';
 export * from './helpers/parseModuleName.js';
 export * from './helpers/toResolvedArtifactPath.js';
 export * from './helpers/toWorkspacePath.js';
+export * from './helpers/normalizeWorkspacePath.js';
 export * from './helpers/matchPackage.js';
 export * from './helpers/withVariant.js';
 export * from './helpers/toVariantList.js';

package/esm/types/Settings.js

@@ -52,13 +52,8 @@ import "../_dnt.polyfills.js";
 import { generatorEnrichments } from './Enrichments.js';
 import * as v from 'valibot';
 import { method } from './Method.js';
+import { hasParentSegment, isAbsolutePath, isValidWorkspacePath } from '../helpers/normalizeWorkspacePath.js';
 import { toWorkspacePath } from '../helpers/toWorkspacePath.js';
-/**
- * Whether a relative path contains a `..` parent-reference segment.
- * `..` is a parent reference only as a whole path segment — a
- * directory name that merely contains dots is not flagged.
- */
-const hasParentSegment = (path) => path.split(/[/\\]/).some(segment => segment === '..');
 /**
  * Valibot schema for {@link ModulePackage}.
  *
@@ -175,7 +170,9 @@ export const anchorsSettings = v.object({
     out: v.optional(v.string())
 });
 export const clientSettings = v.object({
-    basePath: v.optional(v.string()),
+    basePath: v.optional(v.pipe(v.string(), v.check(basePath => !isAbsolutePath(basePath), 'basePath must be relative to the SKMTC root (the directory containing .skmtc/); ' +
+        'absolute paths are not supported because generated output is always written under it'), v.check(basePath => !hasParentSegment(basePath), 'basePath must be a forward path with no ".." segments — it is the on-disk anchor ' +
+        'every generated file sits below'))),
     schemaSource: v.optional(v.string()),
     packages: v.optional(modulePackages),
     enrichments: v.optional(generatorEnrichments),
@@ -185,7 +182,8 @@ export const clientSettings = v.object({
     inputDirs: v.optional(v.array(v.string())),
     formatter: v.optional(v.string()),
     generatedSuffix: v.optional(v.string()),
-    ejected: v.optional(v.array(v.string()))
+    ejected: v.optional(v.array(v.pipe(v.string(), v.check(isValidWorkspacePath, 'settings.ejected entries are export paths: a forward path below basePath, ' +
+        'with no ".." segment and not a Windows drive or UNC path'))))
 });
 /**
  * Valibot schema for validating SKMTC client configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.28.6",
+  "version": "0.29.0",
   "description": "Skmtc is a declarative code generation framework",
   "keywords": [
     "openapi",

package/script/context/GenerateContext.js

@@ -16,7 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 var _GenerateContext_instances, _GenerateContext_files, _GenerateContext_previews, _GenerateContext_captureChannel, _GenerateContext_enrichmentAudit, _GenerateContext_reportSkippedEnrichment, _GenerateContext_schemaRefNames, _GenerateContext_subjectDefaults, _GenerateContext_runOasOperationGenerator, _GenerateContext_runWebhookGenerator, _GenerateContext_runGqlOperationGenerator, _GenerateContext_runModelGenerator, _GenerateContext_addPreview, _GenerateContext_toContentSettingsExportPath, _GenerateContext_ejectedBySuffixedPath_get, _GenerateContext_ejectedBySuffixedPathCache, _GenerateContext_findContainer, _GenerateContext_toContainer;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toModelSource = exports.toGqlOperationSource = exports.toWebhookSource = exports.toOasOperationSource = exports.GenerateContext = void 0;
-const normalize_js_1 = require("../deps/jsr.io/@std/path/1.1.6/normalize.js");
+const normalizeWorkspacePath_js_1 = require("../helpers/normalizeWorkspacePath.js");
 const applyGeneratedSuffix_js_1 = require("../helpers/applyGeneratedSuffix.js");
 const OasOperationDriver_js_1 = require("../dsl/operation/oas/OasOperationDriver.js");
 const WebhookDriver_js_1 = require("../dsl/webhook/WebhookDriver.js");
@@ -449,7 +449,7 @@ class GenerateContext {
      * language-constructed file, use {@link addFile}.
      */
     getFile(filePath) {
-        return __classPrivateFieldGet(this, _GenerateContext_files, "f").get((0, normalize_js_1.normalize)(filePath));
+        return __classPrivateFieldGet(this, _GenerateContext_files, "f").get((0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(filePath));
     }
     /**
      * Read-only view of every file generated so far, keyed by (normalized)
@@ -473,7 +473,7 @@ class GenerateContext {
      * (`context.getFile(path) ?? context.addFile(new KtFile({ … }))`).
      */
     addFile(file) {
-        const normalizedPath = (0, normalize_js_1.normalize)(file.path);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(file.path);
         if (__classPrivateFieldGet(this, _GenerateContext_files, "f").has(normalizedPath)) {
             throw new Error(`File already exists: ${normalizedPath}`);
         }
@@ -487,7 +487,7 @@ class GenerateContext {
      * @param args - Registration arguments with destination path and JSON content
      */
     registerJson({ destinationPath, json }) {
-        const normalizedPath = (0, normalize_js_1.normalize)(destinationPath);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath);
         let currentFile = this.getFile(normalizedPath);
         if (!currentFile) {
             currentFile = new JsonFile_js_1.JsonFile({ path: normalizedPath, content: {} });
@@ -506,7 +506,7 @@ class GenerateContext {
      * @experimental This method is experimental and may change in future versions
      */
     registerMarkdown({ destinationPath, markdown }) {
-        const normalizedPath = (0, normalize_js_1.normalize)(destinationPath);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath);
         let currentFile = this.getFile(normalizedPath);
         if (!currentFile) {
             currentFile = new MarkdownFile_js_1.MarkdownFile({ path: normalizedPath, content: '' });
@@ -527,7 +527,7 @@ class GenerateContext {
      * @mutates this.files
      */
     register({ imports = [], reExports = [], definitions, custom, destinationPath, into }) {
-        const normalizedPath = (0, normalize_js_1.normalize)(destinationPath);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath);
         const currentFile = this.getFile(normalizedPath);
         // `register` never creates files — it speaks pure data and the engine
         // never names a file class. Callers pre-create the destination file
@@ -635,7 +635,7 @@ class GenerateContext {
         // the use site (same ephemeral read the Drivers make) — pre-creates
         // the destination file caller-side, and stores via the pure-data
         // `register`.
-        const normalizedPath = (0, normalize_js_1.normalize)(destinationPath);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath);
         if (!this.getFile(normalizedPath)) {
             this.addFile(projection.lang.createFile({ path: normalizedPath, settings: this.settings }));
         }
@@ -702,7 +702,7 @@ class GenerateContext {
                     enrichments,
                     variant,
                     options
-                })),
+                }), args.projection.id),
                 enrichments,
                 variant
             });
@@ -730,7 +730,7 @@ class GenerateContext {
                     enrichments,
                     variant,
                     options
-                })),
+                }), args.projection.id),
             enrichments,
             variant
         });
@@ -763,7 +763,7 @@ class GenerateContext {
                 enrichments,
                 variant,
                 options
-            })),
+            }), args.projection.id),
             enrichments,
             variant
         });
@@ -785,7 +785,7 @@ class GenerateContext {
                 name: projection.toIdentifierName({ refName, enrichments, variant, options }),
                 ...projection.toIdentifierType(refName, this)
             }),
-            exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, projection.toExportPath({ refName, enrichments, variant, options })),
+            exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, projection.toExportPath({ refName, enrichments, variant, options }), projection.id),
             enrichments,
             variant
         });
@@ -1172,15 +1172,15 @@ _GenerateContext_files = new WeakMap(), _GenerateContext_previews = new WeakMap(
         module: { ...module, exportPath: __classPrivateFieldGet(this, _GenerateContext_instances, "m", _GenerateContext_toContentSettingsExportPath).call(this, module.exportPath) },
         source
     };
-}, _GenerateContext_toContentSettingsExportPath = function _GenerateContext_toContentSettingsExportPath(exportPath) {
-    const suffixed = (0, applyGeneratedSuffix_js_1.applyGeneratedSuffix)(exportPath, this.settings?.generatedSuffix ?? applyGeneratedSuffix_js_1.DEFAULT_GENERATED_SUFFIX);
-    return __classPrivateFieldGet(this, _GenerateContext_instances, "a", _GenerateContext_ejectedBySuffixedPath_get).get((0, normalize_js_1.normalize)(suffixed)) ?? suffixed;
+}, _GenerateContext_toContentSettingsExportPath = function _GenerateContext_toContentSettingsExportPath(exportPath, generatorId) {
+    const suffixed = (0, applyGeneratedSuffix_js_1.applyGeneratedSuffix)((0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(exportPath, { generatorId }), this.settings?.generatedSuffix ?? applyGeneratedSuffix_js_1.DEFAULT_GENERATED_SUFFIX);
+    return __classPrivateFieldGet(this, _GenerateContext_instances, "a", _GenerateContext_ejectedBySuffixedPath_get).get(suffixed) ?? suffixed;
 }, _GenerateContext_ejectedBySuffixedPath_get = function _GenerateContext_ejectedBySuffixedPath_get() {
     if (__classPrivateFieldGet(this, _GenerateContext_ejectedBySuffixedPathCache, "f") === undefined) {
         const suffix = this.settings?.generatedSuffix ?? applyGeneratedSuffix_js_1.DEFAULT_GENERATED_SUFFIX;
         __classPrivateFieldSet(this, _GenerateContext_ejectedBySuffixedPathCache, new Map((this.settings?.ejected ?? []).map(ejectedPath => {
-            const normalized = (0, normalize_js_1.normalize)(ejectedPath);
-            return [(0, normalize_js_1.normalize)((0, applyGeneratedSuffix_js_1.applyGeneratedSuffix)(normalized, suffix)), normalized];
+            const normalized = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(ejectedPath);
+            return [(0, applyGeneratedSuffix_js_1.applyGeneratedSuffix)(normalized, suffix), normalized];
         })), "f");
     }
     return __classPrivateFieldGet(this, _GenerateContext_ejectedBySuffixedPathCache, "f");

package/script/context/RenderContext.d.ts

@@ -130,13 +130,13 @@ export declare class RenderContext {
      */
     collate(stackTrail: StackTrail): FilesRenderResult;
     /**
-     * Retrieves a file from the context by its normalized path.
+     * Retrieves a file from the context by its export path.
      *
-     * This method looks up a file in the context's file map using path normalization
-     * to ensure consistent path resolution. It validates that the requested file
-     * exists and throws an error if not found.
+     * The path is canonicalized first ({@link normalizeWorkspacePath}), so any
+     * spelling of the same export path finds the same file. Throws when no
+     * file exists at that path.
      *
-     * @param filePath - The file path to retrieve (will be normalized)
+     * @param filePath - The export path to retrieve, in any spelling
      * @returns The File or JsonFile instance
      * @throws {Error} When the file is not found in the context
      *
@@ -145,9 +145,9 @@ export declare class RenderContext {
      * const file = renderContext.getFile('./src/models/User.ts');
      * console.log(file.toString()); // Access file content
      *
-     * // Works with various path formats
+     * // Every spelling of the same export path finds the same file
      * const sameFile = renderContext.getFile('src/models/User.ts');
-     * const alsoSameFile = renderContext.getFile('/absolute/path/src/models/User.ts');
+     * const alsoSameFile = renderContext.getFile('@/src/models/User.ts');
      * ```
      */
     getFile(filePath: string): FileBase;

package/script/context/RenderContext.js

@@ -17,7 +17,7 @@ var _RenderContext_captureChannel, _RenderContext_sink, _RenderContext_captures;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RenderContext = void 0;
 const tiny_invariant_1 = __importDefault(require("tiny-invariant"));
-const normalize_js_1 = require("../deps/jsr.io/@std/path/1.1.6/normalize.js");
+const normalizeWorkspacePath_js_1 = require("../helpers/normalizeWorkspacePath.js");
 const toResolvedArtifactPath_js_1 = require("../helpers/toResolvedArtifactPath.js");
 const CodeFileBase_js_1 = require("../dsl/CodeFileBase.js");
 const CaptureSink_js_1 = require("../anchors/CaptureSink.js");
@@ -174,8 +174,9 @@ class RenderContext {
             __classPrivateFieldSet(this, _RenderContext_sink, undefined, "f");
         }
         // Build one sidecar per captured File from the spans the sink
-        // resolved (no re-render, no `toString`). Keyed by destination path,
-        // matching the file map. Accumulate the flat generation map.
+        // resolved (no re-render, no `toString`). Keyed by the resolved artifact
+        // path, matching `artifacts` and the manifest, so a sidecar sits at
+        // `<outDir>/<artifact key>.skm.json` where doctor looks for it.
         const { parser, schemaSrc, generatorMeta } = postPassConfig;
         const sidecars = {};
         const generationMap = [];
@@ -188,7 +189,11 @@ class RenderContext {
                 parser,
                 generatorMeta
             });
-            sidecars[capture.destinationPath] = sidecar;
+            const artifactPath = (0, toResolvedArtifactPath_js_1.toResolvedArtifactPath)({
+                basePath: this.basePath,
+                destinationPath: capture.destinationPath
+            });
+            sidecars[artifactPath] = sidecar;
             generationMap.push(...(0, generationMap_js_1.entriesForSidecar)(sidecar));
         }
         __classPrivateFieldSet(this, _RenderContext_captures, [], "f");
@@ -276,13 +281,13 @@ class RenderContext {
         return output;
     }
     /**
-     * Retrieves a file from the context by its normalized path.
+     * Retrieves a file from the context by its export path.
      *
-     * This method looks up a file in the context's file map using path normalization
-     * to ensure consistent path resolution. It validates that the requested file
-     * exists and throws an error if not found.
+     * The path is canonicalized first ({@link normalizeWorkspacePath}), so any
+     * spelling of the same export path finds the same file. Throws when no
+     * file exists at that path.
      *
-     * @param filePath - The file path to retrieve (will be normalized)
+     * @param filePath - The export path to retrieve, in any spelling
      * @returns The File or JsonFile instance
      * @throws {Error} When the file is not found in the context
      *
@@ -291,13 +296,13 @@ class RenderContext {
      * const file = renderContext.getFile('./src/models/User.ts');
      * console.log(file.toString()); // Access file content
      *
-     * // Works with various path formats
+     * // Every spelling of the same export path finds the same file
      * const sameFile = renderContext.getFile('src/models/User.ts');
-     * const alsoSameFile = renderContext.getFile('/absolute/path/src/models/User.ts');
+     * const alsoSameFile = renderContext.getFile('@/src/models/User.ts');
      * ```
      */
     getFile(filePath) {
-        const normalizedPath = (0, normalize_js_1.normalize)(filePath);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(filePath);
         const currentFile = this.files.get(normalizedPath);
         (0, tiny_invariant_1.default)(currentFile, `File not found during render phase: ${normalizedPath}`);
         return currentFile;

package/script/deps/jsr.io/@std/path/1.1.6/posix/is_absolute.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Verifies whether provided path is absolute.
+ *
+ * @example Usage
+ * ```ts
+ * import { isAbsolute } from "@std/path/posix/is-absolute";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * assert(isAbsolute("/home/user/Documents/"));
+ * assertFalse(isAbsolute("home/user/Documents/"));
+ * ```
+ *
+ * @param path The path to verify.
+ * @returns Whether the path is absolute.
+ */
+export declare function isAbsolute(path: string): boolean;

package/script/deps/jsr.io/@std/path/1.1.6/posix/is_absolute.js

@@ -0,0 +1,26 @@
+"use strict";
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbsolute = isAbsolute;
+const assert_path_js_1 = require("../_common/assert_path.js");
+const _util_js_1 = require("./_util.js");
+/**
+ * Verifies whether provided path is absolute.
+ *
+ * @example Usage
+ * ```ts
+ * import { isAbsolute } from "@std/path/posix/is-absolute";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * assert(isAbsolute("/home/user/Documents/"));
+ * assertFalse(isAbsolute("home/user/Documents/"));
+ * ```
+ *
+ * @param path The path to verify.
+ * @returns Whether the path is absolute.
+ */
+function isAbsolute(path) {
+    (0, assert_path_js_1.assertPath)(path);
+    return path.length > 0 && (0, _util_js_1.isPosixPathSeparator)(path.charCodeAt(0));
+}

package/script/deps/jsr.io/@std/path/1.1.6/windows/is_absolute.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Verifies whether provided path is absolute.
+ *
+ * @example Usage
+ * ```ts
+ * import { isAbsolute } from "@std/path/windows/is-absolute";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * assert(isAbsolute("C:\\foo\\bar"));
+ * assertFalse(isAbsolute("..\\baz"));
+ * ```
+ *
+ * @param path The path to verify.
+ * @returns `true` if the path is absolute, `false` otherwise.
+ */
+export declare function isAbsolute(path: string): boolean;