@ankhorage/paradox 0.1.19 → 0.1.21

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.21
+
+### Patch Changes
+
+- b7cd8b9: Normalize package-local absolute import types emitted through React component prop analysis by carrying the analyzed package root into the existing type-text normalizer.
+
+## 0.1.20
+
+### Patch Changes
+
+- 112f1f0: Normalize absolute TypeScript import-type paths to deterministic package or package-relative specifiers in generated documentation.
+
 ## 0.1.19
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.19](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.21](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 

package/dist/analyze/components.js

@@ -21,7 +21,7 @@ export function analyzeComponents(exports, options = {}) {
             description: member.description ?? null,
         })) ?? [];
         const propsType = getComponentPropsType(e.node);
-        const legacyProps = propsType != null ? getPropsFromType(propsType) : [];
+        const legacyProps = propsType != null ? getPropsFromType(propsType, options.program?.root) : [];
         const props = analyzerProps.length > 0 ? analyzerProps : legacyProps;
         components.push({
             name: e.name,

package/dist/analyze/utils/getExportMetadata.js

@@ -1,6 +1,7 @@
 import { relative } from 'node:path';
 import { Node, } from 'ts-morph';
 import { getParadoxComment } from './getParadoxComment.js';
+import { normalizeTypeText } from './normalizeTypeText.js';
 import { parseParadoxComment } from './parseParadoxComment.js';
 /***
  * Extracts computed metadata for an exported declaration.
@@ -8,8 +9,8 @@ import { parseParadoxComment } from './parseParadoxComment.js';
 export function getExportMetadata(options) {
     const modulePath = toPosixPath(relative(options.root, options.node.getSourceFile().getFilePath()));
     const sourceLocation = getSourceLocation(options.node, options.root);
-    const signatures = getSignatures(options.symbol, options.node);
-    const members = getMembers(options.node);
+    const signatures = getSignatures(options.symbol, options.node, options.root);
+    const members = getMembers(options.node, options.root);
     const structuredRows = getStructuredRows(options.node, options.name);
     const relatedSymbols = collectRelatedSymbols(options.name, signatures.flatMap((signature) => [
         ...signature.parameters.map((parameter) => parameter.type),
@@ -40,9 +41,9 @@ function getSourceLocation(node, root) {
 /***
  * Extracts callable signatures for exported functions and callable values.
  */
-function getSignatures(symbol, node) {
+function getSignatures(symbol, node, root) {
     const parsed = readParadoxMetadata(node);
-    const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns));
+    const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns, root));
     return uniqueBy(signatures.filter((signature) => signature.parameters.length > 0 ||
         signature.returnType !== null ||
         signature.returnDescription !== null), (signature) => signature.label);
