fc4-framework

fc4-tool

A tool for reorganizing, restructuring, and reformatting FC4 diagrams.

CircleCI codecov

Purpose

As explained in The Toolset section of the FC4 Methodology:

This tool was created because when one uses Structurizr Express (SE) to position the elements of a diagram, SE regenerates the diagram source YAML in such a way that the YAML becomes noisy and the sorting can change. This makes the source harder to work with in a text editor and impossible to usefully diff from revision to revision — and without useful diffing it’s very difficult to do effective peer review.

So fc4-tool processes the YAML: cleans it up, applies a stable sort to all properties, removes empty properties, etc — so as to ensure that the changes applied in each revision are very small and specific and all extraneous changes are filtered out. This will hopefully enable effective peer review of revisions to the diagrams.

fc4-tool also “snaps” the elements and vertices in a diagram to a virtual grid.

Setup

  1. Install Clojure as per this guide
    1. This project uses the new Clojure CLI (clj) and tools.deps, both of which are installed by the new official Clojure installers released alongside Clojure 1.9. If you’ve been working with Clojure for awhile, you might not have these tools installed. Try which clj to check, and if that prints a blank line, try running the appropriate installer.
  2. Clone this repo
  3. cd into the repo and then cd tool
  4. To install the dependencies, run: clojure -Sdescribe'

Basic Usage

  1. Have clj installed (guide)
  2. Run in your shell, from the root of the repo: cd tool && ./wcb

Full Usage Workflow

As explained in The Authoring Workflow section of the FC4 Methodology:

  1. In your text editor: either create a new diagram source file or open an existing diagram source file
  2. In a terminal, in your fc4 working dir, run cd tool && ./wcb
    1. This starts the tool in a mode wherein it will watch your clipboard for diagram source YAML and process (clean up) that YAML when it sees that it’s been changed.
  3. In your text editor, add/revise elements and relationships, then select-all and cut the diagram source from your editor into your system clipboard.
    1. This will cause fc4-tool to process the contents of your clipboard.
  4. Switch to Structurizr Express (SE) » paste the source into the YAML textarea » press tab to blur the textarea
    1. SE will either render the diagram, or display a red error indicator in its toolbar
    2. If SE shows its red error indicator, click the indicator button to bring up a dialog listing the errors
  5. Use SE to arrange the elements and edges as desired
  6. Cut the diagram source from the SE YAML textarea into your system clipboard.
    1. This will cause fc4-tool to process the contents of your clipboard.
  7. Paste the diagram source back into the SE YAML textarea so as to re-render the diagram, now that the elements have been “snapped” to a virtual grid.
  8. Continue to cut and past the diagram source between your text editor and SE, using SE to preview and adjust the rendered diagram, while fc4-tool cleans up the diagram as you work.

Running the Tests

  1. Use CI
  2. No, seriously, use CI!
  3. Just kidding, I know sometimes you need to run the tests locally ;)

With Docker

Run this in your shell:

docker run --rm `docker build -q .`

Without Docker

If you’re old-school and prefer to run tests on bare metal:

  1. Have clojure installed (guide)
  2. Run in your shell: clojure -A:test:test/run

Starting a REPL for Dev/Test

You could just run clj but you’re likely to want the test deps and dev utils to be accessible. So you’ll probably want to run clj -A:dev:test

Running the tests in a REPL

$ clj -A:dev:test
Clojure 1.9.0
user=> (require '[eftest.runner :refer [find-tests run-tests]])
user=> (run-tests (find-tests "test") {:fail-fast? true})
...

Running the Linter

For linting, this project uses cljfmt, via cljfmt-runner.

We’ll soon be integrating a lint run into our CI builds so they’ll fail if any source code is formatted incorrectly. Coming soon!

Contributors

Thank you all!

(If you notice that anyone is missing from this list, please open an issue or a PR — thank you!)