inital commit of oclif/plugin-command-snapshot

.eslintignore

@@ -0,0 +1 @@
+/lib

.eslintrc

@@ -0,0 +1,10 @@
+{
+  "extends": [
+    "oclif",
+    "oclif-typescript"
+  ],
+  "rules": {
+    "no-useless-constructor": "off",
+    "@typescript-eslint/no-useless-constructor": "error",
+  }
+}

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+lib/
+.nyc_output/
+oclif.manifest.json
+/package-lock.json
+yarn-error.json

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach",
+      "port": 9229,
+      "skipFiles": [
+        "<node_internals>/**"
+      ]
+    }
+  ]
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Salesforce.com
+
+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.

README.md

@@ -0,0 +1,41 @@
+@oclif/plugin-command-snapshot
+========
+
+Generates and compares OCLIF plugins snapshot files
+
+[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
+[![Version](https://img.shields.io/npm/v/@oclif/plugin-command-snapshot.svg)](https://npmjs.org/package/@oclif/plugin-command-snapshot)
+[![Downloads/week](https://img.shields.io/npm/dw/@oclif/plugin-command-snapshot.svg)](https://npmjs.org/package/@oclif/plugin-command-snapshot)
+[![License](https://img.shields.io/npm/l/@oclif/plugin-command-snapshot.svg)](https://github.com/nramyasri-sf/@oclif/plugin-command-snapshot/blob/master/package.json)
+
+<!-- toc -->
+* [Usage](#usage)
+<!-- tocstop -->
+
+# Usage
+This plugin is used to take snapshot of commands and flags in OCLIF plugins. These snapshots can be used to enforce a deprecation policy or to keep track of changes.
+
+To include it in your plugin, add it to the `devPlugins` section in your package.json.
+
+```json
+"oclif": {
+    ...
+    "devPlugins": [
+      "@oclif/plugin-command-snapshot"
+      ...
+    ]
+```
+
+Use the `snapshot:generate` command in your development process.
+
+```sh-session
+# generates a snapshot file that has a list or commands and flags in the current CLI or plugin
+$ ./bin/run snapshot:generate
+```
+
+Use the `snapshot:compare` command in your continuos integration. This command will fail if changes are detected. The snapshot file should be updated and committed to the repository when legitimate changes are made.
+
+```sh-session
+# compare the current CLI or plugin commands and flags with a snapshot file to identify changes
+$ ./bin/run snapshot:compare
+```

bin/run

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+require('@oclif/command').run()
+.catch(require('@oclif/errors/handle'))

bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

command-snapshot.json

@@ -0,0 +1,20 @@
+[
+    {
+        "command": "help",
+        "flags": [
+            "all"
+        ]
+    },
+    {
+        "command": "snapshot:compare",
+        "flags": [
+            "filepath"
+        ]
+    },
+    {
+        "command": "snapshot:generate",
+        "flags": [
+            "filepath"
+        ]
+    }
+]

package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@oclif/plugin-command-snapshot",
+  "description": "generates and compares OCLIF plugins snapshot files",
+  "version": "0.0.1",
+  "author": "Ramyasri @nramyasri-sf",
+  "bugs": "https://github.com/oclif/plugin-command-snapshot/issues",
+  "dependencies": {
+    "@oclif/command": "^1",
+    "@oclif/config": "^1",
+    "@types/fs-extra": "^8.1.0",
+    "chalk": "^3.0.0",
+    "sinon": "^9.0.0",
+    "tslib": "^1"
+  },
+  "devDependencies": {
+    "@oclif/dev-cli": "^1",
+    "@oclif/plugin-help": "^2",
+    "@oclif/test": "^1",
+    "@types/chai": "^4",
+    "@types/mocha": "^5",
+    "@types/node": "^10",
+    "chai": "^4",
+    "eslint": "^5.13",
+    "eslint-config-oclif": "^3.1",
+    "eslint-config-oclif-typescript": "^0.1",
+    "globby": "^10",
+    "mocha": "^5",
+    "nyc": "^14",
+    "ts-node": "^8",
+    "typescript": "^3.3"
+  },
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/lib",
+    "/npm-shrinkwrap.json",
+    "/oclif.manifest.json",
+    "/yarn.lock"
+  ],
+  "homepage": "https://github.com/oclif/plugin-command-snapshot",
+  "keywords": [
+    "oclif-plugin"
+  ],
+  "license": "MIT",
+  "oclif": {
+    "commands": "./lib/commands",
+    "bin": "oclif-example",
+    "topics": {
+      "snapshot": {
+        "description": "generates and compares OCLIF plugins snapshot files"
+      }
+    },
+    "devPlugins": [
+      "@oclif/plugin-help"
+    ]
+  },
+  "repository": "oclif/plugin-command-snapshot",
+  "scripts": {
+    "postpack": "rm -f oclif.manifest.json",
+    "posttest": "eslint . --ext .ts --config .eslintrc",
+    "prepack": "rm -rf lib && tsc -b && oclif-dev manifest && oclif-dev readme",
+    "test": "nyc --extension .ts mocha --forbid-only \"test/**/*.test.ts\"",
+    "version": "oclif-dev readme && git add README.md"
+  }
+}

src/commands/snapshot/compare.ts

@@ -0,0 +1,136 @@
+
+import {Command, flags} from '@oclif/command'
+import * as _ from 'lodash'
+import * as fsx from 'fs-extra'
+import {EOL} from 'os'
+import {SnapshotEntry} from './generate'
+import * as chalk from 'chalk'
+
+interface Change {
+  name: string;
+  removed?: boolean;
+  added?: boolean;
+}
+
+type CommandChange = {
+  flags: Change[];
+} & Change;
+
+export default class Compare extends Command {
+    public static flags = {
+      filepath: flags.string({
+        description: 'path of the generated snapshot file',
+        default: './command-snapshot.json',
+      }),
+    };
+
+    /**
+     * Compare a snapshot with the current commands
+     * @param {CommandChange[]} initialCommands Command list from the snapshot
+     * @param {CommandChange[]} updatedCommands Command list from runtime
+     */
+    public async compareSnapshot(initialCommands: SnapshotEntry[], updatedCommands: CommandChange[]) {
+      const removedCommands: string[] = []
+      const diffCommands: CommandChange[] = []
+
+      initialCommands.forEach(initialCommand => {
+        const updatedCommand = updatedCommands.find(updatedCommand => initialCommand.command === updatedCommand.name)
+
+        if (updatedCommand) {
+          const {changedFlags} = this.diffCommandFlags(initialCommand.flags, updatedCommand.flags)
+          if (changedFlags.length > 0) {
+            diffCommands.push(updatedCommand)
+          }
+        } else {
+          removedCommands.push(initialCommand.command)
+        }
+      })
+
+      const initialCommandNames = initialCommands.map(initialCommand => initialCommand.command)
+      const updatedCommandNames = updatedCommands.map(updatedCommand => updatedCommand.name)
+      const addedCommands = _.difference(updatedCommandNames, initialCommandNames)
+
+      if (removedCommands.length === 0 && addedCommands.length === 0 && diffCommands.length === 0) {
+        this.log('No changes have been detected.')
+        return
+      }
+
+      // Fail the process since there are changes to the snapshot file
+      process.exitCode = 1
+
+      this.log(`The following commands and flags have modified: (${chalk.green('+')} added, ${chalk.red('-')} removed)${EOL}`)
+
+      removedCommands.forEach(command => {
+        this.log(chalk.red(`\t-${command}`))
+      })
+      addedCommands.forEach(command => {
+        this.log(chalk.green(`\t+${command}`))
+      })
+
+      const removedFlags: string[] = []
+      if (diffCommands.length > 0) {
+        diffCommands.forEach(command => {
+          this.log(`\t ${command.name}`)
+
+          command.flags.forEach(flag => {
+            if (flag.added || flag.removed) {
+              const color = flag.added ? chalk.green : chalk.red
+              this.log(color(`\t\t${flag.added ? '+' : '-'}${flag.name}`))
+            }
+            if (flag.removed) removedFlags.push()
+          })
+        })
+      }
+
+      this.log(`${EOL}Command or flag differences detected. If intended, please update the snapshot file and run again.`)
+
+      // Check if existent commands have been deleted
+      if (removedCommands.length > 0 || removedFlags.length > 0) {
+        this.log(chalk.red(`${EOL}Since there are deletions, a major version bump is required.`))
+      }
+
+      return {addedCommands, removedCommands, removedFlags, diffCommands}
+    }
+
+    /**
+     * Compares a flag snapshot with the current command's flags
+     * @param {string[]} initialFlags Flag list from the snapshot
+     * @param {string[]} updatedFlags Flag list from runtime
+     * @param {string} initialCommand Command the flags belong to
+     * @return {boolean} true if no changes, false otherwise
+     */
+    public diffCommandFlags(initialFlags: string[], updatedFlags: Change[]) {
+      const updatedFlagNames = updatedFlags.map(updatedFlag => updatedFlag.name)
+      const addedFlags = _.difference(updatedFlagNames, initialFlags)
+      const removedFlags = _.difference(initialFlags, updatedFlagNames)
+      const changedFlags: Change[] = []
+
+      updatedFlags.forEach(updatedFlag => {
+        if (addedFlags.includes(updatedFlag.name)) {
+          updatedFlag.added = true
+          changedFlags.push(updatedFlag)
+        }
+      })
+      removedFlags.forEach(removedFlag => {
+        changedFlags.push({name: removedFlag, removed: true})
+        // The removed flags in not included in the updated flags, but we want it to
+        // so it shows removed.
+        updatedFlags.push({name: removedFlag, removed: true})
+      })
+
+      return {addedFlags, removedFlags, updatedFlags, changedFlags}
+    }
+
+    public async run() {
+      const {flags} = this.parse(Compare)
+      const oldCommandFlags = JSON.parse(fsx.readFileSync(flags.filepath).toString('utf8')) as SnapshotEntry[]
+      const newCommandFlags = this.config.commands
+      const resultnewCommandFlags: CommandChange[] = _.sortBy(newCommandFlags, 'id').map(command => {
+        return {
+          name: command.id,
+          flags: Object.entries(command.flags).map(flagName => ({name: flagName[0]})),
+        }
+      })
+      return this.compareSnapshot(oldCommandFlags, resultnewCommandFlags)
+    }
+}

src/commands/snapshot/generate.ts

@@ -0,0 +1,33 @@
+import {Command, flags} from '@oclif/command'
+import * as fs from 'fs'
+import * as _ from 'lodash'
+
+export type SnapshotEntry = {
+  command: string;
+  flags: string[];
+}
+
+export default class Generate extends Command {
+    public static flags = {
+      filepath: flags.string({
+        description: 'path to save the generated snapshot file; can use "{version}" to replace the current CLI/plugin version',
+        default: './command-snapshot.json',
+      }),
+    };
+
+    public async run() {
+      const numberOfSpaceChar = 4
+      const {flags} = this.parse(Generate)
+      const commands = this.config.commands
+      const resultCommands = _.sortBy(commands, 'id').map(command => {
+        return {
+          command: command.id,
+          flags: Object.keys(command.flags),
+        }
+      }) as SnapshotEntry[]
+      const filePath = flags.filepath.replace('{version}', this.config.version)
+
+      fs.writeFileSync(filePath, JSON.stringify(resultCommands, null, numberOfSpaceChar))
+      this.log(`Generated snapshot file "${filePath}"`)
+    }
+}

src/index.ts

@@ -0,0 +1 @@
+export default {}

test/command-snapshot.json

@@ -0,0 +1,20 @@
+[
+    {
+        "command": "help",
+        "flags": [
+            "all"
+        ]
+    },
+    {
+        "command": "snapshot:compare",
+        "flags": [
+            "all"
+        ]
+    },
+    {
+        "command": "removed:command",
+        "flags": [
+            "filepath"
+        ]
+    }
+]