@@ -50,17 +51,17 @@ function getSignatures(symbol, node) {
 /***
  * Builds one normalized call signature from a callable declaration.
  */
-function getSignature(declaration, params, returns) {
+function getSignature(declaration, params, returns, root) {
     const normalizedParameters = declaration.getParameters().map((parameter) => {
         const parameterDescription = params[parameter.getName()];
         return {
             name: parameter.getName(),
-            type: parameter.getType().getText(parameter),
+            type: normalizeTypeText(parameter.getType().getText(parameter), root),
             required: !parameter.isOptional(),
             description: parameterDescription ? parameterDescription.trim() : null,
         };
     });
-    const returnType = declaration.getReturnType().getText(declaration);
+    const returnType = normalizeTypeText(declaration.getReturnType().getText(declaration), root);
     const parameterLabel = normalizedParameters
         .map((parameter) => `${parameter.name}${parameter.required ? '' : '?'}: ${parameter.type}`)
         .join(', ');
@@ -74,24 +75,24 @@ function getSignature(declaration, params, returns) {
 /***
  * Extracts members for interface and type literal exports.
  */
-function getMembers(node) {
+function getMembers(node, root) {
     if (getCallableNode(node) !== null)
         return [];
     if (Node.isInterfaceDeclaration(node)) {
-        return getMembersFromProperties(node.getType().getProperties());
+        return getMembersFromProperties(node.getType().getProperties(), root);
     }
     if (Node.isTypeAliasDeclaration(node)) {
         const typeNode = node.getTypeNode();
         if (!typeNode || !Node.isTypeLiteral(typeNode))
             return [];
-        return getMembersFromProperties(node.getType().getProperties());
+        return getMembersFromProperties(node.getType().getProperties(), root);
     }
     return [];
 }
 /***
  * Converts TypeScript properties into documented member metadata.
  */
-function getMembersFromProperties(properties) {
+function getMembersFromProperties(properties, root) {
     return properties.flatMap((property) => {
         const declaration = getFirstDeclaration(property.getDeclarations());
         if (declaration === null) {
@@ -112,7 +113,7 @@ function getMembersFromProperties(properties) {
             {
                 name: property.getName(),
                 kind: isMemberMethodDeclaration(declaration) ? 'method' : 'property',
-                type: property.getTypeAtLocation(declaration).getText(declaration),
+                type: normalizeTypeText(property.getTypeAtLocation(declaration).getText(declaration), root),
                 required: !property.isOptional(),
                 description: parsed.description,
             },

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

@@ -3,4 +3,4 @@ import type { AnalysisComponent } from '../types.js';
 /***
  * Extracts prop names, types, required flags, and descriptions from a type.
  */
-export declare function getPropsFromType(type: Type): AnalysisComponent['props'];
+export declare function getPropsFromType(type: Type, packageRoot?: string): AnalysisComponent['props'];

package/dist/analyze/utils/getPropsFromType.js

@@ -1,9 +1,10 @@
 import { getParadoxComment } from './getParadoxComment.js';
+import { normalizeTypeText } from './normalizeTypeText.js';
 import { parseParadoxComment } from './parseParadoxComment.js';
 /***
  * Extracts prop names, types, required flags, and descriptions from a type.
  */
-export function getPropsFromType(type) {
+export function getPropsFromType(type, packageRoot) {
     return type.getProperties().map((property) => {
         const [declaration] = property.getDeclarations();
         const propertyType = property.getTypeAtLocation(declaration);
@@ -13,7 +14,7 @@ export function getPropsFromType(type) {
             : { description: null, isConfig: false, params: {}, returns: null };
         return {
             name: property.getName(),
-            type: propertyType.getText(declaration),
+            type: normalizeTypeText(propertyType.getText(declaration), packageRoot),
             required: !property.isOptional(),
             description: parsed.description,
         };

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

@@ -0,0 +1,4 @@
+/***
+ * Removes machine-specific absolute paths from TypeScript import type text.
+ */
+export declare function normalizeTypeText(typeText: string, packageRoot?: string): string;

package/dist/analyze/utils/normalizeTypeText.js

@@ -0,0 +1,33 @@
+/***
+ * Removes machine-specific absolute paths from TypeScript import type text.
+ */
+export function normalizeTypeText(typeText, packageRoot) {
+    let normalized = '';
+    let cursor = 0;
+    for (const match of typeText.matchAll(/import\((['"])([^'"]+)\1\)/g)) {
+        const [fullMatch, quote, importPath] = match;
+        normalized += typeText.slice(cursor, match.index);
+        normalized += `import(${quote}${normalizeImportPath(importPath, packageRoot)}${quote})`;
+        cursor = match.index + fullMatch.length;
+    }
+    return normalized + typeText.slice(cursor);
+}
+function normalizeImportPath(importPath, packageRoot) {
+    const normalizedPath = toPosixPath(importPath);
+    const nodeModulesMarker = '/node_modules/';
+    const nodeModulesIndex = normalizedPath.lastIndexOf(nodeModulesMarker);
+    if (nodeModulesIndex >= 0) {
+        return normalizedPath.slice(nodeModulesIndex + nodeModulesMarker.length);
+    }
+    if (normalizedPath.startsWith('node_modules/')) {
+        return normalizedPath.slice('node_modules/'.length);
+    }
+    const normalizedRoot = packageRoot ? toPosixPath(packageRoot).replace(/\/$/, '') : null;
+    if (normalizedRoot && normalizedPath.startsWith(`${normalizedRoot}/`)) {
+        return `./${normalizedPath.slice(normalizedRoot.length + 1)}`;
+    }
+    return normalizedPath;
+}
+function toPosixPath(value) {
+    return value.replaceAll('\\', '/');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {