feat(utilities): Add a Cassandra schema to D2 diagram entity converter (

#301)

* feat: initial entry

* feat: tokenizer

* feat: complete simple parser

* feat: extract pk

* feat: to d2 diagram formatter

* feat: display format

* feat: tooltip format

* feat: file management

* feat: add pyproject

* docs: readme

* feat: add poetry.lock

* chore: ruff format

* chore: some manual fixes

* chore: final format

* chore: final format

* chore: type fix

* chore: md fix

* chore: manual fix md

* feat: earthly target

* fix: move file

* fix: space

* feat: partition key

* feat: support desc ordering type

* chore: ruff format

* feat: data type enum

* refactor: static key to field

* chore: rename pk to cluster keys

* chore: rename cluster_key to clustering_keys

* feat: generic type parsing

* feat: counter

* fix: containing type format

* chore: ruff format

* feat: support udt

* docs: sectioning comments

* feat: earthfile

* test: adding test files

* docs: update markdown

* docs: fix path

* dix: docs

* fix: cspell

* fix: earthly spelling

* ci: fix target output

* fix: docs

* docs: fix comment

* docs: include diagram

* fix: cspell

* refactor: remove diagram duplication

docs/Earthfile

@@ -1,6 +1,7 @@
 VERSION 0.8
 
 IMPORT ../earthly/docs AS docs-ci
+IMPORT ../utilities/cql-to-d2 AS cql-to-d2-ci
 IMPORT .. AS cat-ci
 IMPORT ../examples/postgresql AS postgresql-ci
 
@@ -12,6 +13,10 @@ src:
     # Now copy into that any artifacts we pull from the builds.
     COPY --dir cat-ci+repo-docs/repo includes
 
+    # Copy D2 contents to display in the docs.
+    COPY cql-to-d2-ci+src/tests/input/test_1.cql src/appendix/examples/diagrams/sample_d2.cql
+    COPY cql-to-d2-ci+src/tests/expected_output/test_1.d2 src/appendix/examples/diagrams/sample_d2.d2
+
     # Copy docs we build in the postgres example.
     COPY --dir postgresql-ci+build/docs src/appendix/examples/built_docs/postgresql
 

docs/src/appendix/examples/d2-diagrams.md

@@ -0,0 +1,39 @@
+---
+icon: material/draw
+---
+
+# Converting CQL to D2
+
+This is the guide how to use the earthly target
+to convert a CQL schema file into D2 diagram entity.
+
+Following is the sample of using the target:
+
+```earthly
+VERSION 0.8
+
+IMPORT utilities/cql-to-d2 AS cql-to-d2-utils
+
+example:
+    FROM scratch
+
+    COPY . .
+
+    COPY (+cql-to-d2/diagrams --input="./input") ./output
+
+    RUN ls ./output
+```
+
+## Converting result sample
+
+This is the sample valid CQL schema code:
+
+```cql
+{{ include_file('src/appendix/examples/diagrams/sample_d2.cql') }}
+```
+
+Resulted in D2:
+
+```d2
+{{ include_file('src/appendix/examples/diagrams/sample_d2.d2') }}
+```

earthly/cassandra/Earthfile

@@ -0,0 +1,37 @@
+# cspell: words scylladb ensurepath
+
+VERSION 0.8
+
+IMPORT ../../utilities/cql-to-d2 AS cql-to-d2-utils
+
+scylladb-base:
+    FROM scylladb/scylla:6.1.1
+
+    WORKDIR /root
+
+    RUN apt-get update && apt-get install -y python3 pipx
+
+    RUN pipx ensurepath
+    RUN pipx install poetry
+
+# cql-to-d2 - converts cql files into d2 diagram entity files
+cql-to-d2:
+    FROM +scylladb-base
+
+    ARG --required input
+
+    COPY cql-to-d2-utils+src/main.py .
+
+    COPY $input ./src
+
+    RUN python3 main.py ./src ./diagrams
+
+    SAVE ARTIFACT ./diagrams
+
+CQL_TO_D2:
+    FUNCTION
+
+    ARG --required input
+    ARG --required output
+
+    COPY (+cql-to-d2/diagrams --input=$input) $output

utilities/cql-to-d2/Earthfile

@@ -0,0 +1,26 @@
+VERSION 0.8
+
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.1.7 AS python-ci
+
+check:
+    FROM python-ci+python-base
+
+    COPY . .
+
+    DO python-ci+CHECK
+
+test:
+    FROM python-ci+python-base
+
+    COPY . .
+
+    RUN python3 main.py tests/input tests/output
+    RUN cmp -s tests/expected_output/test_1.d2 tests/output/test_1.d2 && echo "Results are identical." || { echo "Results are different."; exit 1; }
+
+src:
+    FROM scratch
+
+    COPY . .
+
+    SAVE ARTIFACT tests
+    SAVE ARTIFACT main.py

utilities/cql-to-d2/README.md

@@ -0,0 +1,39 @@
+# Cassandra Schema to D2 Diagram Converter
+
+Converts Cassandra schemas to D2 diagram entity `sql_table`.
+The program accepts two arguments `<src-dir>` and `<out-dir>`.
+So it reads the whole directory.
+The files with `.cql` extension will be read.
+And transform individually into the D2 diagram entity, `.d2` extension file.
+If the `<out-dir>` does not exist,
+then the directory will be created automatically.
+
+## How to use it as a CLI
+
+```bash
+python3 main.py <input-dir> <output-dir>
+```
+
+## How to use it as an Earthly target
+
+You can simply refer the target to `earthly/cassandra` in this repository.
+The target is `cql-to-d2`.
+Make sure you include the required arguments.
+After using the target,
+you can save the artifact (output) according to your output path.
+
+```earthly
+COPY (+cql-to-d2/<output> --input="./<input>" --output="./<output>") ./<save-dir>
+```
+
+And include this line to your target.
+
+## A valid CQL file and limitations
+
+* Make sure that a CQL file is fundamentally syntactically correct.
+* Only unquoted name is supported.
+* Secondary index is not supported.
+* User defined type (UDT) is not supported.
+* One table per one CQL file.
+* Items inside `PRIMARY KEY` must not be empty.
+* In-line primary key is not supported.