@nasebanal/cli 0.3.0 → 0.4.0

package/README.md

@@ -45,7 +45,17 @@ export NB_TOKEN=nbpat_…        # a PAT or service-account token (no browser ne
 
 # JUnit XML: vitest (--reporter=junit), pytest (--junitxml), Specmatic, Playwright (--reporter=junit)
 nb assurance report upload --file report/junit.xml --kind unit --tool pytest
-nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --suite web
+nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --component web
+
+# Two scans of one tool on the same components (ZAP's baseline and full scan): a label tells them apart
+nb assurance report upload --file report/baseline-junit.xml --kind security --tool zap --component frontend --label baseline
+nb assurance report upload --file report/full-scan-junit.xml --kind security --tool zap --component frontend --label full-scan
+
+# The tool's own version is informational and optional
+nb assurance report upload --file report/junit.xml --kind unit --tool pytest --tool-version 9.1.0
+
+# A result may be about several components: repeat the flag (new names are created in the project; none = `default`)
+nb assurance report upload --file results/junit.xml --kind e2e --tool playwright --component frontend --component backend
 
 # Specmatic: the JUnit XML, plus its HTML report for the API coverage (coverage_pct = operations exercised / operations in the spec)
 nb assurance report upload --file specmatic/junit/TEST-junit-jupiter.xml --kind contract --tool specmatic \

package/dist/reports/locust.js

@@ -7,6 +7,20 @@
  * task exception, or a failure ratio above the allowed one, fails the run.
  */
 import { toRecords } from "./csv.js";
