soliddoc 0.6.0-beta.36

package/src/site.ts

@@ -0,0 +1,144 @@
+import path from 'path';
+import { ContractDefinition, SourceUnit } from 'solidity-ast';
+import { SolcOutput, SolcInput } from 'solidity-ast/solc';
+import { astDereferencer, ASTDereferencer, findAll, isNodeType, srcDecoder, SrcDecoder } from 'solidity-ast/utils';
+import { FullConfig } from './config';
+import { DocItem, docItemTypes, isDocItem } from './doc-item';
+import { Properties } from './templates';
+import { clone } from './utils/clone';
+import { isChild } from './utils/is-child';
+import { mapValues } from './utils/map-values';
+import { defineGetterMemoized } from './utils/memoized-getter';
+
+export interface Build {
+  input: SolcInput;
+  output: SolcOutput;
+}
+
+export interface BuildContext extends Build {
+  deref: ASTDereferencer;
+  decodeSrc: SrcDecoder;
+}
+
+export type SiteConfig = Pick<FullConfig, 'pages' | 'exclude' | 'sourcesDir' | 'pageExtension'>;
+export type PageStructure = SiteConfig['pages'];
+export type PageAssigner = ((item: DocItem, file: SourceUnit, config: SiteConfig) => string | undefined);
+
+export const pageAssigner: Record<PageStructure & string, PageAssigner> = {
+  single: (_1, _2, { pageExtension: ext }) => 'index' + ext,
+  items: (item, _, { pageExtension: ext }) => item.name + ext,
+  files: (_, file, { pageExtension: ext, sourcesDir }) =>
+    path.relative(sourcesDir, file.absolutePath).replace('.sol', ext),
+};
+
+export interface Site {
+  items: DocItemWithContext[];
+  pages: Page[];
+}
+
+export interface Page {
+  id: string;
+  items: DocItemWithContext[];
+}
+
+export const DOC_ITEM_CONTEXT = '__item_context' as const;
+export type DocItemWithContext = DocItem & { [DOC_ITEM_CONTEXT]: DocItemContext };
+
+export interface DocItemContext {
+  page?: string;
+  item: DocItemWithContext;
+  contract?: ContractDefinition;
+  file: DocItemContextFile;
+  build: BuildContext;
+}
+
+export interface DocItemContextFile extends SourceUnit {
+  relativePath: string;
+}
+
+export function buildSite(builds: Build[], siteConfig: SiteConfig, properties: Properties = {}): Site {
+  const assign = typeof siteConfig.pages === 'string' ? pageAssigner[siteConfig.pages] : siteConfig.pages;
+
+  const seen = new Set<string>();
+  const items: DocItemWithContext[] = [];
+  const pages: Record<string, DocItemWithContext[]> = {};
+
+  for (let { input, output } of builds) {
+    // Clone because we will mutate in order to add item context.
+    output = { ...output, sources: clone(output.sources) };
+
+    const deref = astDereferencer(output);
+    const decodeSrc = srcDecoder(input, output);
+    const build = { input, output, deref, decodeSrc };
+
+    for (const { ast } of Object.values(output.sources)) {
+      const isNewFile = !seen.has(ast.absolutePath);
+      seen.add(ast.absolutePath);
+
+      const relativePath = path.relative(siteConfig.sourcesDir, ast.absolutePath);
+      const file = Object.assign(ast, { relativePath });
+
+      for (const topLevelItem of file.nodes) {
+        if (!isDocItem(topLevelItem)) continue;
+
+        const page = assignIfIncludedSource(assign, topLevelItem, file, siteConfig);
+
+        const withContext = defineContext(topLevelItem, build, file, page);
+        defineProperties(withContext, properties);
+
+        if (isNewFile && page !== undefined) {
+          (pages[page] ??= []).push(withContext);
+          items.push(withContext);
+        }
+
+        if (!isNodeType('ContractDefinition', topLevelItem)) {
+          continue;
+        }
+
+        for (const item of topLevelItem.nodes) {
+          if (!isDocItem(item)) continue;
+          if (isNewFile && page !== undefined) items.push(item as DocItemWithContext);
+          const contract = topLevelItem.nodeType === 'ContractDefinition' ? topLevelItem : undefined;
+          const withContext = defineContext(item, build, file, page, contract);
+          defineProperties(withContext, properties);
+        }
+      }
+    }
+  }
+
+  return {
+    items,
+    pages: Object.entries(pages).map(([id, pageItems]) => ({ id, items: pageItems })),
+  };
+}
+
+function defineContext(item: DocItem, build: BuildContext, file: DocItemContextFile, page?: string, contract?: ContractDefinition): DocItemWithContext {
+  return Object.assign(item, {
+    [DOC_ITEM_CONTEXT]: { build, file, contract, page, item: item as DocItemWithContext },
+  });
+}
+
+function defineProperties(item: DocItemWithContext, properties: Properties) {
+  for (const [prop, fn] of Object.entries(properties)) {
+    const original: unknown = (item as any)[prop];
+    defineGetterMemoized(item as any, prop, () => fn(item.__item_context, original));
+  }
+}
+
+function assignIfIncludedSource(
+  assign: PageAssigner,
+  item: DocItem,
+  file: DocItemContextFile,
+  config: SiteConfig,
+) {
+  return isFileIncluded(file.absolutePath, config)
+    ? assign(item, file, config)
+    : undefined;
+}
+
+function isFileIncluded(file: string, config: SiteConfig) {
+  return (
+    isChild(file, config.sourcesDir) &&
+    config.exclude.every(e => !isChild(file, path.join(config.sourcesDir, e)))
+  );
+}

