feat: add launcher profiling and build-managed test routing

Author: Pluze

.agents/skills/labkit-test-planner/SKILL.md

@@ -39,11 +39,11 @@ prefer the app-level GUI folder, for example a `Suites` value such as
 `gui/apps/image_measurement/batch_crop` with `IncludeGui=true` and
 `GuiMode="hidden"`.
 
-For long focused suites, `runLabKitTests` can split a selected suite with
-zero-based `ShardCount` and `ShardIndex`. Use shards only when every shard is
-run with a distinct `RunName` and the combined shards cover the same selected
-suite; keep the conservative changed-file or relevant broad build task as the
-handoff gate for substantive changes.
+For broad validation, prefer public buildfile tasks and let the buildfile own
+whether a large selected test set should run serially or through internal
+worker shards. Use runner-level shard arguments only when developing or
+debugging the runner itself; every shard must have a distinct `RunName` and the
+combined shards must cover the same selected suite.
 
 For a dirty worktree, route through the changed-file validation planner before
 manually choosing tests. The focused planner maps the current diff to the
@@ -62,18 +62,19 @@ or the user explicitly asks for a broader/release gate.
 
 ```text
 project                    startup, architecture, package surface, sample-data hygiene
-labkit/dta                 DTA parser, facade, session, item, pulse behavior
-labkit/image               image file IO, RGB normalization, resizing, mean filtering, basic enhancement primitives
-labkit/biosignal           biosignal import, processing, ECG peaks, segments, measurements
-labkit/ui                  reusable UI helpers; include GUI coverage for layout/callback/shell/debug/tool checks
+labkit_framework/dta       DTA parser, facade, session, item, pulse behavior
+labkit_framework/image     image file IO, RGB normalization, resizing, mean filtering, basic enhancement primitives
+labkit_framework/biosignal biosignal import, processing, ECG peaks, segments, measurements
+labkit_framework/ui        reusable UI helpers; include GUI coverage for layout/callback/shell/debug/tool checks
 apps/electrochem           electrochem app-owned calculations, exports, layout
 apps/dic                   DIC app layout
 apps/image_measurement     image measurement calculations, exports, layout
 apps/wearable              wearable app layout
 gui/apps                   app GUI launch, layout, callback wiring, and workflow checks
 gui/apps/<family>/<app_slug>
                            one app GUI layout, callback wiring, and workflow checks
-gui/labkit/launcher        launcher discovery and layout checks
+gui/project/launcher       launcher discovery and layout checks
+gui/labkit_framework/ui    reusable UI GUI, workflow, and gesture checks
 ```
 
 Pair reusable changes with downstream apps when the app-facing contract could

.github/workflows/matlab-tests.yml

