@travetto/doc 7.1.4 → 8.0.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "7.1.4",
+  "version": "8.0.0-alpha.0",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,12 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/runtime": "^7.1.4",
-    "@types/prismjs": "^1.26.5",
+    "@travetto/runtime": "^8.0.0-alpha.0",
+    "@types/prismjs": "^1.26.6",
     "prismjs": "^1.30.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^7.1.4"
+    "@travetto/cli": "^8.0.0-alpha.0"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/jsx.ts

@@ -2,7 +2,7 @@ import { castTo, TypedObject } from '@travetto/runtime';
 
 import type { LIBRARIES } from './mapping/library.ts';
 import type { MODULES } from './mapping/module.ts';
-import type { CodeProps, RunConfig } from './util/types.ts';
+import type { CodeProps, CodeSourceInput, RunConfig } from './util/types.ts';
 
 import { createElement, type JSXElement, type JSXComponentFunction as CompFn } from '../support/jsx-runtime.ts';
 import { PackageDocUtil } from './util/package.ts';
@@ -14,7 +14,7 @@ type HeaderProps = { title: string, description?: string };
 type ModuleProps = { name: keyof typeof MODULES };
 type LibraryProps = { name: keyof typeof LIBRARIES };
 type LinkProps = { title: string, href: string, line?: number };
-type CodeLinkProps = { title: string, src: string | Function, startRe: RegExp };
+type CodeLinkProps = { title: string, src: CodeSourceInput, startRe: RegExp };
 type Named = { name: string };
 type Titled = { title: string };
 
@@ -83,7 +83,7 @@ function CodeLinker(titleOrNode: string | JSXElement, src?: string, startRe?: Re
     props = { title: titleOrNode, src: src!, startRe: startRe! };
   } else if (titleOrNode.type === Code) {
     const node: JSXElementByFn<'Code'> = castTo(titleOrNode);
-    const srcName = typeof node.props.src === 'string' ? node.props.src : node.props.src.name;
+    const srcName = typeof node.props.src === 'string' ? node.props.src : (typeof node.props.src === 'function' ? node.props.src.name : '<UNNAMED>');
     props = {
       title: node.props.title ?? srcName,
       src: node.props.src,

package/src/render/renderer.ts

@@ -45,10 +45,10 @@ export class DocRenderer {
   ) {
     const source = DocFileUtil.readSource(cls);
     if (source) {
-      title = (await DocFileUtil.isDecorator(cls.name, source.file)) ? `@${title ?? cls.name}` : (title ?? cls.name);
+      title = DocFileUtil.isDecorator(cls.name, source.file) ? `@${title ?? cls.name}` : (title ?? cls.name);
       const node = this.#support.createElement('CodeLink', {
         src: source.file,
-        startRe: new RegExp(`(class|function|interface)\\s+(${cls.name.replaceAll('$', '\\$')})`),
+        startRe: new RegExp(`(class|function|interface)\\s+(${RegExp.escape(cls.name)})`),
         title
       });
       // @ts-expect-error

package/src/util/file.ts

@@ -1,9 +1,11 @@
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 
-import { AppError, Runtime, RuntimeIndex } from '@travetto/runtime';
+import { RuntimeError, Runtime, RuntimeIndex } from '@travetto/runtime';
 import { type ManifestModuleFileType, ManifestModuleUtil } from '@travetto/manifest';
 
+import type { CodeSourceInput } from './types.ts';
+
 const ESLINT_PATTERN = /\s{0,10}\/\/ eslint.{0,300}$/g;
 const ENV_KEY = /Env.([^.]{1,100})[.]key/g;
 
@@ -24,6 +26,9 @@ const EXT_TO_LANG: Record<string, string> = {
   '.sh': 'bash',
 };
 
+type SourceOutput = { content: string, language: string, file: string };
+type SnippetOutput = { file: string, startIdx: number, lines: string[], language: string };
+
 /**
  * Standard file utilities
  */
@@ -35,7 +40,7 @@ export class DocFileUtil {
     return /^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,10})$/.test(file);
   }
 