package/src/templates.ts

@@ -0,0 +1,116 @@
+import path from 'path';
+import fs, { promises as fsPromise } from 'fs';
+import Handlebars, { RuntimeOptions } from 'handlebars';
+import { findIn } from './utils/fs-exists';
+import { mapValues } from './utils/map-values';
+import { mapKeys } from './utils/map-keys';
+import { DocItemContext } from './site';
+
+import * as defaultProperties from './common/properties';
+
+export type PropertyGetter = (ctx: DocItemContext, original?: unknown) => unknown;
+export type Properties = Record<string, PropertyGetter>;
+
+export interface Templates {
+  partials?: Record<string, () => string>;
+  helpers?: Record<string, (...args: unknown[]) => string>;
+  properties?: Record<string, PropertyGetter>;
+}
+
+/**
+ * Loads the templates that will be used for rendering a site based on a
+ * default theme and user templates.
+ *
+ * The result contains all partials, helpers, and property getters defined in
+ * the user templates and the default theme, where the user's take precedence
+ * if there is a clash. Additionally, all theme partials and helpers are
+ * included with the theme prefix, e.g. `markdown/contract` will be a partial.
+ */
+export async function loadTemplates(defaultTheme: string, root: string, userTemplatesPath?: string): Promise<Templates> {
+  const themes = await readThemes();
+
+  // Initialize templates with the default theme.
+  const templates: Required<Templates> = {
+    partials: { ...themes[defaultTheme]?.partials },
+    helpers: { ...themes[defaultTheme]?.helpers },
+    properties: { ...defaultProperties },
+  };
+
+  // Overwrite default theme with user templates.
+  if (userTemplatesPath) {
+    const userTemplates = await readTemplates(path.resolve(root, userTemplatesPath));
+    Object.assign(templates.partials, userTemplates.partials);
+    Object.assign(templates.helpers, userTemplates.helpers);
+    Object.assign(templates.properties, userTemplates.properties);
+  }
+
+  // Add partials and helpers from all themes, prefixed with the theme name.
+  for (const [themeName, theme] of Object.entries(themes)) {
+    const addPrefix = (k: string) => `${themeName}/${k}`;
+    Object.assign(templates.partials, mapKeys(theme.partials, addPrefix));
+    Object.assign(templates.helpers, mapKeys(theme.helpers, addPrefix));
+  }
+
+  return templates;
+}
+
+/**
+ * Read templates and helpers from a directory.
+ */
+export async function readTemplates(partialsDir: string, helpersDir = partialsDir): Promise<Required<Templates>> {
+  return {
+    partials: await readPartials(partialsDir),
+    helpers: await readHelpers(helpersDir, 'helpers'),
+    properties: await readHelpers(helpersDir, 'properties'),
+  };
+}
+
+async function readPartials(dir: string) {
+  const partials: NonNullable<Templates['partials']> = {};
+  for (const p of await fsPromise.readdir(dir)) {
+    const { name, ext } = path.parse(p);
+    if (ext === '.hbs') {
+      partials[name] = () => fs.readFileSync(path.join(dir, p), 'utf8');
+    }
+  }
+  return partials;
+}
+
+async function readHelpers(dir: string, name: string) {
+  let helpersPath;
+  try {
+    helpersPath = require.resolve(path.join(dir, name));
+  } catch {
+    return {};
+  }
+  const h = await import(helpersPath);
+  const helpers: Record<string, (...args: any[]) => any> = {};
+  for (const name in h) {
+    if (typeof h[name] === 'function') {
+      helpers[name] = h[name];
+    }
+  }
+  return helpers;
+}
+
+/**
+ * Reads all built-in themes into an object. Partials will always be found in
+ * src/themes, whereas helpers may instead be found in dist/themes if TypeScript
+ * can't be imported directly.
+ */
+async function readThemes(): Promise<Record<string, Required<Templates>>> {
+  const themes: Record<string, Required<Templates>> = {};
+
+  // Handlebars partials are located in src and not in dist
+  const srcThemes = path.resolve(__dirname, '../src/themes');
+  const distThemes = path.resolve(__dirname, 'themes');
+
+  for (const theme of await fsPromise.readdir(srcThemes, { withFileTypes: true })) {
+    if (theme.isDirectory()) {
+      const { name } = theme;
+      themes[name] = await readTemplates(path.join(srcThemes, name), path.join(distThemes, name));
+    }
+  }
+
+  return themes;
+}

