fix: report generator

Author: offgriddev

.github/actions/publish-report/action.yml

@@ -0,0 +1,60 @@
+name: Publish Cyclomatic Complexity Report
+description: For rate of production analysis, this action calculates code metrics on the repo and pushes the results to S3.
+inputs:
+  aws-access-key-id:
+    required: true
+  aws-secret-access-key:
+    required: true
+  environment:
+    required: true
+  npm-token:
+    required: true
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/checkout@v3
+      
+    - name: Use Node.js ${{ env.NODE_VERSION }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+        cache: 'yarn'
+
+    - name: Configure package manager
+      shell: sh
+      run: |
+        npm config set '//registry.npmjs.org/:_authToken' ${{ env.NPM_TOKEN }}
+        yarn config set npmAuthToken ${{ env.NPM_TOKEN }}
+        npm whoami
+      env:
+        NPM_TOKEN: ${{ inputs.npm-token }}
+
+    - name: Install dependencies
+      id: install
+      shell: bash
+      run: yarn install --immutable
+
+    - uses: aws-actions/configure-aws-credentials@v1
+      with:
+        aws-access-key-id: ${{ inputs.aws-access-key-id }}
+        aws-secret-access-key: ${{ inputs.aws-secret-access-key }}
+        aws-region: us-east-1
+
+    - name: Generate Code Metrics for Commit
+      id: metrics
+      uses: offgriddev/cyclomatic-js-action@main
+      with:
+        github_token: ${{ github.token }}
+        event: ${{ toJson(github.event) }}
+        includedFileTypes: .js$
+        excludedFileTypes: __mocks__|.test.js|Test.js|dist
+
+    - name: Print Result
+      shell: bash
+      run: cat ${{ steps.metrics.outputs.export_filename }}
+
+    - name: Publish Commit Analytics
+      id: publish
+      shell: bash
+      run: |
+        aws s3 sync complexity-assessment s3://cyclomatic-js-metrics-${{ inputs.environment }} --cache-control max-age=31536000

README.md

@@ -1,35 +1,123 @@
 # CyclomaticJS - A Complexity Measure for JavaScript
 
-Cyclomatic Complexity was developed by a Computer Scientist at IBM named Thomas McCabe in an article titled [A Complexity Measure](https://ieeexplore.ieee.org/document/1702388). A metric we often use to identify "code quality" concerns, cyclomatic complexity is a useful analytical tool for many reasons. And now it's available for Vanilla JavaScript! 
+Cyclomatic Complexity was developed by a Computer Scientist at IBM named Thomas McCabe in an article titled [A Complexity Measure](https://ieeexplore.ieee.org/document/1702388). A metric we often use to identify "code quality" concerns, cyclomatic complexity is a useful analytical tool for many reasons. And now it's available for both CommonJS and ESModules JavaScript repositories!
 
-If you're unfamiliar with Cyclomatic Complexity, it's an application of Graph Theory to the logical structure of algorithms. The logical structure of algorithms accounts for many constructs we leverage in software engineering: if-statements, switch-statements, for/while/forof/dowhile loops, etc. In measuring these facets of our source code, Cyclomatic Complexity measures _how many possible linear paths through a given algorithm_. It will produce a simple integer value as an assessment. For example, the following code has an objective Complexity of 2:
+First, let's cover the technical How-To for the contained NPM package and it's GitHub Action. Second, we'll dive deep into theory and explain why you would even want to use this anyway.
+
+## Using
+
+You can levarage CyclomaticJS as both a standalone import for your JavaScript project or as a GitHub Action in your CI workflows.
+
+## CyclomaticJS as an Import
+
+CyclomaticJS provides a library for importing into JS:
 
 ```javascript
-function main(a) {
-  if (a > 0) {
-    return "is positive"
+import {calculateComplexity} from 'cyclomatic-js'
+
+const complexity = calculateComplexity('somefile.js')
+console.log(complexity)
+```
+
+This will produce a file called `complexity-report.json` in the main directory of your repository. The file will loo like this:
+
+```json
+[
+  {
+    "file": "./src/some-file.js",
+    "report": {
+      "function1": 2,
+      "function2": 1,
+      "function3": 3
+    }
   }
+]
+```
 
-  return "is negative"
-}
+The report object is simple, it contains the filename and a `report` with the function name and the cyclomatic complexity for that function.
+
+## CyclomaticJS as a GitHub Action
+
+CyclomaticJS also provides a GitHub Action to generate a report for pushing to any BI tool or storage for aggregation and analysis:
+
+```yml
+- name: Generate Code Metrics for Commit
+  id: metrics
+  uses: offgriddev/cyclomatic-js-action@main
+  with:
+    github_token: ${{ github.token }}
+    event: ${{ toJson(github.event) }}
+    includedFileTypes: .js$
+    excludedFileTypes: __mocks__|.test.js|Test.js|dist
 ```
 
-As code grows, and I'm sure we've all seen it, algorithms can take on a life of their own and grow to contain numerous linear paths that all have to be maintained and amount to the cognitive overhead of a given algorithm. 
+This action has one export: `export_filename`. This stores the filename for the report generated by the complexity reporter in the CyclomaticJS package.
 
-This library provides any JS library the ability to analyze the Cyclomatic Complexity of their functions with a dependency solely on the [abstract-syntax-tree](https://www.npmjs.com/package/abstract-syntax-tree)
+## Why Use CyclomaticJS?
 
-# How to Use
+To answer why you would want to use CyclomaticJS, you need to know a little about the code metric it uses. You may be new to software engineering, or you might be a senior or director and have not thoughtfully understood this concept. So let us briefly cover its nature.
 
-CyclomaticJS has two export: `calculateComplexity` and `generateComplexityReport`
+### What is Cyclomatic Complexity
 
-This function takes a `filename` and calculates the logical complexity of a file's contents.
+Cyclomatic Complexity, the code metric this repository analyses, measures the number of linear paths through a given function. Your function may be simple:
 
 ```javascript
-import { calculateComplexity } from 'cyclomatic-js'
+function getNumberPolarity(a) {
+  if (a > 0) {
+    return 'is positive'
+  } else if (a < 0) {
+    return 'is negative'
+  } else {
+    return 'is neither positive nor negative'
+  }
+}
+```
 
-const complexity = calculateComplexity('somefile.js')
+But as you can see, given a specific range of the variable `a`, the output may be different. There are three possible outputs.
 
-```
+1. When `a > 0`, the output is `is positive`.
+2. When `a < 0`, the output is `is negative`.
+3. When `a == 0`, the output is `is neither positive nor negative`.
+
+Since there are 3 possible paths through this function, the Cyclomatic Complexity is 3. This is acquired by creating an Abstract Syntax Tree and measuring the _logical structures_ of a function. An `IfStatement`, for example, increases the Cyclomatic Complexity of the function because it creates a _logical branch_ in it. The lowest possible number of logical branches in a given function is 1 as an empty `BlockStatement`, or `function empty() { }` has one logical branch.
+
+### Logical Structures that Increase Complexity
+
+These logical structures are Universal. Any Turing Complete language can be measured by its logical structures. The following statements and expressions unconditionally increase the complexity of a function:
+
+`IfStatement`
+`TryStatement`
+`CatchClause`
+`DoWhileStatement`
+`ForInStatement`
+`ForOfStatement`
+`WhileStatement`
+`ConditionalExpression`
+
+The following conditionally increase the complexity of a function:
+
+`SwitchCase` as in the `case` statement of a `SwitchStatement` increases the complexity when the `case` has statements.
+`LogicalExpression` increases the complexity when it is a `||`, `&&`, or `??`.
+
+### Why Use Cyclomatic Complexity
+
+Now for the question you may have asked yourself at some point if you've made it this far and have been looking for a JavaScript library to do this analysis for you. There are two main personas this library and action are targetting: Developers and anyone concerned with _estimations_. That last persona is vague. I promise, I will get there.
+
+From a developer perspective, you may be concerned with Code Quality and Maintainability. You may have linting rules setup to limit the "size" if your functions, e.g. [eslint-complexity](https://eslint.org/docs/latest/rules/complexity). Some developers have a genuine interest in this as an engineering concern, and rightfully so. This may be around modularization and the role of writing more simple and elegant functions.
+
+If you don't believe Cyclomatic Complexity or nerd out on analysing the logical complexity of your code, then you may be concerned about Estimations in some sense. You might be a Project Manager, a Lead Engineer, or perhaps you work in Professional Services and are putting a bid on a job and want to be competitive _and_ realistic.
+
+That's right, you might want to give a _realistic estimation for a given software development effort_. You might, for example, be the CTO and need to report to ELT a high-level estimate for getting funding for a project. The second category is broad, but you want to provide as realistic of an estimation as you can.
+
+## Estimation Methodology
+
+Code is complex. Complexity in our functions is a result of the logical structure we write. When we develop, we produce functions, algorithms, that codify _business requirements_. If we take snapshots of this over time, we can understand the pace at which we develop software. Therefore, we can provide realistic estimations based on the concrete code we deliver over time.
+
+This repository allows your teams to analyze the comlexity you're deliver as part of codifying the business requirements in your repositories. Complexity grows over time. Each developer also delivers functions of a given complexity at some rate. Cyclomatic Complexity is the objective measurement you can use the give estimations. By measuring the complexity a developer commits to production, you can do the following:
+
+1. The actual complexity delivered by getting the delta from the previous commit
+2. Validate the accuracy of an estimate
+3. Understand the rate a developer produces business requirements based on the developer's historic delivery of functional complexity
 
 # Supported Source Code