add developing checks guide

Author: krzkaczor

README.md

@@ -30,11 +30,11 @@ Expect more docs soon...
 
 1. [Getting started](getting-started.md)
 1. [How does it work?](how-does-it-work.md)
-1. [How to build X?](how-to-build-X.md)
 1. [Configuration — codechecks.json/ts/js](configuration.md)
-1. Checks (plugins) development
+1. [Checks (plugins) development](developing-checks.md)
    1. Developing reusable checks
    1. Testing checks
+1. [How to build X?](how-to-build-X.md)
 1. Client API reference
 1. [FAQ](faq.md)
 1. Roadmap

developing-checks.md

@@ -0,0 +1,115 @@
+# Developing checks
+
+In this tutorial we are gonna build simplified version of
+[build-size-watcher](https://github.com/codechecks/build-size-watcher). It's gonna be able just to
+watch size of a single file and doesn't support gzip. We are gonna use yarn in this tutorial but you
+can pick npm as well. Lets' start!
+
+We want our check to be fully reusable so we are gonna create new npm package just for it.
+
+```sh
+mkdir simple-build-size-watcher
+cd simple-build-size-watcher
+yarn init -y
+```
+
+Let's install codechecks client.
+
+```
+yarn add --dev @codechecks/client
+```
+
+Let's start developing index.js file. Our check is just a function that takes a path to a file that
+we want to observe and it a default export of a module.
+
+```js
+const { codechecks } = require("@codechecks/client");
+
+module.exports = function(path) {
+  // it's alive!
+};
+```
+
+Lets calculate size of a file pointed by a path. After quick visit at stackoverflow we can come up
+with a function getSize:
+
+```js
+const fs = require("fs");
+function getSize(path) {
+  const stats = fs.statSync(path);
+  return stats.size;
+}
+```
+
+Since we want to track how this value changes in time we need to upload it to StorageAPI. Client
+makes this super simple:
+
+```js
+const { codechecks } = require("@codechecks/client");
+
+module.exports = function(path) {
+  const currentSize = getSize(path);
+  await codechecks.saveValue("simple-build-size-watcher", currentSize);
+};
+```
+
+`saveValue` takes two arguments: unique name of a value and any value. Saving data to storage api is
+automatically prefixed with **current SHA** (opposed to reading).
+
+Yay, we are half way through. Now we need to get previous build size and compare two values.
+Remember that value for base branch may not exist, then we just assume it's 0. Nothing simpler:
+
+```js
+const { codechecks } = require("@codechecks/client");
+const bytes = require("bytes");
+
+module.exports = async function(path) {
+  const currentSize = getSize(path);
+  await codechecks.saveValue("simple-build-size-watcher", currentSize);
+
+  const baseSize = (await codechecks.getValue("simple-build-size-watcher")) || 0;
+
+  const diff = currentSize - baseSize; // ex. 1231
+  const formattedBytes = bytes(diff); // "1KB"
+};
+```
+
+Note how we can use existing packages to easily nicely format bytes into something readable. Now the
+very last thing that we need to do is report data back to github. We use report api for that.
+
+```js
+const { codechecks } = require("@codechecks/client");
+const bytes = require("bytes");
+
+module.exports = async function({ path }) {
+  const currentSize = getSize(path);
+  await codechecks.saveValue("simple-build-size-watcher", currentSize);
+
+  const baseSize = (await codechecks.getValue("simple-build-size-watcher")) || 0;
+
+  const diff = currentSize - baseSize; // ex. 1231
+  const formattedBytes = bytes(diff); // "1KB"
+
+  await codechecks.success({
+    name: "Simple Build Size",
+    shortDescription: `Size changed by: ${formattedBytes} Total size: ${bytes(currentSize)}`,
+  });
+};
+
+const fs = require("fs");
+function getSize(path) {
+  const stats = fs.statSync(path);
+  return stats.size;
+}
+```
+
+That's it. Whole code is placed in `/example` directory of this repo.
+
+## Testing
+
+Because codechecks client is an external dependency that is supposed to be imported by your modules
+this makes testing a little bit harder. We recommend to use jest mocking super powers. Tests for
+this project are part of `/example` dir.
+
+You can find more complicated example here:
+https://github.com/codechecks/build-size-watcher/tree/master/src/__tests__

example/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+lib

example/.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+.vscode
+package.json
+lib

example/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "proseWrap": "always"
+}

example/README.md

