@travetto/doc 5.0.0-rc.3 → 5.0.0-rc.5

package/__index__.ts

@@ -1,3 +1,4 @@
 export { JSXElement as DocJSXElement, isJSXElement as isDocJSXElement } from './jsx-runtime';
 export { c, d, JSXElementByFn as DocJSXElementByFn } from './src/jsx';
-export { MOD_MAPPING as mod } from './src/mapping/mod-mapping';
+export { MOD_MAPPING as mod } from './src/mapping/mod-mapping';
+export { DocFileUtil } from './src/util/file';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "5.0.0-rc.3",
+  "version": "5.0.0-rc.5",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,12 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/runtime": "^5.0.0-rc.3",
+    "@travetto/runtime": "^5.0.0-rc.5",
     "@types/prismjs": "^1.26.4",
     "prismjs": "^1.29.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^5.0.0-rc.3"
+    "@travetto/cli": "^5.0.0-rc.5"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/render/context.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createElement, JSXRuntimeTag } from '@travetto/doc/jsx-runtime';
 
 import { PackageUtil } from '@travetto/manifest';
-import { Runtime, RuntimeIndex } from '@travetto/runtime';
+import { RuntimeIndex } from '@travetto/runtime';
 
 import { JSXElementByFn, c } from '../jsx';
 import { DocResolveUtil, ResolvedCode, ResolvedRef, ResolvedSnippetLink } from '../util/resolve';
