@ankhorage/paradox 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.4
+
+### Patch Changes
+
+- 77bf26a: Reuse the fixed canonical portable-path conversion from @ankhorage/utility and require Utility 1.8.1 or newer.
+
 ## 0.2.3
 
 ### Patch Changes

package/dist/analyze/analyze.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolvePolicyStatus } from '@ankhorage/policy/status';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { validateCollaborators } from '../config/utils/validateCollaborators.js';
 import { validateDonationAccount } from '../config/utils/validateDonationAccount.js';
 import { analyzeBadges } from './badges.js';
@@ -72,7 +73,7 @@ export async function analyze(config, runtime) {
         exports,
         components,
         sourceFunctions,
-        entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
+        entrypoints: entrypoints.map(toPortablePath).sort(),
         modules,
         badges,
         sequenceScenarios,

package/dist/analyze/documentation/collectDocumentationCommentsAsync.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { extname, join, relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { parseParadoxComment } from '../utils/parseParadoxComment.js';
 const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json5']);
 const SCANNED_ROOTS = ['src', 'examples'];
@@ -47,7 +48,7 @@ async function collectRootSourceFilesAsync(root) {
  */
 async function collectFileCommentsAsync(root, filePath) {
     const source = await readFile(filePath, 'utf-8');
-    const sourcePath = toPosixPath(relative(root, filePath));
+    const sourcePath = toPortablePath(relative(root, filePath));
     return [...source.matchAll(COMMENT_PATTERN)].map((match) => {
         const [raw] = match;
         return {
@@ -64,9 +65,3 @@ async function collectFileCommentsAsync(root, filePath) {
 function isMissingPathError(error) {
     return error instanceof Error && 'code' in error && error.code === 'ENOENT';
 }
-/***
- * Normalizes filesystem separators for stable documentation paths.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/exports.js

@@ -1,5 +1,6 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
 import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node } from 'ts-morph';
 import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
@@ -12,7 +13,7 @@ export function analyzeExports(project, options) {
     const exportsByName = new Map();
     let config = null;
     for (const sourceFile of getEntryPointSourceFiles(project, options)) {
-        const entrypointPath = toPosixPath(relative(options.root, sourceFile.getFilePath()));
+        const entrypointPath = toPortablePath(relative(options.root, sourceFile.getFilePath()));
         const exported = sourceFile.getExportSymbols();
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
@@ -107,12 +108,6 @@ function inferKind(node) {
         return 'value';
     return 'unknown';
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}
 /***
  * Creates empty documentation metadata for exports without Paradox comments.
  */

package/dist/analyze/modules.js

@@ -1,5 +1,6 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
 import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 /***
  * Builds a deterministic module relationship graph for documentation renderers.
  */
@@ -11,14 +12,14 @@ export function analyzeModules(project, options) {
         .getSourceFiles()
         .filter((sourceFile) => {
         const filePath = normalize(sourceFile.getFilePath());
-        const normalizedPath = toPosixPath(filePath);
+        const normalizedPath = toPortablePath(filePath);
         return (!sourceFile.isDeclarationFile() &&
             filePath.startsWith(rootPath) &&
             !excludedPaths.has(filePath) &&
             !normalizedPath.includes('/node_modules/'));
     })
         .map((sourceFile) => {
-        const path = toPosixPath(relative(options.root, sourceFile.getFilePath()));
+        const path = toPortablePath(relative(options.root, sourceFile.getFilePath()));
         const dependencies = sourceFile
             .getImportDeclarations()
             .map((declaration) => declaration.getModuleSpecifierSourceFile())
@@ -26,8 +27,8 @@ export function analyzeModules(project, options) {
             .map((dependency) => normalize(dependency.getFilePath()))
             .filter((dependency) => dependency.startsWith(rootPath) &&
             !excludedPaths.has(dependency) &&
-            !toPosixPath(dependency).includes('/node_modules/'))
-            .map((dependency) => toPosixPath(relative(options.root, dependency)));
+            !toPortablePath(dependency).includes('/node_modules/'))
+            .map((dependency) => toPortablePath(relative(options.root, dependency)));
         const exports = sourceFile
             .getExportSymbols()
             .map((symbol) => symbol.getName())
@@ -41,9 +42,3 @@ export function analyzeModules(project, options) {
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/readmeConfig.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { extname, relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 /***
  * Collects the concrete Paradox configuration instance as a README configuration example.
  */
@@ -7,7 +8,7 @@ export async function analyzeReadmeConfig(options) {
     if (options.configFilePath === null)
         return null;
     const source = await readFile(options.configFilePath, 'utf-8');
-    const sourcePath = toPosixPath(relative(options.root, options.configFilePath));
+    const sourcePath = toPortablePath(relative(options.root, options.configFilePath));
     return {
         language: getLanguage(sourcePath),
         code: source.trim(),
@@ -25,9 +26,3 @@ function getLanguage(sourcePath) {
         return 'js';
     return '';
 }
-/***
- * Normalizes filesystem separators for stable documentation paths.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/readmeUsage.js

@@ -1,6 +1,7 @@
 import { readdir } from 'node:fs/promises';
 import { extname, join, relative } from 'node:path';
 import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Project } from 'ts-morph';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
@@ -41,7 +42,7 @@ async function collectSourceFilesAsync(root) {
  */
 function analyzeUsageFile(root, project, filePath) {
     const sourceFile = project.getSourceFile(filePath) ?? project.addSourceFileAtPath(filePath);
-    const sourcePath = toPosixPath(relative(root, filePath));
+    const sourcePath = toPortablePath(relative(root, filePath));
     return sourceFile.getStatements().flatMap((statement) => {
         const comment = getParadoxComment(statement);
         if (comment === null)
@@ -140,9 +141,3 @@ function isMissingPathError(error) {
         typeof error.code === 'string' &&
         error.code === 'ENOENT');
 }
-/***
- * Normalizes filesystem separators for stable documentation paths.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/semantic/createTypeScriptProgram.js

@@ -1,6 +1,6 @@
 import { isAbsolute, join, normalize } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Project } from 'ts-morph';
-import { toPosixPath } from './utils.js';
 /***
  * Creates or reuses a ts-morph project for analysis.
  */
@@ -17,7 +17,7 @@ export function createTypeScriptProgram(options) {
         project,
         typeChecker: project.getTypeChecker(),
         root,
-        entrypoints: entrypoints.map((entrypoint) => toPosixPath(entrypoint)),
+        entrypoints: entrypoints.map((entrypoint) => toPortablePath(entrypoint)),
         entrypointFilePaths,
     };
 }

package/dist/analyze/semantic/utils.d.ts

@@ -1,4 +1,3 @@
-export declare function toPosixPath(path: string): string;
 export declare function relativeToRoot(root: string, filePath: string): string;
 export declare function isPathInsideRoot(root: string, filePath: string): boolean;
 export declare function isNodeModulePath(filePath: string): boolean;

package/dist/analyze/semantic/utils.js

@@ -1,13 +1,11 @@
 import { normalize, relative } from 'node:path';
-export function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}
+import { toPortablePath } from '@ankhorage/utility/node/path';
 export function relativeToRoot(root, filePath) {
-    return toPosixPath(relative(root, filePath));
+    return toPortablePath(relative(root, filePath));
 }
 export function isPathInsideRoot(root, filePath) {
     return normalize(filePath).startsWith(normalize(root));
 }
 export function isNodeModulePath(filePath) {
-    return toPosixPath(filePath).includes('/node_modules/');
+    return toPortablePath(filePath).includes('/node_modules/');
 }

package/dist/analyze/sequenceScenarios.js

@@ -1,7 +1,8 @@
 import { isAbsolute, join, normalize } from 'node:path';
 import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node as MorphNode, } from 'ts-morph';
-import { relativeToRoot, toPosixPath } from './semantic/utils.js';
+import { relativeToRoot } from './semantic/utils.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 /***
@@ -73,7 +74,7 @@ function resolveBinSourceFile(project, root, targetPath) {
     return null;
 }
 function getBinSourceCandidates(targetPath) {
-    const normalized = toPosixPath(targetPath).replace(/^\.\//, '');
+    const normalized = toPortablePath(targetPath).replace(/^\.\//, '');
     const candidates = [];
     if (/^src\/.*\.tsx?$/.test(normalized)) {
         candidates.push(normalized);

package/dist/analyze/sourceFunctions.js

@@ -1,4 +1,5 @@
 import { relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node } from 'ts-morph';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
@@ -11,7 +12,7 @@ export function analyzeSourceFunctions(project, root) {
         .flatMap((sourceFile) => {
         if (sourceFile.isDeclarationFile())
             return [];
-        const filePath = toPosixPath(relative(root, sourceFile.getFilePath()));
+        const filePath = toPortablePath(relative(root, sourceFile.getFilePath()));
         if (!filePath.startsWith('src/'))
             return [];
         return sourceFile.getDescendants().flatMap((node) => {
@@ -50,15 +51,9 @@ function createSourceFunction(name, node, root) {
         see: parsedComment?.see ?? [],
         security: parsedComment?.security ?? [],
         sourceLocation: {
-            filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+            filePath: toPortablePath(relative(root, sourceFile.getFilePath())),
             line,
             column,
         },
     };
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/utils/getExportMetadata.js

@@ -1,4 +1,5 @@
 import { relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node, } from 'ts-morph';
 import { getParadoxComment } from './getParadoxComment.js';
 import { normalizeTypeText } from './normalizeTypeText.js';
@@ -7,7 +8,7 @@ import { parseParadoxComment } from './parseParadoxComment.js';
  * Extracts computed metadata for an exported declaration.
  */
 export function getExportMetadata(options) {
-    const modulePath = toPosixPath(relative(options.root, options.node.getSourceFile().getFilePath()));
+    const modulePath = toPortablePath(relative(options.root, options.node.getSourceFile().getFilePath()));
     const sourceLocation = getSourceLocation(options.node, options.root);
     const signatures = getSignatures(options.symbol, options.node, options.root);
     const members = getMembers(options.node, options.root);
@@ -33,7 +34,7 @@ function getSourceLocation(node, root) {
     const sourceFile = node.getSourceFile();
     const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
     return {
-        filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+        filePath: toPortablePath(relative(root, sourceFile.getFilePath())),
         line,
         column,
     };
@@ -259,12 +260,6 @@ function collectRelatedSymbols(exportName, ...values) {
     }
     return [...related].sort((left, right) => left.localeCompare(right));
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}
 /***
  * Returns unique items by a caller-provided key while preserving first occurrence order.
  */

package/dist/analyze/utils/normalizeTypeText.js

@@ -1,3 +1,4 @@
+import { toPortablePath } from '@ankhorage/utility/node/path';
 /***
  * Removes machine-specific absolute paths from TypeScript import type text.
  */
@@ -13,7 +14,7 @@ export function normalizeTypeText(typeText, packageRoot) {
     return normalized + typeText.slice(cursor);
 }
 function normalizeImportPath(importPath, packageRoot) {
-    const normalizedPath = toPosixPath(importPath);
+    const normalizedPath = toPortablePath(importPath);
     const nodeModulesMarker = '/node_modules/';
     const nodeModulesIndex = normalizedPath.lastIndexOf(nodeModulesMarker);
     if (nodeModulesIndex >= 0) {
@@ -22,12 +23,9 @@ function normalizeImportPath(importPath, packageRoot) {
     if (normalizedPath.startsWith('node_modules/')) {
         return normalizedPath.slice('node_modules/'.length);
     }
-    const normalizedRoot = packageRoot ? toPosixPath(packageRoot).replace(/\/$/, '') : null;
+    const normalizedRoot = packageRoot ? toPortablePath(packageRoot).replace(/\/$/, '') : null;
     if (normalizedRoot && normalizedPath.startsWith(`${normalizedRoot}/`)) {
         return `./${normalizedPath.slice(normalizedRoot.length + 1)}`;
     }
     return normalizedPath;
 }
-function toPosixPath(value) {
-    return value.replaceAll('\\', '/');
-}

package/dist/paths/policy.js

@@ -1,6 +1,7 @@
 import { access } from 'node:fs/promises';
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 const CONFIG_FILENAMES = [
     'paradox.config.ts',
     'paradox.config.js',
@@ -105,7 +106,7 @@ function validateOutputDir(outputDir) {
  * Splits a configured path into normalized non-empty path segments.
  */
 function splitPathSegments(path) {
-    const normalized = path.replaceAll('\\', '/');
+    const normalized = toPortablePath(path);
     return normalized.split('/').filter((segment) => segment.length > 0 && segment !== '.');
 }
 /***

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@ankhorage/policy": "^0.3.1",
-    "@ankhorage/utility": "^1.8.0",
+    "@ankhorage/utility": "^1.8.1",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {