fts/build/parser.js

"use strict";
// TODO: parser would be ~2x faster if we reused the underlying ts program from TS in TJS
var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
};
var __importStar = (this && this.__importStar) || function (mod) {
    if (mod && mod.__esModule) return mod;
    var result = {};
    if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
    result["default"] = mod;
    return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
const doctrine_1 = __importDefault(require("doctrine"));
const fs_extra_1 = __importDefault(require("fs-extra"));
const fts_core_1 = require("fts-core");
const path_1 = __importDefault(require("path"));
const tempy_1 = __importDefault(require("tempy"));
const TS = __importStar(require("ts-morph"));
const TJS = __importStar(require("typescript-json-schema"));
const FTSReturns = 'FTSReturns';
const FTSParams = 'FTSParams';
const promiseTypeRe = /^Promise<(.*)>$/;
const supportedExtensions = {
    js: 'javascript',
    jsx: 'javascript',
    ts: 'typescript',
    tsx: 'typescript'
};
async function generateDefinition(file, options = {}) {
    file = path_1.default.resolve(file);
    const fileInfo = path_1.default.parse(file);
    const language = supportedExtensions[fileInfo.ext.substr(1)];
    if (!language) {
        throw new Error(`File type "${fileInfo.ext}" not supported. "${file}"`);
    }
    const outDir = tempy_1.default.directory();
    // initialize and compile TS program
    const compilerOptions = Object.assign({ allowJs: true, ignoreCompilerErrors: true, esModuleInterop: true, 
        // TODO: why do we need to specify the full filename for these lib definition files?
        lib: ['lib.es2018.d.ts', 'lib.dom.d.ts'], target: TS.ScriptTarget.ES5, outDir }, (options.compilerOptions || {}));
    const jsonSchemaOptions = Object.assign({ noExtraProps: true, required: true, validationKeywords: ['coerceTo', 'coerceFrom'] }, (options.jsonSchemaOptions || {}));
    const definition = {
        config: {
            defaultExport: true,
            language
        },
        params: {
            http: false,
            context: false,
            order: [],
            schema: null
        },
        returns: {
            async: false,
            http: false,
            schema: null
        },
        version: fts_core_1.version
    };
    const project = new TS.Project({ compilerOptions });
    project.addExistingSourceFile(file);
    project.resolveSourceFileDependencies();
    const diagnostics = project.getPreEmitDiagnostics();
    if (diagnostics.length > 0) {
        console.log(project.formatDiagnosticsWithColorAndContext(diagnostics));
        // TODO: throw error?
    }
    const sourceFile = project.getSourceFileOrThrow(file);
    const main = extractMainFunction(sourceFile, definition);
    if (!main) {
        throw new Error(`Unable to infer a main function export "${file}"`);
    }
    // extract main function type and documentation info
    const title = main.getName ? main.getName() : path_1.default.parse(file).name;
    const mainTypeParams = main.getTypeParameters();
    definition.title = title;
    if (mainTypeParams.length > 0) {
        throw new Error(`Generic Type Parameters are not supported for function "${title}"`);
    }
    const doc = main.getJsDocs()[0];
    let docs;
    if (doc) {
        const { description } = doc.getStructure();
        docs = doctrine_1.default.parse(description);
        if (docs.description) {
            definition.description = docs.description;
        }
    }
    const builder = {
        definition,
        docs,
        main,
        sourceFile,
        title
    };
    if (options.emit) {
        const result = project.emit(options.emitOptions);
        if (result.getEmitSkipped()) {
            throw new Error('emit skipped');
        }
    }
    addParamsDeclaration(builder);
    addReturnTypeDeclaration(builder);
    // TODO: figure out a better workaround than mutating the source file directly
    // TODO: fix support for JS files since you can't save TS in JS
    const tempSourceFilePath = path_1.default.format({
        dir: fileInfo.dir,
        ext: '.ts',
        name: `.${fileInfo.name}-fts`
    });
    const tempSourceFile = sourceFile.copy(tempSourceFilePath, {
        overwrite: true
    });
    await tempSourceFile.save();
    try {
        extractJSONSchemas(builder, tempSourceFilePath, jsonSchemaOptions);
    }
    finally {
        await fs_extra_1.default.remove(tempSourceFilePath);
    }
    return builder.definition;
}
exports.generateDefinition = generateDefinition;
/** Find main exported function declaration */
function extractMainFunction(sourceFile, definition) {
    const functionDefaultExports = sourceFile
        .getFunctions()
        .filter((f) => f.isDefaultExport());
    if (functionDefaultExports.length === 1) {
        definition.config.defaultExport = true;
        return functionDefaultExports[0];
    }
    else {
        definition.config.defaultExport = false;
    }
    const functionExports = sourceFile
        .getFunctions()
        .filter((f) => f.isExported());
    if (functionExports.length === 1) {
        const func = functionExports[0];
        definition.config.namedExport = func.getName();
        return func;
    }
    if (functionExports.length > 1) {
        const externalFunctions = functionExports.filter((f) => {
            const docs = f.getJsDocs()[0];
            return (docs &&
                docs.getTags().find((tag) => {
                    const tagName = tag.getTagName();
                    return tagName === 'external' || tagName === 'public';
                }));
        });
        if (externalFunctions.length === 1) {
            const func = externalFunctions[0];
            definition.config.namedExport = func.getName();
            return func;
        }
    }
    // TODO: arrow function exports are a lil hacky
    const arrowFunctionExports = sourceFile
        .getDescendantsOfKind(TS.SyntaxKind.ArrowFunction)
        .filter((f) => TS.TypeGuards.isExportAssignment(f.getParent()));
    if (arrowFunctionExports.length === 1) {
        const func = arrowFunctionExports[0];
        const exportAssignment = func.getParent();
        const exportSymbol = sourceFile.getDefaultExportSymbol();
        // TODO: handle named exports `export const foo = () => 'bar'`
        if (exportSymbol) {
            const defaultExportPos = exportSymbol
                .getValueDeclarationOrThrow()
                .getPos();
            const exportAssignmentPos = exportAssignment.getPos();
            // TODO: better way of comparing nodes
            const isDefaultExport = defaultExportPos === exportAssignmentPos;
            if (isDefaultExport) {
                definition.config.defaultExport = true;
                return func;
            }
        }
    }
    return undefined;
}
function addParamsDeclaration(builder) {
    const mainParams = builder.main.getParameters();
    const paramsDeclaration = builder.sourceFile.addClass({
        name: FTSParams
    });
    const paramComments = {};
    if (builder.docs) {
        const paramTags = builder.docs.tags.filter((tag) => tag.title === 'param');
        for (const tag of paramTags) {
            paramComments[tag.name] = tag.description;
        }
    }
    let httpParameterName;
    for (let i = 0; i < mainParams.length; ++i) {
        const param = mainParams[i];
        const name = param.getName();
        const structure = param.getStructure();
        if (structure.isRestParameter) {
            builder.definition.params.schema = { additionalProperties: true };
            continue;
        }
        // TODO: this handles alias type resolution i think...
        // need to test multiple levels of aliasing
        structure.type = param.getType().getText();
        if (name === 'context') {
            if (i !== mainParams.length - 1) {
                throw new Error(`Function parameter "context" must be last parameter to main function "${builder.title}"`);
            }
            // TODO: ensure context has valid type `FTS.Context`
            builder.definition.params.context = true;
            if (mainParams.length === 1) {
                builder.definition.params.http = true;
                httpParameterName = name;
            }
            // ignore context in parameter aggregation
            continue;
        }
        else if (structure.type === 'Buffer') {
            if (mainParams.length > 2 || i > 0) {
                throw new Error(`Function parameter "${name}" of type "Buffer" must not include additional parameters to main function "${builder.title}"`);
            }
            builder.definition.params.http = true;
            httpParameterName = name;
            builder.definition.params.order.push(name);
            // ignore Buffer in parameter aggregation
            continue;
        }
        else {
            // TODO: ensure that type is valid:
            // not `FTS.Context`
            // not Promise<T>
            // not Function or ArrowFunction
            // not RegExp
        }
        const promiseReMatch = structure.type.match(promiseTypeRe);
        if (promiseReMatch) {
            throw new Error(`Parameter "${name}" has unsupported type "${structure.type}"`);
        }
        addPropertyToDeclaration(paramsDeclaration, structure, paramComments[name]);
        builder.definition.params.order.push(name);
    }
    if (builder.definition.params.http &&
        builder.definition.params.order.length > 1) {
        throw new Error(`Function parameter "${httpParameterName}" of type "Buffer" must not include additional parameters to main function "${builder.title}"`);
    }
    return paramsDeclaration;
}
function addReturnTypeDeclaration(builder) {
    const mainReturnType = builder.main.getReturnType();
    let type = mainReturnType.getText();
    const promiseReMatch = type.match(promiseTypeRe);
    const isAsync = !!promiseReMatch;
    builder.definition.returns.async = builder.main.isAsync();
    if (isAsync) {
        type = promiseReMatch[1];
        builder.definition.returns.async = true;
    }
    if (type === 'void') {
        type = 'any';
    }
    if (type.endsWith('HttpResponse') &&
        (isAsync || mainReturnType.isInterface())) {
        builder.definition.returns.http = true;
    }
    const declaration = builder.sourceFile.addInterface({
        name: FTSReturns
    });
    const jsdoc = builder.docs &&
        builder.docs.tags.find((tag) => tag.title === 'returns' || tag.title === 'return');
    addPropertyToDeclaration(declaration, { name: 'result', type }, jsdoc && jsdoc.description);
}
function addPropertyToDeclaration(declaration, structure, jsdoc) {
    const isDate = structure.type === 'Date';
    const isBuffer = structure.type === 'Buffer';
    // Type coercion for non-JSON primitives like Date and Buffer
    if (isDate || isBuffer) {
        const coercionType = structure.type;
        if (isDate) {
            structure.type = 'Date';
        }
        else {
            structure.type = 'string';
        }
        jsdoc = `${jsdoc ? jsdoc + '\n' : ''}@coerceTo ${coercionType}`;
    }
    const property = declaration.addProperty(structure);
    if (jsdoc) {
        property.addJsDoc(jsdoc);
    }
    return property;
}
function extractJSONSchemas(builder, file, jsonSchemaOptions = {}, jsonCompilerOptions = {}) {
    const compilerOptions = Object.assign({ allowJs: true, lib: ['es2018', 'dom'], target: 'es5', esModuleInterop: true }, jsonCompilerOptions);
    const program = TJS.getProgramFromFiles([file], compilerOptions, process.cwd());
    builder.definition.params.schema = Object.assign({}, TJS.generateSchema(program, FTSParams, jsonSchemaOptions), (builder.definition.params.schema || {}) // Spread any existing schema params
    );
    if (!builder.definition.params.schema) {
        throw new Error(`Error generating params JSON schema for TS file "${file}"`);
    }
    // fix required parameters to only be those which do not have default values
    const { schema } = builder.definition.params;
    schema.required = (schema.required || []).filter((k) => schema.properties[k].default === undefined);
    if (!schema.required.length) {
        delete schema.required;
    }
    builder.definition.returns.schema = TJS.generateSchema(program, FTSReturns, Object.assign({}, jsonSchemaOptions, { required: false }));
    if (!builder.definition.returns.schema) {
        throw new Error(`Error generating returns JSON schema for TS file "${file}"`);
    }
}
/*
// useful for quick testing purposes
if (!module.parent) {
  generateDefinition('./fixtures/http-request.ts')
    .then((definition) => {
      console.log(JSON.stringify(definition, null, 2))
    })
    .catch((err) => {
      console.error(err)
      process.exit(1)
    })
}
*/
//# sourceMappingURL=parser.js.map