soliddoc 0.6.0-beta.36

package/src/utils/natspec.ts

@@ -0,0 +1,145 @@
+import { FunctionDefinition } from 'solidity-ast';
+import { findAll } from 'solidity-ast/utils';
+import { DocItemWithContext, DOC_ITEM_CONTEXT } from '../site';
+import { arraysEqual } from './arrays-equal';
+import { execAll } from './execall';
+import { itemType } from './item-type';
+import { ItemError } from './ItemError';
+import { readItemDocs } from './read-item-docs';
+import { getContractsInScope } from './scope';
+
+export interface NatSpec {
+  title?: string;
+  notice?: string;
+  dev?: string;
+  params?: {
+    name: string;
+    description: string;
+  }[];
+  returns?: {
+    name?: string;
+    description: string;
+  }[];
+  custom?: {
+    [tag: string]: string;
+  };
+}
+
+export function parseNatspec(item: DocItemWithContext): NatSpec {
+  if (!item[DOC_ITEM_CONTEXT]) throw new Error(`Not an item or item is missing context`);
+
+  let res: NatSpec = {};
+
+  const docSource = readItemDocs(item);
+  const docString = docSource !== undefined
+    ? cleanUpDocstringFromSource(docSource)
+    : 'documentation' in item && item.documentation
+    ? typeof item.documentation === 'string'
+    ? item.documentation
+    : cleanUpDocstringFromSolc(item.documentation.text)
+    : '';
+
+  const tagMatches = execAll(
+    /^(?:@(\w+|custom:[a-z][a-z-]*) )?((?:(?!^@(?:\w+|custom:[a-z][a-z-]*) )[^])*)/m,
+    docString,
+  );
+
+  let inheritFrom: FunctionDefinition | undefined;
+
+  for (const [, tag = 'notice', content] of tagMatches) {
+    if (content === undefined) throw new ItemError('Unexpected error', item);
+
+    if (tag === 'dev' || tag === 'notice') {
+      res[tag] ??= '';
+      res[tag] += content;
+    }
+
+    if (tag === 'title') {
+      res.title = content.trim();
+    }
+
+    if (tag === 'param') {
+      const paramMatches = content.match(/(\w+) ([^]*)/);
+      if (paramMatches) {
+        const [, name, description] = paramMatches as [string, string, string];
+        res.params ??= [];
+        res.params.push({ name, description: description.trim() });
+      }
+    }
+
+    if (tag === 'return') {
+      if (!('returnParameters' in item)) {
+        throw new ItemError(`Item does not contain return parameters`, item);
+      }
+      res.returns ??= [];
+      const i = res.returns.length;
+      const p = item.returnParameters.parameters[i];
+      if (p === undefined) {
+        throw new ItemError('Got more @return tags than expected', item);
+      }
+      if (!p.name) {
+        res.returns.push({ description: content.trim() });
+      } else {
+        const paramMatches = content.match(/(\w+)( ([^]*))?/);
+        if (!paramMatches || paramMatches[1] !== p.name) {
+          throw new ItemError(`Expected @return tag to start with name '${p.name}'`, item);
+        }
+        const [, name, description] = paramMatches as [string, string, string?];
+        res.returns.push({ name, description: description?.trim() ?? '' });
+      }
+    }
+
+    if (tag?.startsWith('custom:')) {
+      const key = tag.replace(/^custom:/, '');
+      res.custom ??= {};
+      res.custom[key] ??= '';
+      res.custom[key] += content;
+    }
+
+    if (tag === 'inheritdoc') {
+      if (!(item.nodeType === 'FunctionDefinition' || item.nodeType === 'VariableDeclaration')) {
+        throw new ItemError(`Expected function or variable but saw ${itemType(item)}`, item);
+      }
+      const parentContractName = content.trim();
+      const parentContract = getContractsInScope(item)[parentContractName];
+      if (!parentContract) {
+        throw new ItemError(`Parent contract '${parentContractName}' not found`, item);
+      }
+      inheritFrom = [...findAll('FunctionDefinition', parentContract)].find(f => item.baseFunctions?.includes(f.id));
+    }
+  }
+
+  if (docString.length === 0) {
+    if ('baseFunctions' in item && item.baseFunctions?.length === 1) {
+      const baseFn = item[DOC_ITEM_CONTEXT].build.deref('FunctionDefinition', item.baseFunctions[0]!);
+      const shouldInherit = item.nodeType === 'VariableDeclaration' || arraysEqual(item.parameters.parameters, baseFn.parameters.parameters, p => p.name);
+      if (shouldInherit) {
+        inheritFrom = baseFn;
+      }
+    }
+  }
+
+  if (res.dev) res.dev = res.dev.trim();
+  if (res.notice) res.notice = res.notice.trim();
+
+  if (inheritFrom) {
+    res = { ...parseNatspec(inheritFrom as DocItemWithContext), ...res };
+  }
+
+  return res;
+}
+
+// Fix solc buggy parsing of doc comments.
+// Reverse engineered from solc behavior.
+function cleanUpDocstringFromSolc(text: string) {
+  return text
+    .replace(/\n\n?^[ \t]*(?:\*|\/\/\/)/mg, '\n\n')
+    .replace(/^[ \t]?/mg, '');
+}
+
+function cleanUpDocstringFromSource(text: string) {
+  return text
+    .replace(/^\/\*\*(.*)\*\/$/s, '$1')
+    .trim()
+    .replace(/^[ \t]*(\*|\/\/\/)[ \t]?/mg, '');
+}

