add source location to errors in natspec parsing

Author: frangio

package-lock.json

@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "handlebars": "^4.7.7",
-    "solidity-ast": "^0.4.31"
+    "solidity-ast": "^0.4.38"
   },
   "peerDependencies": {
     "hardhat": "^2.8.0"

package.json

@@ -1,7 +1,7 @@
 import path from 'path';
 import { ContractDefinition, SourceUnit } from 'solidity-ast';
 import { SolcOutput, SolcInput } from 'solidity-ast/solc';
-import { astDereferencer, ASTDereferencer, findAll, isNodeType } from 'solidity-ast/utils';
+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';
@@ -17,6 +17,7 @@ export interface Build {
 
 export interface BuildContext extends Build {
   deref: ASTDereferencer;
+  decodeSrc: SrcDecoder;
 }
 
 export type SiteConfig = Pick<FullConfig, 'pages' | 'exclude' | 'sourcesDir' | 'pageExtension'>;
@@ -63,7 +64,8 @@ export function buildSite(builds: Build[], siteConfig: SiteConfig, properties: P
     output = { ...output, sources: clone(output.sources) };
 
     const deref = astDereferencer(output);
-    const build = { input, output, deref };
+    const decodeSrc = srcDecoder(input, output);
+    const build = { input, output, deref, decodeSrc };
 
     for (const { ast: file } of Object.values(output.sources)) {
       const isNewFile = !seen.has(file.absolutePath);

src/site.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);
+    }
+  }
+}

src/utils/ItemError.ts

@@ -1,9 +1,10 @@
 import { FunctionDefinition } from 'solidity-ast';
 import { findAll } from 'solidity-ast/utils';
-import { DocItemWithContext } from '../site';
+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';
 
@@ -25,7 +26,7 @@ export interface NatSpec {
 }
 
 export function parseNatspec(item: DocItemWithContext): NatSpec {
-  if (!item.__item_context) throw new Error(`Not an item or item is missing context`);
+  if (!item[DOC_ITEM_CONTEXT]) throw new Error(`Not an item or item is missing context`);
 
   let res: NatSpec = {};
 
@@ -46,7 +47,7 @@ export function parseNatspec(item: DocItemWithContext): NatSpec {
   let inheritFrom: FunctionDefinition | undefined;
 
   for (const [, tag = 'notice', content] of tagMatches) {
-    if (content === undefined) throw new Error('Unexpected error');
+    if (content === undefined) throw new ItemError('Unexpected error', item);
 
     if (tag === 'dev' || tag === 'notice') {
       res[tag] ??= '';
@@ -68,20 +69,20 @@ export function parseNatspec(item: DocItemWithContext): NatSpec {
 
     if (tag === 'return') {
       if (!('returnParameters' in item)) {
-        throw new Error(`Item does not contain return parameters`);
+        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 Error(`Got more @return tags than expected for '${item.name}'`);
+        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 Error(`Expected @return tag to start with name '${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() ?? '' });
@@ -97,20 +98,20 @@ export function parseNatspec(item: DocItemWithContext): NatSpec {
 
     if (tag === 'inheritdoc') {
       if (!(item.nodeType === 'FunctionDefinition' || item.nodeType === 'VariableDeclaration')) {
-        throw new Error(`Expected function or variable but saw ${itemType(item)}`);
+        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 Error(`Parent contract '${parentContractName}' not found`);
+        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.__item_context.build.deref('FunctionDefinition', item.baseFunctions[0]!);
+      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;