@travetto/doc 3.0.2 → 3.1.0-rc.0

package/src/render/markdown.ts

@@ -1,67 +1,130 @@
-import { AllType, node as n } from '../nodes';
-import { DocNode, Renderer } from '../types';
-import { AllChildren, RenderContext } from './context';
+import fs from 'fs/promises';
+import { PackageUtil, RootIndex } from '@travetto/manifest';
 
-const titleCase = (a: string): string => a.replace(/^[a-z]/, v => v.toUpperCase());
+import { RenderProvider } from '../types';
+import { c, getComponentName } from '../jsx';
+import { MOD_MAPPING } from '../mapping/mod-mapping';
+import { LIB_MAPPING } from '../mapping/lib-mapping';
+import { RenderContext } from './context';
 
-export const Markdown: Renderer = {
+export const Markdown: RenderProvider<RenderContext> = {
   ext: 'md',
-  render(c: AllChildren, context: RenderContext, root: AllType = c) {
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const recurse = (s: AllChildren | DocNode): string => this.render(s as AllChildren, context, root);
-    switch (c._type) {
-      case 'toc': return recurse(n.Group([n.SubSection(c.title), context.toc(root)]));
-      case 'strong': return `**${recurse(c.content)}**`;
-      case 'group': return c.nodes.map(cc => recurse(cc,)).join('');
-      case 'comment': return `<!-- ${recurse(c.text)} -->`;
-      case 'code':
-      case 'install':
-      case 'terminal':
-      case 'config': return `
-**${titleCase(c._type)}: ${recurse(c.title)}**
-\`\`\`${c.language}
-${context.cleanText(recurse(c.content))}
-\`\`\`\n`;
-      case 'anchor': return `[${recurse(c.title)}](#${context.getAnchorId(recurse(c.fragment))}})`;
-      case 'library':
-      case 'file':
-      case 'ref': return `[${recurse(c.title)}](${context.link(recurse(c.link), c)})`;
-      case 'mod': return `[${recurse(c.title)}](${context.link(recurse(c.link), c)}#readme "${recurse(c.description)}")`;
-      case 'image': return `![${recurse(c.title)}](${context.link(recurse(c.link), c)})`;
-      case 'section': return `## ${recurse(c.title)}`;
-      case 'subsection': return `### ${recurse(c.title)}`;
-      case 'subsubsection': return `#### ${recurse(c.title)}`;
-      case 'command':
-      case 'method':
-      case 'path':
-      case 'class':
-      case 'field':
-      case 'input': return `\`${context.cleanText(recurse(c.content))}\``;
-      case 'note': return `**Note**: ${context.cleanText(recurse(c.content))}`;
-      case 'item': return `${c.ordered ? '1.' : '* '} ${recurse(c.node)}`;
-      case 'list': {
-        const out: string[] = [''];
-        for (const el of c.items) {
-          out.push(...recurse(el).split(/\n/g));
-        }
-        for (let i = 0; i < out.length; i++) {
-          out[i] = `   ${out[i]}`;
-        }
-        return out.join('\n');
-      }
-      case 'table': {
-        const header = ['', ...c.headers.map(h => recurse(h)), ''].join('|');
-        const out: string[] = [
-          header,
-          header.replace(/[^|]/g, '-'),
-          ...c.rows.map(row => ['', ...row.map(r => recurse(r)), ''].join('|'))
-        ];
-        return out.join('\n');
+  finalize: (text, context) => {
+    const brand = `<!-- ${context.generatedStamp} -->\n<!-- ${context.rebuildStamp} -->`;
+    const cleaned = text
+      .replace(/(\[[^\]]+\]\([^)]+\))([A-Za-z0-9$]+)/g, (_, link, v) => v === 's' ? _ : `${link} ${v}`)
+      .replace(/(\S)\n(#)/g, (_, l, r) => `${l}\n\n${r}`);
+    return `${brand}\n${cleaned}`;
+  },
+  strong: async ({ recurse }) => `**${await recurse()}**`,
+  hr: async () => '\n------------------\n',
+  br: async () => '\n\n',
+  em: async ({ recurse }) => `*${await recurse()}*`,
+  ul: async ({ recurse }) => `\n${await recurse()}`,
+  ol: async ({ recurse }) => `\n${await recurse()}`,
+  li: async ({ recurse, stack }) => {
+    const parent = stack.reverse().find(x => x.type === 'ol' || x.type === 'ul');
+    const depth = stack.filter(x => x.type === 'ol' || x.type === 'ul').length;
+    return `${'   '.repeat(depth)}${(parent && parent.type === 'ol') ? '1.' : '* '} ${await recurse()}\n`;
+  },
+  table: async ({ recurse }) => recurse(),
+  tbody: async ({ recurse }) => recurse(),
+  td: async ({ recurse }) => `|${await recurse()}`,
+  tr: async ({ recurse }) => `${await recurse()}|\n`,
+  thead: async ({ recurse }) => {
+    const row = await recurse();
+    return `${row}${row.replace(/[^|\n]/g, '-')}`;
+  },
+  h2: async ({ recurse }) => `\n## ${await recurse()}\n\n`,
+  h3: async ({ recurse }) => `\n### ${await recurse()}\n\n`,
+  h4: async ({ recurse }) => `\n#### ${await recurse()}\n\n`,
+  Execution: async ({ context, el, props, createState }) => {
+    const output = await context.execute(el);
+    const displayCmd = props.config?.formatCommand?.(props.cmd, props.args ?? []) ??
+      `${el.props.cmd} ${(el.props.args ?? []).join(' ')}`;
+    const state = createState('Terminal', {
+      language: 'bash',
+      title: el.props.title,
+      src: [`$ ${displayCmd}`, '', context.cleanText(output)].join('\n')
+    });
+    return Markdown.Terminal(state);
+  },
+  Install: async ({ context, el }) =>
+    `\n\n**Install: ${el.props.title}**
+\`\`\`bash
+npm install ${el.props.pkg}
+
+# or
+
+yarn add ${el.props.pkg}
+\`\`\`
+`,
+  Code: async ({ context, el }) => {
+    const name = getComponentName(el.type);
+    const content = await context.resolveCode(el);
+    let lang = content.language;
+    if (!lang) {
+      if (el.type === c.Terminal) {
+        lang = 'bash';
+      } else if (el.type === c.Code) {
+        lang = 'typescript';
       }
-      case 'header':
-        return `# ${recurse(c.title)}\n${c.description ? `## ${recurse(c.description)}\n` : ''}${('install' in c && c.install) ? recurse(n.Install(c.package, c.package)) : ''}\n`;
-      case 'text':
-        return c.content.replace(/&nbsp;/g, ' ');
     }
+    return `\n\n**${name}: ${el.props.title}**
+\`\`\`${lang}
+${context.cleanText(content.text)}
+\`\`\`\n\n`;
+  },
+  Terminal: state => Markdown.Code(state),
+  Config: state => Markdown.Code(state),
+
+  Section: async ({ el, recurse }) => `\n## ${el.props.title}\n${await recurse()}\n`,
+  SubSection: async ({ el, recurse }) => `\n### ${el.props.title}\n${await recurse()}\n`,
+  SubSubSection: async ({ el, recurse }) => `\n#### ${el.props.title}\n${await recurse()}\n`,
+
+  Command: state => Markdown.Input(state),
+  Method: state => Markdown.Input(state),
+  Path: state => Markdown.Input(state),
+  Class: state => Markdown.Input(state),
+  Field: state => Markdown.Input(state),
+  Input: async ({ props }) => `\`${props.name}\``,
+
+  Anchor: async ({ context, props }) => `[${props.title}](#${context.getAnchorId(props.href)})`,
+  File: state => Markdown.Ref(state),
+  Ref: async ({ context, props }) => `[${props.title}](${context.link(props.href, props)})`,
+
+  CodeLink: async ({ context, props, el }) => {
+    const target = await context.resolveCodeLink(el);
+    return `[${props.title}](${context.link(target.file, target)})`;
+  },
+
+  Image: async ({ props, context }) => {
+    if (!/^https?:/.test(props.href) && !(await fs.stat(props.href).catch(() => false))) {
+      throw new Error(`${props.href} is not a valid location`);
+    }
+    return `![${props.title}](${context.link(props.href)})`;
+  },
+  Note: async ({ context, recurse }) => `\n\n**Note**: ${context.cleanText(await recurse())}\n`,
+  Header: async ({ props }) => `# ${props.title}\n${props.description ? `## ${props.description}\n` : ''}\n`,
+
+  StdHeader: async state => {
+    const mod = state.el.props.mod ?? RootIndex.mainPackage.name;
+    const pkg = PackageUtil.readPackage(RootIndex.getModule(mod)!.sourcePath);
+    const title = pkg.travetto?.displayName ?? pkg.name;
+    const desc = pkg.description;
+    let install = '';
+    if (state.el.props.install !== false) {
+      const sub = state.createState('Install', { title: pkg.name, pkg: pkg.name });
+      install = await Markdown.Install(sub);
+    }
+    return `# ${title}\n${desc ? `## ${desc}\n` : ''}${install}\n`;
+  },
+  Mod: async ({ props, context }) => {
+    const cfg = MOD_MAPPING[props.name];
+    return `[${cfg.displayName}](${context.link(cfg.folder, cfg)}#readme "${cfg.description}")`;
+  },
+  Library: async ({ props }) => {
+    const cfg = LIB_MAPPING[props.name];
+    return `[${cfg.title}](${cfg.href})`;
   }
 };

package/src/render/renderer.ts

@@ -0,0 +1,146 @@
+import { ManifestRoot, PackageUtil, path, RootIndex } from '@travetto/manifest';
+
+import { isJSXElement, JSXElement, createFragment, JSXFragmentType } from '@travetto/doc/jsx-runtime';
+
+import { EMPTY_ELEMENT, getComponentName, JSXElementByFn, c } from '../jsx';
+import { DocumentShape, RenderProvider, RenderState } from '../types';
+import { DocFileUtil } from '../util/file';
+
+import { RenderContext } from './context';
+import { Html } from './html';
+import { Markdown } from './markdown';
+
+const providers = { [Html.ext]: Html, [Markdown.ext]: Markdown };
+
+/**
+ * Doc Renderer
+ */
+export class DocRenderer {
+
+  static async get(file: string, manifest: ManifestRoot): Promise<DocRenderer> {
+    const mod = RootIndex.getFromSource(file)?.import;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const res = await import(mod!) as DocumentShape;
+
+    const pkg = PackageUtil.readPackage(manifest.workspacePath);
+    const mainPath = path.resolve(manifest.workspacePath, manifest.mainFolder);
+    const repoBaseUrl = pkg.travetto?.docBaseUrl ?? mainPath;
+    return new DocRenderer(res,
+      new RenderContext(file, repoBaseUrl, path.resolve(pkg.travetto?.docRoot ?? manifest.workspacePath))
+    );
+  }
+
+  #root: DocumentShape;
+  #rootNode: JSXElement | JSXElement[];
+  #support: RenderContext;
+
+  constructor(root: DocumentShape, support: RenderContext) {
+    this.#root = root;
+    this.#support = support;
+  }
+
+  async #render(
+    renderer: RenderProvider<RenderContext>,
+    node: JSXElement[] | JSXElement | string | bigint | object | number | boolean | null | undefined,
+    stack: JSXElement[] = []
+  ): Promise<string> {
+
+    if (node === null || node === undefined) {
+      return '';
+    } else if (Array.isArray(node)) {
+      const out: string[] = [];
+      for (const el of node) {
+        out.push(await this.#render(renderer, el, stack));
+      }
+      return out.join('');
+    } else if (isJSXElement(node)) {
+      let final: JSXElement = node;
+      // Render simple element if needed
+      if (typeof node.type === 'function') {
+        // @ts-expect-error
+        const out = node.type(node.props);
+        final = out !== EMPTY_ELEMENT ? out : final;
+      }
+
+      if (final.type === createFragment || final.type === JSXFragmentType) {
+        return this.#render(renderer, final.props.children ?? []);
+      }
+
+      if (Array.isArray(final)) {
+        return this.#render(renderer, final, stack);
+      }
+
+      const name = getComponentName(final.type);
+      if (name in renderer) {
+        const recurse = () => this.#render(renderer, final.props.children ?? [], [...stack, final]);
+        // @ts-expect-error
+        const state: RenderState<JSXElement, RenderContext> = {
+          el: final, props: final.props, recurse, stack, context: this.#support
+        };
+        state.createState = (key, props) => this.createState(state, key, props);
+        // @ts-expect-error
+        return renderer[name](state);
+      } else {
+        console.log(final);
+        throw new Error(`Unknown element: ${final.type}`);
+      }
+    } else {
+      switch (typeof node) {
+        case 'string': return node.replace(/&nbsp;/g, ' ');
+        case 'number':
+        case 'bigint':
+        case 'boolean': return `${node}`;
+        default: {
+          const meta = (typeof node === 'function' ? RootIndex.getFunctionMetadata(node) : undefined);
+          if (meta && typeof node === 'function') {
+            const title = (await DocFileUtil.isDecorator(node.name, meta.source)) ? `@${node.name}` : node.name;
+            const el = this.#support.createElement('CodeLink', {
+              src: meta.source,
+              startRe: new RegExp(`(class|function)\\s+(${node.name})`),
+              title
+            });
+            // @ts-expect-error
+            const state: RenderState<JSXElementByFn<'CodeLink'>, RenderContext> = {
+              el, props: el.props, recurse: async () => '', context: this.#support, stack: []
+            };
+            // @ts-expect-error
+            state.createState = (key, props) => this.createState(state, key, props);
+            return await renderer.CodeLink(state);
+          }
+          throw new Error(`Unknown object type: ${typeof node}`);
+        }
+      }
+    }
+  }
+
+  createState<K extends keyof typeof c>(
+    state: RenderState<JSXElement, RenderContext>,
+    key: K,
+    props: JSXElementByFn<K>['props']
+    // @ts-expect-error
+  ): RenderState<JSXElementByFn<K>, RenderContext> {
+    const el = this.#support.createElement(key, props);
+    return { ...state, el, props: el.props };
+  }
+
+  /**
+   * Render a context given a specific renderer
+   * @param renderer
+   */
+  async render(fmt: keyof typeof providers): Promise<string> {
+    if (!providers[fmt]) {
+      throw new Error(`Unknown renderer with format: ${fmt}`);
+    }
+    if (!this.#rootNode) {
+      this.#rootNode = (Array.isArray(this.#root.text) || isJSXElement(this.#root.text)) ?
+        this.#root.text : await (this.#root.text());
+    }
+
+    const text = await this.#render(providers[fmt], this.#rootNode);
+    let cleaned = `${text.replace(/\n{3,100}/msg, '\n\n').trim()}\n`;
+    if (this.#root.wrap?.[fmt]) {
+      cleaned = this.#root.wrap[fmt](cleaned);
+    }
+    return providers[fmt].finalize(cleaned, this.#support);
+  }
+}

package/src/types.ts

@@ -1,64 +1,34 @@
-export interface DocNode { _type: string }
+import { JSXElement, ValidHtmlTags } from '../jsx-runtime';
+import { JSXElementByFn, c } from './jsx';
 
-export type Content = DocNode | string;
-
-export type TextType = { _type: 'text', content: string };
-
-export type Wrapper = Record<string, (c: string) => string>;
+export type Wrapper = Record<string, (cnt: string) => string>;
 
 /**
  * Document file shape
  */
-export interface DocumentShape<T extends DocNode = DocNode> {
-  text: () => (T | Promise<T>);
+export interface DocumentShape {
+  text: JSXElement | JSXElement[] | (() => Promise<JSXElement | JSXElement[]>);
   wrap?: Wrapper;
 }
 
-/**
- * Render context shape
- */
-export interface RenderContextShape {
-
-  /**
-   * Filename
-   */
-  file: string;
-
-  /**
-   * Github root for project
-   */
-  baseUrl: string;
-
-  /**
-   * Github root for Travetto framework
-   */
-  travettoBaseUrl: string;
-
-  /**
-   * Get table of contents
-   */
-  toc(root: DocNode): DocNode;
-
-  /**
-   * Generate link location
-   */
-  link(text: string, line?: number | { [key: string]: unknown, line?: number }): string;
-
-  /**
-   * Clean text
-   */
-  cleanText(a?: string): string;
-
-  /**
-   * Get a consistent anchor id
-   */
-  getAnchorId(a: string): string;
-}
+export type RenderState<T extends JSXElement, C> = {
+  el: T;
+  props: T['props'];
+  recurse: () => Promise<string>;
+  stack: JSXElement[];
+  // @ts-expect-error
+  createState: <K extends keyof typeof c>(key: K, props: JSXElementByFn<K>['props']) => RenderState<JSXElementByFn<K>, C>;
+  context: C;
+};
 
 /**
- * Renderer support
+ * Renderer
  */
-export type Renderer = {
-  ext: string;
-  render(node: DocNode, context: RenderContextShape, root?: DocNode): string;
-};
+export type RenderProvider<C> =
+  {
+    ext: string;
+    finalize: (text: string, ctx: C) => string;
+  } &
+  { [K in ValidHtmlTags]: (state: RenderState<JSXElement<K>, C>) => Promise<string>; } &
+  // @ts-expect-error
+  { [K in keyof typeof c]: (state: RenderState<JSXElementByFn<K>, C>) => Promise<string>; };

package/src/util/file.ts

@@ -1,34 +1,39 @@
-import { existsSync, readFileSync } from 'fs';
+import fs from 'fs/promises';
 
-import { path, RootIndex } from '@travetto/manifest';
+import { ManifestModuleUtil, path, RootIndex } from '@travetto/manifest';
 
 const ESLINT_PATTERN = /\s*\/\/ eslint.*$/;
 
 /**
  * Standard file utilities
  */
-export class FileUtil {
+export class DocFileUtil {
 
   static #decCache: Record<string, boolean> = {};
   static #extToLang: Record<string, string> = {
     ts: 'typescript',
+    tsx: 'typescript',
     js: 'javascript',
     yml: 'yaml',
     sh: 'bash',
   };
 
+  static isFile(src: string): boolean {
+    return /^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,10})$/.test(src);
+  }
+
   /**
    * Resolve file
    * @param file
    * @returns
    */
-  static resolveFile(file: string): string {
+  static async resolveFile(file: string): Promise<string> {
     let resolved = path.resolve(file);
-    if (!existsSync(resolved)) {
-      if (file.endsWith('.ts')) {
+    if (!(await fs.stat(resolved).catch(() => false))) {
+      if (ManifestModuleUtil.getFileType(file) === 'ts') {
         resolved = RootIndex.getSourceFile(file);
       }
-      if (!existsSync(resolved)) {
+      if (!(await fs.stat(resolved).catch(() => false))) {
         throw new Error(`Unknown file to resolve: ${file}`);
       }
     }
@@ -41,15 +46,15 @@ export class FileUtil {
    * @param file
    * @returns
    */
-  static read(file: string): { content: string, language: string, file: string } {
-    file = this.resolveFile(file);
+  static async read(file: string): Promise<{ content: string, language: string, file: string }> {
+    file = await this.resolveFile(file);
 
     const ext = path.extname(file).replace(/^[.]/, '');
     const language = this.#extToLang[ext] ?? ext;
 
     let text: string | undefined;
     if (language) {
-      text = readFileSync(file, 'utf8');
+      text = await fs.readFile(file, 'utf8');
 
       text = text.split(/\n/)
         .map(x => {
@@ -65,18 +70,28 @@ export class FileUtil {
     return { content: text ?? '', language, file };
   }
 
+  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);
+    const startIdx = lines.findIndex(l => startPattern.test(l));
+    if (startIdx < 0) {
+      throw new Error(`Pattern ${startPattern.source} not found in ${file}`);
+    }
+    return { file: res.file, startIdx, lines, language: res.language };
+  }
+
   /**
    * Determine if a file is a decorator
    */
-  static isDecorator(name: string, file: string): boolean {
-    file = this.resolveFile(file);
+  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 = readFileSync(file, 'utf8')
+    const text = (await fs.readFile(file, 'utf8'))
       .split(/\n/g);
 
     const start = text.findIndex(x => new RegExp(`function ${name}\\b`).test(x));

package/src/util/resolve.ts

@@ -1,89 +1,66 @@
-import { FileUtil } from './file';
+import { DocFileUtil } from './file';
+
+export type ResolvedRef = { title: string, file: string, line: number };
+export type ResolvedCode = { text: string, language: string, file?: string };
+export type ResolvedSnippet = { text: string, language: string, file: string, line: number };
+export type ResolvedSnippetLink = { file: string, line: number };
 
 /**
  * Resolve utilities
  */
-export class ResolveUtil {
+export class DocResolveUtil {
 
-  static resolveRef<T>(title: string | T, file: string): { title: string | T, file: string, line: number } {
+  static async resolveRef(title: string, file: string): Promise<ResolvedRef> {
 
     let line = 0;
-    const res = FileUtil.read(file);
+    const res = await DocFileUtil.read(file);
     file = res.file;
 
-    if (typeof title == 'string') {
-      if (res.content) {
-        line = res.content.split(/\n/g)
-          .findIndex(x => new RegExp(`(class|function)[ ]+${title}`).test(x));
-        if (line < 0) {
-          line = 0;
-        } else {
-          line += 1;
-        }
-        if (FileUtil.isDecorator(title, file)) {
-          title = `@${title}`;
-        }
+    if (res.content) {
+      line = res.content.split(/\n/g)
+        .findIndex(x => new RegExp(`(class|function)[ ]+${title}`).test(x));
+      if (line < 0) {
+        line = 0;
+      } else {
+        line += 1;
       }
-    }
-    return { title, file, line };
-  }
-
-  static resolveCode<T>(content: string | T, language: string, outline = false): { content: string | T, language: string, file?: string } {
-    let file: string | undefined;
-    if (typeof content === 'string') {
-      if (/^[@:A-Za-z0-9\/\\\-_.]+[.]([a-z]{2,4})$/.test(content)) {
-        const res = FileUtil.read(content);
-        language = res.language;
-        file = res.file;
-        content = res.content;
-        if (outline) {
-          content = FileUtil.buildOutline(content);
-        }
+      if (await DocFileUtil.isDecorator(title, file)) {
+        title = `@${title}`;
       }
-      content = content.replace(/^\/\/# sourceMap.*$/gm, '');
     }
-    return { content, language, file };
+    return { title, file, line };
   }
 
-  static resolveConfig<T>(content: string | T, language: string): { content: string | T, language: string, file?: string } {
+  static async resolveCode(content: string, language?: string, outline = false): Promise<ResolvedCode> {
     let file: string | undefined;
-    if (typeof content === 'string') {
-      if (/^[@:A-Za-z0-9\/\\\-_.]+[.](json|ya?ml|properties)$/.test(content)) {
-        const res = FileUtil.read(content);
-        language = res.language;
-        file = res.file;
-        content = res.content;
+    if (DocFileUtil.isFile(content)) {
+      const res = await DocFileUtil.read(content);
+      language = res.language;
+      file = res.file;
+      content = res.content;
+      if (outline) {
+        content = DocFileUtil.buildOutline(content);
       }
     }
-    return { content, language, file };
+    content = content.replace(/^\/\/# sourceMap.*$/gm, '');
+    return { text: content, language: language!, file };
   }
 
-  static resolveSnippet(file: string, startPattern: RegExp, endPattern?: RegExp, outline = false): { text: string, language: string, file: string, line: number } {
-    const res = FileUtil.read(file);
-    const language = res.language;
-    file = res.file;
-    const content = res.content.split(/\n/g);
-    const startIdx = content.findIndex(l => startPattern.test(l));
-
-    if (startIdx < 0) {
-      throw new Error(`Pattern ${startPattern.source} not found in ${file}`);
-    }
+  static async resolveSnippet(file: string, startPattern: RegExp, endPattern?: RegExp, outline = false): Promise<ResolvedSnippet> {
+    const { lines, startIdx, language, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
 
-    const endIdx = endPattern ? content.findIndex((l, i) => i > startIdx && endPattern.test(l)) : content.length;
-    let text = content.slice(startIdx, endIdx + 1).join('\n');
+    const endIdx = endPattern ? lines.findIndex((l, i) => i > startIdx && endPattern.test(l)) : lines.length;
+    let text = lines.slice(startIdx, endIdx + 1).join('\n');
 
     if (outline) {
-      text = FileUtil.buildOutline(text);
+      text = DocFileUtil.buildOutline(text);
     }
-    return { text, language, line: startIdx + 1, file };
+
+    return { text, language, line: startIdx + 1, file: resolvedFile };
   }
 
-  static resolveSnippetLink(file: string, startPattern: RegExp): { file: string, line: number } {
-    const res = FileUtil.read(file);
-    const line = res.content.split(/\n/g).findIndex(l => startPattern.test(l));
-    if (line < 0) {
-      throw new Error(`Pattern ${startPattern.source} not found in ${file}`);
-    }
-    return { file: res.file, line: line + 1 };
+  static async resolveCodeLink(file: string, startPattern: RegExp): Promise<ResolvedSnippetLink> {
+    const { startIdx, file: resolvedFile } = await DocFileUtil.readCodeSnippet(file, startPattern);
+    return { file: resolvedFile, line: startIdx + 1 };
   }
 }