qualink 0.3.0 → 0.5.0

package/README.md

@@ -26,18 +26,131 @@ Repo, branch, commit SHA, pipeline run ID, and provider are auto-detected from C
 
 See the [examples/](examples/) folder for copy-paste snippets for Azure DevOps and GitHub Actions.
 
+## Pipeline Tracking
+
+Track pipeline execution metrics — which pipelines run, when, for how long, and their outcome.
+Pipelines self-report by calling `qualink pipeline --status <status>` at the end of a run.
+
+### Azure DevOps
+
+```yaml
+steps:
+  - script: echo "##vso[task.setvariable variable=PIPELINE_START]$(date +%s%3N)"
+    displayName: Record start time
+
+  # ... existing build/test steps ...
+
+  - script: |
+      END_TIME=$(date +%s%3N)
+      DURATION=$(( END_TIME - $(PIPELINE_START) ))
+      npx qualink pipeline \
+        --status "$(Agent.JobStatus)" \
+        --duration "$DURATION" \
+        --sink elastic
+    displayName: Report pipeline metrics
+    condition: always()
+    env:
+      ELASTIC_URL: $(ELASTIC_URL)
+      ELASTIC_API_KEY: $(ELASTIC_API_KEY)
+```
+
+Auto-detected from Azure DevOps env: pipeline name (`BUILD_DEFINITIONNAME`), trigger (`BUILD_REASON`), repo, branch, commit, run ID, provider.
+
+### GitHub Actions
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Record start time
+        run: echo "PIPELINE_START=$(date +%s%3N)" >> "$GITHUB_ENV"
+
+      # ... existing build/test steps ...
+
+      - name: Report pipeline metrics
+        if: always()
+        run: |
+          END_TIME=$(date +%s%3N)
+          DURATION=$(( END_TIME - PIPELINE_START ))
+          npx qualink pipeline \
+            --status "${{ job.status }}" \
+            --duration "$DURATION" \
+            --sink elastic
+        env:
+          ELASTIC_URL: ${{ secrets.ELASTIC_URL }}
+          ELASTIC_API_KEY: ${{ secrets.ELASTIC_API_KEY }}
+```
+
+Auto-detected from GitHub env: pipeline name (`GITHUB_WORKFLOW`), trigger (`GITHUB_EVENT_NAME`), repo, branch, commit, run ID, provider.
+
+### Per-stage reporting
+
+For pipelines with distinct stages, call qualink once per stage with `--stage-name`:
+
+```yaml
+# Azure DevOps example
+- script: |
+    npx qualink pipeline --status "$(Agent.JobStatus)" --stage-name build --duration "$BUILD_DURATION"
+  condition: always()
+
+- script: |
+    npx qualink pipeline --status "$(Agent.JobStatus)" --stage-name deploy --duration "$DEPLOY_DURATION"
+  condition: always()
+```
+
 ## CLI usage
 
+### Single collector
+
 ```bash
 qualink collect <collector> --input <path> --sink elastic [flags]
 ```
 
-Examples:
+```bash
+qualink collect eslint --input eslint-report.json --sink elastic --repo frontend-mono --category frontend --tags frontend,web
+qualink collect sarif --input analyzers.sarif --sink elastic --repo backend-api --category backend --tags backend,api
+qualink collect coverage-dotnet --input coverage.cobertura.xml --sink elastic --repo backend-api
+```
+
+### Multi-collect
+
+Auto-discover report files in a directory tree:
 
 ```bash
