prettify-bru 1.0.2 → 1.2.0

package/README.md

@@ -1,6 +1,16 @@
 # Prettify Bruno Bru Files
 
-A simple CLI tool to prettify the contents of `.bru` files.
+A simple CLI tool to prettify the contents of [Bruno](https://www.usebruno.com/) `.bru` files. It uses [Prettier](https://prettier.io/) to consistently impose a standardised format to both JSON and JavaScript code, in all Bruno files in your project.
+
+## Why use this?
+
+If you use Git (or similar) to track your Bruno collections and share them with your team, nobody wants to waste time discussing cosmetic formatting! Your energy is better spent thinking about the actual tests. If one person happens to be in the habit of using 4-space indentation and adding semi-colons on the end of lines in JavaScript, but another person tends to use 2-space indentation and omits the semi-colons, there is a chance that PRs descend into a tug of war, each pull request containing a bunch of unnecessary cosmetic changes that draw the reviewer's attention away from the important changes that actually impact what is being tested.
+
+Thankfully, Bruno is already somewhat opinionated about code style so this project can follow its lead. In the desktop app, when editing a JSON body on a request there is a "Prettify" button which always reformats JSON with 2-space indentation. There is no adjascent option to reformat the "script" or "tests" tabs, so for JavaScript I've had to pick a set of style rules which I think most closely fit with what a QAer would want... familiar and short. I've gone with the same 2-space indentation as JSON, no semi-colons at the end of lines for cleanliness and double-quotes for strings so you can copy and paste chunks between JavaScript and JSON.
+
+This package is fairly young, I'm developing it in my free time to help the thousands of QA people living through the industry transition from being manual testers to becoming _test engineers_. They now need a lot of the same tools developers use to implement consistent style but they don't have the background of being developers.
+
+Any feedback or bug reports are welcome, the Issues tab is open on the Git repo https://github.com/martinjoiner/prettify-bru
 
 ## Installation
 
@@ -22,7 +32,7 @@ Get a non-destructive report of all files that could potentially be re-formatted
 npx prettify-bru
 ```
 
-The above command will walk all subdirectories finding `.bru` files. 
+The above command will walk all subdirectories finding `.bru` files.
 With each file it will assess the formatting of the JSON/JavaScript inside the following types of block:
 
 - `body:json` will be parsed with the JSON parser
@@ -36,10 +46,20 @@ To actually **modify** the files, I recommend committing your changes before doi
 npx prettify-bru --write
 ```
 
-⚠️ This will modify the files in place, use with caution.
+⚠️ Including the `--write` option will modify the files in place, use with caution.
 
 To just do a single subdirectory, provide the path as an argument, so search the folder names "speed-tests":
 
 ```
 npx prettify-bru speed-tests
 ```
+
+To just do 1 block type (for example just `body:json`), use the `--only` option:
+
+```
+npx prettify-bru --only body:json
+```
+
+## CI Pipelines and Workflows
+
+You may want to configure your CI Pipeline to run this command when a pull-request is raised. The `prettify-bru` command returns exit code 1 if it finds any files that contain an error or require reformatting. Otherwise it will return exit code 0.

package/cli.js

@@ -5,7 +5,7 @@ import {hideBin} from 'yargs/helpers';
 import {main} from './lib/main.mjs';
 
 const argv = yargs(hideBin(process.argv))
-    .command('$0 [path] [-w|--write]', `Formats all .bru files (including subdirectories)`, (yargs) => {
+    .command('$0 [path] [-w|--write] [--only "..."]', `Formats all .bru files (including subdirectories)`, (yargs) => {
         return yargs.positional('path', {
             describe: 'The root path to search from',
             type: 'string',
@@ -15,16 +15,18 @@ const argv = yargs(hideBin(process.argv))
         })
     })
     .options({
+        only: {
+            describe: 'Limit to only 1 block type',
+            type: 'string',
+            choices: ['body:json', 'json', 'script:pre-request', 'pre-request', 'script:post-request', 'post-request', 'tests']
+        },
         w: {
+            describe: 'Write mode (Formats files in place, overwriting contents)',
             alias: 'write',
             type: 'boolean',
             default: false,
         },
     })
-    .describe({
-        w: 'Write mode (Formats files in place, overwriting contents)',
-        h: 'Display the help message',
-    })
     .boolean(['w', 'h'])
     .alias('h', 'help')
     .parse();
@@ -32,11 +34,22 @@ const argv = yargs(hideBin(process.argv))
 if (argv.h) {
     yargs.showHelp();
 } else {
-    go(argv.path, argv.w);
+    go(argv.path, argv.w, argv.only ?? null);
 }
 
-function go(path, write) {
-    main(process.cwd(), path, write).catch((err) => {
+/**
+ * @param {string} path
+ * @param {boolean} write Whether to actually modify the files or not
+ * @param {?string} only Limit to only the block type with a name containing value
+ */
+function go(path, write, only) {
+    main(console, process.cwd(), path, write, only)
+    .then(changesRequired => {
+        if (changesRequired) {
+            process.exitCode = 1
+        }
+    })
+    .catch((err) => {
         console.error(err);
         process.exitCode = 1;
     });

package/lib/files.mjs

@@ -0,0 +1,57 @@
+import fs from 'fs';
+import path from 'path'
+
+/**
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function readFile(filePath) {
+    return fs.readFileSync(filePath, "utf8")
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} contents
+ * @returns void
+ */
+export function writeFile(filePath, contents) {
+    fs.writeFileSync(filePath, contents, "utf8")
+}
+
+export function findFiles(path) {
+    const files = [];
+
+    walkDir(path, (p) => {
+        if (p.endsWith(".bru")) files.push(p);
+    });
+    return files;
+}
+
+/**
+ * @callback fileCallback
+ * @param {string} fullPath
+ */
+
+/**
+ * @param {string} dir
+ * @param {fileCallback} onFile
+ */
+function walkDir(dir, onFile) {
+    // Skip node_modules by default
+    const skip = new Set(["node_modules", ".git"]);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, {withFileTypes: true});
+    } catch (e) {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (skip.has(entry.name)) continue;
+            walkDir(full, onFile);
+        } else if (entry.isFile()) {
+            onFile(full);
+        }
+    }
+}

package/lib/format.mjs

@@ -18,33 +18,49 @@ const formattableBlocks = [
     ['tests', 'babel'],
 ]
 
-
-/**  Uses Prettier to format blocks of JSON/JavaScript */
-export async function formatBlocks(originalContents) {
+/**
+ * Uses Prettier to format blocks of JSON/JavaScript
+ *
+ * @param {string} originalContents The file contents as loaded from file system
+ * @param {?string} only Limit to only the block type with a name containing value
+ * @returns {Promise<{newContents: string, blocksSearchedFor: number, changeable: number, error_messages: string[]}>}
+ */
+export async function formatBlocks(originalContents, only = null) {
 
     let fileOutcome = {
         newContents: originalContents.replace(/\r\n/g, "\n"),
-        changeable: false,
+        blocksSearchedFor: 0,
+        changeable: 0,
         error_messages: []
     }
 
     let i
     for (i in formattableBlocks) {
-        const blockOutcome = await formatBlock(fileOutcome.newContents, ...formattableBlocks[i])
+        let [blockName, parser] = formattableBlocks[i]
+        if (only !== null && !blockName.includes(only)) continue;
+
+        const blockOutcome = await formatBlock(fileOutcome.newContents, blockName, parser)
+        fileOutcome.blocksSearchedFor++
         if (blockOutcome.error_message !== null) {
             fileOutcome.error_messages.push(blockOutcome.error_message)
         } else if (blockOutcome.changeable) {
-            fileOutcome.changeable = true
-            fileOutcome.newContents = blockOutcome.fileContents;
+            fileOutcome.changeable++
+            fileOutcome.newContents = blockOutcome.fileContents
         }
     }
 
     return fileOutcome
 }
 
+/**
+ * @param {string} fileContents
+ * @param {string} blockName
+ * @param {string} parser
+ * @returns {Promise<{fileContents: string, changeable: boolean, error_message: ?string}>}
+ */
 async function formatBlock(fileContents, blockName, parser) {
 
-    let outcome = {fileContents, changeable: false, error_message: null};
+    let outcome = {fileContents, changeable: false, error_message: null}
 
     const blockBodyRegex = new RegExp('\n' + blockName + ' [{]\\n(.+?)\\n}\\n', 's')
     const match = fileContents.match(blockBodyRegex)

package/lib/main.mjs

@@ -1,16 +1,17 @@
-import fs from 'fs'
-import path from 'path'
+import {findFiles, readFile, writeFile} from './files.mjs';
 import {formatBlocks} from './format.mjs'
 
 /**
  * Finds all .bru files and formats contents
  *
- * @param cwd {String} Current working directory
- * @param path {String}
- * @param write {Boolean}
- * @returns {Promise<void>}
+ * @param {object} console The console to be used for outputting messages
+ * @param {string} cwd Current working directory
+ * @param {string} path
+ * @param {boolean} write
+ * @param {?string} only Limit to only the block type with a name containing value
+ * @returns {Promise<boolean>} True means some files contained errors or needed reformatting
  */
-export async function main(cwd, path, write) {
+export async function main(console, cwd, path, write, only = null) {
 
     if (path === '') {
         path = cwd
@@ -19,11 +20,7 @@ export async function main(cwd, path, write) {
         path = cwd + '/' + path
     }
 
-    const files = [];
-
-    walkDir(path, (p) => {
-        if (p.endsWith(".bru")) files.push(p);
-    });
+    const files = findFiles(path);
 
     if (files.length === 0) {
         console.log("No .bru files found.");
@@ -36,7 +33,7 @@ export async function main(cwd, path, write) {
     let erroredFiles = [];
 
     for (const filePath of files) {
-        const outcome = await processFile(filePath, write);
+        const outcome = await processFile(filePath, write, only);
 
         let displayFilePath = filePath.replace(new RegExp('^' + cwd + '/'), "");
 
@@ -69,37 +66,25 @@ export async function main(cwd, path, write) {
     const requireNothing = files.length - changeableFiles.length - erroredFiles.length;
     console.log(
         `\x1b[35mProcessed ${files.length} .bru file(s):\x1b[0m ${changeablePrefix} in ${changeableFiles.length}. `
-         + `Encountered errors in ${erroredFiles.length}. ${requireNothing} file(s) did not require any changes.`
+        + `Encountered errors in ${erroredFiles.length}. ${requireNothing} file(s) did not require any changes.`
     );
-}
 
-function walkDir(dir, onFile) {
-    // Skip node_modules by default
-    const skip = new Set(["node_modules", ".git"]);
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, {withFileTypes: true});
-    } catch (e) {
-        return;
-    }
-    for (const entry of entries) {
-        const full = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (skip.has(entry.name)) continue;
-            walkDir(full, onFile);
-        } else if (entry.isFile()) {
-            onFile(full);
-        }
-    }
+    return (erroredFiles.length > 0 || changeableFiles.length > 0)
 }
 
-async function processFile(filePath, write) {
-    const original = fs.readFileSync(filePath, "utf8");
+/**
+ * @param {string} filePath
+ * @param {boolean} write
+ * @param {?string} only Limit to only the block type with a name containing value
+ * @returns {Promise<void>}
+ */
+async function processFile(filePath, write, only) {
+    const original = readFile(filePath);
 
-    const fileOutcome = await formatBlocks(original);
+    const fileOutcome = await formatBlocks(original, only);
 
-    if (write && fileOutcome.changeable) {
-        fs.writeFileSync(filePath, fileOutcome.newContents, "utf8");
+    if (write && fileOutcome.changeable > 0) {
+        writeFile(filePath, fileOutcome.newContents);
     }
 
     return fileOutcome;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prettify-bru",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Prettifies JSON and JavaScript blocks in Bruno .bru files",
   "keywords": [
     "bruno",
@@ -32,7 +32,7 @@
     "yargs": "18.0.0"
   },
   "scripts": {
-    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest"
+    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --verbose"
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",