@skmtc/core 0.28.7 → 0.29.0

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

@@ -0,0 +1,41 @@
+"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 constants_js_1 = require("../_common/constants.js");
+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/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.
+ */
+function isAbsolute(path) {
+    (0, assert_path_js_1.assertPath)(path);
+    const len = path.length;
+    if (len === 0)
+        return false;
+    const code = path.charCodeAt(0);
+    if ((0, _util_js_1.isPathSeparator)(code)) {
+        return true;
+    }
+    else if ((0, _util_js_1.isWindowsDeviceRoot)(code)) {
+        // Possible device root
+        if (len > 2 && path.charCodeAt(1) === constants_js_1.CHAR_COLON) {
+            if ((0, _util_js_1.isPathSeparator)(path.charCodeAt(2)))
+                return true;
+        }
+    }
+    return false;
+}

package/script/dsl/model/ModelDriver.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelDriver = 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 GeneratorKeys_js_1 = require("../GeneratorKeys.js");
 const Variant_js_1 = require("../../types/Variant.js");
 const ProjectionOptions_js_1 = require("../../types/ProjectionOptions.js");
@@ -110,7 +110,8 @@ class ModelDriver {
     apply({ destinationPath } = {}) {
         const { identifier, exportPath } = this.settings;
         const definition = this.getDefinition({ identifier, exportPath });
-        if (destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)) {
+        if (destinationPath &&
+            (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(exportPath) !== (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath)) {
             // Cross-file import of the peer's identifier from its export path.
             // The language builds the import object (`toImport`) and creates the
             // destination file on first write (caller-side); the engine stores
@@ -130,7 +131,7 @@ class ModelDriver {
      * cache-hit path). Returns the normalized path.
      */
     ensureFile(path) {
-        const normalizedPath = (0, normalize_js_1.normalize)(path);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(path);
         if (!this.context.getFile(normalizedPath)) {
             this.context.addFile(this.projection.lang.createFile({ path: normalizedPath, settings: this.context.settings }));
         }

package/script/dsl/operation/gql/GqlOperationDriver.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GqlOperationDriver = 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 GeneratorKeys_js_1 = require("../../GeneratorKeys.js");
 const Variant_js_1 = require("../../../types/Variant.js");
 const ProjectionOptions_js_1 = require("../../../types/ProjectionOptions.js");
@@ -101,7 +101,8 @@ class GqlOperationDriver {
     apply({ destinationPath } = {}) {
         const { identifier, exportPath } = this.settings;
         const definition = this.getDefinition({ identifier, exportPath });
-        if (destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)) {
+        if (destinationPath &&
+            (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(exportPath) !== (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath)) {
             // Cross-file import of the peer's identifier from its export path.
             // The language builds the import object (`toImport`) and creates the
             // destination file on first write (caller-side); the engine stores
@@ -123,7 +124,7 @@ class GqlOperationDriver {
      * cache-hit path). Returns the normalized path.
      */
     ensureFile(path) {
-        const normalizedPath = (0, normalize_js_1.normalize)(path);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(path);
         if (!this.context.getFile(normalizedPath)) {
             this.context.addFile(this.projection.lang.createFile({ path: normalizedPath, settings: this.context.settings }));
         }

package/script/dsl/operation/oas/OasOperationDriver.js

@@ -16,7 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 var _OasOperationDriver_into;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasOperationDriver = 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 tiny_invariant_1 = __importDefault(require("tiny-invariant"));
 const GeneratorKeys_js_1 = require("../../GeneratorKeys.js");
 const Variant_js_1 = require("../../../types/Variant.js");
@@ -140,7 +140,8 @@ class OasOperationDriver {
         const { identifier, exportPath } = this.settings;
         // The file an import has to be stitched into, or `undefined` when there
         // is none to stitch — no destination, or the projection's own file.
-        const importInto = destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)
+        const importInto = destinationPath &&
+            (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(exportPath) !== (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath)
             ? destinationPath
             : undefined;
         // A member is declared inside its container, so it has no module-level
@@ -174,7 +175,7 @@ class OasOperationDriver {
      * cache-hit path). Returns the normalized path.
      */
     ensureFile(path) {
-        const normalizedPath = (0, normalize_js_1.normalize)(path);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(path);
         if (!this.context.getFile(normalizedPath)) {
             this.context.addFile(this.projection.lang.createFile({ path: normalizedPath, settings: this.context.settings }));
         }

package/script/dsl/webhook/WebhookDriver.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebhookDriver = 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 GeneratorKeys_js_1 = require("../GeneratorKeys.js");
 const Variant_js_1 = require("../../types/Variant.js");
 const ProjectionOptions_js_1 = require("../../types/ProjectionOptions.js");
@@ -101,7 +101,8 @@ class WebhookDriver {
     apply({ destinationPath } = {}) {
         const { identifier, exportPath } = this.settings;
         const definition = this.getDefinition({ identifier, exportPath });
-        if (destinationPath && (0, normalize_js_1.normalize)(exportPath) !== (0, normalize_js_1.normalize)(destinationPath)) {
+        if (destinationPath &&
+            (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(exportPath) !== (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(destinationPath)) {
             // Cross-file import of the peer's identifier from its export path.
             this.ensureFile(destinationPath);
             this.context.register({
@@ -116,7 +117,7 @@ class WebhookDriver {
      * projection's language. Returns the normalized path.
      */
     ensureFile(path) {
-        const normalizedPath = (0, normalize_js_1.normalize)(path);
+        const normalizedPath = (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(path);
         if (!this.context.getFile(normalizedPath)) {
             this.context.addFile(this.projection.lang.createFile({ path: normalizedPath, settings: this.context.settings }));
         }

package/script/helpers/applyGeneratedSuffix.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeGeneratedSuffix = exports.applyGeneratedSuffix = exports.DEFAULT_GENERATED_SUFFIX = void 0;
-const extname_js_1 = require("../deps/jsr.io/@std/path/1.1.6/extname.js");
+const extname_js_1 = require("../deps/jsr.io/@std/path/1.1.6/posix/extname.js");
 /**
  * The filename suffix marking a file as engine-owned, applied by the
  * engine when a projection's `toExportPath` result is stored into

package/script/helpers/isImported.d.ts

@@ -1,81 +1,17 @@
 /**
- * Determines whether two file paths represent different locations (import required).
+ * Whether two workspace paths name different files, so a symbol from one
+ * must be imported into the other.
  *
- * This utility function normalizes two file paths and compares them to determine
- * if they represent different files. It's used throughout the SKMTC system to
- * decide when import statements are needed - if two paths are different, an
- * import is required to access symbols from one file in another.
+ * Both are canonicalized with {@link normalizeWorkspacePath}, so every
+ * spelling of one file compares equal: `@/`, `./`, the bare form, and
+ * Windows separators. Throws, as that does, for a path that cannot name a
+ * file below `basePath` (a `..` segment, a Windows drive path).
  *
- * The function handles path normalization to ensure consistent comparisons
- * across different operating systems and path formats (handling './' vs absolute
- * paths, different separators, etc.).
- *
- * @param pathOne - The first file path to compare
- * @param pathTwo - The second file path to compare
- * @returns `true` if the paths are different (import needed), `false` if they're the same file
- *
- * @example Basic path comparison
- * ```typescript
- * import { isImported } from '@skmtc/core';
- *
- * // Same file, no import needed
- * console.log(isImported('./src/user.ts', './src/user.ts')); // false
- *
- * // Different files, import needed
- * console.log(isImported('./src/user.ts', './src/product.ts')); // true
- * ```
- *
- * @example Path normalization handling
- * ```typescript
- * // These all represent the same file after normalization
- * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
- * ```
- *
- * @example Usage in import decision logic
+ * @example
  * ```typescript
- * class FileGenerator {
- *   addImportIfNeeded(
- *     sourceFile: string,
- *     targetFile: string,
- *     importName: string
- *   ) {
- *     if (isImported(sourceFile, targetFile)) {
- *       // Files are different, add import
- *       this.addImport(sourceFile, targetFile, importName);
- *       console.log(`Added import: ${importName} from ${targetFile}`);
- *     } else {
- *       // Same file, no import needed
- *       console.log(`No import needed - same file: ${sourceFile}`);
- *     }
- *   }
- * }
- * ```
- *
- * @example Cross-platform path handling
- * ```typescript
- * // Works consistently across platforms
- * const windowsPath = 'src\\models\\user.ts';
- * const unixPath = 'src/models/user.ts';
- *
- * console.log(isImported(windowsPath, unixPath)); // false (same file)
- * ```
- *
- * @example In generator context
- * ```typescript
- * class ModelGenerator {
- *   generateModel(modelPath: string, referencePath: string) {
- *     const definition = this.createModelDefinition();
- *
- *     if (isImported(modelPath, referencePath)) {
- *       // Need to import the referenced model
- *       definition.addImport(referencePath, 'ReferencedModel');
- *     }
- *
- *     return definition;
- *   }
- * }
+ * isImported('@/src/user.ts', './src/user.ts')    // false — one file
+ * isImported('src\\user.ts', 'src/user.ts')       // false — one file
+ * isImported('@/src/user.ts', '@/src/product.ts') // true
  * ```
  */
 export declare const isImported: (pathOne: string, pathTwo: string) => boolean;

package/script/helpers/isImported.js

@@ -1,88 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isImported = void 0;
-const normalize_js_1 = require("../deps/jsr.io/@std/path/1.1.6/normalize.js");
+const normalizeWorkspacePath_js_1 = require("./normalizeWorkspacePath.js");
 /**
- * Determines whether two file paths represent different locations (import required).
+ * Whether two workspace paths name different files, so a symbol from one
+ * must be imported into the other.
  *
- * This utility function normalizes two file paths and compares them to determine
- * if they represent different files. It's used throughout the SKMTC system to
- * decide when import statements are needed - if two paths are different, an
- * import is required to access symbols from one file in another.
+ * Both are canonicalized with {@link normalizeWorkspacePath}, so every
+ * spelling of one file compares equal: `@/`, `./`, the bare form, and
+ * Windows separators. Throws, as that does, for a path that cannot name a
+ * file below `basePath` (a `..` segment, a Windows drive path).
  *
- * The function handles path normalization to ensure consistent comparisons
- * across different operating systems and path formats (handling './' vs absolute
- * paths, different separators, etc.).
- *
- * @param pathOne - The first file path to compare
- * @param pathTwo - The second file path to compare
- * @returns `true` if the paths are different (import needed), `false` if they're the same file
- *
- * @example Basic path comparison
- * ```typescript
- * import { isImported } from '@skmtc/core';
- *
- * // Same file, no import needed
- * console.log(isImported('./src/user.ts', './src/user.ts')); // false
- *
- * // Different files, import needed
- * console.log(isImported('./src/user.ts', './src/product.ts')); // true
- * ```
- *
- * @example Path normalization handling
- * ```typescript
- * // These all represent the same file after normalization
- * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
- * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
- * ```
- *
- * @example Usage in import decision logic
+ * @example
  * ```typescript
- * class FileGenerator {
- *   addImportIfNeeded(
- *     sourceFile: string,
- *     targetFile: string,
- *     importName: string
- *   ) {
- *     if (isImported(sourceFile, targetFile)) {
- *       // Files are different, add import
- *       this.addImport(sourceFile, targetFile, importName);
- *       console.log(`Added import: ${importName} from ${targetFile}`);
- *     } else {
- *       // Same file, no import needed
- *       console.log(`No import needed - same file: ${sourceFile}`);
- *     }
- *   }
- * }
- * ```
- *
- * @example Cross-platform path handling
- * ```typescript
- * // Works consistently across platforms
- * const windowsPath = 'src\\models\\user.ts';
- * const unixPath = 'src/models/user.ts';
- *
- * console.log(isImported(windowsPath, unixPath)); // false (same file)
- * ```
- *
- * @example In generator context
- * ```typescript
- * class ModelGenerator {
- *   generateModel(modelPath: string, referencePath: string) {
- *     const definition = this.createModelDefinition();
- *
- *     if (isImported(modelPath, referencePath)) {
- *       // Need to import the referenced model
- *       definition.addImport(referencePath, 'ReferencedModel');
- *     }
- *
- *     return definition;
- *   }
- * }
+ * isImported('@/src/user.ts', './src/user.ts')    // false — one file
+ * isImported('src\\user.ts', 'src/user.ts')       // false — one file
+ * isImported('@/src/user.ts', '@/src/product.ts') // true
  * ```
  */
 const isImported = (pathOne, pathTwo) => {
-    return (0, normalize_js_1.normalize)(pathOne) !== (0, normalize_js_1.normalize)(pathTwo);
+    return (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(pathOne) !== (0, normalizeWorkspacePath_js_1.normalizeWorkspacePath)(pathTwo);
 };
 exports.isImported = isImported;

package/script/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/script/helpers/normalizeWorkspacePath.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkspacePath = exports.toNormalizedWorkspacePath = exports.isValidWorkspacePath = exports.hasWorkspaceAnchor = exports.isAbsolutePath = exports.hasParentSegment = void 0;
+const normalize_js_1 = require("../deps/jsr.io/@std/path/1.1.6/posix/normalize.js");
+const is_absolute_js_1 = require("../deps/jsr.io/@std/path/1.1.6/posix/is_absolute.js");
+const is_absolute_js_2 = require("../deps/jsr.io/@std/path/1.1.6/windows/is_absolute.js");
+const toWorkspacePath_js_1 = require("./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.
+ */
+const hasParentSegment = (path) => path.split(/[/\\]/).some(segment => segment === '..');
+exports.hasParentSegment = hasParentSegment;
+/**
+ * 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.
+ */
+const isAbsolutePath = (path) => (0, is_absolute_js_1.isAbsolute)(path.replaceAll('\\', '/')) || (0, is_absolute_js_2.isAbsolute)(path);
+exports.isAbsolutePath = isAbsolutePath;
+/**
+ * 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`.
+ */
+const hasWorkspaceAnchor = (path) => /^(@[\\/]|\.[\\/]|[\\/])/.test(path);
+exports.hasWorkspaceAnchor = hasWorkspaceAnchor;
+/**
+ * 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.
+ */
+const isValidWorkspacePath = (path) => !isDriveOrUncPath(path) && !(0, exports.hasParentSegment)(path) && toBody(path) !== '';
+exports.isValidWorkspacePath = isValidWorkspacePath;
+/**
+ * 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 (`@/`, `@`, `./`, `.`, `/`, ``).
+ */
+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 ((0, exports.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;
+};
+exports.toNormalizedWorkspacePath = toNormalizedWorkspacePath;
+/**
+ * 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
+ * ```
+ */
+const normalizeWorkspacePath = (path, options = {}) => `@/${(0, exports.toNormalizedWorkspacePath)(path, options)}`;
+exports.normalizeWorkspacePath = normalizeWorkspacePath;
+/**
+ * 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 = (0, toWorkspacePath_js_1.toWorkspacePath)(path.replaceAll('\\', '/'));
+    if (stripped === '') {
+        return '';
+    }
+    const normalized = (0, normalize_js_1.normalize)(stripped);
+    return normalized === '.' ? '' : normalized;
+};

package/script/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/script/helpers/toResolvedArtifactPath.js

@@ -5,18 +5,22 @@ exports.toResolvedArtifactPath = void 0;
  * 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
  */
 require("../_dnt.polyfills.js");
-const join_js_1 = require("../deps/jsr.io/@std/path/1.1.6/join.js");
+const join_js_1 = require("../deps/jsr.io/@std/path/1.1.6/posix/join.js");
+const normalizeWorkspacePath_js_1 = require("./normalizeWorkspacePath.js");
 const toWorkspacePath_js_1 = require("./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
@@ -27,6 +31,6 @@ const toWorkspacePath_js_1 = require("./toWorkspacePath.js");
  * ```
  */
 const toResolvedArtifactPath = ({ basePath, destinationPath }) => {
-    return (0, join_js_1.join)(basePath ?? './', (0, toWorkspacePath_js_1.toWorkspacePath)(destinationPath));
+    return (0, join_js_1.join)((0, toWorkspacePath_js_1.toWorkspacePath)(basePath ?? ''), (0, normalizeWorkspacePath_js_1.toNormalizedWorkspacePath)(destinationPath));
 };
 exports.toResolvedArtifactPath = toResolvedArtifactPath;

package/script/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/script/helpers/toWorkspacePath.js

@@ -10,9 +10,9 @@ exports.isUnderRoot = exports.toWorkspacePath = void 0;
  * 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
@@ -32,9 +32,9 @@ exports.isUnderRoot = exports.toWorkspacePath = void 0;
 const toWorkspacePath = (path) => {
     const withoutAnchor = path
         .replaceAll('\\', '/')
-        .replace(/^(?:@\/|\.\/)+/, '')
+        .replace(/^(?:@\/|\.\/|\/)+/, '')
         .replace(/\/+$/, '');
-    return withoutAnchor === '.' ? '' : withoutAnchor;
+    return withoutAnchor === '.' || withoutAnchor === '@' ? '' : withoutAnchor;
 };
 exports.toWorkspacePath = toWorkspacePath;
 /**

package/script/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';