@travetto/doc 3.0.0-rc.1 → 3.0.0-rc.4

package/src/render/code-highlight.ts

@@ -1,31 +1,24 @@
-type Lang = {};
-
-// TODO: Get proper typings
-const Prism: {
-  plugins: { NormalizeWhitespace: Record<string, Function> };
-  languages: Record<string, Lang>;
-  highlight(text: string, grammar: Lang, language: string): string;
-} = require('prismjs');
-
-import 'prismjs/plugins/normalize-whitespace/prism-normalize-whitespace';
-import 'prismjs/components/prism-typescript';
-import 'prismjs/components/prism-javascript';
-import 'prismjs/components/prism-css';
-import 'prismjs/components/prism-scss';
-import 'prismjs/components/prism-yaml';
-import 'prismjs/components/prism-json';
-import 'prismjs/components/prism-sql';
-import 'prismjs/components/prism-properties';
-import 'prismjs/components/prism-bash';
-
-Prism.plugins.NormalizeWhitespace.setDefaults({
+import { default as prismjs } from 'prismjs';
+
+import 'prismjs/plugins/normalize-whitespace/prism-normalize-whitespace.js';
+import 'prismjs/components/prism-typescript.js';
+import 'prismjs/components/prism-javascript.js';
+import 'prismjs/components/prism-css.js';
+import 'prismjs/components/prism-scss.js';
+import 'prismjs/components/prism-yaml.js';
+import 'prismjs/components/prism-json.js';
+import 'prismjs/components/prism-sql.js';
+import 'prismjs/components/prism-properties.js';
+import 'prismjs/components/prism-bash.js';
+
+prismjs.plugins.NormalizeWhitespace.setDefaults({
   'remove-trailing': true,
   'remove-indent': true,
   'left-trim': true,
   'right-trim': true
 });
 
-const nw = Prism.plugins.NormalizeWhitespace;
+const nw = prismjs.plugins.NormalizeWhitespace;
 
 const tokenMapping: { [key: string]: string } = {
   gt: '>',
@@ -44,7 +37,7 @@ export function highlight(text: string, lang: string): string | undefined {
     .replace(/&([a-z][^;]*);/g, (a, k) => tokenMapping[k] || a);
 
   try {
-    return Prism.highlight(text, Prism.languages[lang], lang)
+    return prismjs.highlight(text, prismjs.languages[lang], lang)
       .replace(/(@\s*<span[^>]*)function("\s*>)/g, (a, pre, post) => `${pre}meta${post}`)
       .replace(/[{}]/g, a => `{{'${a}'}}`);
   } catch (err) {

package/src/render/context.ts

@@ -1,6 +1,4 @@
-import * as path from 'path';
-
-import { PathUtil, FsUtil, Package, EnvUtil } from '@travetto/boot';
+import { path } from '@travetto/manifest';
 
 import { AllType, AllTypeMap, node as n } from '../nodes';
 import { DocNode, RenderContextShape } from '../types';
@@ -13,31 +11,15 @@ export type AllChildren = AllType;
 export class RenderContext implements RenderContextShape {
 
   file: string;
+  baseUrl: string;
+  travettoBaseUrl: string;
+  repoRoot: string;
 
-  constructor(file: string) {
-    this.file = PathUtil.resolveUnix(file);
-  }
-
-  get #repoUrl(): string {
-    return (Package.repository?.url ?? '').replace(/[.]git$/, '');
-  }
-
-  get gitBaseUrl(): string {
-    return `${this.#repoUrl}/tree/${EnvUtil.get('TRV_DOC_BRANCH', 'main')}`;
-  }
-
-  get travettoGitBaseUrl(): string {
-    return this.#repoUrl.includes('travetto/travetto') ? this.gitBaseUrl : 'https://github.com/travetto/travetto/main';
-  }
-
-  get gitFolder(): string {
-    let base = PathUtil.cwd;
-
-    while (base && !(FsUtil.existsSync(PathUtil.resolveUnix(base, '.git')))) {
-      base = path.dirname(base);
-    }
-
-    return `${this.gitBaseUrl}${PathUtil.cwd.replace(base, '')}`;
+  constructor(file: string, repoRoot: string, baseUrl: string, travettoBaseUrl: string) {
+    this.file = path.toPosix(file);
+    this.baseUrl = baseUrl;
+    this.repoRoot = repoRoot;
+    this.travettoBaseUrl = travettoBaseUrl;
   }
 
   toc(root: DocNode): AllTypeMap['Ordered'] {
@@ -57,15 +39,14 @@ export class RenderContext implements RenderContextShape {
     return n.Group([
       n.Comment('This file was generated by @travetto/doc and should not be modified directly'),
       n.Text('\n'),
-      n.Comment(`Please modify ${this.file.replace(PathUtil.cwd, this.gitFolder)} and execute "npx trv doc" to rebuild`),
+      n.Comment(`Please modify ${this.file.replace(this.repoRoot, this.baseUrl)} and execute "npx trv doc" to rebuild`),
     ]);
   }
 
   link(text: string, line?: number | { [key: string]: unknown, line?: number }): string {
     const num = typeof line === 'number' ? line : line?.line;
-    text = PathUtil.normalizeFrameworkPath(text);
-    return `${text.replace(PathUtil.cwd, this.gitBaseUrl)
-      .replace(/.*@travetto\//, `${this.travettoGitBaseUrl}/module/`)}${num ? `#L${num}` : ''}`;
+    return `${text.replace(this.repoRoot, this.baseUrl)
+      .replace(/.*@travetto\//, `${this.travettoBaseUrl}/module/`)}${num ? `#L${num}` : ''}`;
   }
 
   cleanText(a?: string): string {

package/src/render/markdown.ts

@@ -60,7 +60,7 @@ ${context.cleanText(recurse(c.content))}
       case 'header':
         return `# ${recurse(c.title)}\n${c.description ? `## ${recurse(c.description)}\n` : ''}${'install' in c ? recurse(n.Install(c.package, c.package)) : ''}\n`;
       case 'text':
-        return c.content;
+        return c.content.replace(/ /g, ' ');
     }
   }
 };

package/src/render/prism.d.ts

@@ -1,389 +1,17 @@
-// Type definitions for prismjs 1.16
-// Project: http://prismjs.com/, https://github.com/leaverou/prism
-// Definitions by: Michael Schmidt <https://github.com/RunDevelopment>
-//                 ExE Boss <https://github.com/ExE-Boss>
-//                 Erik Lieben <https://github.com/eriklieben>
-//                 Andre Wiggins <https://github.com/andrewiggins>
-//                 Michał Miszczyszyn <https://github.com/mmiszy>
-// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.8
-
-export as namespace Prism;
-export const languages: Languages;
-export const plugins: Record<string, any>;
-
-/**
- * A function which will be invoked after an element was successfully highlighted.
- *
- * @param element The element successfully highlighted.
- */
-export type HighlightCallback = (element?: any) => void;
-
-/**
- * This is the most high-level function in Prism’s API.
- * It fetches all the elements that have a `.language-xxxx` class and then calls {@link Prism.highlightElement} on
- * each one of them.
- *
- * This is equivalent to `Prism.highlightAllUnder(document, async, callback)`.
- *
- * @param [async=false] Same as in {@link Prism.highlightAllUnder}.
- * @param [callback] Same as in {@link Prism.highlightAllUnder}.
- */
-export function highlightAll(
-  async?: boolean,
-  callback?: HighlightCallback
-): void;
-
-/**
- * Low-level function, only use if you know what you’re doing. It accepts a string of text as input
- * and the language definitions to use, and returns a string with the HTML produced.
- *
- * The following hooks will be run:
- * 1. `before-tokenize`
- * 2. `after-tokenize`
- * 3. `wrap`: On each {@link Prism.Token}.
- *
- * @param text A string with the code to be highlighted.
- * @param grammar An object containing the tokens to use.
- *
- * Usually a language definition like `Prism.languages.markup`.
- * @param language The name of the language definition passed to `grammar`.
- * @returns The highlighted HTML.
- *
- * @example
- * Prism.highlight('var foo = true;', Prism.languages.js, 'js');
- */
-export function highlight(
-  text: string,
-  grammar: Grammar,
-  language: string
-): string;
-
-/**
- * This is the heart of Prism, and the most low-level function you can use. It accepts a string of text as input
- * and the language definitions to use, and returns an array with the tokenized code.
- *
- * When the language definition includes nested tokens, the function is called recursively on each of these tokens.
- *
- * This method could be useful in other contexts as well, as a very crude parser.
- *
- * @param text A string with the code to be highlighted.
- * @param grammar An object containing the tokens to use.
- *
- * Usually a language definition like `Prism.languages.markup`.
- * @returns An array of strings, tokens and other arrays.
- */
-export function tokenize(
-  text: string,
-  grammar: Grammar
-): Array<string | Token>;
-
-export interface Environment extends Record<string, any> {
-  selector?: string;
-  element?: any;
-  language?: string;
-  grammar?: Grammar;
-  code?: string;
-  highlightedCode?: string;
-  type?: string;
-  content?: string;
-  tag?: string;
-  classes?: string[];
-  attributes?: Record<string, string>;
-  parent?: Array<string | Token>;
-}
-
-export namespace util {
-  interface Identifier {
-    value: number;
-  }
-
-  /** Encode raw strings in tokens in preparation to display as HTML */
-  function encode(tokens: TokenStream): TokenStream;
-
-  /** Determine the type of the object */
-  function type(o: null): "Null";
-  function type(o: undefined): "Undefined";
-  // tslint:disable:ban-types
-  function type(o: boolean | Boolean): "Boolean";
-  function type(o: number | Number): "Number";
-  function type(o: string | String): "String";
-  function type(o: Function): "Function";
-  // tslint:enable:ban-types
-  function type(o: RegExp): "RegExp";
-  function type(o: any[]): "Array";
-  function type(o: any): string;
-
-  /** Get the unique id of this object or give it one if it does not have one */
-  function objId(obj: any): Identifier;
-
-  /** Deep clone a language definition (e.g. to extend it) */
-  function clone<T>(o: T): T;
-}
-
-export type GrammarValue = RegExp | TokenObject | Array<RegExp | TokenObject>;
-export type Grammar = GrammarRest & Record<string, GrammarValue>;
-export interface GrammarRest {
-  keyword?: GrammarValue;
-  number?: GrammarValue;
-  function?: GrammarValue;
-  string?: GrammarValue;
-  boolean?: GrammarValue;
-  operator?: GrammarValue;
-  punctuation?: GrammarValue;
-  atrule?: GrammarValue;
-  url?: GrammarValue;
-  selector?: GrammarValue;
-  property?: GrammarValue;
-  important?: GrammarValue;
-  style?: GrammarValue;
-  comment?: GrammarValue;
-  "class-name"?: GrammarValue;
-
-  /**
-   * An optional grammar object that will appended to this grammar.
-   */
-  rest?: Grammar;
-}
-
-/**
- * The expansion of a simple `RegExp` literal to support additional properties.
- */
-export interface TokenObject {
-  /**
-   * The regular expression of the token.
-   */
-  pattern: RegExp;
-
-  /**
-   * If `true`, then the first capturing group of `pattern` will (effectively) behave as a lookbehind
-   * group meaning that the captured text will not be part of the matched text of the new token.
-   */
-  lookbehind?: boolean;
-
-  /**
-   * Whether the token is greedy.
-   *
-   * @default false
-   */
-  greedy?: boolean;
-
-  /**
-   * An optional alias or list of aliases.
-   */
-  alias?: string | string[];
-
-  /**
-   * The nested tokens of this token.
-   *
-   * This can be used for recursive language definitions.
-   *
-   * Note that this can cause infinite recursion.
-   */
-  inside?: Grammar;
-}
-export type Languages = LanguageMapProtocol & LanguageMap;
-export interface LanguageMap {
-  /**
-   * Get a defined language's definition.
-   */
-  [language: string]: Grammar;
-}
-export interface LanguageMapProtocol {
-  /**
-   * Creates a deep copy of the language with the given id and appends the given tokens.
-   *
-   * If a token in `redef` also appears in the copied language, then the existing token in the copied language
-   * will be overwritten at its original position.
-   *
-   * @param id The id of the language to extend. This has to be a key in `Prism.languages`.
-   * @param redef The new tokens to append.
-   * @returns The new language created.
-   * @example
-   * Prism.languages['css-with-colors'] = Prism.languages.extend('css', {
-   *     'color': /\b(?:red|green|blue)\b/
-   * });
-   */
-  extend(id: string, redef: Grammar): Grammar;
-
-  /**
-   * Inserts tokens _before_ another token in a language definition or any other grammar.
-   *
-   * As this needs to recreate the object (we cannot actually insert before keys in object literals),
-   * we cannot just provide an object, we need an object and a key.
-   *
-   * If the grammar of `inside` and `insert` have tokens with the same name, the tokens in `inside` will be ignored.
-   *
-   * All references of the old object accessible from `Prism.languages` or `insert` will be replace with the new one.
-   *
-   * @param inside The property of `root` that contains the object to be modified.
-   *
-   * This is usually a language id.
-   * @param before The key to insert before.
-   * @param insert An object containing the key-value pairs to be inserted.
-   * @param [root] The object containing `inside`, i.e. the object that contains the object that will be modified.
-   *
-   * Defaults to `Prism.languages`.
-   * @returns The new grammar created.
-   * @example
-   * Prism.languages.insertBefore('markup', 'cdata', {
-   *     'style': { ... }
-   * });
-   */
-  insertBefore(
-    inside: string,
-    before: string,
-    insert: Grammar,
-    root: LanguageMap
-  ): Grammar;
-}
-
-export namespace hooks {
-  /**
-   * @param env The environment variables of the hook.
-   */
-  type HookCallback = (env: Environment) => void;
-  type HookTypes = keyof HookEnvironmentMap;
-
-  interface HookEnvironmentMap {
-    "before-highlightall": RequiredEnvironment<"selector">;
-
-    "before-sanity-check": ElementEnvironment;
-    "before-highlight": ElementEnvironment;
-
-    "before-insert": ElementHighlightedEnvironment;
-    "after-highlight": ElementHighlightedEnvironment;
-    complete: ElementHighlightedEnvironment;
-
-    "before-tokenize": TokenizeEnvironment;
-    "after-tokenize": TokenizeEnvironment;
-
-    wrap: RequiredEnvironment<
-      "type" | "content" | "tag" | "classes" | "attributes" | "language"
-    >;
-  }
-
-  type RequiredEnvironment<
-    T extends keyof Environment,
-    U extends Environment = Environment
-    > = U & Required<Pick<U, T>>;
-  type ElementEnvironment = RequiredEnvironment<
-    "element" | "language" | "grammar" | "code"
-  >;
-  type ElementHighlightedEnvironment = RequiredEnvironment<
-    "highlightedCode",
-    ElementEnvironment
-  >;
-  type TokenizeEnvironment = RequiredEnvironment<
-    "code" | "grammar" | "language"
-  >;
-
-  interface RegisteredHooks {
-    [hook: string]: HookCallback[];
-  }
-
-  const all: RegisteredHooks;
-
-  /**
-   * Adds the given callback to the list of callbacks for the given hook.
-   *
-   * The callback will be invoked when the hook it is registered for is run.
-   * Hooks are usually directly run by a highlight function but you can also run hooks yourself.
-   *
-   * One callback function can be registered to multiple hooks and the same hook multiple times.
-   *
-   * @param name The name of the hook.
-   * @param callback The callback function which is given environment variables.
-   */
-  function add<K extends keyof HookEnvironmentMap>(
-    name: K,
-    callback: (env: HookEnvironmentMap[K]) => void
-  ): void;
-  function add(name: string, callback: HookCallback): void;
-
-  /**
-   * Runs a hook invoking all registered callbacks with the given environment variables.
-   *
-   * Callbacks will be invoked synchronously and in the order in which they were registered.
-   *
-   * @param name The name of the hook.
-   * @param env The environment variables of the hook passed to all callbacks registered.
-   */
-  function run<K extends keyof HookEnvironmentMap>(
-    name: K,
-    env: HookEnvironmentMap[K]
-  ): void;
-  function run(name: string, env: Environment): void;
+declare namespace PrismAlt {
+  export interface Grammar { }
+  export const languages: { [language: string]: Grammar; };
+  export const plugins: Record<string, {
+    setDefaults(cfg: Record<string, unknown>): void;
+    normalize(text: string, config?: unknown): string;
+  }>;
+  export function highlight(
+    text: string,
+    grammar: Grammar,
+    language: string
+  ): string;
 }
 
-export type TokenStream = string | Token | Array<string | Token>;
-
-export class Token {
-  /**
-   * Creates a new token.
-   *
-   * @param type See {@link Prism.Token#type type}
-   * @param content See {@link Prism.Token#content content}
-   * @param [alias] The alias(es) of the token.
-   * @param [matchedStr=""] A copy of the full string this token was created from.
-   * @param [greedy=false] See {@link Prism.Token#greedy greedy}
-   */
-  constructor(
-    type: string,
-    content: TokenStream,
-    alias?: string | string[],
-    matchedStr?: string,
-    greedy?: boolean
-  );
-
-  /**
-   * The type of the token.
-   *
-   * This is usually the key of a pattern in a {@link Grammar}.
-   */
-  type: string;
-
-  /**
-   * The strings or tokens contained by this token.
-   *
-   * This will be a token stream if the pattern matched also defined an `inside` grammar.
-   */
-  content: TokenStream;
-
-  /**
-   * The alias(es) of the token.
-   *
-   * @see TokenObject
-   */
-  alias: string | string[];
-
-  /**
-   * The length of the matched string or 0.
-   */
-  length: number;
-
-  /**
-   * Whether the pattern that created this token is greedy or not.
-   *
-   * @see TokenObject
-   */
-  greedy: boolean;
-
-  /**
-   * Converts the given token or token stream to an HTML representation.
-   *
-   * The following hooks will be run:
-   * 1. `wrap`: On each {@link Prism.Token}.
-   *
-   * @param token The token or token stream to be converted.
-   * @param language The name of current language.
-   * @param [parent] The parent token stream, if any.
-   * @return The HTML representation of the token or token stream.
-   * @private
-   */
-  static stringify(
-    token: TokenStream,
-    language: string,
-    parent?: Array<string | Token>
-  ): string;
+declare module "prismjs" {
+  export default PrismAlt;
 }

package/src/render/util.ts

@@ -1,3 +1,5 @@
+import { RootIndex, PackageUtil, path } from '@travetto/manifest';
+
 import { RenderContext } from './context';
 import { Html } from './html';
 import { Markdown } from './markdown';
@@ -29,20 +31,34 @@ export class RenderUtil {
       throw new Error(`Unknown renderer with format: ${fmt}`);
     }
 
+    const mod = RootIndex.getFromSource(file)?.import;
+
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const res = (await import(file)) as DocumentShape;
+    const res = await import(mod!) as DocumentShape;
 
     if (!this.#imported.has(file)) {
       this.#imported.set(file, {
         wrap: res.wrap,
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        root: ('_type' in res.text ? res.text : await res.text()) as AllType
+        root: await res.text() as AllType
       });
     }
 
     const { wrap, root } = this.#imported.get(file)!;
 
-    const ctx = new RenderContext(file);
+    const manifestPkg = PackageUtil.readPackage(RootIndex.getModule('@travetto/manifest')!.source);
+
+    const mf = RootIndex.manifest;
+
+    const pkg = PackageUtil.readPackage(mf.workspacePath);
+    const repoBaseUrl = pkg.travetto?.docBaseUrl ?? mf.mainPath;
+
+    const ctx = new RenderContext(
+      file,
+      path.resolve(pkg.travetto?.docRoot ?? mf.workspacePath),
+      repoBaseUrl,
+      repoBaseUrl.includes('travetto.github') ? repoBaseUrl : manifestPkg.travetto!.docBaseUrl!
+    );
     const content = renderers[fmt].render(root, ctx).replace(/\n{3,100}/msg, '\n\n').trim();
     const preamble = renderers[fmt].render(ctx.preamble, ctx);
     return `${preamble}\n${wrap?.[fmt]?.(content) ?? content}\n`;

package/src/types.ts

@@ -10,7 +10,7 @@ export type Wrapper = Record<string, (c: string) => string>;
  * Document file shape
  */
 export interface DocumentShape<T extends DocNode = DocNode> {
-  text: T | (() => (T | Promise<T>));
+  text: () => (T | Promise<T>);
   wrap?: Wrapper;
 }
 
@@ -27,17 +27,12 @@ export interface RenderContextShape {
   /**
    * Github root for project
    */
-  gitBaseUrl: string;
+  baseUrl: string;
 
   /**
    * Github root for travetto framework
    */
-  travettoGitBaseUrl: string;
-
-  /**
-   * Local folder root for git
-   */
-  gitFolder: string;
+  travettoBaseUrl: string;
 
   /**
    * Get table of contents

package/src/util/file.ts

@@ -1,7 +1,6 @@
-import { readFileSync } from 'fs';
-import * as path from 'path';
+import { existsSync, readFileSync } from 'fs';
 
-import { FsUtil, Package, PathUtil } from '@travetto/boot';
+import { path, RootIndex } from '@travetto/manifest';
 
 const ESLINT_PATTERN = /\s*\/\/ eslint.*$/;
 
@@ -23,12 +22,18 @@ export class FileUtil {
    * @param file
    * @returns
    */
-  static resolveFile(file: string): { resolved: string, cleaned: string } {
-    if (!FsUtil.existsSync(PathUtil.resolveUnix(file))) {
-      file = require.resolve(file);
+  static resolveFile(file: string): string {
+    let resolved = path.resolve(file);
+    if (!existsSync(resolved)) {
+      if (file.endsWith('.ts')) {
+        resolved = RootIndex.resolveFileImport(file);
+        resolved = RootIndex.getSourceFile(resolved);
+      }
+      if (!existsSync(resolved)) {
+        throw new Error(`Unknown file to resolve: ${file}`);
+      }
     }
-    const resolved = PathUtil.resolveUnix(file);
-    return { resolved, cleaned: PathUtil.simplifyPath(resolved, Package.name) };
+    return resolved;
   }
 
   /**
@@ -38,15 +43,14 @@ export class FileUtil {
    * @returns
    */
   static read(file: string): { content: string, language: string, file: string } {
-    const { resolved, cleaned } = this.resolveFile(file);
+    file = this.resolveFile(file);
 
-    const ext = path.extname(resolved).replace(/^[.]/, '');
+    const ext = path.extname(file).replace(/^[.]/, '');
     const language = this.#extToLang[ext] ?? ext;
 
     let text: string | undefined;
     if (language) {
-      text = readFileSync(resolved, 'utf8')
-        .replace(/^\/\/\s*@with-module.*/, '');
+      text = readFileSync(file, 'utf8');
 
       text = text.split(/\n/)
         .map(x => {
@@ -59,21 +63,21 @@ export class FileUtil {
         .join('\n');
     }
 
-    return { content: text ?? '', language, file: cleaned };
+    return { content: text ?? '', language, file };
   }
 
   /**
    * Determine if a file is a decorator
    */
   static isDecorator(name: string, file: string): boolean {
-    const { resolved } = this.resolveFile(file);
+    file = this.resolveFile(file);
 
-    const key = `${name}:${resolved}`;
+    const key = `${name}:${file}`;
     if (key in this.#decCache) {
       return this.#decCache[key];
     }
 
-    const text = readFileSync(resolved, 'utf8')
+    const text = readFileSync(file, 'utf8')
       .split(/\n/g);
 
     const start = text.findIndex(x => new RegExp(`function ${name}\\b`).test(x));