qualink 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Allan Kimmer Jensen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,32 @@
 # qualink
 
+[![CI](https://github.com/Saturate/qualink/actions/workflows/ci.yml/badge.svg)](https://github.com/Saturate/qualink/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/qualink)](https://www.npmjs.com/package/qualink)
+
 Collect, normalize, and relay code quality metrics from CI.
+`qualink` standardizes code quality telemetry across repos and languages, then ships it to a sink (Elastic for now, if you need something else do a PR or a ticket).
+
+## Install
 
-## Why
+```bash
+npm install -g qualink
+pnpm add -g qualink
+bun add -g qualink
+```
 
-`qualink` standardizes code quality telemetry across repos and languages, then ships it to a sink (Elastic first).
+Or run directly:
 
-## Scope (v1)
+```bash
+npx qualink collect eslint --input report.json --sink stdout
+```
 
-- Frontend: ESLint, Lighthouse, Vitest coverage
-- Backend: Roslyn analyzers (SARIF), .NET coverage
-- CI: Azure DevOps
-- Sink: Elasticsearch
+## CI Examples
 
-## CLI shape
+Repo, branch, commit SHA, pipeline run ID, and provider are auto-detected from CI environment variables, no need to pass them manually.
+
+See the [examples/](examples/) folder for copy-paste snippets for Azure DevOps and GitHub Actions.
+
+## CLI usage
 
 ```bash
 qualink collect <collector> --input <path> --sink elastic [flags]
@@ -22,8 +35,53 @@ qualink collect <collector> --input <path> --sink elastic [flags]
 Examples:
 
 ```bash
-qualink collect eslint --input eslint-report.json --sink elastic --repo frontend-mono --team frontend --branch main --commit-sha abc123 --pipeline-run-id 987
-qualink collect sarif --input analyzers.sarif --sink elastic --repo backend-api --team backend --branch main --commit-sha def456 --pipeline-run-id 654
+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
 ```
 
-See `ADR-qualink-v1.md` for the full architecture and rollout plan.
+Collectors:
+
+- `biome` (Biome JSON)
+- `eslint` (ESLint JSON)
+- `lighthouse` (Lighthouse JSON)
+- `coverage-js` (Istanbul/Vitest JSON)
+- `sarif` (Roslyn or generic SARIF JSON)
+- `coverage-dotnet` (Cobertura/OpenCover XML)
+
+ESLint file-level options (optional):
+
+- `--top-files <n>` adds `top_files` with the top offending files (default: `0`, disabled)
+- `--include-all-files` adds `all_files` with every file that has lint issues
+
+Classification metadata (optional):
+
+- `--category` for a single broad bucket
+- `--tags` for flexible multi-label filtering (`comma,separated`)
+
+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>`
+
+If needed, you can still pass explicit values with `--repo`, `--branch`, `--commit-sha`, and `--pipeline-run-id`.
+
+Sink configuration:
+
+- `--sink elastic` (default) requires `ELASTIC_URL` and `ELASTIC_API_KEY`
+- `--sink stdout` prints normalized documents for debugging
+
+Dry run mode:
+
+- `--dry-run` validates and prints normalized payloads without sending to any sink
+
+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_PIPELINE_PROVIDER` (auto-detected, fallback: `local`)
+- `QUALINK_ENVIRONMENT` (default: `ci`)
+- `QUALINK_SINK` (default: `elastic`)

package/bin/qualink.js

@@ -1,3 +1,17 @@
 #!/usr/bin/env node
 
-console.log('qualink: CLI scaffold is in place.');
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const cliFile = join(currentDir, "..", "dist", "cli", "index.js");
+
+if (!existsSync(cliFile)) {
+  process.stderr.write(
+    "qualink build output not found. Run `npm run build` before using the CLI.\n",
+  );
+  process.exit(1);
+}
+
+await import(cliFile);

package/dist/cli/cli-error.d.ts

@@ -0,0 +1,4 @@
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}

package/dist/cli/cli-error.js

@@ -0,0 +1,7 @@
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}

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

@@ -0,0 +1,77 @@
+import type { CommonMetadata, MetricType, NormalizedDocument } from "../types.js";
+import { type CommonArgs } from "./common-args.js";
+interface CollectorResult {
+    metricType: MetricType;
+    documents: NormalizedDocument[];
+}
+interface CollectorCommandConfig<TExtra extends Record<string, unknown>> {
+    name: string;
+    description: string;
+    extraArgs?: TExtra;
+    collect: (args: CommonArgs, metadata: CommonMetadata) => Promise<CollectorResult>;
+}
+export declare function createCollectorCommand<TExtra extends Record<string, unknown>>(config: CollectorCommandConfig<TExtra>): import("citty").CommandDef<{
+    input: {
+        readonly type: "string";
+        readonly required: true;
+    };
+    sink: {
+        readonly type: "string";
+        readonly default: "elastic";
+    };
+    repo: {
+        readonly type: "string";
+    };
+    category: {
+        readonly type: "string";
+    };
+    tags: {
+        readonly type: "string";
+    };
+    branch: {
+        readonly type: "string";
+    };
+    "commit-sha": {
+        readonly type: "string";
+    };
+    "pipeline-run-id": {
+        readonly type: "string";
+    };
+    "pipeline-provider": {
+        readonly type: "string";
+    };
+    environment: {
+        readonly type: "string";
+        readonly default: "ci";
+    };
+    package: {
+        readonly type: "string";
+    };
+    project: {
+        readonly type: "string";
+    };
+    "collector-version": {
+        readonly type: "string";
+    };
+    "elastic-url": {
+        readonly type: "string";
+    };
+    "elastic-api-key": {
+        readonly type: "string";
+    };
+    "retry-max": {
+        readonly type: "string";
+    };
+    "retry-backoff-ms": {
+        readonly type: "string";
+    };
+    "allow-empty": {
+        readonly type: "boolean";
+        readonly default: false;
+    };
+    "dry-run": {
+        readonly type: "boolean";
+        readonly default: false;
+    };
+}>;
+export {};

package/dist/cli/command-factory.js

@@ -0,0 +1,36 @@
+import { defineCommand } from "citty";
+import { CliError } from "./cli-error.js";
+import { commonArgs, isDryRun } from "./common-args.js";
+import { parseCommonMetadata } from "./parse-metadata.js";
+import { sendToSink } from "./send-to-sink.js";
+export function createCollectorCommand(config) {
+    return defineCommand({
+        meta: {
+            name: config.name,
+            description: config.description,
+        },
+        args: {
+            ...commonArgs,
+            ...config.extraArgs,
+        },
+        async run({ args }) {
+            try {
+                const parsedArgs = args;
+                const metadata = parseCommonMetadata(parsedArgs);
+                const { metricType, documents } = await config.collect(parsedArgs, metadata);
+                await sendToSink(metricType, parsedArgs, documents);
+                const verb = isDryRun(parsedArgs) ? "dry-run produced" : "relayed";
+                process.stdout.write(`${verb} ${documents.length} ${metricType} document(s)\n`);
+            }
+            catch (error) {
+                if (error instanceof CliError) {
+                    throw error;
+                }
+                if (error instanceof Error) {
+                    throw new CliError(error.message, 2);
+                }
+                throw new CliError("Unknown error", 2);
+            }
+        },
+    });
+}

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

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

package/dist/cli/commands/biome.js

@@ -0,0 +1,38 @@
+import { collectBiome } from "../../collectors/biome.js";
+import { createCollectorCommand } from "../command-factory.js";
+import { loadJsonInput } from "../load-input.js";
+import { parseLanguages } from "../parse-languages.js";
+function parseIntWithMin(value, fallback, min) {
+    if (typeof value === "number") {
+        return value >= min ? Math.floor(value) : fallback;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed >= min) {
+            return Math.floor(parsed);
+        }
+    }
+    return fallback;
+}
+export const biomeCommand = createCollectorCommand({
+    name: "biome",
+    description: "Collect Biome lint metrics and relay them",
+    extraArgs: {
+        "include-rules": { type: "boolean", default: true },
+        "top-rules": { type: "string", default: "25" },
+        "include-all-files": { type: "boolean", default: false },
+        "top-files": { type: "string", default: "0" },
+        language: { type: "string" },
+    },
+    async collect(args, metadata) {
+        const input = await loadJsonInput(args);
+        const documents = collectBiome(input, metadata, {
+            includeRules: (args.includeRules ?? args["include-rules"]) !== false,
+            topRules: parseIntWithMin(args.topRules ?? args["top-rules"], 25, 1),
+            includeAllFiles: (args.includeAllFiles ?? args["include-all-files"]) === true,
+            topFiles: parseIntWithMin(args.topFiles ?? args["top-files"], 0, 0),
+            languages: parseLanguages(args.language),
+        });
+        return { metricType: "biome", documents };
+    },
+});

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

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

package/dist/cli/commands/coverage-dotnet.js

@@ -0,0 +1,12 @@
+import { collectCoverageDotnet } from "../../collectors/coverage-dotnet.js";
+import { createCollectorCommand } from "../command-factory.js";
+import { loadTextInput } from "../load-input.js";
+export const coverageDotnetCommand = createCollectorCommand({
+    name: "coverage-dotnet",
+    description: "Collect .NET coverage metrics and relay them",
+    async collect(args, metadata) {
+        const input = await loadTextInput(args);
+        const documents = collectCoverageDotnet(input, metadata);
+        return { metricType: "coverage-dotnet", documents };
+    },
+});

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

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

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

@@ -0,0 +1,21 @@
+import { collectCoverageJs } from "../../collectors/coverage-js.js";
+import { createCollectorCommand } from "../command-factory.js";
+import { loadJsonInput } from "../load-input.js";
+import { parseLanguages } from "../parse-languages.js";
+export const coverageJsCommand = createCollectorCommand({
+    name: "coverage-js",
+    description: "Collect JS coverage metrics and relay them",
+    extraArgs: {
+        language: { type: "string" },
+        "tool-name": { type: "string" },
+    },
+    async collect(args, metadata) {
+        const input = await loadJsonInput(args);
+        const toolName = args["tool-name"];
+        const documents = collectCoverageJs(input, metadata, {
+            languages: parseLanguages(args.language),
+            tool: typeof toolName === "string" && toolName.length > 0 ? toolName : undefined,
+        });
+        return { metricType: "coverage-js", documents };
+    },
+});

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

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

package/dist/cli/commands/eslint.js

@@ -0,0 +1,38 @@
+import { collectEslint } from "../../collectors/eslint.js";
+import { createCollectorCommand } from "../command-factory.js";
+import { loadJsonInput } from "../load-input.js";
+import { parseLanguages } from "../parse-languages.js";
+function parseIntWithMin(value, fallback, min) {
+    if (typeof value === "number") {
+        return value >= min ? Math.floor(value) : fallback;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed >= min) {
+            return Math.floor(parsed);
+        }
+    }
+    return fallback;
+}
+export const eslintCommand = createCollectorCommand({
+    name: "eslint",
+    description: "Collect ESLint metrics and relay them",
+    extraArgs: {
+        "include-rules": { type: "boolean", default: true },
+        "top-rules": { type: "string", default: "25" },
+        "include-all-files": { type: "boolean", default: false },
+        "top-files": { type: "string", default: "0" },
+        language: { type: "string" },
+    },
+    async collect(args, metadata) {
+        const input = await loadJsonInput(args);
+        const documents = collectEslint(input, metadata, {
+            includeRules: (args.includeRules ?? args["include-rules"]) !== false,
+            topRules: parseIntWithMin(args.topRules ?? args["top-rules"], 25, 1),
+            includeAllFiles: (args.includeAllFiles ?? args["include-all-files"]) === true,
+            topFiles: parseIntWithMin(args.topFiles ?? args["top-files"], 0, 0),
+            languages: parseLanguages(args.language),
+        });
+        return { metricType: "eslint", documents };
+    },
+});

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

@@ -0,0 +1,7 @@
+export { biomeCommand } from "./biome.js";
+export { coverageDotnetCommand } from "./coverage-dotnet.js";
+export { coverageJsCommand } from "./coverage-js.js";
+export { eslintCommand } from "./eslint.js";
+export { lighthouseCommand } from "./lighthouse.js";
+export { metaCommand } from "./meta.js";
+export { sarifCommand } from "./sarif.js";

package/dist/cli/commands/index.js

@@ -0,0 +1,7 @@
+export { biomeCommand } from "./biome.js";
+export { coverageDotnetCommand } from "./coverage-dotnet.js";
+export { coverageJsCommand } from "./coverage-js.js";
+export { eslintCommand } from "./eslint.js";
+export { lighthouseCommand } from "./lighthouse.js";
+export { metaCommand } from "./meta.js";
+export { sarifCommand } from "./sarif.js";