powerbi-visuals-tools 4.3.2 → 5.0.0

package/src/ConsoleWriter.ts

@@ -0,0 +1,206 @@
+/*
+ *  Power BI Visual CLI
+ *
+ *  Copyright (c) Microsoft Corporation
+ *  All rights reserved.
+ *  MIT License
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the ""Software""), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
+ */
+
+"use strict";
+
+import chalk from 'chalk';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { getRootPath } from './utils.js';
+
+const preferredChalk = os.platform() === 'darwin' ? chalk.bold : chalk;
+
+function prependLogTag(tag, args) {
+    return [tag].concat(args);
+}
+
+export default class ConsoleWriter {
+    /** Causes the terminal to beep */
+    static beep() {
+        process.stdout.write("\x07");
+    }
+
+    /** Outputs a blank line */
+    static blank() {
+        console.info(preferredChalk.reset(' '));
+    }
+
+    /**
+     * Outputs arguments with the "done" tag / colors
+     * 
+     * @param {array} arguments - arguments passed through to console.info
+     */
+    static done(args) {
+        const tag = preferredChalk.bgGreen(' done  ');
+        console.info.apply(this, prependLogTag(tag, args));
+    }
+
+    /**
+     * Outputs arguments with the "info" tag / colors
+     * 
+     * @param {array} args - arguments passed through to console.info
+     */
+    static info(args) {
+        const tag = preferredChalk.bgCyan(' info  ');
+        console.info.apply(this, prependLogTag(tag, args));
+    }
+
+    /**
+     * Outputs arguments with the "warn" tag / colors
+     * 
+     * @param {array} args - arguments passed through to console.warn
+     */
+    static warning(args) {
+        const tag = preferredChalk.bgYellow.black(' warn  ');
+        console.warn.apply(this, prependLogTag(tag, args));
+    }
+
+    /**
+     * Outputs arguments with the "error" tag / colors
+     * 
+     * @param {array} args - arguments passed through to console.error
+     */
+    static error(args) {
+        const tag = preferredChalk.bgRed(' error ');
+        console.error.apply(this, prependLogTag(tag, args));
+    }
+
+    /**
+     * Outputs an object as a table
+     * 
+     * @param {string} data - object to output
+     * @param {number} [depthLimit=Infinity] - limit the number of levels to recurse
+     * @param {string} [keyPrefix=''] - text to prepend to each key
+     */
+    static infoTable(data, depthLimit?, keyPrefix?) {
+        if (!data) {
+            return;
+        }
+        const limit = typeof depthLimit === 'undefined' ? Infinity : depthLimit;
+        for (const key in data) {
+            const item = data[key];
+            const itemKey = (keyPrefix || '') + key;
+            if (limit > 1 && typeof item === 'object' && !Array.isArray(item)) {
+                ConsoleWriter.infoTable(item, limit - 1, itemKey + '.');
+            } else {
+                ConsoleWriter.infoTableRow(itemKey, item);
+            }
+        }
+    }
+
+    /**
+     * Outputs a table row with even spaced keys
+     * 
+     * @param {string} key - title of this row
+     * @param {string} value - value for this row
+     * @param {number} [keyWidth=30] - width used for padding of the key column
+     */
+    static infoTableRow(key, value, keyWidth?) {
+        const width = keyWidth || 30;
+        const padding = Math.max(0, width - key.length);
+        const paddedKey = preferredChalk.bold(key) + (new Array(padding)).join('.');
+        ConsoleWriter.info([paddedKey, value]);
+    }
+
+    /**
+     * Outputs formatted errors
+     * 
+     * @param {Array<Error>} errors
+     */
+    static formattedErrors(errors) {
+        if (errors && Array.isArray(errors)) {
+            errors.forEach((error) => {
+                if (!error) {
+                    return;
+                }
+                const tag = error.type ? preferredChalk.bold(error.type.toUpperCase()) : 'UNKNOWN';
+                const file = error.filename ? preferredChalk.bgWhite.black(` ${error.filename} `) + ':' : '';
+                const position = (error.line && error.column) ? preferredChalk.cyan(`(${error.line},${error.column})`) : '';
+                const message = error.message || '';
+                ConsoleWriter.error([tag, `${file} ${position} ${message}`]);
+            });
+        } else {
+            ConsoleWriter.error(['UNKNOWN', errors]);
+        }
+    }
+
+    /**
+     * Outputs ascii art of the PowerBI logo
+     */
+    static getLogoVisualization() {
+        return fs.readFileSync(path.join(getRootPath(), 'assets', 'logo.txt')).toString();
+    }
+
+    /**
+     * Outputs validation log from PBIVIZ package checking
+     */
+    static validationLog(log) {
+
+        // api/js/css/pkg
+        const filterChecks = (attrCB, propCB) => {
+            for (const checkname in log) {
+                if (checkname !== 'valid') {
+                    const checkpoint = log[checkname];
+                    ConsoleWriter[checkpoint.error.length ? 'info' : 'done'](checkpoint.check);
+                    attrCB(checkpoint, propCB);
+                }
+            }
+        };
+
+        // error/message/ok
+        const filterCheckAttrs = (checkpoint, propCB) => {
+            for (const propName in checkpoint) {
+                if (propName !== 'message') {
+                    const prop = checkpoint[propName];
+                    if (typeof (prop) === 'object' && prop.length) {
+                        propCB(prop, propName);
+                    }
+                }
+            }
+        };
+
+        // col/line/text
+        const filterAttrProps = (props, propName) => {
+            props.forEach((opt) => {
+                const result = [];
+                for (const key in opt) {
+                    result.push(opt[key]);
+                }
+                if (result.length) {
+                    ConsoleWriter[propName === 'error' ? 'error' : 'warn'](result.join(' --> '));
+                }
+            });
+        };
+
+        filterChecks(filterCheckAttrs, filterAttrProps);
+
+        const type = log.valid ? 'done' : 'error';
+        const text = log.valid ? 'Valid package' : 'Invalid package';
+        ConsoleWriter.blank();
+        ConsoleWriter[type](text);
+    }
+}