@@ -108,18 +108,16 @@ export class RenderContext {
    * Resolve code link
    */
   async resolveCodeLink(node: JSXElementByFn<'CodeLink'>): Promise<ResolvedSnippetLink> {
-    const src = typeof node.props.src === 'string' ? node.props.src : Runtime.getSource(node.props.src);
-    return DocResolveUtil.resolveCodeLink(src, node.props.startRe);
+    return DocResolveUtil.resolveCodeLink(node.props.src, node.props.startRe);
   }
 
   /**
    * Resolve code/config
    */
   async resolveCode(node: JSXElementByFn<'Code' | 'Config'>): Promise<ResolvedCode> {
-    const src = typeof node.props.src === 'string' ? node.props.src : Runtime.getSource(node.props.src);
     return node.props.startRe ?
-      DocResolveUtil.resolveSnippet(src, node.props.startRe, node.props.endRe, node.props.outline) :
-      DocResolveUtil.resolveCode(src, node.props.language, node.props.outline);
+      DocResolveUtil.resolveSnippet(node.props.src, node.props.startRe, node.props.endRe, node.props.outline) :
+      DocResolveUtil.resolveCode(node.props.src, node.props.language, node.props.outline);
   }
 
   /**

package/src/render/renderer.ts

@@ -2,7 +2,7 @@ import path from 'node:path';
 
 import { type ManifestContext, PackageUtil } from '@travetto/manifest';
 import { isJSXElement, JSXElement, JSXFragmentType } from '@travetto/doc/jsx-runtime';
-import { Runtime, RuntimeIndex } from '@travetto/runtime';
+import { RuntimeIndex } from '@travetto/runtime';
 
 import { EMPTY_ELEMENT, getComponentName, JSXElementByFn, c } from '../jsx';
 import { DocumentShape, RenderProvider, RenderState } from '../types';
@@ -93,12 +93,12 @@ export class DocRenderer {
         case 'number':
         case 'bigint':
         case 'boolean': return `${node}`;
-        default: {
-          const source = typeof node === 'function' ? Runtime.getSource(node) : undefined;
-          if (source && typeof node === 'function') {
-            const title = (await DocFileUtil.isDecorator(node.name, source)) ? `@${node.name}` : node.name;
+        case 'function': {
+          const source = DocFileUtil.readSource(node);
+          if (source.file) {
+            const title = (await DocFileUtil.isDecorator(node.name, source.file)) ? `@${node.name}` : node.name;
             const el = this.#support.createElement('CodeLink', {
-              src: source,
+              src: source.file,
               startRe: new RegExp(`(class|function)\\s+(${node.name})`),
               title
             });
@@ -110,9 +110,10 @@ export class DocRenderer {
             state.createState = (key, props) => this.createState(state, key, props);
             return await renderer.CodeLink(state);
           }
-          throw new Error(`Unknown object type: ${typeof node}`);
+          break;
         }
       }
+      throw new Error(`Unknown object type: ${typeof node}`);
     }
   }
 

package/src/util/file.ts

@@ -1,8 +1,7 @@
-import fs from 'node:fs/promises';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
-import { ManifestModuleUtil } from '@travetto/manifest';
-import { RuntimeIndex } from '@travetto/runtime';
+import { Runtime, RuntimeIndex } from '@travetto/runtime';
 
 const ESLINT_PATTERN = /\s*\/\/ eslint.*$/g;
 const ENV_KEY = /Env.([^.]+)[.]key/g;
@@ -25,58 +24,56 @@ export class DocFileUtil {
     return /^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,10})$/.test(src);
   }
 
-  /**
-   * Resolve file
-   * @param file
-   * @returns
-   */
-  static async resolveFile(file: string): Promise<string> {
-    let resolved = path.resolve(file);
-    if (!(await fs.stat(resolved).catch(() => false))) {
-      if (ManifestModuleUtil.getFileType(file) === 'ts') {
-        resolved = RuntimeIndex.getSourceFile(file);
-      }
-      if (!(await fs.stat(resolved).catch(() => false))) {
-        throw new Error(`Unknown file to resolve: ${file}`);
+  static readSource(src: string | Function): { content: string, language: string, file: string } {
+    let file: string | undefined;
+    let content: string | undefined;
+
+    if (typeof src === 'string') {
+      if (src.includes('\n') || src.includes(' ')) {
+        content = src;
+      } else {
+        const resolved = path.resolve(src);
+        if (existsSync(resolved)) {
+          content = readFileSync(resolved, 'utf8');
+          file = resolved;
+        } else {
+          file = RuntimeIndex.getSourceFile(src);
+          content = readFileSync(file, 'utf8');
+        }
       }
+    } else {
+      file = Runtime.getSourceFile(src);
+      content = readFileSync(file, 'utf8');
     }
-    return resolved;
-  }
 
-  /**
-   * Read file
-   *
-   * @param file
-   * @returns
-   */
-  static async read(file: string): Promise<{ content: string, language: string, file: string }> {
-    file = await this.resolveFile(file);
-
-    const ext = path.extname(file);
-    const language = this.#extToLang[ext] ?? ext.replace('.', '');
-
-    let text: string | undefined;
-    if (language) {
-      text = await fs.readFile(file, 'utf8');
-
-      text = text.split(/\n/)
+    if (content) {
+      content = content.split(/\n/)
         .map(x => x
           .replace(ESLINT_PATTERN, '')
           .replace(ENV_KEY, (_, k) => `'${k}'`)
         )
-        .filter(x => !x.includes('@doc-exclude'))
-        .join('\n');
+        .join('\n')
+        .replace(/^\/\/# sourceMap.*$/gsm, '')
+        .replace(/[ ]*[/][/][ ]*@ts-expect-error[^\n]*\n/gsm, '') // Excluding errors
+        .replace(/^[ ]*[/][/][ ]*[{][{][^\n]*\n/gsm, '') // Excluding conditional comments, full-line
+        .replace(/[ ]*[/][/][ ]*[{][{][^\n]*/gsm, ''); // Excluding conditional comments
     }
 
-    return { content: text ?? '', language, file };
+    if (file !== undefined) {
+      const ext = path.extname(file);
+      const language = this.#extToLang[ext] ?? ext.replace('.', '');
+      return { content, file, language };
+    } else {
+      return { content, file: '', language: '' };
+    }
   }
 
-  static async readCodeSnippet(file: string, startPattern: RegExp): Promise<{ file: string, startIdx: number, lines: string[], language: string }> {
-    const res = await this.read(file);
-    const lines = res.content.split(/\n/g);
+  static async readCodeSnippet(src: string | Function, startPattern: RegExp): Promise<{ file: string, startIdx: number, lines: string[], language: string }> {
+    const res = this.readSource(src);
+    const lines = res.content.split(/\n/);
     const startIdx = lines.findIndex(l => startPattern.test(l));
     if (startIdx < 0) {
-      throw new Error(`Pattern ${startPattern.source} not found in ${file}`);
+      throw new Error(`Pattern ${startPattern.source} not found in ${src}`);
     }
     return { file: res.file, startIdx, lines, language: res.language };
   }
@@ -85,15 +82,14 @@ export class DocFileUtil {
    * Determine if a file is a decorator
    */
   static async isDecorator(name: string, file: string): Promise<boolean> {
-    file = await this.resolveFile(file);
 
     const key = `${name}:${file}`;
     if (key in this.#decCache) {
       return this.#decCache[key];
     }
 
-    const text = (await fs.readFile(file, 'utf8'))
-      .split(/\n/g);
+    const res = await this.readSource(file);
+    const text = res.content.split(/\n/g);
 
     const start = text.findIndex(x => new RegExp(`function ${name}\\b`).test(x));
     let ret = false;

package/src/util/resolve.ts

@@ -13,7 +13,7 @@ export class DocResolveUtil {
   static async resolveRef(title: string, file: string): Promise<ResolvedRef> {
 
     let line = 0;
-    const res = await DocFileUtil.read(file);
+    const res = await DocFileUtil.readSource(file);
     file = res.file;
 
     if (res.content) {
@@ -31,22 +31,22 @@ export class DocResolveUtil {
     return { title, file, line };
   }
 
-  static async resolveCode(content: string, language?: string, outline = false): Promise<ResolvedCode> {
+  static async resolveCode(content: string | Function, language?: string, outline = false): Promise<ResolvedCode> {
+    const res = DocFileUtil.readSource(content);
+    let text = res.content;
+
     let file: string | undefined;
-    if (DocFileUtil.isFile(content)) {
-      const res = await DocFileUtil.read(content);
+    if (res.file) {
       language = res.language;
       file = res.file;
-      content = res.content;
       if (outline) {
-        content = DocFileUtil.buildOutline(content);
+        text = DocFileUtil.buildOutline(text);
       }
     }
-    content = content.replace(/^\/\/# sourceMap.*$/gm, '');
-    return { text: content, language: language!, file };
+    return { text, language: language!, file };
   }
 
-  static async resolveSnippet(file: string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
+  static async resolveSnippet(file: Function | string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
     const { lines, startIdx, language, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
 
     const endIdx = endPattern ? lines.findIndex((l, i) => i > startIdx && endPattern.test(l)) : lines.length;
@@ -59,7 +59,7 @@ export class DocResolveUtil {
     return { text, language, line: startIdx + 1, file: resolvedFile };
   }
 
-  static async resolveCodeLink(file: string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
+  static async resolveCodeLink(file: Function | string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
     const { startIdx, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
     return { file: resolvedFile, line: startIdx + 1 };
   }