package/src/themes/markdown/common.hbs

@@ -0,0 +1,34 @@
+{{h}} {{name}}
+
+{{#if signature}}
+```solidity
+{{{signature}}}
+```
+{{/if}}
+
+{{{natspec.notice}}}
+
+{{#if natspec.dev}}
+_{{{natspec.dev}}}_
+{{/if}}
+
+{{#if natspec.params}}
+{{h 2}} Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+{{#each params}}
+| {{name}} | {{type}} | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
+
+{{#if natspec.returns}}
+{{h 2}} Return Values
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+{{#each returns}}
+| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} |
+{{/each}}
+{{/if}}
+

package/src/themes/markdown/contract.hbs

@@ -0,0 +1,8 @@
+{{>common}}
+
+{{#each items}}
+{{#hsection}}
+{{>item}}
+{{/hsection}}
+
+{{/each}}

package/src/themes/markdown/enum.hbs

@@ -0,0 +1,9 @@
+{{>common}}
+
+```solidity
+enum {{name}} {
+{{#each members}}
+  {{name}}{{#unless @last}},{{/unless}}
+{{/each}}
+}
+```

package/src/themes/markdown/error.hbs

@@ -0,0 +1 @@
+{{>common}}

package/src/themes/markdown/event.hbs

@@ -0,0 +1 @@
+{{>common}}

package/src/themes/markdown/function.hbs

@@ -0,0 +1 @@
+{{>common}}

package/src/themes/markdown/helpers.ts

@@ -0,0 +1,49 @@
+import { HelperOptions, Utils } from 'handlebars';
+
+export * from '../../common/helpers';
+
+/**
+ * Returns a Markdown heading marker. An optional number increases the heading level.
+ *
+ *    Input                  Output
+ *    {{h}} {{name}}         # Name
+ *    {{h 2}} {{name}}       ## Name
+ */
+export function h(opts: HelperOptions): string;
+export function h(hsublevel: number, opts: HelperOptions): string;
+export function h(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  const { hlevel } = getHLevel(hsublevel, opts);
+  return new Array(hlevel).fill('#').join('');
+};
+
+/**
+ * Delineates a section where headings should be increased by 1 or a custom number.
+ *
+ *    {{#hsection}}
+ *    {{>partial-with-headings}}
+ *    {{/hsection}}
+ */
+export function hsection(opts: HelperOptions): string;
+export function hsection(hsublevel: number, opts: HelperOptions): string;
+export function hsection(this: unknown, hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  let hlevel;
+  ({ hlevel, opts } = getHLevel(hsublevel, opts));
+  opts.data = Utils.createFrame(opts.data);
+  opts.data.hlevel = hlevel;
+  return opts.fn(this as unknown, opts);
+}
+
+/**
+ * Helper for dealing with the optional hsublevel argument.
+ */
+function getHLevel(hsublevel: number | HelperOptions, opts?: HelperOptions) {
+  if (typeof hsublevel === 'number') {
+    opts = opts!;
+    hsublevel = Math.max(1, hsublevel);
+  } else {
+    opts = hsublevel;
+    hsublevel = 1;
+  }
+  const contextHLevel: number = opts.data?.hlevel ?? 0;
+  return { opts, hlevel: contextHLevel + hsublevel };
+}

package/src/themes/markdown/modifier.hbs

@@ -0,0 +1 @@
+{{>common}}

package/src/themes/markdown/page.hbs

@@ -0,0 +1,8 @@
+# Solidity API
+
+{{#each items}}
+{{#hsection}}
+{{>item}}
+{{/hsection}}
+
+{{/each}}

package/src/themes/markdown/struct.hbs

@@ -0,0 +1,9 @@
+{{>common}}
+
+```solidity
+struct {{name}} {
+{{#each members}}
+  {{{typeName.typeDescriptions.typeString}}} {{name}};
+{{/each}}
+}
+```

package/src/themes/markdown/user-defined-value-type.hbs

@@ -0,0 +1 @@
+{{>common}}

package/src/themes/markdown/variable.hbs

@@ -0,0 +1 @@
+{{>common}}

package/src/utils/ItemError.ts

@@ -0,0 +1,13 @@
+import { DocItemWithContext, DOC_ITEM_CONTEXT } from '../site';
+
+export class ItemError extends Error {
+  constructor(msg: string, item: DocItemWithContext) {
+    const ctx = item[DOC_ITEM_CONTEXT];
+    const src = ctx && ctx.build.decodeSrc(item);
+    if (src) {
+      super(msg + ` (${src})`);
+    } else {
+      super(msg);
+    }
+  }
+}

package/src/utils/arrays-equal.ts

@@ -0,0 +1,5 @@
+export function arraysEqual<T>(a: T[], b: T[]): boolean;
+export function arraysEqual<T, U>(a: T[], b: T[], mapFn: (x: T) => U): boolean;
+export function arraysEqual<T>(a: T[], b: T[], mapFn = (x: T) => x): boolean {
+  return a.length === b.length && a.every((x, i) => mapFn(x) === mapFn(b[i]!));
+}

package/src/utils/assert-equal-types.ts

@@ -0,0 +1 @@
+export type AssertEqual<T, U> = [T, U] extends [U, T] ? true : never;

package/src/utils/clone.ts

@@ -0,0 +1,6 @@
+/**
+ * Deep cloning good enough for simple objects like solc output. Types are not
+ * sound because the function may lose information: non-enumerable properties,
+ * symbols, undefined values, prototypes, etc.
+ */
+export const clone = <T>(obj: T): T => JSON.parse(JSON.stringify(obj));

package/src/utils/ensure-array.ts

@@ -0,0 +1,12 @@
+// The function below would not be correctly typed if the return type was T[]
+// because T may itself be an array type and Array.isArray would not know the
+// difference. Adding IfArray<T> makes sure the return type is always correct.
+type IfArray<T> = T extends any[] ? T : never;
+
+export function ensureArray<T>(x: T | T[]): T[] | IfArray<T> {
+  if (Array.isArray(x)) {
+    return x;
+  } else {
+    return [x];
+  }
+}

package/src/utils/execall.ts

@@ -0,0 +1,18 @@
+/**
+ * Iterates over all contiguous matches of the regular expression over the
+ * text. Stops as soon as the regular expression no longer matches at the
+ * current position.
+ */
+export function* execAll(re: RegExp, text: string) {
+  re = new RegExp(re, re.flags + (re.sticky ? '' : 'y'));
+
+  while (true) {
+    const match = re.exec(text);
+
+    // We break out of the loop if there is no match or if the empty string is
+    // matched because no progress will be made and it will loop indefinitely.
+    if (!match?.[0]) break;
+
+    yield match;
+  }
+}

package/src/utils/fs-exists.ts

@@ -0,0 +1,23 @@
+import { promises as fs, constants } from 'fs';
+import path from 'path';
+
+export async function exists(path: string, mode: number = constants.R_OK): Promise<boolean> {
+  try {
+    await fs.access(path, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function findExists(...paths: string[]): Promise<string | undefined> {
+  for (const p of paths) {
+    if (await exists(p)) {
+      return p;
+    }
+  }
+}
+
+export async function findIn(f: string, dirs: string[]): Promise<string | undefined> {
+  return findExists(...dirs.map(d => path.resolve(d, f)));
+}

package/src/utils/is-child.ts

@@ -0,0 +1,5 @@
+import path from 'path';
+
+export function isChild(file: string, parent: string) {
+  return path.normalize(file + path.sep).startsWith(path.normalize(parent + path.sep));
+}

package/src/utils/item-type.ts

@@ -0,0 +1,7 @@
+import { DocItem } from '../doc-item';
+
+export function itemType(item: DocItem): string {
+  return item.nodeType
+    .replace(/(Definition|Declaration)$/, '')
+    .replace(/(\w)([A-Z])/g, '$1 $2');
+}

package/src/utils/map-keys.ts

@@ -0,0 +1,4 @@
+export function mapKeys<T>(obj: Record<string, T>, fn: (key: string) => string): Record<string, T> {
+  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [fn(k), v]));
+}
+

package/src/utils/map-values.ts

@@ -0,0 +1,19 @@
+export function mapValues<T, U>(obj: Record<string, T>, fn: (value: T) => U): Record<string, U> {
+  const res: Record<string, U> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    res[k] = fn(v);
+  }
+  return res;
+}
+
+export function filterValues<T, U extends T>(obj: Record<string, T>, fn: (value: T) => value is U): Record<string, U>;
+export function filterValues<T>(obj: Record<string, T>, fn: (value: T) => boolean): Record<string, T>;
+export function filterValues<T>(obj: Record<string, T>, fn: (value: T) => boolean): Record<string, T> {
+  const res: Record<string, T> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (fn(v)) {
+      res[k] = v;
+    }
+  }
+  return res;
+}

package/src/utils/memoized-getter.ts

@@ -0,0 +1,23 @@
+export function defineGetterMemoized<K extends keyof any, T, O extends { [k in K]?: T }>(obj: O, key: K, getter: () => T) {
+  let state: 'todo' | 'doing' | 'done' = 'todo';
+  let value: T;
+
+  Object.defineProperty(obj, key, {
+    enumerable: true,
+    get() {
+      switch (state) {
+        case 'done': 
+          return value;
+
+        case 'doing':
+          throw new Error("Detected recursion");
+
+        case 'todo':
+          state = 'doing';
+          value = getter();
+          state = 'done';
+          return value;
+      }
+    }
+  });
+}