package/src/utils/read-item-docs.ts

@@ -0,0 +1,26 @@
+import { DocItemWithContext, DOC_ITEM_CONTEXT, Build } from '../site';
+
+export function readItemDocs(item: DocItemWithContext): string | undefined {
+  const { build } = item[DOC_ITEM_CONTEXT];
+  // Note that Solidity 0.5 has item.documentation: string even though the
+  // types do not reflect that. This is why we check typeof === object.
+  if ('documentation' in item && item.documentation && typeof item.documentation === 'object') {
+    const { source, start, length } = decodeSrc(item.documentation.src, build);
+    const content = build.input.sources[source]?.content;
+    if (content !== undefined) {
+      return Buffer.from(content, 'utf8').slice(start, start + length).toString('utf8');
+    }
+  }
+}
+
+function decodeSrc(src: string, build: Build): { source: string; start: number; length: number } {
+  const [start, length, sourceId] = src.split(':').map(s => parseInt(s));
+  if (start === undefined || length === undefined || sourceId === undefined) {
+    throw new Error(`Bad source string ${src}`);
+  }
+  const source = Object.keys(build.output.sources).find(s => build.output.sources[s]?.id === sourceId);
+  if (source === undefined) {
+    throw new Error(`No source with id ${sourceId}`);
+  }
+  return { source, start, length };
+}

package/src/utils/scope.ts

@@ -0,0 +1,63 @@
+import { ContractDefinition, SourceUnit } from "solidity-ast";
+import { findAll, isNodeType } from "solidity-ast/utils";
+import { DocItemWithContext } from "../site";
+import { filterValues, mapValues } from './map-values';
+import { mapKeys } from './map-keys';
+
+type Definition = SourceUnit['nodes'][number] & { name: string };
+type Scope = { [name in string]: () => { namespace: Scope } | { definition: Definition } };
+
+export function getContractsInScope(item: DocItemWithContext) {
+  const cache = new WeakMap<SourceUnit, Scope>();
+
+  return filterValues(
+    flattenScope(run(item.__item_context.file)),
+    isNodeType('ContractDefinition'),
+  );
+
+  function run(file: SourceUnit): Scope {
+    if (cache.has(file)) {
+      return cache.get(file)!;
+    }
+
+    const scope: Scope = {};
+
+    cache.set(file, scope);
+
+    for (const c of file.nodes) {
+      if ('name' in c) {
+        scope[c.name] = () => ({ definition: c });
+      }
+    }
+
+    for (const i of findAll('ImportDirective', file)) {
+      const importedFile = item.__item_context.build.deref('SourceUnit', i.sourceUnit);
+      const importedScope = run(importedFile);
+      if (i.unitAlias) {
+        scope[i.unitAlias] = () => ({ namespace: importedScope });
+      } else if (i.symbolAliases.length === 0) {
+        Object.assign(scope, importedScope);
+      } else {
+        for (const a of i.symbolAliases) {
+          // Delayed function call supports circular dependencies
+          scope[a.local ?? a.foreign.name] = importedScope[a.foreign.name] ?? (() => importedScope[a.foreign.name]!());
+        }
+      }
+    };
+
+    return scope;
+  }
+}
+
+function flattenScope(scope: Scope): Record<string, Definition> {
+  return Object.fromEntries(
+    Object.entries(scope).flatMap(([k, fn]) => {
+      const v = fn();
+      if ('definition' in v) {
+        return [[k, v.definition] as const];
+      } else {
+        return Object.entries(mapKeys(flattenScope(v.namespace), k2 => k + '.' + k2));
+      }
+    }),
+  );
+}

package/src/utils/test.ts

@@ -0,0 +1,18 @@
+import _test, { TestFn } from 'ava';
+import hre from 'hardhat';
+import { BuildInfo } from 'hardhat/types';
+import { promises as fs } from 'fs';
+
+interface Context {
+  build: BuildInfo[];
+}
+
+const test = _test as TestFn<Context>;
+
+test.before('reading build info', async t => {
+  t.context.build = await Promise.all(
+    (await hre.artifacts.getBuildInfoPaths()).map(async p => JSON.parse(await fs.readFile(p, 'utf8')))
+  );
+});
+
+export default test;