path: root/packages/sol-doc/src/sol_doc.ts

import * as path from 'path';

import {
    AbiDefinition,
    ConstructorAbi,
    DataItem,
    DevdocOutput,
    EventAbi,
    EventParameter,
    FallbackAbi,
    MethodAbi,
    StandardContractOutput,
} from 'ethereum-types';
import ethUtil = require('ethereumjs-util');
import * as _ from 'lodash';

import { Compiler, CompilerOptions } from '@0x/sol-compiler';
import {
    CustomType,
    CustomTypeChild,
    DocAgnosticFormat,
    DocSection,
    Event,
    EventArg,
    ObjectMap,
    Parameter,
    SolidityMethod,
    Type,
    TypeDocTypes,
} from '@0x/types';

export class SolDoc {
    private _customTypeHashToName: ObjectMap<string> | undefined;
    private static _genEventDoc(abiDefinition: EventAbi): Event {
        const eventDoc: Event = {
            name: abiDefinition.name,
            eventArgs: SolDoc._genEventArgsDoc(abiDefinition.inputs),
        };
        return eventDoc;
    }
    private static _devdocMethodDetailsIfExist(
        methodSignature: string,
        devdocIfExists: DevdocOutput | undefined,
    ): string | undefined {
        let details;
        if (!_.isUndefined(devdocIfExists)) {
            const devdocMethodsIfExist = devdocIfExists.methods;
            if (!_.isUndefined(devdocMethodsIfExist)) {
                const devdocMethodIfExists = devdocMethodsIfExist[methodSignature];
                if (!_.isUndefined(devdocMethodIfExists)) {
                    const devdocMethodDetailsIfExist = devdocMethodIfExists.details;
                    if (!_.isUndefined(devdocMethodDetailsIfExist)) {
                        details = devdocMethodDetailsIfExist;
                    }
                }
            }
        }
        return details;
    }
    private static _genFallbackDoc(
        abiDefinition: FallbackAbi,
        devdocIfExists: DevdocOutput | undefined,
    ): SolidityMethod {
        const methodSignature = `()`;
        const comment = SolDoc._devdocMethodDetailsIfExist(methodSignature, devdocIfExists);

        const returnComment =
            _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature])
                ? undefined
                : devdocIfExists.methods[methodSignature].return;

        const methodDoc: SolidityMethod = {
            isConstructor: false,
            name: 'fallback',
            callPath: '',
            parameters: [],
            returnType: { name: 'void', typeDocType: TypeDocTypes.Intrinsic },
            returnComment,
            isConstant: true,
            isPayable: abiDefinition.payable,
            isFallback: true,
            comment: _.isEmpty(comment)
                ? 'The fallback function. It is executed on a call to the contract if none of the other functions match the given public identifier (or if no data was supplied at all).'
                : comment,
        };
        return methodDoc;
    }
    private static _genEventArgsDoc(args: EventParameter[]): EventArg[] {
        const eventArgsDoc: EventArg[] = [];

        for (const arg of args) {
            const name = arg.name;

            const type: Type = {
                name: arg.type,
                typeDocType: TypeDocTypes.Intrinsic,
            };

            const eventArgDoc: EventArg = {
                isIndexed: arg.indexed,
                name,
                type,
            };

            eventArgsDoc.push(eventArgDoc);
        }
        return eventArgsDoc;
    }
    private static _dedupStructs(customTypes: CustomType[]): CustomType[] {
        const uniqueCustomTypes: CustomType[] = [];
        const seenTypes: { [hash: string]: boolean } = {};
        _.each(customTypes, customType => {
            const hash = SolDoc._generateCustomTypeHash(customType);
            if (!seenTypes[hash]) {
                uniqueCustomTypes.push(customType);
                seenTypes[hash] = true;
            }
        });
        return uniqueCustomTypes;
    }
    private static _capitalize(text: string): string {
        return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
    }
    private static _generateCustomTypeHash(customType: CustomType): string {
        const customTypeWithoutName = _.cloneDeep(customType);
        delete customTypeWithoutName.name;
        const customTypeWithoutNameStr = JSON.stringify(customTypeWithoutName);
        const hash = ethUtil.sha256(customTypeWithoutNameStr).toString('hex');
        return hash;
    }
    private static _makeCompilerOptions(contractsDir: string, contractsToCompile?: string[]): CompilerOptions {
        const compilerOptions: CompilerOptions = {
            contractsDir,
            contracts: '*',
            compilerSettings: {
                outputSelection: {
                    ['*']: {
                        ['*']: ['abi', 'devdoc'],
                    },
                },
            },
        };

        const shouldOverrideCatchAllContractsConfig =
            !_.isUndefined(contractsToCompile) && contractsToCompile.length > 0;
        if (shouldOverrideCatchAllContractsConfig) {
            compilerOptions.contracts = contractsToCompile;
        }

        return compilerOptions;
    }
    /**
     * Invoke the Solidity compiler and transform its ABI and devdoc outputs into a
     * JSON format easily consumed by documentation rendering tools.
     * @param contractsToDocument list of contracts for which to generate doc objects
     * @param contractsDir the directory in which to find the `contractsToCompile` as well as their dependencies.
     * @return doc object for use with documentation generation tools.
     */
    public async generateSolDocAsync(
        contractsDir: string,
        contractsToDocument?: string[],
        customTypeHashToName?: ObjectMap<string>,
    ): Promise<DocAgnosticFormat> {
        this._customTypeHashToName = customTypeHashToName;
        const docWithDependencies: DocAgnosticFormat = {};
        const compilerOptions = SolDoc._makeCompilerOptions(contractsDir, contractsToDocument);
        const compiler = new Compiler(compilerOptions);
        const compilerOutputs = await compiler.getCompilerOutputsAsync();
        let structs: CustomType[] = [];
        for (const compilerOutput of compilerOutputs) {
            const contractFileNames = _.keys(compilerOutput.contracts);
            for (const contractFileName of contractFileNames) {
                const contractNameToOutput = compilerOutput.contracts[contractFileName];

                const contractNames = _.keys(contractNameToOutput);
                for (const contractName of contractNames) {
                    const compiledContract = contractNameToOutput[contractName];
                    if (_.isUndefined(compiledContract.abi)) {
                        throw new Error('compiled contract did not contain ABI output');
                    }
                    docWithDependencies[contractName] = this._genDocSection(compiledContract, contractName);
                    structs = [...structs, ...this._extractStructs(compiledContract)];
                }
            }
        }
        structs = SolDoc._dedupStructs(structs);
        structs = this._overwriteStructNames(structs);

        let doc: DocAgnosticFormat = {};
        if (_.isUndefined(contractsToDocument) || contractsToDocument.length === 0) {
            doc = docWithDependencies;
        } else {
            for (const contractToDocument of contractsToDocument) {
                const contractBasename = path.basename(contractToDocument);
                const contractName =
                    contractBasename.lastIndexOf('.sol') === -1
                        ? contractBasename
                        : contractBasename.substring(0, contractBasename.lastIndexOf('.sol'));
                doc[contractName] = docWithDependencies[contractName];
            }
        }

        if (structs.length > 0) {
            doc.structs = {
                comment: '',
                constructors: [],
                methods: [],
                properties: [],
                types: structs,
                functions: [],
                events: [],
            };
        }

        delete this._customTypeHashToName; // Clean up instance state
        return doc;
    }
    private _getCustomTypeFromDataItem(inputOrOutput: DataItem): CustomType {
        const customType: CustomType = {
            name: _.capitalize(inputOrOutput.name),
            kindString: 'Interface',
            children: [],
        };
        _.each(inputOrOutput.components, (component: DataItem) => {
            const childType = this._getTypeFromDataItem(component);
            const customTypeChild = {
                name: component.name,
                type: childType,
            };
            // (fabio): Not sure why this type casting is necessary. Seems TS doesn't
            // deduce that `customType.children` cannot be undefined anymore after being
            // set to `[]` above.
            (customType.children as CustomTypeChild[]).push(customTypeChild);
        });
        return customType;
    }
    private _getNameFromDataItemIfExists(dataItem: DataItem): string | undefined {
        if (_.isUndefined(dataItem.components)) {
            return undefined;
        }
        const customType = this._getCustomTypeFromDataItem(dataItem);
        const hash = SolDoc._generateCustomTypeHash(customType);
        if (_.isUndefined(this._customTypeHashToName) || _.isUndefined(this._customTypeHashToName[hash])) {
            return undefined;
        }
        return this._customTypeHashToName[hash];
    }
    private _getTypeFromDataItem(dataItem: DataItem): Type {
        const typeDocType = !_.isUndefined(dataItem.components) ? TypeDocTypes.Reference : TypeDocTypes.Intrinsic;
        let typeName: string;
        if (typeDocType === TypeDocTypes.Reference) {
            const nameIfExists = this._getNameFromDataItemIfExists(dataItem);
            typeName = _.isUndefined(nameIfExists) ? SolDoc._capitalize(dataItem.name) : nameIfExists;
        } else {
            typeName = dataItem.type;
        }

        const isArrayType = _.endsWith(dataItem.type, '[]');
        let type: Type;
        if (isArrayType) {
            // tslint:disable-next-line:custom-no-magic-numbers
            typeName = typeDocType === TypeDocTypes.Intrinsic ? typeName.slice(0, -2) : typeName;
            type = {
                elementType: { name: typeName, typeDocType },
                typeDocType: TypeDocTypes.Array,
                name: '',
            };
        } else {
            type = { name: typeName, typeDocType };
        }
        return type;
    }
    private _overwriteStructNames(customTypes: CustomType[]): CustomType[] {
        if (_.isUndefined(this._customTypeHashToName)) {
            return customTypes;
        }
        const localCustomTypes = _.cloneDeep(customTypes);
        _.each(localCustomTypes, (customType, i) => {
            const hash = SolDoc._generateCustomTypeHash(customType);
            if (!_.isUndefined(this._customTypeHashToName) && !_.isUndefined(this._customTypeHashToName[hash])) {
                localCustomTypes[i].name = this._customTypeHashToName[hash];
            }
        });
        return localCustomTypes;
    }
    private _extractStructs(compiledContract: StandardContractOutput): CustomType[] {
        let customTypes: CustomType[] = [];
        for (const abiDefinition of compiledContract.abi) {
            let types: CustomType[] = [];
            switch (abiDefinition.type) {
                case 'constructor': {
                    types = this._getStructsAsCustomTypes(abiDefinition);
                    break;
                }
                case 'function': {
                    types = this._getStructsAsCustomTypes(abiDefinition);
                    break;
                }
                case 'event':
                case 'fallback':
                    // No types exist
                    break;
                default:
                    throw new Error(
                        `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, // tslint:disable-line:no-unnecessary-type-assertion
                    );
            }
            customTypes = [...customTypes, ...types];
        }
        return customTypes;
    }
    private _genDocSection(compiledContract: StandardContractOutput, contractName: string): DocSection {
        const docSection: DocSection = {
            comment: _.isUndefined(compiledContract.devdoc) ? '' : compiledContract.devdoc.title,
            constructors: [],
            methods: [],
            properties: [],
            types: [],
            functions: [],
            events: [],
        };

        for (const abiDefinition of compiledContract.abi) {
            switch (abiDefinition.type) {
                case 'constructor':
                    docSection.constructors.push(
                        // tslint:disable-next-line:no-unnecessary-type-assertion
                        this._genConstructorDoc(contractName, abiDefinition as ConstructorAbi, compiledContract.devdoc),
                    );
                    break;
                case 'event':
                    // tslint:disable-next-line:no-unnecessary-type-assertion
                    (docSection.events as Event[]).push(SolDoc._genEventDoc(abiDefinition as EventAbi));
                    // note that we're not sending devdoc to this._genEventDoc().
                    // that's because the type of the events array doesn't have any fields for documentation!
                    break;
                case 'function':
                    // tslint:disable-next-line:no-unnecessary-type-assertion
                    docSection.methods.push(this._genMethodDoc(abiDefinition as MethodAbi, compiledContract.devdoc));
                    break;
                case 'fallback':
                    // tslint:disable-next-line:no-unnecessary-type-assertion
                    docSection.methods.push(
                        SolDoc._genFallbackDoc(abiDefinition as FallbackAbi, compiledContract.devdoc),
                    );
                    break;
                default:
                    throw new Error(
                        `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, // tslint:disable-line:no-unnecessary-type-assertion
                    );
            }
        }

        return docSection;
    }
    private _genConstructorDoc(
        contractName: string,
        abiDefinition: ConstructorAbi,
        devdocIfExists: DevdocOutput | undefined,
    ): SolidityMethod {
        const { parameters, methodSignature } = this._genMethodParamsDoc('', abiDefinition.inputs, devdocIfExists);

        const comment = SolDoc._devdocMethodDetailsIfExist(methodSignature, devdocIfExists);

        const constructorDoc: SolidityMethod = {
            isConstructor: true,
            name: contractName,
            callPath: '',
            parameters,
            returnType: { name: contractName, typeDocType: TypeDocTypes.Reference }, // sad we have to specify this
            isConstant: false,
            isPayable: abiDefinition.payable,
            comment,
        };

        return constructorDoc;
    }
    private _genMethodDoc(abiDefinition: MethodAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod {
        const name = abiDefinition.name;
        const { parameters, methodSignature } = this._genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists);
        const devDocComment = SolDoc._devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
        const returnType = this._genMethodReturnTypeDoc(abiDefinition.outputs);
        const returnComment =
            _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature])
                ? undefined
                : devdocIfExists.methods[methodSignature].return;

        const hasNoNamedParameters = _.isUndefined(_.find(parameters, p => !_.isEmpty(p.name)));
        const isGeneratedGetter = hasNoNamedParameters;
        const comment =
            _.isEmpty(devDocComment) && isGeneratedGetter
                ? `This is an auto-generated accessor method of the '${name}' contract instance variable.`
                : devDocComment;
        const methodDoc: SolidityMethod = {
            isConstructor: false,
            name,
            callPath: '',
            parameters,
            returnType,
            returnComment,
            isConstant: abiDefinition.constant,
            isPayable: abiDefinition.payable,
            comment,
        };
        return methodDoc;
    }
    /**
     * Extract documentation for each method parameter from @param params.
     */
    private _genMethodParamsDoc(
        name: string,
        abiParams: DataItem[],
        devdocIfExists: DevdocOutput | undefined,
    ): { parameters: Parameter[]; methodSignature: string } {
        const parameters: Parameter[] = [];
        for (const abiParam of abiParams) {
            const type = this._getTypeFromDataItem(abiParam);

            const parameter: Parameter = {
                name: abiParam.name,
                comment: '<No comment>',
                isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232
                type,
            };
            parameters.push(parameter);
        }

        const methodSignature = `${name}(${abiParams
            .map(abiParam => {
                if (!_.startsWith(abiParam.type, 'tuple')) {
                    return abiParam.type;
                } else {
                    // Need to expand tuples:
                    // E.g: fillOrder(tuple,uint256,bytes) -> fillOrder((address,address,address,address,uint256,uint256,uint256,uint256,uint256,uint256,bytes,bytes),uint256,bytes)
                    const isArray = _.endsWith(abiParam.type, '[]');
                    const expandedTypes = _.map(abiParam.components, c => c.type);
                    const type = `(${expandedTypes.join(',')})${isArray ? '[]' : ''}`;
                    return type;
                }
            })
            .join(',')})`;

        if (!_.isUndefined(devdocIfExists)) {
            const devdocMethodIfExists = devdocIfExists.methods[methodSignature];
            if (!_.isUndefined(devdocMethodIfExists)) {
                const devdocParamsIfExist = devdocMethodIfExists.params;
                if (!_.isUndefined(devdocParamsIfExist)) {
                    for (const parameter of parameters) {
                        parameter.comment = devdocParamsIfExist[parameter.name];
                    }
                }
            }
        }

        return { parameters, methodSignature };
    }
    private _genMethodReturnTypeDoc(outputs: DataItem[]): Type {
        let type: Type;
        if (outputs.length > 1) {
            type = {
                name: '',
                typeDocType: TypeDocTypes.Tuple,
                tupleElements: [],
            };
            for (const output of outputs) {
                const tupleType = this._getTypeFromDataItem(output);
                (type.tupleElements as Type[]).push(tupleType);
            }
            return type;
        } else if (outputs.length === 1) {
            const output = outputs[0];
            type = this._getTypeFromDataItem(output);
        } else {
            type = {
                name: 'void',
                typeDocType: TypeDocTypes.Intrinsic,
            };
        }
        return type;
    }
    private _getStructsAsCustomTypes(abiDefinition: AbiDefinition): CustomType[] {
        const customTypes: CustomType[] = [];
        // We cast to `any` here because we do not know yet if this type of abiDefinition contains
        // an `input` key
        if (!_.isUndefined((abiDefinition as any).inputs)) {
            const methodOrConstructorAbi = abiDefinition as MethodAbi | ConstructorAbi;
            _.each(methodOrConstructorAbi.inputs, input => {
                if (!_.isUndefined(input.components)) {
                    const customType = this._getCustomTypeFromDataItem(input);
                    customTypes.push(customType);
                }
            });
        }
        if (!_.isUndefined((abiDefinition as any).outputs)) {
            const methodAbi = abiDefinition as MethodAbi; // tslint:disable-line:no-unnecessary-type-assertion
            _.each(methodAbi.outputs, output => {
                if (!_.isUndefined(output.components)) {
                    const customType = this._getCustomTypeFromDataItem(output);
                    customTypes.push(customType);
                }
            });
        }
        return customTypes;
    }
}
// tslint:disable:max-file-line-count