@@ -0,0 +1,41 @@
+<p align="center">
+  <h3 align="center">Simple build size watcher</h3>
+</p>
+
+## Install
+
+```sh
+npm add --save-dev simple-build-size-watcher
+```
+
+or
+
+```sh
+yarn add --dev simple-build-size-watcher
+```
+
+## Usage
+
+Add to your `codechecks.json` file:
+
+<!-- prettier-ignore -->
+```json5
+{
+  "checks": [
+    {
+      "name": "simple-build-size-watcher",
+      "options": {
+        "path": "./index.js"
+      }
+    }
+
+    // ...
+  ]
+}
+```
+
+With each pull request you will get information how does build size change over time.
+
+## Licence
+
+MIT @ [codechecks.io](https://codechecks.io)

example/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  roots: ["<rootDir>/src"],
+  testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.jsx?$",
+  moduleFileExtensions: ["js", "jsx", "json", "node"],
+};

example/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@codechecks/commit-deployment",
+  "description": "Ship every code change that you make",
+  "keywords": [
+    "commit-deploy",
+    "deployment",
+    "continuous deployment",
+    "codechecks"
+  ],
+  "repository": "codechecks/commit-deployment",
+  "author": "Chris Kaczor <[email protected]>",
+  "version": "0.0.4",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "rm -rf ./lib && tsc",
+    "format": "prettier --list-different '**/*.{ts,json,md, gql}'",
+    "format:fix": "prettier --write '**/*.{ts,json,md,gql}'",
+    "lint": "yarn format",
+    "lint:fix": "yarn format:fix",
+    "test:unit": "jest",
+    "test:watch": "jest --watch",
+    "test": "yarn lint && yarn test:unit",
+    "test:fix": "yarn lint:fix && yarn test:unit",
+    "prepublishOnly": "yarn test && yarn build"
+  },
+  "files": [
+    "lib/**/*"
+  ],
+  "devDependencies": {
+    "@codechecks/client": "^0.0.52",
+    "jest": "^23.6.0",
+    "mock-fs": "^4.8.0",
+    "prettier": "^1.15.3"
+  },
+  "peerDependencies": {
+    "@codechecks/client": "^0.0.48"
+  },
+  "dependencies": {
+    "bytes": "^3.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=6"
+  }
+}

example/src/__mocks__/@codechecks/client.js

@@ -0,0 +1,15 @@
+module.exports.codechecks = {
+  report: jest.fn(),
+  getValue: jest.fn(),
+  saveValue: jest.fn(),
+  getCollection: jest.fn(),
+  saveCollection: jest.fn(),
+  isPr: jest.fn(),
+  context: {
+    workspaceRoot: "/codechecks",
+  },
+  getArtifactLink: jest.fn(),
+  getPageLink: jest.fn(),
+  success: jest.fn(),
+  failure: jest.fn(),
+};

example/src/__tests__/index.spec.js

@@ -0,0 +1,60 @@
+const { join } = require("path");
+const mockFS = require("mock-fs");
+
+const simpleBuildSizeWatcher = require("../index");
+const { codechecks } = require("@codechecks/client");
+
+describe("simple-build-size-watcher", () => {
+  const codeChecksMock = require("../__mocks__/@codechecks/client").codechecks;
+  beforeEach(() => jest.resetAllMocks());
+
+  it("should work", async () => {
+    codeChecksMock.isPr.mockReturnValue(true);
+    mockFS({
+      [join(__dirname, "../build")]: {
+        "main.js": "APP JS",
+      },
+    });
+
+    await simpleBuildSizeWatcher({
+      path: join(__dirname, "../build/main.js"),
+    });
+
+    mockFS.restore();
+    expect(codechecks.saveValue).toMatchInlineSnapshot(`
+[MockFunction] {
+  "calls": Array [
+    Array [
+      "simple-build-size-watcher",
+      6,
+    ],
+  ],
+  "results": Array [
+    Object {
+      "isThrow": false,
+      "value": undefined,
+    },
+  ],
+}
+`);
+
+    expect(codechecks.success).toMatchInlineSnapshot(`
+[MockFunction] {
+  "calls": Array [
+    Array [
+      Object {
+        "name": "Simple Build Size",
+        "shortDescription": "Size changed by: 6B Total size: 6B",
+      },
+    ],
+  ],
+  "results": Array [
+    Object {
+      "isThrow": false,
+      "value": undefined,
+    },
+  ],
+}
+`);
+  });
+});

example/src/index.js

@@ -0,0 +1,23 @@
+const { codechecks } = require("@codechecks/client");
+const bytes = require("bytes");
+
+module.exports = async function({ path }) {
+  const currentSize = getSize(path);
+  await codechecks.saveValue("simple-build-size-watcher", currentSize);
+
+  const baseSize = await codechecks.getValue("simple-build-size-watcher") || 0;
+
+  const diff = currentSize - baseSize; // ex. 1231
+  const formattedBytes = bytes(diff); // "1KB"
+
+  await codechecks.success({
+    name: "Simple Build Size",
+    shortDescription: `Size changed by: ${formattedBytes} Total size: ${bytes(currentSize)}`,
+  });
+};
+
+const fs = require("fs");
+function getSize(path) {
+  const stats = fs.statSync(path);
+  return stats.size;
+}