@travetto/doc 2.1.1 → 2.2.0

package/README.md

@@ -142,7 +142,7 @@ Sample documentation for fictional module.  This module fictitiously relies upon
       <cite><a target="_blank" href="https://github.com/travetto/travetto/tree/main/module/doc/docs/test.ts">Source</a></cite>
       </figcaption>
       <pre><code class="language-typescript"><span class="token keyword">class</span> <span class="token class-name">TestFile</span> <span class="token punctuation">{{'{'}}</span>
-  <span class="token keyword">static</span> <span class="token function">method</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{{'{'}}</span> <span class="token punctuation">{{'}'}}</span>
+  <span class="token keyword">static</span> <span class="token function">method</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token keyword">void</span> <span class="token punctuation">{{'{'}}</span> <span class="token punctuation">{{'}'}}</span>
 <span class="token punctuation">{{'}'}}</span></code></pre>     
       </figure>
 

package/bin/cli-doc.ts

@@ -11,6 +11,7 @@ import { PathUtil } from '@travetto/boot';
 export class DocPlugin extends BasePlugin {
   name = 'doc';
 
+  // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
   getOptions() {
     return {
       input: this.option({ desc: 'Input File', def: 'doc.ts' }),
@@ -20,7 +21,7 @@ export class DocPlugin extends BasePlugin {
     };
   }
 
-  async envInit() {
+  async envInit(): Promise<void> {
     EnvInit.init({
       debug: '0',
       append: {
@@ -35,7 +36,9 @@ export class DocPlugin extends BasePlugin {
     });
   }
 
-  async action() {
+  async action(): Promise<void> {
+    console.error(process.env);
+
     const { PhaseManager } = await import('@travetto/base');
     // Standard compile
     await PhaseManager.run('init');
@@ -46,7 +49,7 @@ export class DocPlugin extends BasePlugin {
 
     // If specifying output
     if (this.cmd.output.length) {
-      const write = async () => {
+      const write = async (): Promise<void> => {
         RenderUtil.purge(docFile);
         for (const out of this.cmd.output) {
           const fmt = path.extname(out) ?? this.cmd.format;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/doc",
   "displayName": "Documentation",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Documentation support for the travetto framework",
   "keywords": [
     "docs",
@@ -25,11 +25,11 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/base": "^2.1.1",
-    "prismjs": "^1.27.0"
+    "@travetto/base": "^2.2.0",
+    "prismjs": "^1.28.0"
   },
   "optionalPeerDependencies": {
-    "@travetto/cli": "^2.1.1"
+    "@travetto/cli": "^2.2.0"
   },
   "private": false,
   "publishConfig": {

package/src/doc.ts

@@ -1,6 +1,6 @@
 import { AllType, node } from './nodes';
 
-export function doc(values: TemplateStringsArray, ...keys: (AllType | { ᚕfile: string, name: string } | string)[]) {
+export function doc(values: TemplateStringsArray, ...keys: (AllType | { ᚕfile: string, name: string } | string)[]): AllType {
   const out: AllType[] = [];
 
   keys.forEach((el, i) =>
@@ -20,4 +20,5 @@ export function doc(values: TemplateStringsArray, ...keys: (AllType | { ᚕfile:
 
 Object.assign(doc, node);
 
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
 export const d = doc as (typeof doc) & (typeof node);

package/src/lib.ts

@@ -88,7 +88,7 @@ export const lib = {
   Busboy: Library('busboy', 'https://github.com/mscdex/busboy'),
   Cookies: Library('cookies', 'https://www.npmjs.com/package/cookies'),
   ServerlessExpress: Library('aws-serverless-express', 'https://github.com/awslabs/aws-serverless-express/blob/master/README.md'),
-  AwsLambdaFastify: Library('aws-lambda-fastify', 'https://github.com/fastify/aws-lambda-fastify/blob/master/README.md'),
+  AwsLambdaFastify: Library('@fastify/aws-lambda', 'https://github.com/fastify/aws-lambda-fastify/blob/master/README.md'),
   Fastify: Library('fastify', 'https://www.fastify.io/'),
   Koa: Library('koa', 'https://koajs.com/'),
 };

package/src/mod.ts

@@ -47,8 +47,12 @@ const MAPPING = {
   Yaml: '@travetto/yaml'
 };
 
-export const mod = new Proxy({}, {
-  get(tgt, p: keyof typeof MAPPING) {
-    return node.Mod(MAPPING[p]);
+export const mod = new Proxy<Record<keyof typeof MAPPING, AllTypeMap['Mod']>>(
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  {} as Record<keyof typeof MAPPING, AllTypeMap['Mod']>,
+  {
+    get(tgt, p: keyof typeof MAPPING): AllTypeMap['Mod'] {
+      return node.Mod(MAPPING[p]);
+    }
   }
-}) as Record<keyof typeof MAPPING, AllTypeMap['Mod']>;
+);

package/src/nodes.ts

@@ -10,15 +10,20 @@ function $c(val: string): TextType;
 function $c(val: DocNode | string): DocNode;
 function $c(val: DocNode | string | undefined): DocNode | undefined;
 function $c(val: string | DocNode | undefined): DocNode | undefined {
-  return val === undefined ? undefined : typeof val === 'string' ? { _type: 'text' as const, content: val } as TextType : val;
+  return val === undefined ? undefined : typeof val === 'string' ?
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    { _type: 'text' as const, content: val } as TextType : val;
 }
-const $n = <T extends string, U extends Record<string, unknown>>(t: T, vals: U) => ({ _type: t, ...vals } as { _type: T } & U);
+const $n = <T extends string, U extends Record<string, unknown>>(t: T, values: U): { _type: T } & U =>
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  ({ _type: t, ...values } as { _type: T } & U);
+
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
 
 /**
  * All Node Types
  */
 export const node = {
-
   buildList(items: Content[], ordered = false) {
     return $n('list', {
       items: items.map(x => {

package/src/render/code-highlight.ts

@@ -1,11 +1,11 @@
 type Lang = {};
 
 // TODO: Get proper typings
-const Prism = require('prismjs') as {
+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';
@@ -34,7 +34,7 @@ const tokenMapping: { [key: string]: string } = {
   apos: "'"
 };
 
-export function highlight(text: string, lang: string) {
+export function highlight(text: string, lang: string): string | undefined {
   text = nw.normalize(text, {
     indent: 0
   });
@@ -47,8 +47,12 @@ export function highlight(text: string, lang: string) {
     return Prism.highlight(text, Prism.languages[lang], lang)
       .replace(/(@\s*<span[^>]*)function("\s*>)/g, (a, pre, post) => `${pre}meta${post}`)
       .replace(/[{}]/g, a => `{{'${a}'}}`);
-  } catch (e) {
-    console.error(e.message as string, { error: e });
+  } catch (err) {
+    if (err instanceof Error) {
+      console.error(err.message, { error: err });
+    } else {
+      throw err;
+    }
   }
 }
 

package/src/render/context.ts

@@ -18,19 +18,19 @@ export class RenderContext implements RenderContextShape {
     this.file = PathUtil.resolveUnix(file);
   }
 
-  get #repoUrl() {
+  get #repoUrl(): string {
     return (Package.repository?.url ?? '').replace(/[.]git$/, '');
   }
 
-  get gitBaseUrl() {
+  get gitBaseUrl(): string {
     return `${this.#repoUrl}/tree/${EnvUtil.get('TRV_DOC_BRANCH', 'main')}`;
   }
 
-  get travettoGitBaseUrl() {
+  get travettoGitBaseUrl(): string {
     return this.#repoUrl.includes('travetto/travetto') ? this.gitBaseUrl : 'https://github.com/travetto/travetto/main';
   }
 
-  get gitFolder() {
+  get gitFolder(): string {
     let base = PathUtil.cwd;
 
     while (base && !(FsUtil.existsSync(PathUtil.resolveUnix(base, '.git')))) {
@@ -40,18 +40,20 @@ export class RenderContext implements RenderContextShape {
     return `${this.gitBaseUrl}${PathUtil.cwd.replace(base, '')}`;
   }
 
-  toc(root: DocNode) {
+  toc(root: DocNode): AllTypeMap['Ordered'] {
     return n.Ordered(
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
       ...(root as AllTypeMap['Group']).nodes
         .filter(x => x._type === 'section')
         .map(x => {
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
           const { title } = x as AllTypeMap['Section'];
           return n.Anchor(title, title);
         })
     );
   }
 
-  get preamble() {
+  get preamble(): AllTypeMap['Group'] {
     return n.Group([
       n.Comment('This file was generated by @travetto/doc and should not be modified directly'),
       n.Text('\n'),
@@ -59,18 +61,18 @@ export class RenderContext implements RenderContextShape {
     ]);
   }
 
-  link(text: string, line?: number | { [key: string]: unknown, line?: number }) {
+  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}` : ''}`;
   }
 
-  cleanText(a?: string) {
+  cleanText(a?: string): string {
     return a ? a.replace(/^[\n ]+|[\n ]+$/gs, '') : '';
   }
 
-  getAnchorId(a: string) {
+  getAnchorId(a: string): string {
     return a.toLowerCase().replace(/<[^>]+>/g, ' ').replace(/[^a-z0-9]+/g, ' ').trim().replace(/ /g, '-');
   }
 }

package/src/render/html.ts

@@ -9,7 +9,8 @@ const ENTITY_RE = new RegExp(`[${Object.keys(ESCAPE_ENTITIES).join('')}]`, 'gm')
 export const Html: Renderer = {
   ext: 'html',
   render(c: AllChildren, context: RenderContext, root = c) {
-    const recurse = (s: AllChildren | DocNode) => this.render(s as AllChildren, context, root);
+    // 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': {
         const content = recurse(n.Group([n.SubSection(c.title), context.toc(root)]));

package/src/render/markdown.ts

@@ -2,12 +2,13 @@ import { AllType, node as n } from '../nodes';
 import { DocNode, Renderer } from '../types';
 import { AllChildren, RenderContext } from './context';
 
-const titleCase = (a: string) => a.replace(/^[a-z]/, v => v.toUpperCase());
+const titleCase = (a: string): string => a.replace(/^[a-z]/, v => v.toUpperCase());
 
 export const Markdown: Renderer = {
   ext: 'md',
   render(c: AllChildren, context: RenderContext, root: AllType = c) {
-    const recurse = (s: AllChildren | DocNode) => this.render(s as AllChildren, context, root);
+    // 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)}**`;

package/src/render/util.ts

@@ -13,7 +13,7 @@ export class RenderUtil {
 
   static #imported = new Map<string, { root: AllType, wrap?: Wrapper }>();
 
-  static purge(file: string) {
+  static purge(file: string): void {
     this.#imported.delete(file);
   }
 
@@ -23,17 +23,19 @@ export class RenderUtil {
    * @param fmt
    * @returns
    */
-  static async render(file: string, fmt: string = Markdown.ext) {
+  static async render(file: string, fmt: string = Markdown.ext): Promise<string> {
     fmt = fmt.replace(/^[.]/, ''); // Strip leading .
     if (!renderers[fmt]) {
       throw new Error(`Unknown renderer with format: ${fmt}`);
     }
 
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     const res = (await import(file)) 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
       });
     }
@@ -41,7 +43,7 @@ export class RenderUtil {
     const { wrap, root } = this.#imported.get(file)!;
 
     const ctx = new RenderContext(file);
-    const content = renderers[fmt].render(root as AllType, ctx).replace(/\n{3,100}/msg, '\n\n').trim();
+    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/util/file.ts

@@ -23,7 +23,7 @@ export class FileUtil {
    * @param file
    * @returns
    */
-  static resolveFile(file: string) {
+  static resolveFile(file: string): { resolved: string, cleaned: string } {
     if (!FsUtil.existsSync(PathUtil.resolveUnix(file))) {
       file = require.resolve(file);
     }
@@ -37,7 +37,7 @@ export class FileUtil {
    * @param file
    * @returns
    */
-  static read(file: string) {
+  static read(file: string): { content: string, language: string, file: string } {
     const { resolved, cleaned } = this.resolveFile(file);
 
     const ext = path.extname(resolved).replace(/^[.]/, '');
@@ -65,7 +65,7 @@ export class FileUtil {
   /**
    * Determine if a file is a decorator
    */
-  static isDecorator(name: string, file: string) {
+  static isDecorator(name: string, file: string): boolean {
     const { resolved } = this.resolveFile(file);
 
     const key = `${name}:${resolved}`;
@@ -94,7 +94,7 @@ export class FileUtil {
    * Clean code snippet
    * @returns
    */
-  static buildOutline(code: string) {
+  static buildOutline(code: string): string {
     let methodPrefix = '';
     code = code.split(/\n/).map((x) => {
       if (!methodPrefix) {

package/src/util/resolve.ts

@@ -6,7 +6,7 @@ import { FileUtil } from './file';
  */
 export class ResolveUtil {
 
-  static resolveRef<T>(title: string | T, file: string) {
+  static resolveRef<T>(title: string | T, file: string): { title: string | T, file: string, line: number } {
 
     let line = 0;
     const { resolved } = FileUtil.resolveFile(file);
@@ -35,7 +35,7 @@ export class ResolveUtil {
     return { title, file, line };
   }
 
-  static resolveCode<T>(content: string | T, language: string, outline = false) {
+  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)) {
@@ -52,7 +52,7 @@ export class ResolveUtil {
     return { content, language, file };
   }
 
-  static resolveConfig<T>(content: string | T, language: string) {
+  static resolveConfig<T>(content: string | T, language: string): { content: string | T, language: string, file?: string } {
     let file: string | undefined;
     if (typeof content === 'string') {
       if (/^[@:A-Za-z0-9\/\\\-_.]+[.](ya?ml|properties)$/.test(content)) {
@@ -65,7 +65,7 @@ export class ResolveUtil {
     return { content, language, file };
   }
 
-  static resolveSnippet(file: string, startPattern: RegExp, endPattern?: RegExp, outline = false) {
+  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;
@@ -85,7 +85,7 @@ export class ResolveUtil {
     return { text, language, line: startIdx + 1, file };
   }
 
-  static resolveSnippetLink(file: string, startPattern: RegExp) {
+  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) {

package/src/util/run.ts

@@ -1,6 +1,6 @@
 import { spawnSync } from 'child_process';
 
-import { PathUtil, ExecUtil, EnvUtil } from '@travetto/boot';
+import { PathUtil, ExecUtil, EnvUtil, ExecutionOptions, ExecutionState } from '@travetto/boot';
 
 export type RunConfig = {
   filter?: (line: string) => boolean;
@@ -9,22 +9,28 @@ export type RunConfig = {
   cwd?: string;
 };
 
+type RunState = {
+  cmd: string;
+  args: string[];
+  opts: ExecutionOptions;
+};
+
 class DocState {
   baseline = new Date(`${new Date().getFullYear()}-03-14T00:00:00.000`).getTime();
   _s = 37;
   ids: Record<string, string> = {};
 
-  rng() {
+  rng(): number {
     this._s = Math.sin(this._s) * 10000;
     return this._s - Math.floor(this._s);
   }
 
-  getDate(d: string) {
+  getDate(d: string): string {
     this.baseline += this.rng() * 1000;
     return new Date(this.baseline).toISOString();
   }
 
-  getId(id: string) {
+  getId(id: string): string {
     if (!this.ids[id]) {
       this.ids[id] = ' '.repeat(id.length).split('').map(x => Math.trunc(this.rng() * 16).toString(16)).join('');
     }
@@ -38,7 +44,7 @@ class DocState {
 export class DocRunUtil {
   static #docState = new DocState();
 
-  static runState(cmd: string, args: string[], config: RunConfig = {}) {
+  static runState(cmd: string, args: string[], config: RunConfig = {}): RunState {
     args = [...args];
     if (cmd.endsWith('.ts')) {
       const mod = config.module ?? 'base';
@@ -64,7 +70,7 @@ export class DocRunUtil {
   /**
    * Clean run output
    */
-  static cleanRunOutput(text: string, cfg: RunConfig) {
+  static cleanRunOutput(text: string, cfg: RunConfig): string {
     text = text.trim()
       // eslint-disable-next-line no-control-regex
       .replace(/\x1b\[[?]?[0-9]{1,2}[a-z]/gi, '')
@@ -83,7 +89,7 @@ export class DocRunUtil {
   /**
    * Run process in the background
    */
-  static runBackground(cmd: string, args: string[], config: RunConfig = {}) {
+  static runBackground(cmd: string, args: string[], config: RunConfig = {}): ExecutionState {
     const state = this.runState(cmd, args, config);
     return ExecUtil.spawn(state.cmd, state.args, {
       ...state.opts,
@@ -94,7 +100,7 @@ export class DocRunUtil {
   /**
    * Run command synchronously and return output
    */
-  static run(cmd: string, args: string[], config: RunConfig = {}) {
+  static run(cmd: string, args: string[], config: RunConfig = {}): string {
     let final: string;
     try {
       const state = this.runState(cmd, args, config);
@@ -110,8 +116,12 @@ export class DocRunUtil {
       }
       final = res.stdout.toString() || res.stderr.toString();
     } catch (err) {
-      console.log('Found!', cmd, args, '\n', err);
-      final = err.message;
+      if (err instanceof Error) {
+        console.log('Found!', cmd, args, '\n', err);
+        final = err.message;
+      } else {
+        throw err;
+      }
     }
 
     return this.cleanRunOutput(final, config);