-qualink collect eslint --input eslint-report.json --sink elastic --repo frontend-mono --category frontend --tags frontend,web --branch main --commit-sha abc123 --pipeline-run-id 987
-qualink collect sarif --input analyzers.sarif --sink elastic --repo backend-api --category backend --tags backend,api --branch main --commit-sha def456 --pipeline-run-id 654
-qualink collect coverage-dotnet --input coverage.cobertura.xml --sink elastic --repo backend-api --category backend --tags backend,api --branch main --commit-sha def456 --pipeline-run-id 654
+qualink collect --dir=./output --repo myapp --sink elastic
+```
+
+Or use a config file for explicit control:
+
+```bash
+qualink collect --config=qualink.json --repo myapp --sink elastic
+```
+
+Config file example (`qualink.json`):
+
+```json
+[
+  { "type": "eslint", "input": "packages/*/eslint-report.json" },
+  { "type": "coverage-js", "input": "packages/*/coverage-summary.json" },
+  { "type": "sarif", "input": "**/*.sarif" }
+]
+```
+
+Each entry supports optional overrides: `tags`, `category`, `project`, `solution`, `url`.
+See [qualink-config.schema.json](qualink-config.schema.json) for the full schema.
+
+Auto-discovery recognizes: `eslint-report.json`, `biome-report.json`, `coverage-summary.json`, `coverage.cobertura.xml`, `*.sarif`/`*.sarif.json`, `lhr-*.json` inside `.lighthouseci/`, `junit.xml`, and `TEST-*.xml`.
+
+### Pipeline tracking
+
+Top-level command, not under `collect`:
+
+```bash
+qualink pipeline --status succeeded --sink elastic
+qualink pipeline --status succeeded --duration 125000 --pipeline-name "Build and Deploy"
+qualink pipeline --status succeeded --stage-name build --duration 45000
+qualink pipeline --status failed --dry-run
 ```
 
 Collectors:
@@ -48,6 +161,7 @@ Collectors:
 - `coverage-js` (Istanbul/Vitest JSON)
 - `sarif` (Roslyn or generic SARIF JSON)
 - `coverage-dotnet` (Cobertura/OpenCover XML)
+- `junit` (JUnit XML)
 
 ESLint file-level options (optional):
 
@@ -59,12 +173,19 @@ Classification metadata (optional):
 - `--category` for a single broad bucket
 - `--tags` for flexible multi-label filtering (`comma,separated`)
 
+Project hierarchy (auto-detected or explicit):
+
+- `--solution` groups related projects (auto-detected from `.sln` or workspace root `package.json`)
+- `--project` identifies the individual project (auto-detected from nearest `.csproj` or `package.json`)
+
 Metadata auto-detection:
 
 - `repo`: from flag/env, then git origin, then current folder name
 - `branch`: from flag/env, then git branch
 - `commit_sha`: from flag/env, then git commit
 - `pipeline_run_id`: from flag/env, fallback `local-<timestamp>`
+- `project`: from flag/env, then nearest `.csproj`/`package.json`
+- `solution`: from flag/env, then nearest `.sln`/workspace root `package.json`
 
 If needed, you can still pass explicit values with `--repo`, `--branch`, `--commit-sha`, and `--pipeline-run-id`.
 
@@ -81,8 +202,8 @@ Dry run mode:
 Useful env fallbacks:
 
 - `QUALINK_REPO`, `QUALINK_CATEGORY`, `QUALINK_TAGS`, `QUALINK_BRANCH`, `QUALINK_COMMIT_SHA`, `QUALINK_PIPELINE_RUN_ID`
-- `QUALINK_PACKAGE` (monorepo package name, auto-detected from `PNPM_PACKAGE_NAME`)
-- `QUALINK_PROJECT` (backend project identity)
+- `QUALINK_PROJECT` (auto-detected from nearest `.csproj`/`package.json` or `PNPM_PACKAGE_NAME`)
+- `QUALINK_SOLUTION` (auto-detected from `.sln` or workspace root `package.json`)
 - `QUALINK_PIPELINE_PROVIDER` (auto-detected, fallback: `local`)
 - `QUALINK_ENVIRONMENT` (default: `ci`)
 - `QUALINK_SINK` (default: `elastic`)

package/dist/cli/command-factory.d.ts

@@ -44,7 +44,7 @@ export declare function createCollectorCommand<TExtra extends Record<string, unk
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/biome.d.ts

@@ -32,7 +32,7 @@ export declare const biomeCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/coverage-dotnet.d.ts

@@ -32,7 +32,7 @@ export declare const coverageDotnetCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/coverage-js.d.ts

@@ -32,7 +32,7 @@ export declare const coverageJsCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/eslint.d.ts

@@ -32,7 +32,7 @@ export declare const eslintCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/index.d.ts

@@ -2,6 +2,8 @@ export { biomeCommand } from "./biome.js";
 export { coverageDotnetCommand } from "./coverage-dotnet.js";
 export { coverageJsCommand } from "./coverage-js.js";
 export { eslintCommand } from "./eslint.js";
+export { junitCommand } from "./junit.js";
 export { lighthouseCommand } from "./lighthouse.js";
 export { metaCommand } from "./meta.js";
+export { pipelineCommand } from "./pipeline.js";
 export { sarifCommand } from "./sarif.js";

package/dist/cli/commands/index.js

@@ -2,6 +2,8 @@ export { biomeCommand } from "./biome.js";
 export { coverageDotnetCommand } from "./coverage-dotnet.js";
 export { coverageJsCommand } from "./coverage-js.js";
 export { eslintCommand } from "./eslint.js";
+export { junitCommand } from "./junit.js";
 export { lighthouseCommand } from "./lighthouse.js";
 export { metaCommand } from "./meta.js";
+export { pipelineCommand } from "./pipeline.js";
 export { sarifCommand } from "./sarif.js";

package/dist/cli/commands/junit.d.ts

@@ -0,0 +1,76 @@
+export declare const junitCommand: import("citty").CommandDef<{
+    readonly input: {
+        readonly type: "string";
+        readonly required: true;
+    };
+    readonly sink: {
+        readonly type: "string";
+        readonly default: "elastic";
+    };
+    readonly repo: {
+        readonly type: "string";
+    };
+    readonly category: {
+        readonly type: "string";
+    };
+    readonly tags: {
+        readonly type: "string";
+    };
+    readonly branch: {
+        readonly type: "string";
+    };
+    readonly "commit-sha": {
+        readonly type: "string";
+    };
+    readonly "pipeline-run-id": {
+        readonly type: "string";
+    };
+    readonly "pipeline-provider": {
+        readonly type: "string";
+    };
+    readonly environment: {
+        readonly type: "string";
+        readonly default: "ci";
+    };
+    readonly solution: {
+        readonly type: "string";
+    };
+    readonly project: {
+        readonly type: "string";
+    };
+    readonly "collector-version": {
+        readonly type: "string";
+    };
+    readonly "elastic-url": {
+        readonly type: "string";
+    };
+    readonly "elastic-api-key": {
+        readonly type: "string";
+    };
+    readonly "loki-url": {
+        readonly type: "string";
+    };
+    readonly "loki-username": {
+        readonly type: "string";
+    };
+    readonly "loki-password": {
+        readonly type: "string";
+    };
+    readonly "loki-tenant-id": {
+        readonly type: "string";
+    };
+    readonly "retry-max": {
+        readonly type: "string";
+    };
+    readonly "retry-backoff-ms": {
+        readonly type: "string";
+    };
+    readonly "allow-empty": {
+        readonly type: "boolean";
+        readonly default: false;
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly default: false;
+    };
+}>;

package/dist/cli/commands/junit.js

@@ -0,0 +1,12 @@
+import { collectJunit } from "../../collectors/junit.js";
+import { createCollectorCommand } from "../command-factory.js";
+import { loadTextInput } from "../load-input.js";
+export const junitCommand = createCollectorCommand({
+    name: "junit",
+    description: "Collect JUnit XML test results and relay them",
+    async collect(args, metadata) {
+        const input = await loadTextInput(args);
+        const documents = collectJunit(input, metadata);
+        return { metricType: "junit", documents };
+    },
+});

package/dist/cli/commands/lighthouse.d.ts

@@ -32,7 +32,7 @@ export declare const lighthouseCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/meta.d.ts

@@ -32,7 +32,7 @@ export declare const metaCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/commands/pipeline.d.ts

@@ -0,0 +1,76 @@
+export declare const pipelineCommand: import("citty").CommandDef<{
+    readonly input: {
+        readonly type: "string";
+        readonly required: true;
+    };
+    readonly sink: {
+        readonly type: "string";
+        readonly default: "elastic";
+    };
+    readonly repo: {
+        readonly type: "string";
+    };
+    readonly category: {
+        readonly type: "string";
+    };
+    readonly tags: {
+        readonly type: "string";
+    };
+    readonly branch: {
+        readonly type: "string";
+    };
+    readonly "commit-sha": {
+        readonly type: "string";
+    };
+    readonly "pipeline-run-id": {
+        readonly type: "string";
+    };
+    readonly "pipeline-provider": {
+        readonly type: "string";
+    };
+    readonly environment: {
+        readonly type: "string";
+        readonly default: "ci";
+    };
+    readonly solution: {
+        readonly type: "string";
+    };
+    readonly project: {
+        readonly type: "string";
+    };
+    readonly "collector-version": {
+        readonly type: "string";
+    };
+    readonly "elastic-url": {
+        readonly type: "string";
+    };
+    readonly "elastic-api-key": {
+        readonly type: "string";
+    };
+    readonly "loki-url": {
+        readonly type: "string";
+    };
+    readonly "loki-username": {
+        readonly type: "string";
+    };
+    readonly "loki-password": {
+        readonly type: "string";
+    };
+    readonly "loki-tenant-id": {
+        readonly type: "string";
+    };
+    readonly "retry-max": {
+        readonly type: "string";
+    };
+    readonly "retry-backoff-ms": {
+        readonly type: "string";
+    };
+    readonly "allow-empty": {
+        readonly type: "boolean";
+        readonly default: false;
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly default: false;
+    };
+}>;

package/dist/cli/commands/pipeline.js

@@ -0,0 +1,35 @@
+import { collectPipeline } from "../../collectors/pipeline.js";
+import { createCollectorCommand } from "../command-factory.js";
+import { detectPipelineName, detectPipelineTrigger } from "../detect-ci.js";
+export const pipelineCommand = createCollectorCommand({
+    name: "pipeline",
+    description: "Report pipeline execution metrics",
+    extraArgs: {
+        input: { type: "string" },
+        sink: { type: "string", default: "elastic" },
+        status: { type: "string", required: true },
+        "pipeline-name": { type: "string" },
+        trigger: { type: "string" },
+        duration: { type: "string" },
+        "start-time": { type: "string" },
+        "stage-name": { type: "string" },
+    },
+    async collect(args, metadata) {
+        const status = args.status;
+        const pipelineName = (args.pipelineName ?? args["pipeline-name"]);
+        const trigger = args.trigger;
+        const rawDuration = args.duration;
+        const startTime = (args.startTime ?? args["start-time"]);
+        const stageName = (args.stageName ?? args["stage-name"]);
+        const durationMs = rawDuration ? Number(rawDuration) : null;
+        const documents = collectPipeline({
+            status,
+            pipelineName: pipelineName ?? detectPipelineName(args),
+            trigger: trigger ?? detectPipelineTrigger(args),
+            durationMs: durationMs !== null && Number.isFinite(durationMs) ? durationMs : null,
+            startTime: startTime ?? null,
+            stageName: stageName ?? null,
+        }, metadata);
+        return { metricType: "pipeline", documents };
+    },
+});

package/dist/cli/commands/sarif.d.ts

@@ -32,7 +32,7 @@ export declare const sarifCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/common-args.d.ts

@@ -10,7 +10,7 @@ export interface CommonArgs {
     pipelineRunId?: unknown;
     pipelineProvider?: unknown;
     environment?: unknown;
-    package?: unknown;
+    solution?: unknown;
     project?: unknown;
     collectorVersion?: unknown;
     elasticUrl?: unknown;
@@ -60,7 +60,7 @@ export declare const commonArgs: {
         readonly type: "string";
         readonly default: "ci";
     };
-    readonly package: {
+    readonly solution: {
         readonly type: "string";
     };
     readonly project: {

package/dist/cli/common-args.js

@@ -32,7 +32,7 @@ export const commonArgs = {
     "pipeline-run-id": { type: "string" },
     "pipeline-provider": { type: "string" },
     environment: { type: "string", default: "ci" },
-    package: { type: "string" },
+    solution: { type: "string" },
     project: { type: "string" },
     "collector-version": { type: "string" },
     "elastic-url": { type: "string" },

package/dist/cli/detect-ci.d.ts

@@ -2,4 +2,6 @@ import { type CommonArgs } from "./common-args.js";
 export declare function detectBranch(args: CommonArgs): string;
 export declare function detectCommitSha(args: CommonArgs): string;
 export declare function detectPipelineRunId(args: CommonArgs): string;
+export declare function detectPipelineName(args: CommonArgs): string;
+export declare function detectPipelineTrigger(args: CommonArgs): string;
 export declare function detectPipelineProvider(args: CommonArgs): string;

package/dist/cli/detect-ci.js

@@ -23,6 +23,53 @@ export function detectPipelineRunId(args) {
         process.env.CI_PIPELINE_ID ??
         `local-${Date.now().toString()}`);
 }
+export function detectPipelineName(args) {
+    return (envOrArg(argValue(args, "pipelineName", "pipeline-name"), "QUALINK_PIPELINE_NAME") ??
+        process.env.BUILD_DEFINITIONNAME ??
+        process.env.GITHUB_WORKFLOW ??
+        process.env.CI_PIPELINE_NAME ??
+        process.env.CI_PROJECT_NAME ??
+        "unknown");
+}
+const AZURE_TRIGGER_MAP = {
+    IndividualCI: "push",
+    BatchedCI: "push",
+    PullRequest: "pr",
+    Manual: "manual",
+    Schedule: "schedule",
+};
+const GITHUB_TRIGGER_MAP = {
+    push: "push",
+    pull_request: "pr",
+    workflow_dispatch: "manual",
+    schedule: "schedule",
+};
+const GITLAB_TRIGGER_MAP = {
+    push: "push",
+    merge_request_event: "pr",
+    web: "manual",
+    schedule: "schedule",
+    api: "api",
+};
+export function detectPipelineTrigger(args) {
+    const explicit = envOrArg(argValue(args, "trigger"), "QUALINK_PIPELINE_TRIGGER");
+    if (explicit) {
+        return explicit;
+    }
+    const azureReason = process.env.BUILD_REASON;
+    if (azureReason) {
+        return AZURE_TRIGGER_MAP[azureReason] ?? azureReason;
+    }
+    const githubEvent = process.env.GITHUB_EVENT_NAME;
+    if (githubEvent) {
+        return GITHUB_TRIGGER_MAP[githubEvent] ?? githubEvent;
+    }
+    const gitlabSource = process.env.CI_PIPELINE_SOURCE;
+    if (gitlabSource) {
+        return GITLAB_TRIGGER_MAP[gitlabSource] ?? gitlabSource;
+    }
+    return "unknown";
+}
 export function detectPipelineProvider(args) {
     const explicit = envOrArg(argValue(args, "pipelineProvider", "pipeline-provider"), "QUALINK_PIPELINE_PROVIDER");
     if (explicit) {

package/dist/cli/detect-project.js

@@ -1,7 +1,14 @@
-import { readdirSync } from "node:fs";
-import { basename } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
 import { argValue, envOrArg } from "./common-args.js";
-import { isInsideWorkspacePackage } from "./detect-package.js";
+import { runGit } from "./git.js";
+function isInsideWorkspacePackage() {
+    const gitRoot = runGit(["rev-parse", "--show-toplevel"]);
+    if (!gitRoot) {
+        return false;
+    }
+    return resolve(".") !== resolve(gitRoot);
+}
 function readCsprojName() {
     try {
         const files = readdirSync(".");
@@ -15,14 +22,33 @@ function readCsprojName() {
     }
     return undefined;
 }
+function readPackageJsonName() {
+    try {
+        const pkgPath = resolve("package.json");
+        if (!existsSync(pkgPath)) {
+            return undefined;
+        }
+        const raw = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (typeof raw === "object" && raw !== null && "name" in raw && typeof raw.name === "string") {
+            return raw.name;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
 export function detectProjectName(args) {
     const explicit = envOrArg(argValue(args, "project"), "QUALINK_PROJECT");
     if (explicit) {
         return explicit;
     }
-    // Auto-detect from .csproj when running inside a project subdirectory
+    const pnpmName = process.env.PNPM_PACKAGE_NAME;
+    if (pnpmName && pnpmName.trim().length > 0) {
+        return pnpmName;
+    }
     if (isInsideWorkspacePackage()) {
-        return readCsprojName();
+        return readCsprojName() ?? readPackageJsonName();
     }
     return undefined;
 }

package/dist/cli/detect-solution.d.ts

@@ -0,0 +1,2 @@
+import { type CommonArgs } from "./common-args.js";
+export declare function detectSolution(args: CommonArgs): string | undefined;