+/**
+ * The CSV's column names changed between Locust versions: 1.x wrote "# requests" / "# failures" / "Median response
+ * time" (and named the aggregate row "Total"), 2.x writes "Request Count" / "Failure Count" / "Median Response Time"
+ * ("Aggregated"). Each value is read under every name it has had, the first present one winning.
+ */
+const COLUMNS = {
+    requests: ["Request Count", "# requests"],
+    failures: ["Failure Count", "# failures"],
+    median: ["Median Response Time", "Median response time"],
+    average: ["Average Response Time", "Average response time"],
+    max: ["Max Response Time", "Max response time"],
+};
+const has = (row, names) => names.some((n) => n in row);
+const read = (row, names) => num(row[names.find((n) => n in row) ?? ""]);
 function num(value) {
     if (value === undefined || value === "" || value === "N/A")
         return null;
@@ -16,21 +30,26 @@ function num(value) {
 const round = (n, digits = 2) => Math.round(n * 10 ** digits) / 10 ** digits;
 export function summariseLocust(files, maxFailRatio) {
     const stats = toRecords(files.stats);
-    const total = stats.find((r) => r.Name === "Aggregated");
+    // The row of all requests together: "Aggregated" (2.x) or "Total" (1.x).
+    const total = stats.find((r) => r.Name === "Aggregated" || r.Name === "Total");
     if (!total)
-        throw new Error('No "Aggregated" row in the stats CSV - is this a Locust *_stats.csv file?');
-    const requests = num(total["Request Count"]) ?? 0;
-    const failed = num(total["Failure Count"]) ?? 0;
+        throw new Error('No "Aggregated" (or "Total") row in the stats CSV - is this a Locust *_stats.csv file?');
+    // Without the counts the numbers below would silently be 0, a green result for a report nobody understood: refuse it.
+    if (!has(total, COLUMNS.requests) || !has(total, COLUMNS.failures)) {
+        throw new Error(`The stats CSV has no request / failure count column (looked for ${[...COLUMNS.requests, ...COLUMNS.failures].map((n) => `"${n}"`).join(", ")}; found: ${Object.keys(total).join(", ")}) - is it from a Locust version this nb does not know?`);
+    }
+    const requests = read(total, COLUMNS.requests) ?? 0;
+    const failed = read(total, COLUMNS.failures) ?? 0;
     const metrics = { requests, failures: failed };
     const put = (key, value) => {
         if (value !== null)
             metrics[key] = round(value);
     };
-    put("avg_ms", num(total["Average Response Time"]));
-    put("p50_ms", num(total["50%"]) ?? num(total["Median Response Time"]));
+    put("avg_ms", read(total, COLUMNS.average));
+    put("p50_ms", num(total["50%"]) ?? read(total, COLUMNS.median));
     put("p95_ms", num(total["95%"]));
     put("p99_ms", num(total["99%"]));
-    put("max_ms", num(total["Max Response Time"]));
+    put("max_ms", read(total, COLUMNS.max));
     put("rps", num(total["Requests/s"]));
     const ratio = requests > 0 ? failed / requests : 0;
     metrics.error_rate_pct = round(ratio * 100);

package/dist/reports/upload.js

@@ -127,7 +127,13 @@ function locustSibling(statsFile, suffix) {
 }
 export function parseReport(opts) {
     const text = readFileSync(opts.file, "utf8");
-    const base = { kind: opts.kind, tool: opts.tool, ...(opts.suiteName ? { name: opts.suiteName } : {}) };
+    const base = {
+        kind: opts.kind,
+        tool: opts.tool,
+        ...(opts.components && opts.components.length > 0 ? { components: opts.components } : {}),
+        ...(opts.label ? { label: opts.label } : {}),
+        ...(opts.toolVersion ? { tool_version: opts.toolVersion } : {}),
+    };
     if (opts.format === "junit") {
         const j = parseJunit(text);
         const status = opts.status ?? (j.failed === 0 ? "passed" : "failed");
@@ -214,6 +220,49 @@ function statsFileIn(dir) {
         fail(`No *_stats.csv file in ${dir}`);
     return join(dir, files.sort()[files.length - 1]);
 }
+/** At most this many components per result (the API's limit) and this many characters in a name. */
+const MAX_COMPONENTS = 20;
+const MAX_COMPONENT_LENGTH = 100;
+/** The `--label`: trimmed, not empty, within the API's limit. */
+function checkLabel(raw) {
+    if (raw === undefined)
+        return undefined;
+    const label = raw.trim();
+    if (label === "")
+        fail("--label must not be empty");
+    if (label.length > MAX_COMPONENT_LENGTH)
+        fail(`--label must be ${MAX_COMPONENT_LENGTH} characters or fewer`);
+    return label;
+}
+/** The `--tool-version`: trimmed, not empty, within the API's limit. */
+function checkToolVersion(raw) {
+    if (raw === undefined)
+        return undefined;
+    const version = raw.trim();
+    if (version === "")
+        fail("--tool-version must not be empty");
+    if (version.length > 50)
+        fail("--tool-version must be 50 characters or fewer");
+    return version;
+}
+/** The `--component` names: trimmed, no empty one, no two alike ignoring case, within the API's limits. */
+function checkComponents(raw) {
+    if (raw === undefined)
+        return undefined;
+    const out = [];
+    for (const value of raw) {
+        const name = value.trim();
+        if (name === "")
+            fail("--component must not be empty");
+        if (name.length > MAX_COMPONENT_LENGTH)
+            fail(`--component must be ${MAX_COMPONENT_LENGTH} characters or fewer: ${name.slice(0, 20)}…`);
+        if (!out.some((o) => o.toLowerCase() === name.toLowerCase()))
+            out.push(name);
+    }
+    if (out.length > MAX_COMPONENTS)
+        fail(`At most ${MAX_COMPONENTS} --component values`);
+    return out;
+}
 function resolveFormat(opts, file) {
     if (opts.format !== undefined) {
         if (opts.format !== "junit" && opts.format !== "locust")
@@ -235,9 +284,11 @@ export function buildReportUploadCommand() {
         .option("--format <format>", "junit | locust (default: from the file name)")
         .option("--kind <kind>", `what the suite proves: ${SUITE_KINDS.join(" | ")} (locust: load)`)
         .option("--tool <label>", "the producing tool, a free label, e.g. vitest, pytest, playwright, specmatic, zap, trivy (locust: locust)")
-        .option("--suite <name>", "tells apart several suites of one kind in a run (e.g. api, web)")
+        .option("--component <name>", "a component the result is for (e.g. frontend, backend), repeatable when it covers several (e.g. an end-to-end test: --component frontend --component backend); new names are created in the project; leave it out for the component `default`", (v, all = []) => [...all, v])
+        .option("--label <name>", "tells apart results that are otherwise the same, such as two scans of one tool on the same components (e.g. --label baseline, --label full-scan); part of the result's identity, so the same label again replaces the result; optional")
+        .option("--tool-version <version>", "the version of the tool that produced the report (e.g. 9.1.0): informational, shown next to the tool, handy when a tool's new version changes its layout; optional")
         .option("--metric <key=value>", "an extra number for the suite, repeatable (e.g. --metric high=0 --metric medium=3; for security: critical, high, medium, low, info)", (v, all = []) => [...all, v])
-        .option("--api-version <label>", "the API version the result is for (e.g. v1, v2), part of the suite's identity next to its kind and name; leave it out for results that hold for every version, such as unit tests")
+        .option("--api-version <label>", "the API version the result is for (e.g. v1, v2), part of the result's identity next to its kind and components; leave it out for results that hold for every version, such as unit tests")
         .option("--project <name>", "project name (CI: the repository); found, or created if missing")
         .option("--repo <repo>", "repository recorded on a newly created project (CI: detected)")
         .option("--run-key <key>", "identity of the pipeline run (CI: detected); all jobs of a run share it")
@@ -272,7 +323,9 @@ export function buildReportUploadCommand() {
             format,
             kind,
             tool: checkedTool,
-            suiteName: opts.suite,
+            components: checkComponents(opts.component),
+            label: checkLabel(opts.label),
+            toolVersion: checkToolVersion(opts.toolVersion),
             status: opts.status,
             maxFailRatio,
             file,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nasebanal/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "gcloud-style command-line interface for NASEBANAL APIs, generated from nb-api-specs OpenAPI contracts.",
   "license": "MIT",
   "type": "module",

package/specs/account.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: NASEBANAL Account API
   description: Centralized user and billing management API for NASEBANAL applications. Manages user profiles, per-service subscriptions, Stripe billing, and Personal Access Tokens (PAT).
-  version: 1.5.1
+  version: 1.6.0
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com