Merge pull request #18 from cinaq/docs

Docs

.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  publish-docs:
+    name: Release Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build
+        run: |
+          git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY -b gh-pages public
+          pip install -r requirements.txt
+          python scripts/generate-policies-docs.py
+          mkdocs build --verbose --clean
+
+      - name: Publish
+        run: |
+          git config --global user.name 'Robot'
+          git config --global user.email '[email protected]'
+          rsync -av --delete site/ public/
+          cd public && git add . && git commit -m "Publish" && git push origin gh-pages

.github/workflows/release.yml

@@ -42,7 +42,7 @@ jobs:
         id: get_release
         uses: bruceadams/[email protected]
         env:
-          GITHUB_TOKEN: ${{ github.token }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Upload Release Asset (ZIP)
         uses: actions/upload-release-asset@v1
@@ -63,4 +63,3 @@ jobs:
           asset_path: ./policies.tar.gz
           asset_name: policies-${{ steps.get_release.outputs.tag_name}}.tar.gz
           asset_content_type: application/gzip
-

.gitignore

@@ -50,3 +50,8 @@ go.mod
 
 # Visual Studio Code
 .vscode/
+
+# ignore generated files
+site
+docs/policies
+

Makefile

@@ -47,4 +47,7 @@ deps:
 	@echo "Fetching dependencies"
 	@go mod tidy
 
-.PHONY: all build-macos build-windows clean test deps
+docs:
+	mkdocs build
+
+.PHONY: all build-macos build-windows clean test deps docs

docs/CNAME

@@ -0,0 +1 @@
+mxlint.cinaq.com

docs/README.md

@@ -0,0 +1,3 @@
+# MxLint Documentation
+
+MxLint (Formerly Mendix-CLI) is a set of tools to help you build high quality Mendix apps. 

docs/TODO/Datamodel/4-More-than-2-microflow-attributes-within-one-domain-object.markdown

@@ -0,0 +1,19 @@
+---
+
+layout: post
+title:  "More than 2 microflow attributes within one domain object"
+categories: Datamodel
+prio: 4
+rulenumber: 4
+rulename: AvoidTooMuchCalculatedAttributes
+ruleset: Performance
+
+---
+
+**Why**
+Microflow attributes have a strong negative impact on performance, especially the attributes that have database interaction. If you managed to eliminate for example about 100 MF attributes on a medium/large application (model size +- 100MB) you will probably increase performance on load tests with factor 3-6.
+
+![4.png]({{ site.url }}/assets/4.png)
+
+**How to fix**
+Make the attributes 'stored' and calculate them in an event, or put the microflow attributes in a separate object.

mkdocs.yaml

@@ -0,0 +1,52 @@
+site_name: MxLint
+theme:
+  name: 'material'
+  logo: assets/logo.png
+#  custom_dir: overrides
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: blue
+      accent: blue grey
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue grey
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  features:
+    - search.suggest
+    - search.highlight
+    - search.share
+    - navigation.footer
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.tracking
+    # - navigation.sections
+    # - navigation.expand
+    # - toc.integrate
+    - header.autohide
+extra:
+  homepage: /
+plugins:
+  - search
+  - awesome-pages
+copyright: Copyright &copy; 2022 - 2024 <a href="https://cinaq.com">CINAQ.com</a>
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format

requirements.txt

@@ -0,0 +1,33 @@
+Babel==2.14.0
+bracex==2.4
+certifi==2023.11.17
+charset-normalizer==3.3.2
+click==8.1.7
+colorama==0.4.6
+ghp-import==2.1.0
+idna==3.6
+Jinja2==3.1.2
+Markdown==3.5.1
+MarkupSafe==2.1.3
+mergedeep==1.3.4
+mkdocs==1.5.3
+mkdocs-awesome-pages-plugin==2.9.3
+mkdocs-get-deps==0.2.0
+mkdocs-material==9.5.3
+mkdocs-material-extensions==1.3.1
+natsort==8.4.0
+packaging==23.2
+paginate==0.5.6
+pathspec==0.12.1
+platformdirs==4.1.0
+Pygments==2.17.2
+pymdown-extensions==10.7
+python-dateutil==2.8.2
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.12.25
+requests==2.31.0
+six==1.16.0
+urllib3==2.1.0
+watchdog==3.0.0
+wcmatch==8.5.2

scripts/generate-policies-docs.py

@@ -0,0 +1,105 @@
+#! /usr/bin/env python3
+
+import json
+import os
+import sys
+import argparse
+import yaml
+
+"""
+# METADATA
+# scope: package
+# title: No more than 15 persistent entities within one domain model
+# description: The bigger the domain models, the harder they will be to maintain. It adds complexity to your security model as well. The smaller the modules, the easier to reuse.
+# authors:
+# - Xiwen Cheng <[email protected]>
+# custom:
+#  category: Maintainability
+#  rulename: NumberOfEntities
+#  severity: MEDIUM
+#  rulenumber: 002_0001
+#  remediation: Split domain model into multiple modules.
+#  input: "*/DomainModels$DomainModel.yaml"
+"""
+
+def parse(policy_file: str):
+    """
+    Parse the policy.
+    """
+    metadata_lines = []
+
+    with open(policy_file, "r") as f:
+        for line in f.readlines():
+            if line.startswith("# METADATA"):
+                continue
+            clean_line = line.replace("# ", "", 1).strip()
+            if line.startswith("#"):
+                metadata_lines.append(clean_line)
+            else:
+                break
+    raw_yaml = "\n".join(metadata_lines)
+    metadata = yaml.load(raw_yaml, Loader=yaml.SafeLoader)
+    return metadata
+
+def generate_policies_docs(policies_dir: str, output_dir: str):
+    """
+    Generate the policies documentation from the policies directory.
+    """
+    for policy in os.listdir(policies_dir):
+        out_dir = os.path.join(output_dir, policy)
+        in_dir = os.path.join(policies_dir, policy)
+        os.makedirs(out_dir, exist_ok=True)
+
+        if os.path.isdir(in_dir):
+            for file in os.listdir(in_dir):
+                if file.endswith(".rego") and not file.endswith("_test.rego"):
+                    in_file = os.path.join(in_dir, file)
+                    out_file = os.path.join(out_dir, file.replace(".rego", ".md"))
+                    generate_policy_docs(in_file, out_file)
+
+def get_test_file(policy_file: str):
+    """
+    Get the test file for the policy.
+    """
+    test_file = policy_file.replace(".rego", "_test.rego")
+    if not os.path.exists(test_file):
+        return "# No test file found"
+
+    with open(test_file, "r") as f:
+        body = f.read()
+    return body
+
+def generate_policy_docs(policy_file: str, output_file: str):
+    policy = parse(policy_file)
+
+    title = policy.get("title", "Untitled")
+    description = policy.get("description", "No description provided")
+    remediation = policy.get("remediation", "No remediation provided")
+    del policy["title"]
+    del policy["description"]
+    del policy["remediation"]
+
+    with open(output_file, "w") as f:
+        f.write(f"# {title}\n")
+        f.write(f"## Description\n")
+        f.write(f"{description}\n")
+        f.write(f"## Remediation\n")
+        f.write(f"{remediation}\n")
+        f.write(f"## Metadata\n")
+        f.write(f"```yaml\n")
+        f.write(f"{yaml.dump(policy)}\n")
+        f.write(f"```\n")
+        f.write(f"## Test script\n")
+        f.write(f"```rego\n")
+        f.write(f"{get_test_file(policy_file)}\n")
+        f.write(f"```\n")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-p", "--policies", type=str, default="policies", help="The directory containing the policy definitions")
+    parser.add_argument("-o", "--output", type=str, default="docs/policies", help="The directory to output the policies documentation")
+    args = parser.parse_args()
+
+    generate_policies_docs(args.policies, args.output)
+