feat: include short SHA in CROSSPOINT_VERSION (#1728)

## Summary

* Includes short SHA in version string for better version tracking, so
it looks like `1.1.0-dev-feat-kosync-xpath-05c6cf8`
* Closes
https://github.com/crosspoint-reader/crosspoint-reader/issues/1247

---

### AI Usage

While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.

Did you use AI tools to help write this code? _**< YES >**_

platformio.ini

@@ -69,7 +69,7 @@ lib_deps =
 extends = base
 build_flags =
   ${base.build_flags}
-  ; CROSSPOINT_VERSION is set by scripts/git_branch.py (includes current branch)
+  ; CROSSPOINT_VERSION is set by scripts/git_branch.py (includes branch + short SHA)
   -DENABLE_SERIAL_LOG
   -DLOG_LEVEL=2 ; Set log level to debug for development builds
 

scripts/git_branch.py

@@ -1,8 +1,8 @@
 """
-PlatformIO pre-build script: inject git branch into CROSSPOINT_VERSION for
-the default (dev) environment.
+PlatformIO pre-build script: inject git branch and short SHA into
+CROSSPOINT_VERSION for the default (dev) environment.
 
-Results in a version string like:  1.1.0-dev+feat-koysnc-xpath
+Results in a version string like:  1.1.0-dev-feat-kosync-xpath-05c6cf8
 Release environments are unaffected; they set CROSSPOINT_VERSION in the ini.
 """
 
@@ -16,29 +16,51 @@ def warn(msg):
     print(f'WARNING [git_branch.py]: {msg}', file=sys.stderr)
 
 
-def get_git_branch(project_dir):
+def run_git_value(project_dir, args, label):
     try:
-        branch = subprocess.check_output(
-            ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+        value = subprocess.check_output(
+            ['git', *args],
             text=True, stderr=subprocess.PIPE, cwd=project_dir
         ).strip()
-        # Detached HEAD — show the short SHA instead
-        if branch == 'HEAD':
-            branch = subprocess.check_output(
-                ['git', 'rev-parse', '--short', 'HEAD'],
-                text=True, stderr=subprocess.PIPE, cwd=project_dir
-            ).strip()
         # Strip characters that would break a C string literal
-        return ''.join(c for c in branch if c not in '"\\')
+        return ''.join(c for c in value if c not in '"\\')
     except FileNotFoundError:
-        warn('git not found on PATH; branch suffix will be "unknown"')
+        warn(f'git not found on PATH; {label} suffix will be "unknown"')
         return 'unknown'
     except subprocess.CalledProcessError as e:
-        warn(f'git command failed (exit {e.returncode}): {e.stderr.strip()}; branch suffix will be "unknown"')
+        warn(
+            f'git command failed (exit {e.returncode}): '
+            f'{e.stderr.strip()}; {label} suffix will be "unknown"'
+        )
         return 'unknown'
-    except Exception as e:
-        warn(f'Unexpected error reading git branch: {e}; branch suffix will be "unknown"')
+    except OSError as e:
+        warn(
+            f'OS error reading git {label}: {e}; '
+            f'{label} suffix will be "unknown"'
+        )
         return 'unknown'
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        warn(
+            f'Unexpected error reading git {label}: {e}; '
+            f'{label} suffix will be "unknown"'
+        )
+        return 'unknown'
+
+
+def get_git_branch(project_dir):
+    branch = run_git_value(
+        project_dir, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch'
+    )
+    # Detached HEAD has no branch name.
+    if branch == 'HEAD':
+        return 'detached'
+    return branch
+
+
+def get_git_short_sha(project_dir):
+    return run_git_value(
+        project_dir, ['rev-parse', '--short', 'HEAD'], 'short SHA'
+    )
 
 
 def get_base_version(project_dir):
@@ -63,7 +85,8 @@ def inject_version(env):
     project_dir = env['PROJECT_DIR']
     base_version = get_base_version(project_dir)
     branch = get_git_branch(project_dir)
-    version_string = f'{base_version}-dev+{branch}'
+    short_sha = get_git_short_sha(project_dir)
+    version_string = f'{base_version}-dev-{branch}-{short_sha}'
 
     env.Append(CPPDEFINES=[('CROSSPOINT_VERSION', f'\\"{version_string}\\"')])
     print(f'CrossPoint build version: {version_string}')