Enrich quality reports with baseline signal metrics (#40)

kenahrens · web-flow · commit ba09a2d9740a · 2026-04-10T20:41:15.000-04:00
Capture stdout/stderr line counts in baseline artifacts and compare them in QualityReport highlights so QA output is more informative than exit codes alone; add a baseline-mode intake example for onboarding workflows.
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ kubectl apply -k examples/deploy/kubernetes/base
 kubectl apply -k examples/deploy/kubernetes/overlays/redis
 ```
 
-Submit quality runs through intake API `POST /qa/runs` using payloads in `examples/runs/`.
+Submit quality runs through intake API `POST /qa/runs` using payloads in `examples/runs/` (comparison and baseline examples are included).
 
 ## Core Artifacts Per Run
 
diff --git a/docs/server.md b/docs/server.md
@@ -230,6 +230,14 @@ curl -sS -X POST http://127.0.0.1:8080/qa/runs \
   --data-binary @examples/runs/demo-node-pr-quality-intake.json
 ```
 
+Onboarding baseline capture example:
+
+```bash
+curl -sS -X POST http://127.0.0.1:8080/qa/runs \
+  -H "content-type: application/json" \
+  --data-binary @examples/runs/demo-node-baseline-intake.json
+```
+
 Stop services:
 
 ```bash
diff --git a/examples/runs/demo-node-baseline-intake.json b/examples/runs/demo-node-baseline-intake.json
@@ -0,0 +1,23 @@
+{
+  "source": "developer",
+  "repository": {
+    "provider": "github",
+    "owner": "speedscale",
+    "name": "demo"
+  },
+  "appRef": {
+    "name": "demo-node",
+    "qualityTarget": "demo-node"
+  },
+  "request": {
+    "mode": "baseline",
+    "branch": "main"
+  },
+  "requestedBy": {
+    "type": "user",
+    "login": "developer"
+  },
+  "metadata": {
+    "reason": "initial-onboarding-baseline"
+  }
+}
diff --git a/schemas/quality-baseline.schema.yaml b/schemas/quality-baseline.schema.yaml
@@ -63,22 +63,34 @@ properties:
             required:
               - command
               - exitCode
+              - stdoutLines
+              - stderrLines
             properties:
               command:
                 type: string
               exitCode:
                 type: number
+              stdoutLines:
+                type: number
+              stderrLines:
+                type: number
             additionalProperties: false
           validation:
             type: object
             required:
               - command
               - exitCode
+              - stdoutLines
+              - stderrLines
             properties:
               command:
                 type: string
               exitCode:
                 type: number
+              stdoutLines:
+                type: number
+              stderrLines:
+                type: number
             additionalProperties: false
         additionalProperties: false
     additionalProperties: false
diff --git a/schemas/quality-report.schema.yaml b/schemas/quality-report.schema.yaml
@@ -35,6 +35,7 @@ properties:
       - outcome
       - summary
       - comparedCommands
+      - highlights
     properties:
       runRef:
         type: object
@@ -88,22 +89,46 @@ properties:
             type: object
             required:
               - currentExitCode
+              - currentStdoutLines
+              - currentStderrLines
             properties:
               baselineExitCode:
                 type: number
               currentExitCode:
                 type: number
+              baselineStdoutLines:
+                type: number
+              currentStdoutLines:
+                type: number
+              baselineStderrLines:
+                type: number
+              currentStderrLines:
+                type: number
             additionalProperties: false
           validation:
             type: object
             required:
               - currentExitCode
+              - currentStdoutLines
+              - currentStderrLines
             properties:
               baselineExitCode:
                 type: number
               currentExitCode:
                 type: number
+              baselineStdoutLines:
+                type: number
+              currentStdoutLines:
+                type: number
+              baselineStderrLines:
+                type: number
+              currentStderrLines:
+                type: number
             additionalProperties: false
         additionalProperties: false
+      highlights:
+        type: array
+        items:
+          type: string
     additionalProperties: false
 additionalProperties: false
diff --git a/src/bin/demo.ts b/src/bin/demo.ts
@@ -99,11 +99,15 @@ async function main(): Promise<void> {
       app: sampleApp,
       build: {
         command: buildResult.result.command,
-        exitCode: buildResult.result.exitCode
+        exitCode: buildResult.result.exitCode,
+        stdout: buildResult.result.stdout,
+        stderr: buildResult.result.stderr
       },
       validation: {
         command: validationResult.result.command,
-        exitCode: validationResult.result.exitCode
+        exitCode: validationResult.result.exitCode,
+        stdout: validationResult.result.stdout,
+        stderr: validationResult.result.stderr
       }
     });
 
diff --git a/src/bin/worker.ts b/src/bin/worker.ts
@@ -93,7 +93,9 @@ async function processRun(runName: string, sourceDir?: string): Promise<void> {
       app: runnerContext.app,
       build: {
         command: buildResult.result.command,
-        exitCode: buildResult.result.exitCode
+        exitCode: buildResult.result.exitCode,
+        stdout: buildResult.result.stdout,
+        stderr: buildResult.result.stderr
       }
     });
 
@@ -126,11 +128,15 @@ async function processRun(runName: string, sourceDir?: string): Promise<void> {
     app: runnerContext.app,
     build: {
       command: buildResult.result.command,
-      exitCode: buildResult.result.exitCode
+      exitCode: buildResult.result.exitCode,
+      stdout: buildResult.result.stdout,
+      stderr: buildResult.result.stderr
     },
     validation: {
       command: validationResult.result.command,
-      exitCode: validationResult.result.exitCode
+      exitCode: validationResult.result.exitCode,
+      stdout: validationResult.result.stdout,
+      stderr: validationResult.result.stderr
     }
   });
 
diff --git a/src/contracts/quality-baseline.ts b/src/contracts/quality-baseline.ts
@@ -18,10 +18,14 @@ export interface QualityBaseline {
       build: {
         command: string;
         exitCode: number;
+        stdoutLines: number;
+        stderrLines: number;
       };
       validation?: {
         command: string;
         exitCode: number;
+        stdoutLines: number;
+        stderrLines: number;
       };
     };
   };
diff --git a/src/contracts/quality-report.ts b/src/contracts/quality-report.ts
@@ -24,11 +24,20 @@ export interface QualityReport {
       build: {
         baselineExitCode?: number;
         currentExitCode: number;
+        baselineStdoutLines?: number;
+        currentStdoutLines: number;
+        baselineStderrLines?: number;
+        currentStderrLines: number;
       };
       validation?: {
         baselineExitCode?: number;
         currentExitCode: number;
+        baselineStdoutLines?: number;
+        currentStdoutLines: number;
+        baselineStderrLines?: number;
+        currentStderrLines: number;
       };
     };
+    highlights: string[];
   };
 }
diff --git a/src/lib/quality-report.ts b/src/lib/quality-report.ts
@@ -7,6 +7,8 @@ import { readJsonFile, resolveFromRepo, writeJsonFile } from "./io.js";
 interface CommandSnapshot {
   command: string;
   exitCode: number;
+  stdout: string;
+  stderr: string;
 }
 
 interface WriteQualityArtifactsInput {
@@ -84,12 +86,33 @@ function toMarkdown(report: QualityReport): string {
     `- outcome: ${report.spec.outcome}`,
     `- summary: ${report.spec.summary}`,
     `- build baseline/current: ${String(report.spec.comparedCommands.build.baselineExitCode ?? "n/a")} -> ${report.spec.comparedCommands.build.currentExitCode}`,
+    `- build stderr lines baseline/current: ${String(report.spec.comparedCommands.build.baselineStderrLines ?? "n/a")} -> ${report.spec.comparedCommands.build.currentStderrLines}`,
     validationSection,
     `- baseline store: ${report.spec.target.baselineStorePath}`,
+    report.spec.highlights.length > 0 ? "- highlights:" : "- highlights: none",
+    ...report.spec.highlights.map((entry) => `  - ${entry}`),
     ""
   ].join("\n");
 }
 
+function countLines(text: string): number {
+  const normalized = text.trim();
+  if (normalized.length === 0) {
+    return 0;
+  }
+
+  return normalized.split(/\r?\n/).length;
+}
+
+function firstUsefulLine(text: string): string | undefined {
+  const line = text
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .find((entry) => entry.length > 0);
+
+  return line;
+}
+
 export async function writeQualityArtifacts(input: WriteQualityArtifactsInput): Promise<QualityReportOutcome> {
   const { run, app, build, validation } = input;
   const target = resolveQualityTarget(run, app);
@@ -111,8 +134,21 @@ export async function writeQualityArtifacts(input: WriteQualityArtifactsInput):
       },
       target,
       commands: {
-        build,
-        validation
+        build: {
+          command: build.command,
+          exitCode: build.exitCode,
+          stdoutLines: countLines(build.stdout),
+          stderrLines: countLines(build.stderr)
+        },
+        validation:
+          typeof validation !== "undefined"
+            ? {
+                command: validation.command,
+                exitCode: validation.exitCode,
+                stdoutLines: countLines(validation.stdout),
+                stderrLines: countLines(validation.stderr)
+              }
+            : undefined
       }
     }
   };
@@ -173,16 +209,30 @@ export async function writeQualityArtifacts(input: WriteQualityArtifactsInput):
       comparedCommands: {
         build: {
           baselineExitCode: baselineForCompare?.spec.commands.build.exitCode,
-          currentExitCode: build.exitCode
+          currentExitCode: build.exitCode,
+          baselineStdoutLines: baselineForCompare?.spec.commands.build.stdoutLines,
+          currentStdoutLines: countLines(build.stdout),
+          baselineStderrLines: baselineForCompare?.spec.commands.build.stderrLines,
+          currentStderrLines: countLines(build.stderr)
         },
         validation:
           typeof validation !== "undefined"
             ? {
                 baselineExitCode: baselineForCompare?.spec.commands.validation?.exitCode,
-                currentExitCode: validation.exitCode
+                currentExitCode: validation.exitCode,
+                baselineStdoutLines: baselineForCompare?.spec.commands.validation?.stdoutLines,
+                currentStdoutLines: countLines(validation.stdout),
+                baselineStderrLines: baselineForCompare?.spec.commands.validation?.stderrLines,
+                currentStderrLines: countLines(validation.stderr)
               }
             : undefined
-      }
+      },
+      highlights: [
+        firstUsefulLine(build.stderr) ? `build stderr: ${firstUsefulLine(build.stderr)}` : undefined,
+        typeof validation !== "undefined" && firstUsefulLine(validation.stderr)
+          ? `validation stderr: ${firstUsefulLine(validation.stderr)}`
+          : undefined
+      ].filter((entry): entry is string => typeof entry === "string")
     }
   };
 
