@theholocron/holocron-plugin-codecov 0.0.0-stage → 5.0.0-alpha.445

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+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/dist/index.d.mts

@@ -0,0 +1,73 @@
+import { AuthError, Coverage, CoverageTokenCheck, PluginToken, ResolveTokenInput } from "@theholocron/cli";
+import { CodecovClient, CodecovClientOptions, CodecovService, createCodecovClient } from "@theholocron/codecov-client";
+/** Resolves the Codecov token from `--token`, `HOLOCRON_CODECOV_TOKEN`, `CODECOV_TOKEN` or the keyring entry for `codecov`, and throws an `AuthError` when none is set. */
+export declare const resolveToken: import("@theholocron/cli").TokenResolver;
+/** Every token this plugin takes, for `holocron doctor tokens`, with the layers that hold it. */
+export declare const tokens: PluginToken[];
+/** The repository the plugin asks Codecov about. */
+interface CodecovTarget {
+  /** The git hosting service Codecov knows the owner by. */
+  service: CodecovService;
+  /** The owner (user or organization) on that service. */
+  owner: string;
+  /** The repository name. */
+  repo: string;
+}
+/** The options that say which repository to ask about. */
+interface CodecovTargetOptions {
+  /** The git hosting service. Default `github`. */
+  service?: CodecovService;
+  /** The owner. Default: the owner of `repo` when it is `owner/name`, else the active `org`. */
+  owner?: string;
+  /** The repository: `owner/name`, or a bare name. The CLI passes the repo it is operating on. */
+  repo?: string;
+  /** The active org, which the CLI passes to every plugin. */
+  org?: string;
+}
+/** Works out the repository from the plugin options, or `undefined` when they do not name one. */
+export declare function resolveTarget(options: CodecovTargetOptions): CodecovTarget | undefined;
+/** The `coverage` capability for Codecov. */
+export declare class CodecovCoverage implements Coverage {
+  private readonly client;
+  private readonly target;
+  /** The capability key, always `coverage`. */
+  readonly key: "coverage";
+  /** The provider name, `codecov`. */
+  readonly providerName = "codecov";
+  /**
+   * `client` is a thunk, so the token is resolved on first use and a plugin load never needs one. `target` is `undefined`
+   * when the options name no repository.
+   */
+  constructor(client: () => CodecovClient, target: CodecovTarget | undefined);
+  checkToken(): Promise<CoverageTokenCheck>;
+}
+/** Options for the Codecov plugin: token resolution, the repository and test overrides. */
+export interface CodecovPluginOptions extends ResolveTokenInput, CodecovTargetOptions {
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+/** What the plugin's capability and probes share: the options and a lazily built client. */
+export interface PluginContext {
+  /** The options the plugin was created with. */
+  options: CodecovPluginOptions;
+  /** Builds the client on first call and reuses it; the token is resolved then, not at plugin load. */
+  client: () => CodecovClient;
+}
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
+export declare function createContext(options?: CodecovPluginOptions): PluginContext;
+/** Builds the `coverage` capability from a plugin context. */
+export declare function coverage(ctx: PluginContext): Coverage;
+/** Creates the Codecov plugin: its `connection` and `token` probes and the `coverage` capability. */
+export declare function createPlugin(options?: CodecovPluginOptions): {
+  name: string;
+  probes: {
+    connection: import("@theholocron/cli").Probe;
+    token: import("@theholocron/cli").Probe;
+  };
+  capabilities: {
+    coverage: () => Coverage;
+  };
+};
+export { AuthError, type CodecovClient, type CodecovClientOptions, type CodecovTarget, type CodecovTargetOptions, type ResolveTokenInput, createCodecovClient };

package/dist/index.mjs

@@ -0,0 +1,226 @@
+import { AuthError, ProviderApiError, connectionProbe, createResolveToken, tokenExpectations } from "@theholocron/cli";
+import { createCodecovClient } from "@theholocron/codecov-client";
+// src/probes/token/expectations.ts
+/**
+* Where the Codecov token is held: CI only (`measure:bundle` uploads bundle stats with it), so `ci` is the one layer
+* declared. Codecov has one token that does one thing, upload, and no permission model, so no permissions are declared and
+* the probe says so instead of guessing. This is the plugin's `tokens` declaration, read through `tokenExpectations()`;
+* change it and the Codecov row in `docs/src/content/docs/tokens.mdx` together.
+*/
+const EXPECTED = { layers: ["ci"] };
+// src/auth.ts
+/** Resolves the Codecov token from `--token`, `HOLOCRON_CODECOV_TOKEN`, `CODECOV_TOKEN` or the keyring entry for `codecov`, and throws an `AuthError` when none is set. */
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_CODECOV_TOKEN",
+	vendorEnvName: "CODECOV_TOKEN",
+	keyringService: "codecov",
+	errorMessage: "no Codecov token found. Pass --token <TOKEN>, set HOLOCRON_CODECOV_TOKEN / CODECOV_TOKEN, or run: holocron new token codecov <TOKEN>"
+});
+/** Every token this plugin takes, for `holocron doctor tokens`, with the layers that hold it. */
+const tokens = [{
+	...resolveToken.token,
+	expect: EXPECTED
+}];
+// src/target.ts
+/** Works out the repository from the plugin options, or `undefined` when they do not name one. */
+function resolveTarget(options) {
+	const [first, second] = (options.repo ?? "").split("/");
+	const name = second === void 0 ? first : second;
+	const owner = options.owner ?? (second === void 0 ? void 0 : first) ?? options.org;
+	if (!owner || !name) return void 0;
+	return {
+		service: options.service ?? "github",
+		owner,
+		repo: name
+	};
+}
+/** `owner/repo`, for messages. */
+function describeTarget(target) {
+	return `${target.owner}/${target.repo}`;
+}
+// src/capabilities/coverage.ts
+/** The `coverage` capability for Codecov. */
+var CodecovCoverage = class {
+	client;
+	target;
+	/** The capability key, always `coverage`. */
+	key = "coverage";
+	/** The provider name, `codecov`. */
+	providerName = "codecov";
+	/**
+	* `client` is a thunk, so the token is resolved on first use and a plugin load never needs one. `target` is `undefined`
+	* when the options name no repository.
+	*/
+	constructor(client, target) {
+		this.client = client;
+		this.target = target;
+	}
+	async checkToken() {
+		if (!this.target) throw new Error("@theholocron/holocron-plugin-codecov needs a repository (the plugin options owner and repo, or the active repo) for checkToken");
+		const { service, owner, repo } = this.target;
+		try {
+			const found = await this.client().repos.get(service, owner, repo);
+			return {
+				outcome: "accepted",
+				...found.private === void 0 ? {} : { repoPrivate: found.private }
+			};
+		} catch (err) {
+			if (err instanceof ProviderApiError) {
+				if (err.status === 401 || err.status === 403) return {
+					outcome: "refused",
+					status: err.status
+				};
+				if (err.status === 404) return {
+					outcome: "not-found",
+					status: 404
+				};
+			}
+			throw new Error(`Codecov could not be asked about ${describeTarget(this.target)}: ${String(err)}`, { cause: err });
+		}
+	}
+};
+// src/probes/token/parse-token-args.ts
+/** Reads `--layer <word>` and `--token-name <VAR>` (either spelling) from the words after the probe name. */
+function parseTokenArgs(args) {
+	let layer;
+	let tokenName;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--layer") layer = args[++i];
+		else if (arg.startsWith("--layer=")) layer = arg.slice(8);
+		else if (arg === "--token-name") tokenName = args[++i];
+		else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
+	}
+	return {
+		...layer ? { layer } : {},
+		...tokenName ? { tokenName } : {}
+	};
+}
+// src/probes/token/token.ts
+/**
+* The `token` probe for Codecov. Codecov has no permission model, so the probe cannot judge permissions; it checks what
+* can be proved. It reads the repository once from Codecov's REST API with the token (`coverage.checkToken()`):
+*
+* - **accepted** (200): Codecov answered for the repository with this token. For a public repository that proves little,
+*   because the API answers without a token, and the row says so.
+* - **refused** (401, 403): `info`, never `fail`. The repository upload token (`measure:bundle`'s) is not a credential
+*   the REST API takes, and a revoked API token answers the same, so Codecov cannot tell this probe which it is.
+* - **not found** (404): `info`. No such repository on Codecov, or the token cannot see it.
+* - anything else (the network, a 5xx): `fail`, because that says nothing about access.
+*
+* With `--layer` (the CLI passes it when `--environment` named a layer) it also says whether that layer is one that
+* should hold the token, against the plugin's `tokens` declaration. It never prints the token.
+*/
+function tokenProbe(ctx) {
+	return {
+		summary: "Ask Codecov's REST API for the repository with a token, and for a layer check that it is one that should hold the token. Codecov reports no permissions, and an upload token cannot be checked this way. Read-only.",
+		writes: false,
+		acceptsToken: true,
+		async run(probe) {
+			probe.secret(ctx.token());
+			probe.say({
+				status: "ok",
+				label: "token",
+				detail: "set"
+			});
+			const { layer, tokenName } = parseTokenArgs(probe.args ?? []);
+			if (layer) {
+				const declared = tokenExpectations(tokens, {
+					layer,
+					...tokenName ? { envName: tokenName } : {}
+				}).length > 0;
+				probe.say(declared ? {
+					status: "ok",
+					label: layer,
+					detail: "a layer that should hold this token"
+				} : {
+					status: "info",
+					label: layer,
+					detail: "not a layer this token is declared for, so it is only described"
+				});
+			}
+			if (!ctx.repo) probe.say({
+				status: "info",
+				label: "repository",
+				detail: "none to ask Codecov about: set the plugin options owner and repo"
+			});
+			else try {
+				const found = await ctx.coverage().checkToken();
+				if (found.outcome === "accepted") {
+					probe.say({
+						status: "ok",
+						label: "Codecov API",
+						detail: `answered for ${ctx.repo} with this token`
+					});
+					if (found.repoPrivate === false) probe.say({
+						status: "info",
+						label: "public repository",
+						detail: "Codecov answers a public repository without a token, so this does not prove the token"
+					});
+				} else if (found.outcome === "refused") probe.say({
+					status: "info",
+					label: "Codecov API",
+					detail: `answered ${found.status} for ${ctx.repo}. A repository upload token is not one the REST API takes, so this cannot be checked for it; a revoked or wrong API token answers the same`
+				});
+				else probe.say({
+					status: "info",
+					label: "repository",
+					detail: `Codecov has no ${ctx.repo}, or the token cannot see it (404)`
+				});
+			} catch (err) {
+				probe.say({
+					status: "fail",
+					label: "Codecov API",
+					detail: err instanceof Error ? err.message : String(err)
+				});
+			}
+			probe.say({
+				status: "info",
+				label: "permissions",
+				detail: "Codecov has no permission model and reports none, so they are not checked"
+			});
+		}
+	};
+}
+// src/index.ts
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
+function createContext(options = {}) {
+	let client;
+	return {
+		options,
+		client: () => client ??= createCodecovClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
+	};
+}
+/** Builds the `coverage` capability from a plugin context. */
+function coverage(ctx) {
+	return new CodecovCoverage(ctx.client, resolveTarget(ctx.options));
+}
+/** Creates the Codecov plugin: its `connection` and `token` probes and the `coverage` capability. */
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	const target = resolveTarget(options);
+	return {
+		name: "@theholocron/holocron-plugin-codecov",
+		probes: {
+			connection: connectionProbe({
+				provider: "Codecov",
+				token: () => resolveToken(options),
+				verify: async () => ({
+					ok: true,
+					subject: "a token is set (see `probe codecov token` for what can be checked)"
+				})
+			}),
+			token: tokenProbe({
+				token: () => resolveToken(options),
+				coverage: () => coverage(ctx),
+				repo: target ? describeTarget(target) : void 0
+			})
+		},
+		capabilities: { coverage: () => coverage(ctx) }
+	};
+}
+export { AuthError, CodecovCoverage, coverage, createCodecovClient, createContext, createPlugin, resolveTarget, resolveToken, tokens };

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@theholocron/holocron-plugin-codecov",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "5.0.0-alpha.445",
+  "description": "Holocron plugin for Codecov. Implements the coverage capability against Codecov's REST API: checks that the service accepts a token for the repository.",
+  "keywords": [
+    "codecov",
+    "coverage",
+    "holocron",
+    "plugin"
+  ],
+  "homepage": "https://docs.theholocron.dev/holocron/plugins/codecov/",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "plugins/holocron-plugin-codecov"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^5.1.0",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.5",
+    "typescript": "^5.9.3",
+    "vitest": "^5.1.0",
+    "@theholocron/eslint-config": "^8.9.0-alpha.17",
+    "@theholocron/codecov-client": "^1.58.0-alpha.32",
+    "@theholocron/http-client": "^1.58.0-alpha.32",
+    "@theholocron/tsconfig": "^8.9.0-alpha.17",
+    "@theholocron/cli": "5.0.0-alpha.445",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.17",
+    "@theholocron/vitest-config": "^8.9.0-alpha.17"
+  },
+  "peerDependencies": {
+    "@theholocron/codecov-client": "^1.58.0",
+    "@theholocron/cli": "5.0.0-alpha.445"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.