Merge branch 'main' into main

.github/workflows/test.yml

@@ -150,9 +150,11 @@ jobs:
 
       - name: Docker Test Analysis
         run: |
-          docker build ./analysis -t local-ccsh --build-arg USER_UID=1001
+          user_instance="docker_runner"
+          docker build ./analysis -t local-ccsh --build-arg USER_ADD=true --build-arg USER_ID=1001 --build-arg USERNAME=${user_instance} --no-cache
           current_version=$(node -pe "require('./analysis/node-wrapper/package.json').version")
-          docker run -w /home/nonroot-docker-user/cc/analysis/test -v $(pwd):/home/nonroot-docker-user/cc local-ccsh bash ./golden_test.sh ${current_version} /home/nonroot-docker-user/tmp-files/ /usr/local/bin/ccsh
+          docker run -w /home/${user_instance}/cc/analysis/test -v $(pwd):/home/${user_instance}/cc local-ccsh bash ./golden_test.sh ${current_version} /home/${user_instance}/tmp-files/ /usr/local/bin/ccsh
+          docker build ./analysis -t local-ccsh --no-cache
         working-directory: ${{env.project-directory}}
 
       - name: Setup Java JDK

DEV_START_GUIDE.md

@@ -90,26 +90,36 @@ npm run start
 You can also directly build a distributable package (.zip) of the standalone client for your system.
 For more information, see the 'Package' section of the [visualisation readme](https://github.com/MaibornWolff/codecharta/tree/main/visualization#package).
 
-# IntelliJ setup
+# Testing
+
+The analysis and visualisation parts are tested separately with different tools. \
+For the analysis, we use gradle for testing, linting and formatting. More information is available [here](https://maibornwolff.github.io/codecharta/docs/new-to-code-analysis/#testing).\
+For the visualisation, we utilize Jest and puppeteer for unit- and e2e-tests. To run all unit tests, execute `npm test`. More information about e2e-tests can be found [here](https://maibornwolff.github.io/codecharta/dev-guide/e2e-testing-with-puppeteer/).
+
+When opening a pull requests, all tests are executed automatically using GitHub-actions and a branch can only be merged if all tests are successful. However, it is highly recommended to test changes before pushing them!
+
+# Docker
+
+For deployment and usage of the docker images, check out our documentation page [here](https://maibornwolff.github.io/codecharta/docs/docker-containers/).
+
+# Troubleshooting
 
-We mainly use IntelliJ for our development. The project generally works right away, except for two issues that sometimes occur:
+We mainly use IntelliJ for our development. The project generally works right away, but sometimes issues can occur:
 
 -   Sometimes when opening the main CodeCharta folder, the analysis part does not get detected as a module. To solve this, directly open the analysis folder.
+-   The integration tests for the analysis (`./gradlew integrationTest`) can fail due to OS specific problems:
+
+    -   On **windows** this may be caused by a missing or unknown `sh` command.
+        To make it work, add the path to the Git `sh.exe` (which is normally placed here `C:\<path-to-git>\Git\bin`) to your PATH variable.
+    -   For **macOS**, it is necessary to install the `timeout` command (e.g. using `brew install coreutils`) to execute the integration tests.
+
 -   When working on visualization, IntelliJ does not correctly detect our test-suite. To execute tests using the build in runners,
     it is necessary to adjust the Jest-Configuration:
     -   First select 'Edit...' from the 'More actions' menu next to the Runner icon
     -   Inside there, select 'Edit configuration templates...' at the bottom left
     -   Select 'Jest' and set 'jestUnit.config.json' as the configuration file as well as adding the Jest option '--env=jsdom'
     -   After clicking apply, IntelliJ should e able to execute all visualisation tests
 
-# Testing
-
-The analysis and visualisation parts are tested separately with different tools. \
-For the analysis, we use gradle for testing, linting and formatting. More information is available [here](https://maibornwolff.github.io/codecharta/docs/new-to-code-analysis/#testing).\
-For the visualisation, we utilize Jest and puppeteer for unit- and e2e-tests. To run all unit tests, execute `npm test`. More information about e2e-tests can be found [here](https://maibornwolff.github.io/codecharta/dev-guide/e2e-testing-with-puppeteer/).
-
-When opening a pull requests, all tests are executed automatically using GitHub-actions and a branch can only be merged if all tests are successful. However, it is highly recommended to test changes before pushing them!
-
 # Documentation structure
 
 Our documentation is generally split between user docs and developer docs.

README.md

@@ -24,7 +24,7 @@
 
 <p align="center">
 Latest Release: <br>
- Analysis <a href="https://github.com/MaibornWolff/codecharta/releases/tag/ana-1.123.0">1.123.0</a> | Visualization <a href="https://github.com/MaibornWolff/codecharta/releases/tag/vis-1.125.0">1.125.0</a>
+ Analysis <a href="https://github.com/MaibornWolff/codecharta/releases/tag/ana-1.125.0">1.125.0</a> | Visualization <a href="https://github.com/MaibornWolff/codecharta/releases/tag/vis-1.125.0">1.125.0</a>
 
 [comment]: ##################################################################################
 [comment]: <Ensure that the words 'latest release' are above the line with the links>

analysis/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
 
 ## [unreleased] (Added 🚀 | Changed | Removed 🗑 | Fixed 🐞 | Chore 👨‍💻 👩‍💻)
 
+## [1.125.0] - 2024-05-16
+
+### Changed
+
+-   Update GH-Pages and dev guide on how to use our docker images [#3621](https://github.com/MaibornWolff/codecharta/pull/3621/files)
+
 ### Fixed 🐞
 
 -   Add default Docker user to mitigate `GitLogParser` issues during repo-scan [#3571](https://github.com/MaibornWolff/codecharta/pull/3571)
@@ -16,6 +22,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
 Chore 👨‍💻 👩‍💻
 
 -   Upgrade Gradle to version 8.7, now with support for Java version 21. [#3570](https://github.com/MaibornWolff/codecharta/pull/3570)
+-   Update docs to include that the `timeout` command is necessary on macOS to run integration tests [#3322](https://github.com/MaibornWolff/codecharta/pull/3615)
 
 ## [1.123.0] - 2024-04-10
 

analysis/Dockerfile

@@ -1,5 +1,10 @@
 FROM sapmachine:11.0.23
 
+ARG USER_ADD
+ARG USER_ID=1000
+ARG USER_GID=$USER_ID
+ARG USERNAME=ubuntu
+
 COPY ./build/distributions/codecharta-analysis-*.tar /usr/local/
 
 RUN cd /usr/local; \
@@ -34,12 +39,11 @@ RUN wget -qO /tmp/sonar-scanner.zip https://binaries.sonarsource.com/Distributio
     mkdir --parents /usr/local/conf ; cp ./conf/sonar-scanner.properties /usr/local/conf/; \
     cp -r ./jre/ /usr/local/jre; cd /; rm /tmp/sonar-scanner.zip; rm -rf /tmp/sonar-scanner-*-linux;
 
-ARG USERNAME=nonroot-docker-user
-ARG USER_UID=1000
-ARG USER_GID=$USER_UID
 
-RUN groupadd --gid $USER_GID $USERNAME \
-    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME;
+RUN if [ -n "$USER_ADD" ]; then \
+      groupadd --gid $USER_GID $USERNAME \
+          && useradd --uid $USER_ID --gid $USER_GID -m $USERNAME; \
+    fi
 
 USER $USERNAME
 

analysis/gradle.properties

@@ -1,4 +1,4 @@
-currentVersion=1.123.0
+currentVersion=1.125.0
 org.gradle.parallel=true
 org.gradle.caching=true
 org.gradle.unsafe.configuration-cache=true

analysis/node-wrapper/package.json

@@ -10,7 +10,7 @@
 		"url": "https://github.com/MaibornWolff/codecharta.git"
 	},
 	"name": "codecharta-analysis",
-	"version": "1.123.0",
+	"version": "1.125.0",
 	"description": "MaibornWolff CodeCharta Analysis Tools",
 	"scripts": {
 		"prepare": "rm -rf ../build/install/codecharta-analysis public && ../gradlew -p .. installDist && cp -R ../build/install/codecharta-analysis public",

analysis/tools/ccsh/src/test/kotlin/de/maibornwolff/codecharta/ccsh/CcshTest.kt

@@ -153,8 +153,8 @@ private val outContent = ByteArrayOutputStream()
 
         // then
         Assertions.assertThat(exitCode).isEqualTo(0)
-        Assertions.assertThat(outStream.toString())
-            .contains(listOf("version", "Copyright(c) 2024, MaibornWolff GmbH\n"))
+        // The actual printed version is null, as well as the package name, as it is not set for this test class
+        Assertions.assertThat(outStream.toString()).contains("version", "Copyright(c) 2024, MaibornWolff GmbH")
         verify(exactly = 0) { ParserService.executePreconfiguredParser(any(), any()) }
 
         // clean up

gh-pages/_docs/01-04-docker-containers.md

@@ -83,5 +83,39 @@ docker run -it -v $(pwd):/src -w /src codecharta/codecharta-analysis ccsh gitlog
 # gitlogparser [...] : check the gitlogparser documentation for more info
 ```
 
-> Be aware, that by default the user inside the docker image is 'nonroot-docker-user' with an ID of 1000. You may
+> Be aware, that by default the user inside the docker image is 'ubuntu' with an ID of 1000. You may
 > encounter errors with `git` when you try to execute commands inside a repository cloned by a different `UID`
+
+> For **macOS users**, it is necessary to add `--user=501:dialout` Before the image name. Why? because docker on mac is fun :)
+
+### Build it yourself
+
+You can also build a docker image from the locally installed instance of codecharta. To do this, you would execute the following commands:
+
+```bash
+# to build the container you need to navigate into the analysis folder
+cd analysis
+
+# makes a clean build to ensure everything will be built correctly
+./gradlew clean build
+
+# builds the docker container with an image name of your choice
+docker build . -t your-image-name
+
+# executes bash inside of the created container
+docker run -it your-image-name bash
+
+# to run the docker container with your current working directory mounted into it,
+# you can alternatively run this
+docker run -it -v $(pwd):/src -w /src your-image-name bash
+```
+
+There is also the option to customize the used docker user during the build.
+This will create a new user with the given name and IDs.
+
+```bash
+#USER_ADD: set it to any value to to add a new user
+#USERNAME: the name of the user to be created
+#USER_ID: the ID that is used for the new user and for its group
+docker build ./analysis -t local-ccsh --build-arg USER_ADD=true --build-arg USER_ID=1001 --build-arg USERNAME=your_name
+```

gh-pages/_docs/07-02-new-to-code-analysis.md

@@ -60,6 +60,8 @@ A simple way to only import the analysis is to clone the whole repository and th
 The integration tests might fail on windows, because of a missing or unknown `sh` command.
 To make it work, add the path to the Git `sh.exe` (which is normally placed here `C:\<path-to-git>\Git\bin`) to your PATH variable.
 
+If the integration tests fail on macOS, it is likely because the `timeout` command is not installed. This is necessary for the integration test and can be installed e.g. with `brew install coreutils`.
+
 **If you want to run the JUnit tests with the IntelliJ-Runner, make sure to go to `File -> Settings ->Build,Execution, Deployment -> Build Tools -> Gradle` and select `Run test using: IntelliJ IDEA`**
 
 ### Linting/Formatting

gh-pages/_posts/release/2024-05-16-ana_1_125_0.md

@@ -0,0 +1,28 @@
+---
+categories:
+    - Release
+tags:
+    - gh-pages
+    - release
+    - analysis
+
+title: Analysis version 1.125.0
+---
+
+{{page.title}} is live and ready for [download](https://github.com/MaibornWolff/codecharta/releases/tag/ana-1.125.0).
+This version brings the following:
+
+### Changed
+
+-   Update GH-Pages and dev guide on how to use our docker images [#3621](https://github.com/MaibornWolff/codecharta/pull/3621/files)
+
+### Fixed 🐞
+
+-   Add default Docker user to mitigate `GitLogParser` issues during repo-scan [#3571](https://github.com/MaibornWolff/codecharta/pull/3571)
+-   Escaping and un-escaping windows paths, auto-detecting path separator for Unix and Windows
+    paths [#3569](https://github.com/MaibornWolff/codecharta/pull/3569)
+
+Chore 👨‍💻 👩‍💻
+
+-   Upgrade Gradle to version 8.7, now with support for Java version 21. [#3570](https://github.com/MaibornWolff/codecharta/pull/3570)
+-   Update docs to include that the `timeout` command is necessary on macOS to run integration tests [#3322](https://github.com/MaibornWolff/codecharta/pull/3615)