package/src/TemplateFetcher.ts

@@ -0,0 +1,122 @@
+
+import { createFolder, download, readJsonFromRoot } from './utils.js';
+import ConsoleWriter from './ConsoleWriter.js';
+import JSZip from 'jszip';
+import VisualGenerator from "./VisualGenerator.js";
+import { exec } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
+
+const config = readJsonFromRoot('config.json');
+
+export default class TemplateFetcher {
+    private templateName: string;
+    private visualName: string;
+    private folderName: string;
+    private apiVersion: string;
+
+    constructor(templateName: string, visualName: string, apiVersion: string) {
+        this.templateName = templateName;
+        this.visualName = visualName;
+        this.folderName = `${this.visualName}`;
+        this.apiVersion = apiVersion;
+    }
+
+    fetch() {
+        const folder = createFolder.call(this, this.folderName);
+        download.call(this, config.visualTemplates[this.templateName], path.join(folder, "template.zip"))
+            .then(this.extractFiles.bind(this))
+            .then(this.removeZipFile.bind(this))
+            .then(this.setVisualGUID.bind(this))
+            .then(this.setApiVersion.bind(this))
+            .then(this.runNpmInstall.bind(this))
+            .then(this.showNextSteps.bind(this));
+    }
+
+    async removeZipFile() {
+        const folder = path.join("./", this.folderName);
+        const fileName = path.join(folder, "template.zip");
+        await fs.unlink(`.${path.sep}${fileName}`, (err) => {
+            if (err) {
+                ConsoleWriter.warning(`.${path.sep}${fileName} was not deleted`);
+            }
+        });
+    }
+
+    async extractFiles(file) {
+        const filePath = path.join(process.cwd(), file.path);
+        const buffer = await fs.readFile(filePath);
+        const zip = await JSZip.loadAsync(buffer);
+
+        const filesList = Object.keys(zip.files);
+        for (const filename of filesList) {
+            if (filename[filename.length - 1] === "/") {
+                // generate folders                            for exclude parent folder
+                const dest = path.join(path.dirname(filePath), path.join(filename, ".."));
+                await fs.ensureDir(dest);
+            } else {
+                // write files into dirs                       for exclude parent folder
+                const dest = path.join(path.dirname(filePath), path.join(path.dirname(filename), "..", filename.split("/").pop() ?? ""));
+                const content = await zip.file(filename)?.async('nodebuffer');
+                await fs.writeFile(dest, content);
+            }
+        }
+    }
+
+    async setApiVersion() {
+        if (!this.apiVersion) {
+            return;
+        }
+        ConsoleWriter.info(`Set Visual API to ${this.apiVersion}`);
+        const packageJsonFile = path.join(process.cwd(), this.folderName, "package.json");
+        const packageJson = await fs.readJson(packageJsonFile);
+        if (packageJson.devDependencies && packageJson.devDependencies["powerbi-visuals-api"]) {
+            packageJson.devDependencies["powerbi-visuals-api"] = `~${this.apiVersion}`;
+        }
+        if (packageJson.dependencies && packageJson.dependencies["powerbi-visuals-api"]) {
+            packageJson.dependencies["powerbi-visuals-api"] = `~${this.apiVersion}`;
+        }
+        await fs.writeJSON(packageJsonFile, packageJson);
+    }
+
+    async setVisualGUID() {
+        const pbivizJsonFile = path.join(process.cwd(), this.folderName, "pbiviz.json");
+        const pbivizJson = await fs.readJson(pbivizJsonFile);
+        pbivizJson.visual.guid = this.visualName + VisualGenerator.generateVisualGuid();
+        await fs.writeJSON(pbivizJsonFile, pbivizJson);
+    }
+
+    runNpmInstall() {
+        return new Promise((resolve, reject) => {
+            ConsoleWriter.info("Installing packages...");
+            process.chdir(this.folderName);
+            // const { stdout, stderr } = await exec('ls');
+            const child = exec('npm install', (error, stdout, stderr) => {
+                if (error) {
+                    ConsoleWriter.error(error.stack);
+                    ConsoleWriter.error(`Error code: ${error.code}`);
+                    ConsoleWriter.error(`Signal received: ${error.signal}`);
+                }
+                ConsoleWriter.warning(stderr);
+                ConsoleWriter.info(stdout);
+                resolve(true);
+            });
+            child.on("error", (er) => {
+                ConsoleWriter.error(er);
+                reject();
+            });
+            child.on("exit", (code) => {
+                if (code !== 0) {
+                    ConsoleWriter.error(`npm install stopped with code ${code}`);
+                    reject();
+                }
+            });
+        });
+    }
+
+    showNextSteps() {
+        ConsoleWriter.blank();
+        ConsoleWriter.info("Run `npm run start` to start visual development");
+        ConsoleWriter.info("Run `npm run package` to create visual package");
+    }
+}

