qualink 0.3.0 → 0.4.0

package/README.md

@@ -26,6 +26,79 @@ 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
 
 ```bash
@@ -38,6 +111,12 @@ Examples:
 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
+
+# Pipeline tracking (top-level command, not under collect)
+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:

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

@@ -4,4 +4,5 @@ export { coverageJsCommand } from "./coverage-js.js";
 export { eslintCommand } from "./eslint.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

@@ -4,4 +4,5 @@ export { coverageJsCommand } from "./coverage-js.js";
 export { eslintCommand } from "./eslint.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/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;

package/dist/cli/detect-solution.js

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { argValue, envOrArg } from "./common-args.js";
+import { runGit } from "./git.js";
+function findGitRoot() {
+    return runGit(["rev-parse", "--show-toplevel"]);
+}
+/**
+ * Walk up from CWD to git root looking for a .sln file.
+ */
+function findSlnName() {
+    const gitRoot = findGitRoot();
+    if (!gitRoot) {
+        return undefined;
+    }
+    let current = resolve(".");
+    const boundary = resolve(gitRoot);
+    while (current.startsWith(boundary)) {
+        try {
+            const files = readdirSync(current);
+            const sln = files.find((f) => f.endsWith(".sln"));
+            if (sln) {
+                return basename(sln, ".sln");
+            }
+        }
+        catch {
+            // permission error, keep walking
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * If CWD is inside a workspace subdirectory, read the git root's
+ * package.json name as the workspace root (solution).
+ */
+function findWorkspaceRootName() {
+    const gitRoot = findGitRoot();
+    if (!gitRoot) {
+        return undefined;
+    }
+    // Only counts as workspace if CWD != git root
+    if (resolve(".") === resolve(gitRoot)) {
+        return undefined;
+    }
+    try {
+        const pkgPath = join(gitRoot, "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 detectSolution(args) {
+    const explicit = envOrArg(argValue(args, "solution"), "QUALINK_SOLUTION");
+    if (explicit) {
+        return explicit;
+    }
+    return findSlnName() ?? findWorkspaceRootName();
+}

package/dist/cli/index.js

@@ -1,11 +1,31 @@
 import { defineCommand, runMain } from "citty";
 import { CliError } from "./cli-error.js";
-import { biomeCommand, coverageDotnetCommand, coverageJsCommand, eslintCommand, lighthouseCommand, metaCommand, sarifCommand, } from "./commands/index.js";
+import { biomeCommand, coverageDotnetCommand, coverageJsCommand, eslintCommand, lighthouseCommand, metaCommand, pipelineCommand, sarifCommand, } from "./commands/index.js";
+import { commonArgs, isDryRun } from "./common-args.js";
+import { parseConfig, resolveConfig } from "./multi-collect/config.js";
+import { discoverFiles } from "./multi-collect/discover.js";
+import { mergeMetadata, resolveFileMetadata, } from "./multi-collect/resolve-metadata.js";
+import { runCollector } from "./multi-collect/run-collector.js";
+import { parseCommonMetadata } from "./parse-metadata.js";
+import { sendToSink } from "./send-to-sink.js";
+// Common args without `input` (required by single-collector subcommands but not multi-collect)
+const { input: _input, ...multiCollectBaseArgs } = commonArgs;
 const collectCommand = defineCommand({
     meta: {
         name: "collect",
         description: "Collect quality metrics from a specific collector",
     },
+    args: {
+        ...multiCollectBaseArgs,
+        dir: {
+            type: "string",
+            description: "Auto-discover report files under a directory",
+        },
+        config: {
+            type: "string",
+            description: "Config file path or inline JSON for multi-collection",
+        },
+    },
     subCommands: {
         biome: biomeCommand,
         eslint: eslintCommand,
@@ -14,7 +34,108 @@ const collectCommand = defineCommand({
         sarif: sarifCommand,
         "coverage-dotnet": coverageDotnetCommand,
     },
+    async run({ args }) {
+        const parsedArgs = args;
+        const dirValue = args.dir;
+        const configValue = args.config;
+        if (typeof dirValue === "string" && typeof configValue === "string") {
+            throw new CliError("--dir and --config are mutually exclusive", 2);
+        }
+        if (typeof dirValue === "string") {
+            await runDirMode(dirValue, parsedArgs);
+        }
+        else if (typeof configValue === "string") {
+            await runConfigMode(configValue, parsedArgs);
+        }
+        // If neither --dir nor --config, citty will show help for subcommands
+    },
 });
+async function runDirMode(dir, args) {
+    const metadata = parseCommonMetadata(args);
+    const discovered = await discoverFiles(dir);
+    const accumulated = new Map();
+    const counts = new Map();
+    for (const [collectorKey, files] of discovered) {
+        for (const filePath of files) {
+            try {
+                const fileOverrides = resolveFileMetadata(filePath, collectorKey);
+                const merged = mergeMetadata(metadata, fileOverrides);
+                const output = await runCollector(collectorKey, filePath, merged);
+                accumulate(accumulated, output);
+                counts.set(collectorKey, (counts.get(collectorKey) ?? 0) + output.documents.length);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`warning: skipping ${filePath} (${collectorKey}): ${msg}\n`);
+            }
+        }
+    }
+    await sendAll(accumulated, args);
+    printSummary(counts, args);
+}
+async function runConfigMode(configValue, args) {
+    const metadata = parseCommonMetadata(args);
+    const entries = await parseConfig(configValue);
+    const resolved = await resolveConfig(entries, ".");
+    const accumulated = new Map();
+    const counts = new Map();
+    for (const entry of resolved) {
+        const configOverrides = {};
+        if (entry.tags !== undefined)
+            configOverrides.tags = entry.tags;
+        if (entry.category !== undefined)
+            configOverrides.category = entry.category;
+        if (entry.project !== undefined)
+            configOverrides.projectName = entry.project;
+        if (entry.solution !== undefined)
+            configOverrides.solution = entry.solution;
+        for (const filePath of entry.files) {
+            try {
+                const fileOverrides = resolveFileMetadata(filePath, entry.type);
+                const merged = mergeMetadata(metadata, fileOverrides, configOverrides);
+                const output = await runCollector(entry.type, filePath, merged, entry.url);
+                accumulate(accumulated, output);
+                counts.set(entry.type, (counts.get(entry.type) ?? 0) + output.documents.length);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`warning: skipping ${filePath} (${entry.type}): ${msg}\n`);
+            }
+        }
+    }
+    await sendAll(accumulated, args);
+    printSummary(counts, args);
+}
+function accumulate(map, output) {
+    const existing = map.get(output.metricType);
+    if (existing) {
+        existing.push(...output.documents);
+    }
+    else {
+        map.set(output.metricType, [...output.documents]);
+    }
+}
+async function sendAll(accumulated, args) {
+    for (const [metricType, documents] of accumulated) {
+        if (documents.length > 0) {
+            await sendToSink(metricType, { ...args, "allow-empty": true }, documents);
+        }
+    }
+}
+function printSummary(counts, args) {
+    const verb = isDryRun(args) ? "dry-run" : "collected";
+    const parts = [];
+    let total = 0;
+    for (const [key, count] of counts) {
+        parts.push(`${count} ${key}`);
+        total += count;
+    }
+    if (total === 0) {
+        process.stderr.write("warning: no report files found\n");
+        return;
+    }
+    process.stdout.write(`${verb}: ${parts.join(", ")}\n`);
+}
 const main = defineCommand({
     meta: {
         name: "qualink",
@@ -24,6 +145,7 @@ const main = defineCommand({
     subCommands: {
         collect: collectCommand,
         meta: metaCommand,
+        pipeline: pipelineCommand,
     },
 });
 runMain(main).catch((error) => {