From 9168fb8dbcf61a90f6a8e4d61a8b566ede871d56 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 18:38:46 +0100 Subject: [PATCH 01/14] Improve the reliability of JVM project check --- migrate | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/migrate b/migrate index c7ed5253..83e0d745 100644 --- a/migrate +++ b/migrate @@ -12,6 +12,15 @@ for hugo_dir in docs site; do done done +# Detect if the target repo is a JVM (Gradle) repository. +# The presence of the Spine dependency declarations directory is the reliable marker — +# build files alone can exist in non-JVM repos for convenience tooling. +IS_JVM=false +if [ -d "../buildSrc/src/main/kotlin/io/spine/dependency" ]; then + IS_JVM=true + echo "Detected JVM repository." +fi + echo "Updating IDEA configuration" cp -R .idea .. @@ -175,11 +184,13 @@ else echo "Updating GitHub Copilot instructions" cp .github/copilot-instructions.md ../.github/copilot-instructions.md - # Update existing workflows with more recent versions - echo "Updating GitHub workflows" - cp -a .github-workflows/. ../.github/workflows - cp -a .github/workflows/. ../.github/workflows - rm -f ../.github/workflows/detekt-code-analysis.yml # This one is `config`-only workflow. + # Update existing workflows with more recent versions (JVM-only) + if [ "$IS_JVM" = "true" ]; then + echo "Updating GitHub workflows" + cp -a .github-workflows/. ../.github/workflows + cp -a .github/workflows/. ../.github/workflows + rm -f ../.github/workflows/detekt-code-analysis.yml # This one is `config`-only workflow. + fi cp -a gradle.properties .. cp -a .gitignore .. From b119dca82e0da434c79b906af5df886ded17d2d6 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 18:42:29 +0100 Subject: [PATCH 02/14] Improve `pre-pr` skill description --- .agents/skills/pre-pr/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/pre-pr/SKILL.md b/.agents/skills/pre-pr/SKILL.md index 2c81dfde..72dbd6a8 100644 --- a/.agents/skills/pre-pr/SKILL.md +++ b/.agents/skills/pre-pr/SKILL.md @@ -2,9 +2,10 @@ name: pre-pr description: > Run the pre-PR checklist for this repo: apply the version gate only when - the repository has a root `version.gradle.kts`, run the configured - build/check command per `.agents/running-builds.md`, and invoke the - configured reviewers (`kotlin-review`, `review-docs`, `dependency-audit`, + the repository has a root `version.gradle.kts`, run a scope-dependent + build/check command per `.agents/running-builds.md` (deps-only → skipped; + docs-only → `dokka`; code → `build`; proto → `clean build`), and invoke + the relevant reviewers (`kotlin-review`, `review-docs`, `dependency-audit`, `check-links`) against the branch diff. On success, write a sentinel file at `.git/pre-pr.ok` so the `gh pr create` hook can verify the checklist ran for the current HEAD. Use before opening a PR, or when CI rejected a From 149c14158d1dd83c583c3b90da5bb34bcedb357c Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:00:45 +0100 Subject: [PATCH 03/14] Improve getting Hugo site directory --- .github/workflows/check-links.yml | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index 7a51f8f1..a6779543 100644 --- a/.github/workflows/check-links.yml +++ b/.github/workflows/check-links.yml @@ -36,7 +36,12 @@ jobs: uses: actions/checkout@v4 # Detect the Hugo site root (`docs/` or `site/`) by looking for a Hugo - # config file. Outputs `present=true|false` and `site_dir=docs|site`. + # config file. Hugo config may live directly in the site root or in a + # `config/` or `config/_default/` subdirectory (both layouts are valid). + # Outputs `present=true|false`, `site_dir=docs|site`, and `work_dir` + # (the directory where `npm ci` / `hugo` commands should run — either + # `$site_dir/_preview` for repos that use a separate preview sub-tree, + # or `$site_dir` for repos whose Node/Hugo setup lives at the root). # When neither directory has a Hugo config, the job short-circuits to a # success so that this shared workflow stays green on repos that do not # host a Hugo site at all. @@ -44,15 +49,20 @@ jobs: id: docs run: | for dir in docs site; do - for cfg in hugo.toml hugo.yaml; do + for cfg in hugo.toml hugo.yaml config/hugo.toml config/_default/hugo.toml; do if [ -f "$dir/$cfg" ]; then echo "site_dir=$dir" >> "$GITHUB_OUTPUT" if [ -f "$dir/_preview/package-lock.json" ]; then + echo "work_dir=$dir/_preview" >> "$GITHUB_OUTPUT" echo "present=true" >> "$GITHUB_OUTPUT" - echo "::notice::Hugo site found under $dir/" + echo "::notice::Hugo site found under $dir/ (work_dir: $dir/_preview)" + elif [ -f "$dir/package-lock.json" ]; then + echo "work_dir=$dir" >> "$GITHUB_OUTPUT" + echo "present=true" >> "$GITHUB_OUTPUT" + echo "::notice::Hugo site found under $dir/ (work_dir: $dir)" else echo "present=false" >> "$GITHUB_OUTPUT" - echo "::notice::Hugo config found in $dir/ but $dir/_preview/package-lock.json is missing — skipping link check." + echo "::notice::Hugo config found in $dir/ but no package-lock.json found — skipping link check." fi exit 0 fi @@ -78,7 +88,7 @@ jobs: with: node-version: '26' cache: 'npm' - cache-dependency-path: ${{ steps.docs.outputs.site_dir }}/_preview/package-lock.json + cache-dependency-path: ${{ steps.docs.outputs.work_dir }}/package-lock.json # `HUGO_CACHEDIR=/tmp/hugo_cache` (set in `env:` above) makes Hugo # actually write to the path this step restores from. The key hashes @@ -95,12 +105,12 @@ jobs: - name: Install Dependencies if: steps.docs.outputs.present == 'true' - working-directory: ${{ steps.docs.outputs.site_dir }}/_preview + working-directory: ${{ steps.docs.outputs.work_dir }} run: npm ci - name: Build docs preview site if: steps.docs.outputs.present == 'true' - working-directory: ${{ steps.docs.outputs.site_dir }}/_preview + working-directory: ${{ steps.docs.outputs.work_dir }} run: hugo -e development # Cache Lychee results to avoid hitting rate limits. @@ -183,7 +193,7 @@ jobs: # Lychee step is visible — change one, change the other. - name: Start Hugo server if: steps.docs.outputs.present == 'true' - working-directory: ${{ steps.docs.outputs.site_dir }}/_preview + working-directory: ${{ steps.docs.outputs.work_dir }} run: | nohup hugo server \ --environment development \ @@ -202,4 +212,4 @@ jobs: run: | ./lychee/lychee --config lychee.toml --timeout 60 \ --base-url http://localhost:1313/ \ - '${{ steps.docs.outputs.site_dir }}/_preview/public/**/*.html' + '${{ steps.docs.outputs.work_dir }}/public/**/*.html' From 90aea300b4c8f2cf2bbdb02236056aab6115da1a Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:10:42 +0100 Subject: [PATCH 04/14] Fix spelling issues --- .idea/live-templates/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.idea/live-templates/README.md b/.idea/live-templates/README.md index 66713b34..95006673 100644 --- a/.idea/live-templates/README.md +++ b/.idea/live-templates/README.md @@ -5,12 +5,12 @@ This directory contains two live template groups: 1. `Spine.xml`: shortcuts for the repeated patterns used in the framework. 2. `User.xml`: a single shortcut to generate TODO comments. -### Instlallation +### Installation Live templates are not picked up by IDEA automatically. They should be added manually. In order to add these templates, perform the following steps: -1. Copy `*.xml` files from this directory to `templates` directory in the IntelliJ IDEA +1. Copy `*.xml` files from this directory to `templates` directory in the IntelliJ IDEA [settings folder][settings_folder]. 2. Restart IntelliJ IDEA: `File -> Invalidate Caches -> Just restart`. 3. Go to `Preferences -> Editor -> Live Templates`. @@ -23,5 +23,5 @@ In order to add these templates, perform the following steps: 1. Open the corresponding template: `Preferences -> Editor -> Live Templates -> User.todo`. 2. Click on `Edit variables`. 3. Set `USER` variable to your domain email address without `@teamdev.com` ending. For example, - for `jack.sparrow@teamdev.com` use the follwoing expression `"jack.sparrow"`. + for `jack.sparrow@teamdev.com` use the following expression `"jack.sparrow"`. 4. Verify that the template generates expected comments: `// TODO:2022-11-03:jack.sparrow: <...>`. From 7cd19efbcd5e802130af3cafcd8123540a783d38 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:28:24 +0100 Subject: [PATCH 05/14] Fix setting index numbering --- .github/workflows/check-links.yml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index a6779543..cc70021b 100644 --- a/.github/workflows/check-links.yml +++ b/.github/workflows/check-links.yml @@ -38,10 +38,10 @@ jobs: # Detect the Hugo site root (`docs/` or `site/`) by looking for a Hugo # config file. Hugo config may live directly in the site root or in a # `config/` or `config/_default/` subdirectory (both layouts are valid). - # Outputs `present=true|false`, `site_dir=docs|site`, and `work_dir` - # (the directory where `npm ci` / `hugo` commands should run — either - # `$site_dir/_preview` for repos that use a separate preview sub-tree, - # or `$site_dir` for repos whose Node/Hugo setup lives at the root). + # Outputs `present=true|false` and `work_dir` (the directory where + # `npm ci` / `hugo` commands should run — either `$dir/_preview` for + # repos that use a separate preview sub-tree, or `$dir` for repos whose + # Node/Hugo setup lives at the site root). # When neither directory has a Hugo config, the job short-circuits to a # success so that this shared workflow stays green on repos that do not # host a Hugo site at all. @@ -51,7 +51,6 @@ jobs: for dir in docs site; do for cfg in hugo.toml hugo.yaml config/hugo.toml config/_default/hugo.toml; do if [ -f "$dir/$cfg" ]; then - echo "site_dir=$dir" >> "$GITHUB_OUTPUT" if [ -f "$dir/_preview/package-lock.json" ]; then echo "work_dir=$dir/_preview" >> "$GITHUB_OUTPUT" echo "present=true" >> "$GITHUB_OUTPUT" From 262fab9ba47b5aeeebd104da4deb041ae7ab1d54 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:28:34 +0100 Subject: [PATCH 06/14] Fix setting index numbering --- .idea/misc.xml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/.idea/misc.xml b/.idea/misc.xml index 5358548e..264f8230 100644 --- a/.idea/misc.xml +++ b/.idea/misc.xml @@ -1,3 +1,4 @@ + @@ -23,21 +24,21 @@ - - \ No newline at end of file + + From b906c90560bb59150706fcbf77962ffd2b7d7867 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:30:11 +0100 Subject: [PATCH 07/14] Improve detection of JVM-based repository --- migrate | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/migrate b/migrate index 83e0d745..51b2796b 100644 --- a/migrate +++ b/migrate @@ -12,15 +12,6 @@ for hugo_dir in docs site; do done done -# Detect if the target repo is a JVM (Gradle) repository. -# The presence of the Spine dependency declarations directory is the reliable marker — -# build files alone can exist in non-JVM repos for convenience tooling. -IS_JVM=false -if [ -d "../buildSrc/src/main/kotlin/io/spine/dependency" ]; then - IS_JVM=true - echo "Detected JVM repository." -fi - echo "Updating IDEA configuration" cp -R .idea .. @@ -184,14 +175,6 @@ else echo "Updating GitHub Copilot instructions" cp .github/copilot-instructions.md ../.github/copilot-instructions.md - # Update existing workflows with more recent versions (JVM-only) - if [ "$IS_JVM" = "true" ]; then - echo "Updating GitHub workflows" - cp -a .github-workflows/. ../.github/workflows - cp -a .github/workflows/. ../.github/workflows - rm -f ../.github/workflows/detekt-code-analysis.yml # This one is `config`-only workflow. - fi - cp -a gradle.properties .. cp -a .gitignore .. @@ -215,6 +198,24 @@ else rm -f "$PRESERVE_TMP" fi + # Detect JVM after buildSrc is in place so that the Spine dependency + # declarations directory is present even on a first-time configure run. + # Convenience Gradle files alone can exist in non-JVM repos and are not + # a reliable marker; this specific directory is. + IS_JVM=false + if [ -d "../buildSrc/src/main/kotlin/io/spine/dependency" ]; then + IS_JVM=true + echo "Detected JVM repository." + fi + + # Update existing workflows with more recent versions (JVM-only) + if [ "$IS_JVM" = "true" ]; then + echo "Updating GitHub workflows" + cp -a .github-workflows/. ../.github/workflows + cp -a .github/workflows/. ../.github/workflows + rm -f ../.github/workflows/detekt-code-analysis.yml # This one is `config`-only workflow. + fi + echo "Updating Gradle Wrapper" cp -R ./gradle .. cp gradlew .. From 73befa1d4152d6d5a78b4cafd35a83e0a7aa846a Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:30:57 +0100 Subject: [PATCH 08/14] Match the description of the `pre-pr` skill with the procedure --- .agents/skills/pre-pr/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/pre-pr/SKILL.md b/.agents/skills/pre-pr/SKILL.md index 72dbd6a8..e656b0b4 100644 --- a/.agents/skills/pre-pr/SKILL.md +++ b/.agents/skills/pre-pr/SKILL.md @@ -3,9 +3,10 @@ name: pre-pr description: > Run the pre-PR checklist for this repo: apply the version gate only when the repository has a root `version.gradle.kts`, run a scope-dependent - build/check command per `.agents/running-builds.md` (deps-only → skipped; - docs-only → `dokka`; code → `build`; proto → `clean build`), and invoke - the relevant reviewers (`kotlin-review`, `review-docs`, `dependency-audit`, + build/check command per `.agents/running-builds.md` (docs-only → `dokka`; + code/deps → `build`; proto → `clean build`; no documented command → skipped), + and invoke the relevant reviewers (`kotlin-review`, `review-docs`, + `dependency-audit`, `check-links`) against the branch diff. On success, write a sentinel file at `.git/pre-pr.ok` so the `gh pr create` hook can verify the checklist ran for the current HEAD. Use before opening a PR, or when CI rejected a From 57c3ed193e7f2a95f1d01d3c9eabd02fd145b8d7 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:41:14 +0100 Subject: [PATCH 09/14] Improve check-links workflow site detection --- .github/workflows/check-links.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index cc70021b..a6779543 100644 --- a/.github/workflows/check-links.yml +++ b/.github/workflows/check-links.yml @@ -38,10 +38,10 @@ jobs: # Detect the Hugo site root (`docs/` or `site/`) by looking for a Hugo # config file. Hugo config may live directly in the site root or in a # `config/` or `config/_default/` subdirectory (both layouts are valid). - # Outputs `present=true|false` and `work_dir` (the directory where - # `npm ci` / `hugo` commands should run — either `$dir/_preview` for - # repos that use a separate preview sub-tree, or `$dir` for repos whose - # Node/Hugo setup lives at the site root). + # Outputs `present=true|false`, `site_dir=docs|site`, and `work_dir` + # (the directory where `npm ci` / `hugo` commands should run — either + # `$site_dir/_preview` for repos that use a separate preview sub-tree, + # or `$site_dir` for repos whose Node/Hugo setup lives at the root). # When neither directory has a Hugo config, the job short-circuits to a # success so that this shared workflow stays green on repos that do not # host a Hugo site at all. @@ -51,6 +51,7 @@ jobs: for dir in docs site; do for cfg in hugo.toml hugo.yaml config/hugo.toml config/_default/hugo.toml; do if [ -f "$dir/$cfg" ]; then + echo "site_dir=$dir" >> "$GITHUB_OUTPUT" if [ -f "$dir/_preview/package-lock.json" ]; then echo "work_dir=$dir/_preview" >> "$GITHUB_OUTPUT" echo "present=true" >> "$GITHUB_OUTPUT" From a9cfb5465909efbb9b54b06506c6eb78190111a1 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Mon, 25 May 2026 19:44:12 +0100 Subject: [PATCH 10/14] Fix week-based date format --- .idea/live-templates/User.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.idea/live-templates/User.xml b/.idea/live-templates/User.xml index cc156507..958e2ea9 100644 --- a/.idea/live-templates/User.xml +++ b/.idea/live-templates/User.xml @@ -1,7 +1,7 @@