package/src/VisualGenerator.ts

@@ -0,0 +1,236 @@
+/*
+ *  Power BI Visual CLI
+ *
+ *  Copyright (c) Microsoft Corporation
+ *  All rights reserved.
+ *  MIT License
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the ""Software""), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
+ */
+
+"use strict";
+
+import crypto from 'crypto';
+import { getRootPath, readJsonFromRoot } from './utils.js';
+import { compareVersions } from "compare-versions";
+import fs from 'fs-extra';
+import lodashDefaults from 'lodash.defaults';
+import path from 'path';
+import template from '../templates/pbiviz-json-template.js';
+
+const config = readJsonFromRoot('config.json');
+
+const VISUAL_TEMPLATES_PATH = path.join(getRootPath(), config.templates.visuals);
+const API_VERSION = config.generate.apiVersion;
+const minAPIversion = config.constants.minAPIversion;
+
+/**
+ * Generates the data for the visual
+ */
+function generateVisualOptions(visualName, apiVersion) {
+    const name = generateVisualName(visualName);
+    return {
+        name: name,
+        displayName: visualName,
+        guid: name + VisualGenerator.generateVisualGuid(),
+        visualClassName: 'Visual',
+        apiVersion: apiVersion
+    };
+}
+
+/**
+ * 
+ */
+function generateVisualName(displayName) {
+    return displayName.replace(/(?:^\w|[A-Z]|\b\w|_|\s+)/g, (match, index) => {
+        if (/\s|_+/.test(match)) {
+            return "";
+        }
+        return index === 0 ? match.toLowerCase() : match.toUpperCase();
+    });
+}
+
+/**
+ * Creates a default pbiviz.json config file
+ * 
+ * @param {string} visualPath - path to the visual
+ * @param {Object} options - visual information for populating the pbiviz.json template
+ * @param {string} templateName - external js files
+ */
+function createPbiVizJson(visualPath, options, templateName) {
+
+    // read the global template data
+    // and generate the actual file content
+    let data = template(options);
+
+    // write out the target file content
+    const targetPath = path.join(visualPath, 'pbiviz.json');
+    fs.writeFileSync(targetPath, data);
+
+    let templatePath = path.join(VISUAL_TEMPLATES_PATH, templateName);
+    templatePath = path.join(templatePath, 'pbiviz.json');
+    if (templateName && fileExists(templatePath)) {
+        //read the target file content 
+        data = fs.readJsonSync(targetPath);
+
+        //override externalJS settings with those of the local template file
+        const templateData = fs.readJsonSync(templatePath);
+        for (const objKey of Object.keys(templateData)) {
+            data[objKey] = templateData[objKey];
+        }
+
+        // write out the target file content
+        fs.writeJsonSync(targetPath, data);
+    }
+}
+
+/**
+ * Checks if the specified file exists
+ * 
+ * @param {string} file - path to the file 
+ */
+function fileExists(file) {
+    try {
+        fs.accessSync(file);
+    } catch (e) {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * Copies the visual template directory
+ * 
+ * @param {string} targetPath - file path to root of visual package
+ * @param {string} templateName - template to use for generating the visual
+ */
+function copyVisualTemplate(targetPath, templateName) {
+    fs.copySync(path.join(VISUAL_TEMPLATES_PATH, '_global'), targetPath);
+    fs.copySync(path.join(VISUAL_TEMPLATES_PATH, templateName), targetPath);
+}
+
+/**
+ * Checks if the specified template is valid
+ * 
+ * @param {string} templateName - template to use for generating the visual
+ */
+function validTemplate(templateName) {
+    try {
+        fs.accessSync(path.join(VISUAL_TEMPLATES_PATH, templateName));
+    } catch (e) {
+        return false;
+    }
+    return true;
+}
+
+const defaultOptions = {
+    force: false,
+    template: 'default',
+    apiVersion: API_VERSION,
+    externalJS: []
+};
+
+export default class VisualGenerator {
+    /**
+     * Generates a new visual
+     * 
+     * @param {string} targetPath - file path for creation of the new visual package
+     * @param {string} visualName - name of the new visual package
+     * @param {object} options - specify options for the visual generator
+     * @returns {Promise<string>} - promise resolves with the path to the newly created package 
+     */
+    static generateVisual(targetPath, visualName, options): Promise<string> {
+        return new Promise((resolve, reject) => {
+            const buildOptions = lodashDefaults(options, defaultOptions);
+            if (!buildOptions.apiVersion || compareVersions(buildOptions.apiVersion, minAPIversion) === -1) {
+                return reject(new Error(`Can not generate a visual with an API below than ${minAPIversion}, current API is '${buildOptions.apiVersion}'.`));
+            }
+            const visualOptions = generateVisualOptions(visualName, buildOptions.apiVersion);
+            const validationResult = VisualGenerator.checkVisualName(visualOptions.name);
+            if (!visualOptions || !visualOptions.name || validationResult) {
+                return reject(new Error(validationResult || "Invalid visual name"));
+            }
+
+            if (!validTemplate(buildOptions.template)) {
+                return reject(new Error(`Invalid template "${buildOptions.template}"`));
+            }
+
+            const visualPath = path.join(targetPath, visualOptions.name);
+            fs.access(visualPath, err => {
+                if (!err && !buildOptions.force) {
+                    return reject(new Error('This visual already exists. Use force to overwrite.'));
+                }
+                try {
+                    if (!err && buildOptions.force) {
+                        fs.removeSync(visualPath);
+                    }
+                    copyVisualTemplate(visualPath, buildOptions.template);
+                    createPbiVizJson(visualPath, visualOptions, options.template);
+                    resolve(visualPath);
+                } catch (e) {
+                    reject(e);
+                }
+            });
+        });
+    }
+
+    /**
+     * Generates a random GUID for your visual
+     */
+    static generateVisualGuid() {
+        return crypto.randomUUID().replace(/-/g, '').toUpperCase();
+    }
+
+    /**
+     * Check visual name 
+     * Using https://github.com/mathiasbynens/mothereff.in/tree/master/js-properties
+     * 
+     * @static
+     * @param {string} name Visual name
+     * @returns {string} error message
+     * 
+     * @memberof VisualGenerator
+     */
+    static checkVisualName(name) {
+        const regexES3ReservedWord = /^(?:do|if|in|for|int|new|try|var|byte|case|char|else|enum|goto|long|null|this|true|void|with|break|catch|class|const|false|final|float|short|super|throw|while|delete|double|export|import|native|public|return|static|switch|throws|typeof|boolean|default|extends|finally|package|private|abstract|continue|debugger|function|volatile|interface|protected|transient|implements|instanceof|synchronized)$/;
+        const regexNumber = /^(?![+-])([0-9\+\-\.]+)/; // eslint-disable-line no-useless-escape
+        const regexZeroWidth = /\u200c|\u200d/;
+        const regexpWrongSymbols = /^[a-zA-Z0-9]+$/;
+        const valueAsUnescapedString = name.replace(/\\u([a-fA-F0-9]{4})|\\u\{([0-9a-fA-F]{1,})\}/g, ($0, $1, $2) => {
+            const codePoint = parseInt($2 || $1, 16);
+            // If it’s a surrogate…
+            if (codePoint >= 0xD800 && codePoint <= 0xDFFF) {
+                // Return a character that is never valid in an identifier.
+                // This prevents the surrogate from pairing with another.
+                return '\0';
+            }
+            return String.fromCodePoint(codePoint);
+        });
+        if (regexNumber.test(name)) {
+            return `The visual name can't begin with a number digit`;
+        } else if (!regexpWrongSymbols.test(name)) {
+            return `The visual name can contain only letters and numbers`;
+        } else if (regexES3ReservedWord.test(valueAsUnescapedString)) {
+            return `The visual name cannot be equal to a reserved JavaScript keyword.
+                More information: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Keywords`;
+        } else if (regexZeroWidth.test(valueAsUnescapedString)) {
+            return `The visual name can't be empty`;
+        }
+    }
+}