@@ -19,31 +19,12 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  headless-shards:
-    name: ${{ matrix.label }}
+  headless:
+    name: Headless Tests
     runs-on: ubuntu-latest
     timeout-minutes: 25
     env:
       MLM_LICENSE_TOKEN: ${{ secrets.MLM_LICENSE_TOKEN }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - label: Unit Tests - LabKit
-            run_name: unit-labkit
-            task: ciUnitLabKit
-          - label: Unit Tests - Apps
-            run_name: unit-apps
-            task: ciUnitApps
-          - label: Unit Tests - Project
-            run_name: unit-project
-            task: ciUnitProject
-          - label: Integration Tests - Apps
-            run_name: integration-apps
-            task: ciIntegrationApps
-          - label: Integration Tests - Project
-            run_name: integration-project
-            task: ciIntegrationProject
 
     steps:
       - name: Check out repository
@@ -57,34 +38,49 @@ jobs:
           release: ${{ env.MATLAB_RELEASE }}
 
       - name: Prepare artifact directories
-        run: mkdir -p artifacts/logs/${{ matrix.run_name }}
+        run: mkdir -p artifacts/logs/headless
 
-      - name: Run ${{ matrix.label }}
+      - name: Run headless tests
         uses: matlab-actions/run-build@v3
         with:
-          tasks: ${{ matrix.task }}
-          startup-options: -logfile artifacts/logs/${{ matrix.run_name }}/matlab.log
+          tasks: headless
+          startup-options: -logfile artifacts/logs/headless/matlab.log
 
-      - name: Summarize ${{ matrix.label }}
+      - name: Summarize headless tests
         if: always()
-        run: >
-          python scripts/summarize_junit.py
-          artifacts/test-results/${{ matrix.run_name }}/junit.xml
-          --run-name ${{ matrix.run_name }}
-          --html artifacts/test-results/${{ matrix.run_name }}/html/index.html
-          --log artifacts/logs/${{ matrix.run_name }}/matlab.log
-
-      - name: Upload ${{ matrix.label }} artifacts
+        run: |
+          found=0
+          for junit in artifacts/test-results/*/junit.xml; do
+            [ -f "$junit" ] || continue
+            found=1
+            run_name="$(basename "$(dirname "$junit")")"
+            log_path="artifacts/logs/${run_name}/matlab.log"
+            if [ ! -f "$log_path" ] && [ -f "artifacts/logs/headless-orchestrator/${run_name}.log" ]; then
+              log_path="artifacts/logs/headless-orchestrator/${run_name}.log"
+            fi
+            python scripts/summarize_junit.py "$junit" \
+              --run-name "$run_name" \
+              --html "artifacts/test-results/${run_name}/html/index.html" \
+              --log "$log_path"
+          done
+          if [ "$found" -eq 0 ]; then
+            python scripts/summarize_junit.py artifacts/test-results/headless/junit.xml \
+              --run-name headless \
+              --html artifacts/test-results/headless/html/index.html \
+              --log artifacts/logs/headless/matlab.log
+          fi
+
+      - name: Upload headless artifacts
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: matlab-${{ matrix.run_name }}
+          name: matlab-headless
           if-no-files-found: warn
           retention-days: 14
           path: |
-            artifacts/test-results/${{ matrix.run_name }}/**
-            artifacts/debug/${{ matrix.run_name }}/**
-            artifacts/logs/${{ matrix.run_name }}/**
+            artifacts/test-results/**
+            artifacts/debug/**
+            artifacts/logs/**
 
   coverage:
     name: Coverage Report

buildfile.m

@@ -1,5 +1,18 @@
 function plan = buildfile
 %BUILDFILE LabKit build and validation entry points.
+%
+% User-facing commands:
+%   buildtool changed       conservative validation routed from the git diff
+%   buildtool changedFast   faster local iteration routed from the git diff
+%   buildtool headless      full non-GUI validation
+%   buildtool gui           full automated GUI validation with hidden figures
+%   buildtool coverage      coverage report for manual or scheduled runs
+%   buildtool listTasks     print the public task catalog
+%
+% The buildfile deliberately stays thin. It exposes stable tasks and passes
+% suite/tag choices to tests/runLabKitTests.m. Ownership-specific routing
+% lives in the runner and changed-file planner, derived from
+% tests/cases/<kind>/<owner>/<area>/ paths.
 
     plan = buildplan(localfunctions);
     plan.DefaultTasks = "headless";
@@ -30,26 +43,6 @@ function coverageTask(~)
     runCatalogTask("coverage");
 end
 
-function ciUnitLabKitTask(~)
-    runCatalogTask("ciUnitLabKit");
-end
-
-function ciUnitAppsTask(~)
-    runCatalogTask("ciUnitApps");
-end
-
-function ciUnitProjectTask(~)
-    runCatalogTask("ciUnitProject");
-end
-
-function ciIntegrationAppsTask(~)
-    runCatalogTask("ciIntegrationApps");
-end
-
-function ciIntegrationProjectTask(~)
-    runCatalogTask("ciIntegrationProject");
-end
-
 function listTasksTask(~)
     printTaskCatalog(taskCatalog());
 end
@@ -61,11 +54,6 @@ function listTasksTask(~)
         taskSpec("headless", "Run the full non-GUI validation set.", "IncludeGui", false), ...
         taskSpec("gui", "Run noninteractive GUI launch, layout, and gesture checks.", "Suites", "gui", "IncludeGui", true, "GuiMode", "hidden"), ...
         taskSpec("coverage", "Run official tests with coverage artifacts.", "Tags", ["Unit", "Integration"], "IncludeCoverage", true), ...
-        taskSpec("ciUnitLabKit", "Run CI LabKit unit shard.", "Visibility", "ci", "Suites", "labkit", "Tags", "Unit", "IncludeGui", false, "HtmlReport", false), ...
-        taskSpec("ciUnitApps", "Run CI app unit shard.", "Visibility", "ci", "Suites", "apps", "Tags", "Unit", "IncludeGui", false, "HtmlReport", false), ...
-        taskSpec("ciUnitProject", "Run CI project unit shard.", "Visibility", "ci", "Suites", "project", "Tags", "Unit", "IncludeGui", false, "HtmlReport", false), ...
-        taskSpec("ciIntegrationApps", "Run CI app integration shard.", "Visibility", "ci", "Suites", "apps", "Tags", "Integration", "IncludeGui", false, "HtmlReport", false), ...
-        taskSpec("ciIntegrationProject", "Run CI project integration shard.", "Visibility", "ci", "Suites", "project", "Tags", "Integration", "IncludeGui", false, "HtmlReport", false), ...
         taskSpec("listTasks", "List official LabKit build tasks.", "RunTests", false)];
 end
 
@@ -108,6 +96,9 @@ function runCatalogTask(runName)
     end
 
     args = taskRunArguments(spec);
+    if runWithInternalShards(spec, args)
+        return;
+    end
     runBuildTests(spec.Name, args{:});
 end
 
@@ -154,6 +145,138 @@ function runBuildTests(runName, varargin)
         "ArtifactsRoot", fullfile(root, "artifacts"));
 end
 
+function handled = runWithInternalShards(spec, args)
+    handled = false;
+    if spec.Name ~= "headless" || isInternalShardWorker() || ispc
+        return;
+    end
+
+    root = fileparts(mfilename("fullpath"));
+    addpath(fullfile(root, "tests"));
+    try
+        probe = runLabKitTests(args{:}, ...
+            "ListOnly", true, ...
+            "FailIfNoTests", false, ...
+            "RunName", spec.Name + "_probe", ...
+            "ArtifactsRoot", fullfile(root, "artifacts"));
+    catch
+        return;
+    end
+
+    shardCount = recommendedShardCount(probe.count);
+    if shardCount <= 1
+        return;
+    end
+
+    fprintf("LabKit shard probe: %d test(s) matched; running %d internal headless shard(s).\n", ...
+        probe.count, shardCount);
+    runInternalShardWorkers(root, spec.Name, args, shardCount);
+    handled = true;
+end
+
+function tf = isInternalShardWorker()
+    tf = string(getenv("LABKIT_INTERNAL_SHARD_WORKER")) == "1";
+end
+
+function shardCount = recommendedShardCount(testCount)
+    if testCount >= 300
+        shardCount = 3;
+    elseif testCount >= 80
+        shardCount = 2;
+    else
+        shardCount = 1;
+    end
+end
+
+function runInternalShardWorkers(root, runName, args, shardCount)
+    logsRoot = fullfile(root, "artifacts", "logs", runName + "-orchestrator");
+    ensureFolder(logsRoot);
+    scriptPath = fullfile(logsRoot, "run_shards.sh");
+    fid = fopen(scriptPath, "w");
+    if fid < 0
+        error("LabKit:Build:ShardScript", "Could not create shard script.");
+    end
+    cleanup = onCleanup(@() fclose(fid));
+
+    fprintf(fid, "#!/bin/sh\n");
+    fprintf(fid, "status=0\n");
+    matlabExe = fullfile(matlabroot, "bin", "matlab");
+    for k = 0:(shardCount - 1)
+        shardName = sprintf("%s-shard-%d", runName, k);
+        workerLog = fullfile(logsRoot, shardName + ".log");
+        batch = shardBatchCommand(root, args, shardName, shardCount, k);
+        fprintf(fid, "LABKIT_INTERNAL_SHARD_WORKER=1 %s -batch %s > %s 2>&1 &\n", ...
+            shellQuote(matlabExe), shellQuote(batch), shellQuote(workerLog));
+        fprintf(fid, "pids_%d=$!\n", k + 1);
+    end
+    for k = 1:shardCount
+        fprintf(fid, "wait $pids_%d || status=1\n", k);
+    end
+    fprintf(fid, 'if [ "$status" -ne 0 ]; then\n');
+    fprintf(fid, "  cat %s/*.log\n", shellQuote(logsRoot));
+    fprintf(fid, "fi\n");
+    fprintf(fid, "exit $status\n");
+    clear cleanup;
+    fileattrib(scriptPath, "+x");
+
+    [status, output] = system(shellQuote(scriptPath));
+    if strlength(string(output)) > 0
+        fprintf("%s", output);
+    end
+    if status ~= 0
+        error("LabKit:Build:ShardFailure", ...
+            "One or more internal test shards failed. Logs: %s", logsRoot);
+    end
+end
+
+function batch = shardBatchCommand(root, args, runName, shardCount, shardIndex)
+    shardArgs = [args, { ...
+        "ShardCount", shardCount, ...
+        "ShardIndex", shardIndex, ...
+        "RunName", string(runName), ...
+        "ArtifactsRoot", fullfile(root, "artifacts")}];
+    batch = "addpath(" + matlabLiteral(fullfile(root, "tests")) + "); " + ...
+        "runLabKitTests(" + matlabArgumentList(shardArgs) + ");";
+end
+
+function text = matlabArgumentList(args)
+    parts = strings(1, numel(args));
+    for k = 1:numel(args)
+        parts(k) = matlabLiteral(args{k});
+    end
+    text = strjoin(parts, ", ");
+end
+
+function text = matlabLiteral(value)
+    if islogical(value)
+        if value
+            text = "true";
+        else
+            text = "false";
+        end
+    elseif isnumeric(value)
+        text = string(value);
+    else
+        value = string(value);
+        if isscalar(value)
+            text = """" + replace(value, """", """""") + """";
+        else
+            quoted = """" + replace(value, """", """""") + """";
+            text = "[" + strjoin(quoted, ", ") + "]";
+        end
+    end
+end
+
+function text = shellQuote(value)
+    text = "'" + replace(string(value), "'", "'\''") + "'";
+end
+
+function ensureFolder(folder)
+    if exist(folder, "dir") ~= 7
+        mkdir(folder);
+    end
+end
+
 function printTaskCatalog(catalog)
     fprintf("LabKit build tasks:\n");
     for k = 1:numel(catalog)