-  static readSource(input: string | Function): { content: string, language: string, file: string } {
+  static readSource(input: Exclude<CodeSourceInput, Promise<string>>): SourceOutput {
     let file: string | undefined;
     let content: string | undefined;
 
@@ -55,7 +60,7 @@ export class DocFileUtil {
     } else {
       file = Runtime.getSourceFile(input);
       if (!existsSync(file)) {
-        throw new AppError(`Unknown file: ${typeof input === 'string' ? input : input.name} => ${file}`);
+        throw new RuntimeError(`Unknown file: ${typeof input === 'string' ? input : input.name} => ${file}`);
       }
       content = readFileSync(file, 'utf8');
     }
@@ -83,8 +88,8 @@ export class DocFileUtil {
     }
   }
 
-  static async readCodeSnippet(input: string | Function, startPattern: RegExp): Promise<{ file: string, startIdx: number, lines: string[], language: string }> {
-    const result = this.readSource(input);
+  static async readCodeSnippet(input: CodeSourceInput, startPattern: RegExp): Promise<SnippetOutput> {
+    const result = this.readSource(await input);
     const lines = result.content.split(/\n/);
     const startIdx = lines.findIndex(line => startPattern.test(line));
     if (startIdx < 0) {
@@ -96,14 +101,14 @@ export class DocFileUtil {
   /**
    * Determine if a file is a decorator
    */
-  static async isDecorator(name: string, file: string): Promise<boolean> {
+  static isDecorator(name: string, file: string): boolean {
 
     const key = `${name}:${file}`;
     if (key in this.#decCache) {
       return this.#decCache[key];
     }
 
-    const text = await this.readSource(file);
+    const text = this.readSource(file);
     const lines = text.content.split(/\n/g);
 
     const start = lines.findIndex(line => new RegExp(`function ${name}\\b`).test(line));

package/src/util/resolve.ts

@@ -1,5 +1,5 @@
 import { DocFileUtil } from './file.ts';
-import type { CodeProps } from './types.ts';
+import type { CodeProps, CodeSourceInput } from './types.ts';
 
 export type ResolvedRef = { title: string, file: string, line: number };
 export type ResolvedCode = { text: string, language: string, file?: string };
@@ -14,26 +14,26 @@ export class DocResolveUtil {
   static async resolveRef(title: string, file: string): Promise<ResolvedRef> {
 
     let line = 0;
-    const result = await DocFileUtil.readSource(file);
+    const result = DocFileUtil.readSource(file);
     file = result.file;
 
     if (result.content) {
       line = result.content.split(/\n/g)
-        .findIndex(lineText => new RegExp(`(class|interface|function)[ ]+${title.replaceAll('$', '\\$')}`).test(lineText));
+        .findIndex(lineText => new RegExp(`(class|interface|function)[ ]+${RegExp.escape(title)}`).test(lineText));
       if (line < 0) {
         line = 0;
       } else {
         line += 1;
       }
-      if (await DocFileUtil.isDecorator(title, file)) {
+      if (DocFileUtil.isDecorator(title, file)) {
         title = `@${title}`;
       }
     }
     return { title, file, line };
   }
 
-  static async resolveCode(content: string | Function, language?: string, outline = false): Promise<ResolvedCode> {
-    const result = DocFileUtil.readSource(content);
+  static async resolveCode(content: CodeSourceInput, language?: string, outline = false): Promise<ResolvedCode> {
+    const result = DocFileUtil.readSource(await content);
     let text = result.content;
 
     let file: string | undefined;
@@ -47,7 +47,7 @@ export class DocResolveUtil {
     return { text, language: language!, file };
   }
 
-  static async resolveSnippet(file: Function | string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
+  static async resolveSnippet(file: CodeSourceInput, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
     const { lines, startIdx, language, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
 
     const endIdx = endPattern ? lines.findIndex((line, i) => i > startIdx && endPattern.test(line)) : lines.length;
@@ -60,14 +60,14 @@ export class DocResolveUtil {
     return { text, language, line: startIdx + 1, file: resolvedFile };
   }
 
-  static async resolveCodeLink(file: Function | string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
+  static async resolveCodeLink(file: CodeSourceInput, startPattern: RegExp): Promise<ResolvedSnippetLink> {
     const { startIdx, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
     return { file: resolvedFile, line: startIdx + 1 };
   }
 
-  static applyCodePropDefaults(props: CodeProps) {
+  static applyCodePropDefaults(props: CodeProps): void {
     const type = typeof props.src === 'function' ? props.src : undefined;
-    props.startRe ??= (type ? new RegExp(`^(export)?\\s*(interface|class)\\s+${type.name.replaceAll('$', '\\$')}\\b`) : undefined);
+    props.startRe ??= (type ? new RegExp(`^(export)?\\s*(interface|class)\\s+${RegExp.escape(type.name)}\\b`) : undefined);
     props.language ??= (type ? 'typescript' : undefined);
     props.endRe ??= (type ? /^[}]/ : undefined);
     props.title ??= typeof props.src == 'function' ? props.src.name.replace(/^[$]/, '') : undefined;

package/src/util/run.ts

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { Env, ExecUtil, Runtime, RuntimeIndex } from '@travetto/runtime';
 import type { RunConfig } from './types.ts';
 
-export const COMMON_DATE = new Date('2029-03-14T00:00:00.000').getTime();
+export const COMMON_DATE = new Date('2029-03-14T00:00:00.000-0400').getTime();
 
 class DocState {
   baseline = COMMON_DATE;

package/src/util/types.ts

@@ -9,4 +9,6 @@ export type RunConfig = {
   spawn?: (cmd: string, args: string[], options: SpawnOptions) => ChildProcess;
 };
 
-export type CodeProps = { title?: string, src: string | Function, language?: string, outline?: boolean, startRe?: RegExp, endRe?: RegExp };
+export type CodeSourceInput = string | Promise<string> | Function;
+
+export type CodeProps = { title?: string, src: CodeSourceInput, language?: string, outline?: boolean, startRe?: RegExp, endRe?: RegExp };