workspace-conformance 1.4.0 → 1.6.0

package/dist/index.cjs

@@ -100,6 +100,23 @@ function expandTemplate(template, values) {
 		return value;
 	});
 }
+const NAME_PLACEHOLDER = "{name}";
+/**
+* What a name template must be, as a configuration error says it. It does not quote the template, as no configuration error quotes a value.
+*/
+const NAME_TEMPLATE_REQUIREMENT = "needs {name} exactly once, other text beside it and no other placeholder";
+const ANY_PLACEHOLDER = /\{[a-z]+\}/u;
+/**
+* `template` split at `{name}`, or `undefined` unless it holds `{name}` exactly once, other text beside it and no other placeholder. Without other text every name would match, and with `{name}` twice a name could be split more than one way.
+*/
+function parseNameTemplate(template) {
+	const [before, after, ...rest] = template.split(NAME_PLACEHOLDER);
+	if (before === void 0 || after === void 0 || rest.length > 0 || before + after === "" || ANY_PLACEHOLDER.test(before + after)) return;
+	return {
+		before,
+		after
+	};
+}
 //#endregion
 //#region src/ts-project.ts
 /**
@@ -213,6 +230,97 @@ const aggregateMappers = async ({ cwd, options }) => {
 	return violations.sort((a, b) => a.file.localeCompare(b.file) || (a.location?.line ?? 0) - (b.location?.line ?? 0) || a.message.localeCompare(b.message));
 };
 //#endregion
+//#region src/checks/codec-pairs.ts
+function collect(container, prefix, found, entered) {
+	for (const [name, declarations] of container.getExportedDeclarations()) {
+		const value = declarations.find((declaration) => !ts_morph.Node.isInterfaceDeclaration(declaration) && !ts_morph.Node.isTypeAliasDeclaration(declaration) && !ts_morph.Node.isModuleDeclaration(declaration) && !ts_morph.Node.isSourceFile(declaration));
+		if (value !== void 0) found.set(`${prefix}${name}`, value);
+		for (const member of declarations) if (ts_morph.Node.isModuleDeclaration(member)) collect(member, `${prefix}${name}.`, found, entered);
+		else if (ts_morph.Node.isSourceFile(member) && !entered.has(member)) collect(member, `${prefix}${name}.`, found, /* @__PURE__ */ new Set([...entered, member]));
+	}
+}
+/**
+* The values `file` exports, by name, wherever they are declared: a re-export counts. Those inside an exported namespace, or in a module re-exported as a namespace (`export * as ns from './x'`), are included under their qualified name (`Namespace.value`). Interfaces and type aliases are types, not codecs, and a namespace is where codecs live rather than one itself, so all three are left out.
+*/
+function exportedValues(file) {
+	const found = /* @__PURE__ */ new Map();
+	collect(file, "", found, /* @__PURE__ */ new Set([file]));
+	return found;
+}
+/**
+* Where the declaration's name is written, or where the declaration starts when it has no name node.
+*/
+function valueLocation(declaration) {
+	const nameNode = ts_morph.Node.hasName(declaration) ? declaration.getNameNode() : void 0;
+	const { line, column } = declaration.getSourceFile().getLineAndColumnAtPos((nameNode ?? declaration).getStart());
+	return {
+		line,
+		column
+	};
+}
+/**
+* The template of an option, which the configuration has already validated; a template that does not parse is a configuration error naming the option.
+*/
+function templateOf(options, option) {
+	const template = parseNameTemplate(options[option]);
+	if (template === void 0) throw new ConformanceError(`checks.codec-pairs.${option}: ${NAME_TEMPLATE_REQUIREMENT}`);
+	return template;
+}
+/**
+* The shared name a qualified export name gives under `template`, or `undefined` when its last segment does not fit the template. The namespace part is kept apart so a counterpart is looked for in the same namespace.
+*/
+function sharedName(qualified, template) {
+	const namespace = qualified.slice(0, qualified.lastIndexOf(".") + 1);
+	const local = qualified.slice(namespace.length);
+	if (local.length <= template.before.length + template.after.length || !local.startsWith(template.before) || !local.endsWith(template.after)) return;
+	return {
+		namespace,
+		name: local.slice(template.before.length, local.length - template.after.length)
+	};
+}
+/**
+* Every encoder a codec file exports has the decoder its name implies, exported by the same file, and every decoder the encoder. A name is an encoder or a decoder when it fits that template; other exports are not codecs and are not judged. A half re-exported from another file counts, and is reported where it is declared.
+*
+* It checks that the counterpart is exported, not that the two round-trip: that is a property test of the repository's own.
+*/
+const codecPairs = async ({ cwd, options }) => {
+	const { project, files } = await createProject(cwd, options.tsConfig, options.codecs, {
+		check: "codec-pairs",
+		files: "codecs"
+	});
+	const excluded = new Set(options.exclude);
+	const encoder = templateOf(options, "encoder");
+	const decoder = templateOf(options, "decoder");
+	const halves = [{
+		template: encoder,
+		counterpart: decoder,
+		missing: "decoder"
+	}, {
+		template: decoder,
+		counterpart: encoder,
+		missing: "encoder"
+	}];
+	const violations = [];
+	for (const file of files) {
+		const values = exportedValues(project.getSourceFileOrThrow((0, node_path.resolve)(cwd, file)));
+		for (const [qualified, declaration] of values) {
+			if (excluded.has(qualified)) continue;
+			for (const { template, counterpart, missing } of halves) {
+				const shared = sharedName(qualified, template);
+				if (shared === void 0) continue;
+				const expected = `${shared.namespace}${counterpart.before}${shared.name}${counterpart.after}`;
+				if (!values.has(expected)) violations.push({
+					code: `codec-pairs/missing-${missing}`,
+					message: `${qualified} has no ${missing}: ${file} does not export ${expected}`,
+					file: relativePosix(cwd, declaration.getSourceFile().getFilePath()),
+					location: valueLocation(declaration)
+				});
+			}
+		}
+	}
+	return violations.sort((a, b) => a.file.localeCompare(b.file) || (a.location?.line ?? 0) - (b.location?.line ?? 0) || a.message.localeCompare(b.message));
+};
+//#endregion
 //#region src/checks/type-references.ts
 /**
 * The identifier a reference ends in: `infer` in `z.infer`, the name itself when it is not qualified.
@@ -2020,6 +2128,9 @@ function runsOnOf(reader, value, what) {
 		group
 	};
 }
+function environmentOf(reader, value, what) {
+	return isRecord(value) ? reader.text(value["name"], `${what}.name`) : reader.text(value, what);
+}
 function stepOf(reader, value, jobPath, index) {
 	const path = [
 		...jobPath,
@@ -2052,6 +2163,7 @@ function jobOf(reader, id, value) {
 		needs: reader.list(job["needs"], `${what}.needs`),
 		condition: reader.text(job["if"], `${what}.if`),
 		permissions: permissionsOf(reader, job["permissions"], `${what}.permissions`),
+		environment: environmentOf(reader, job["environment"], `${what}.environment`),
 		env: reader.texts(job["env"], `${what}.env`),
 		runsOn: runsOnOf(reader, job["runs-on"], `${what}.runs-on`),
 		timeoutMinutes: reader.text(job["timeout-minutes"], `${what}.timeout-minutes`),
@@ -2087,6 +2199,7 @@ function parseWorkflow(file, source) {
 		triggers,
 		triggerLocations: triggerLocationsOf(reader, triggers, root["on"]),
 		permissions: permissionsOf(reader, root["permissions"], "permissions"),
+		permissionsLocation: root["permissions"] === void 0 ? void 0 : reader.location(["permissions"]),
 		env: reader.texts(root["env"], "env"),
 		jobs: Object.entries(reader.record(root["jobs"], "jobs")).map(([id, job]) => jobOf(reader, id, job)),
 		callOutputs: Object.fromEntries(Object.entries(outputs).map(([name, output]) => [name, reader.text(reader.record(output, `on.workflow_call.outputs.${name}`)["value"], `on.workflow_call.outputs.${name}.value`) ?? ""]))
@@ -2265,6 +2378,14 @@ function callsAlways(condition) {
 * The default ids of junction jobs, shared by the checks that look for one.
 */
 const DEFAULT_JUNCTION_JOBS = ["required-checks"];
+/**
+* The default ids of release jobs, shared by the checks that look for one.
+*/
+const DEFAULT_RELEASE_JOBS = ["release"];
+/**
+* The variables a token for the npm registry is passed in.
+*/
+const REGISTRY_TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 //#endregion
 //#region src/checks/settings-required-checks.ts
 /**
@@ -2415,10 +2536,6 @@ const PACKAGE_MANAGER_OPTIONS = String.raw`(?:\s+(?:(?:--filter|-F|--workspace|-
 * Commands that publish a package to a registry.
 */
 const PUBLISH_COMMAND = new RegExp(String.raw`^(?:(?:npm|pnpm|yarn)${PACKAGE_MANAGER_OPTIONS}(?:\s+npm)?\s+publish|(?:(?:pnpm|yarn)(?:\s+exec)?\s+|npx\s+)?(?:semantic-release|changeset\s+publish|lerna\s+publish))(?:\s|$)`, "u");
-/**
-* The variables a token for the registry is passed in.
-*/
-const TOKEN_VARIABLES = ["NODE_AUTH_TOKEN", "NPM_TOKEN"];
 const PROVENANCE_FLAG = /--provenance(?:=true)?(?:\s|$)/u;
 /**
 * Whether the `package.json` in the working directory asks for provenance with `publishConfig.provenance: true`, which applies to every publish of that package.
@@ -2442,7 +2559,7 @@ function attestationViolations(workflow, job) {
 * Whether the job passes a registry token to a step, which makes its publish not tokenless: a token variable with a value other than the empty string, anywhere in the environment.
 */
 function passesToken(workflow, job) {
-	return [void 0, ...job.steps].some((step) => TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
+	return [void 0, ...job.steps].some((step) => REGISTRY_TOKEN_VARIABLES.some((variable) => (effectiveEnv(workflow, job, step)[variable] ?? "") !== ""));
 }
 function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 	if (accessOf(effectivePermissions(workflow, job), "id-token") !== "write" || passesToken(workflow, job)) return [];
@@ -2450,9 +2567,9 @@ function tokenlessPublishViolations(workflow, job, provenanceInManifest) {
 		const publishes = scriptCommands(step.run).filter((line) => PUBLISH_COMMAND.test(line));
 		if (publishes.length === 0) return [];
 		const env = effectiveEnv(workflow, job, step);
-		const blanked = TOKEN_VARIABLES.every((variable) => env[variable] === "");
+		const blanked = REGISTRY_TOKEN_VARIABLES.every((variable) => env[variable] === "");
 		const provenance = provenanceInManifest || publishes.some((line) => PROVENANCE_FLAG.test(line)) || env["NPM_CONFIG_PROVENANCE"] === "true";
-		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
+		return blanked || provenance ? [] : [workflowViolation(workflow, "workflow-credentials/tokenless-publish-unprotected", `job '${job.id}' publishes with an OIDC identity and no token, but does not set ${REGISTRY_TOKEN_VARIABLES.join(" and ")} to the empty string, so a token inherited from the environment is used when the OIDC exchange fails; set them to the empty string to prevent that, or request provenance so that such a publish at least carries a traceable attestation`, step.location)];
 	});
 }
 /**
@@ -2470,7 +2587,6 @@ const workflowCredentials = async ({ cwd, options }) => {
 };
 //#endregion
 //#region src/checks/workflow-job-ordering.ts
-const DEFAULT_RELEASE_JOBS = ["release"];
 const DEFAULT_DEPLOY_JOBS = ["deploy"];
 const DEFAULT_DOCS_DEPLOY_JOBS = ["docs-deploy"];
 const DEFAULT_BRANCH = "main";
@@ -2618,6 +2734,71 @@ const workflowMergeGroup = async ({ cwd, options }) => (await loadWorkflows(cwd,
 	return location === void 0 || workflow.triggers.has("merge_group") ? [] : [workflowViolation(workflow, "workflow-merge-group/missing-trigger", "the workflow runs for pull requests but has no merge_group trigger, so its checks do not report for a pull request in the merge queue", location)];
 });
 //#endregion
+//#region src/checks/workflow-release-job.ts
+const CHECKOUT_ACTION$1 = "actions/checkout";
+/**
+* A value that reads the `secrets` context inside an expression.
+*/
+const FROM_SECRET = /\$\{\{[^}]*\bsecrets\./u;
+/**
+* The release jobs named for a message: `release job 'a'` or `release jobs 'a' and 'b'`.
+*/
+function releaseJobsText(releases) {
+	const ids = releases.map((job) => `'${job.id}'`);
+	return `release job${ids.length === 1 ? "" : "s"} ${ids.join(" and ")}`;
+}
+function grantsIdToken(permissions) {
+	return accessOf(permissions, "id-token") === "write";
+}
+function idTokenViolations(workflow, releases) {
+	const releaseIds = new Set(releases.map((job) => job.id));
+	const named = releaseJobsText(releases);
+	const workflowLevel = grantsIdToken(workflow.permissions) && workflow.permissionsLocation !== void 0 ? [workflowViolation(workflow, "workflow-release-job/id-token-workflow-level", `the workflow's permissions grant id-token: write to every job that declares none of its own; grant it on ${named} only`, workflow.permissionsLocation)] : [];
+	const jobLevel = workflow.jobs.filter((job) => !releaseIds.has(job.id) && grantsIdToken(job.permissions)).map((job) => workflowViolation(workflow, "workflow-release-job/id-token-outside-release", `job '${job.id}' is granted id-token: write but is not a release job, so it can mint the OIDC identity npm trusted publishing accepts for this workflow; only ${named} may hold it`, job.location));
+	return [...workflowLevel, ...jobLevel];
+}
+/**
+* What a checkout that does not set `persist-credentials: false` leaves in git config.
+*/
+function persistedCredential(step) {
+	if (step.with["ssh-key"] !== void 0) return "the SSH key";
+	return step.with["token"] === void 0 ? "the job token" : "the token it was given";
+}
+function releaseJobViolations(workflow, job) {
+	if (job.uses !== void 0) return [];
+	const environment = job.environment === void 0 ? [workflowViolation(workflow, "workflow-release-job/missing-environment", `release job '${job.id}' declares no environment, so nothing outside the workflow file stops a branch's copy of it publishing; run it in a protected environment restricted to the default branch`, job.location)] : [];
+	const checkouts = job.steps.filter((step) => stepUses(step, CHECKOUT_ACTION$1) && step.with["persist-credentials"] !== "false").map((step) => workflowViolation(workflow, "workflow-release-job/persisted-credentials", `release job '${job.id}' checks out without persist-credentials: false, which leaves ${persistedCredential(step)} in git config for every later step`, step.location));
+	return [...environment, ...checkouts];
+}
+/**
+* The token variables an environment sets from a secret.
+*/
+function secretTokens(env) {
+	return REGISTRY_TOKEN_VARIABLES.filter((variable) => FROM_SECRET.test(env[variable] ?? ""));
+}
+function tokenBesideOidcViolations(workflow, job) {
+	if (!grantsIdToken(effectivePermissions(workflow, job))) return [];
+	const report = (variables, location) => variables.length === 0 ? [] : [workflowViolation(workflow, "workflow-release-job/token-beside-oidc", `job '${job.id}' holds id-token: write and passes ${variables.join(" and ")} from a secret, a long-lived npm token beside the OIDC identity; publish through trusted publishing and blank the token variables`, location)];
+	return [...report(secretTokens(effectiveEnv(workflow, job, void 0)), job.location), ...job.steps.flatMap((step) => report(secretTokens(step.env), step.location))];
+}
+/**
+* npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+*
+* In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+*
+* In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+*
+* Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+*/
+const workflowReleaseJob = async ({ cwd, options }) => {
+	return (await loadWorkflows(cwd, options)).flatMap((workflow) => {
+		const releases = jobsNamed(workflow, options.releaseJobs ?? DEFAULT_RELEASE_JOBS);
+		const releaseFindings = releases.length === 0 ? [] : idTokenViolations(workflow, releases);
+		const jobFindings = workflow.jobs.flatMap((job) => [...releases.includes(job) ? releaseJobViolations(workflow, job) : [], ...tokenBesideOidcViolations(workflow, job)]);
+		return [...releaseFindings, ...jobFindings];
+	});
+};
+//#endregion
 //#region src/checks/workflow-repository-dispatch.ts
 const DEFAULT_BRANCHES = ["main", "master"];
 const DEFAULT_BRANCH_EXPRESSION = /\$\{\{\s*github\.event\.repository\.default_branch\s*\}\}/u;
@@ -3071,6 +3252,10 @@ function compiles(source) {
 */
 const pattern = zod.z.string().min(1).refine(compiles, "not a valid regular expression");
 const patterns = zod.z.array(pattern);
+/**
+* A name template of `codec-pairs`.
+*/
+const nameTemplate = zod.z.string().refine((template) => parseNameTemplate(template) !== void 0, NAME_TEMPLATE_REQUIREMENT);
 const severity = zod.z.enum(["warn", "error"]);
 const requiredRules = zod.z.record(zod.z.string().min(1), severity);
 const selection = {
@@ -3103,6 +3288,16 @@ const checks = zod.z.strictObject({
 		exclude: zod.z.exactOptional(names),
 		tsConfig: zod.z.exactOptional(path)
 	}))),
+	"codec-pairs": zod.z.exactOptional(enabled(zod.z.strictObject({
+		codecs: paths,
+		encoder: nameTemplate,
+		decoder: nameTemplate,
+		exclude: zod.z.exactOptional(names),
+		tsConfig: zod.z.exactOptional(path)
+	}).refine((options) => options.encoder !== options.decoder, {
+		path: ["decoder"],
+		message: "the decoder template is the encoder template, so every name would be its own pair"
+	}))),
 	"command-types": zod.z.exactOptional(enabled(zod.z.strictObject({
 		commands: paths,
 		exclude: zod.z.exactOptional(names),
@@ -3180,6 +3375,10 @@ const checks = zod.z.strictObject({
 	}))),
 	"workflow-version-single-source": zod.z.exactOptional(enabled(zod.z.strictObject(selection))),
 	"workflow-credentials": zod.z.exactOptional(enabled(zod.z.strictObject(selection))),
+	"workflow-release-job": zod.z.exactOptional(enabled(zod.z.strictObject({
+		...selection,
+		releaseJobs: zod.z.exactOptional(names)
+	}))),
 	"workflow-repository-dispatch": zod.z.exactOptional(enabled(zod.z.strictObject({
 		...selection,
 		defaultBranches: zod.z.exactOptional(names),
@@ -3359,6 +3558,12 @@ const registry = {
 		select: (checks) => enabledOptions(checks["aggregate-mappers"]),
 		check: aggregateMappers
 	}),
+	"codec-pairs": plain({
+		name: "codec-pairs",
+		description: "Every exported encoder in a codec file has a decoder under the naming templates, and every decoder an encoder",
+		select: (checks) => enabledOptions(checks["codec-pairs"]),
+		check: codecPairs
+	}),
 	"command-types": plain({
 		name: "command-types",
 		description: "Every exported command type is derived from a schema, not hand-written",
@@ -3467,6 +3672,12 @@ const registry = {
 		select: (checks) => enabledOptions(checks["workflow-credentials"]),
 		check: workflowCredentials
 	}),
+	"workflow-release-job": plain({
+		name: "workflow-release-job",
+		description: "The release job alone holds id-token, runs in an environment and persists no credentials, and no job with id-token passes an npm token secret",
+		select: (checks) => enabledOptions(checks["workflow-release-job"]),
+		check: workflowReleaseJob
+	}),
 	"workflow-repository-dispatch": plain({
 		name: "workflow-repository-dispatch",
 		description: "A repository_dispatch handler does not push to the default branch, auto-merge unguarded, or rely on the default token",
@@ -3729,6 +3940,7 @@ exports.accessOf = accessOf;
 exports.aggregateMappers = aggregateMappers;
 exports.checkNames = checkNames;
 exports.classifyPackages = classifyPackages;
+exports.codecPairs = codecPairs;
 exports.commandTypes = commandTypes;
 exports.commitTypes = commitTypes;
 exports.conformanceSchema = conformanceSchema;
@@ -3773,6 +3985,7 @@ exports.workflowActionPinning = workflowActionPinning;
 exports.workflowCredentials = workflowCredentials;
 exports.workflowJobOrdering = workflowJobOrdering;
 exports.workflowMergeGroup = workflowMergeGroup;
+exports.workflowReleaseJob = workflowReleaseJob;
 exports.workflowRepositoryDispatch = workflowRepositoryDispatch;
 exports.workflowRunnerResolution = workflowRunnerResolution;
 exports.workflowSkippableJobs = workflowSkippableJobs;

package/dist/index.d.cts

@@ -255,6 +255,10 @@ interface Job {
   readonly needs: readonly string[];
   readonly condition: string | undefined;
   readonly permissions: Permissions;
+  /**
+   * The name of the deployment environment the job runs in, written as `environment: <name>` or `environment: { name: <name> }`; `undefined` when it names none.
+   */
+  readonly environment: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly runsOn: RunsOn;
   readonly timeoutMinutes: string | undefined;
@@ -282,6 +286,10 @@ interface Workflow {
    */
   readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
   readonly permissions: Permissions;
+  /**
+   * Where the workflow's `permissions` is written; `undefined` when it declares none.
+   */
+  readonly permissionsLocation: SourceLocation | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly jobs: readonly Job[];
   /**
@@ -376,6 +384,31 @@ interface AggregateMappersOptions {
    */
   readonly tsConfig?: string;
 }
+/**
+ * Options of the `codec-pairs` check: every encoder a codec file exports has a decoder it also exports, and every decoder an encoder.
+ */
+interface CodecPairsOptions {
+  /**
+   * Globs of the codec files, relative to the directory the checks run in. Each file is judged on its own exports, re-exports included.
+   */
+  readonly codecs: readonly string[];
+  /**
+   * The name of an encoder, with `{name}` standing for the name it shares with its decoder, such as `encode{name}` or `{name}Encoder`. `{name}` appears exactly once, beside other text, and is the only placeholder.
+   */
+  readonly encoder: string;
+  /**
+   * The name of a decoder, in the same form as `encoder` and different from it.
+   */
+  readonly decoder: string;
+  /**
+   * Names of exported encoders and decoders that need no counterpart, such as an encoder for a format that is only ever written.
+   */
+  readonly exclude?: readonly string[];
+  /**
+   * The tsconfig that supplies compiler options and module resolution; `tsconfig.json` when omitted.
+   */
+  readonly tsConfig?: string;
+}
 /**
  * Options of the `command-types` check: every command type a file exports is derived from a schema.
  */
@@ -642,6 +675,15 @@ type WorkflowVersionSingleSourceOptions = WorkflowSelection;
  * Options of the `workflow-credentials` check.
  */
 type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-release-job` check: the job that publishes is the only one that can mint the OIDC identity, runs in an environment and leaves no credentials behind.
+ */
+interface WorkflowReleaseJobOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs: the jobs that publish, and the only ones that may hold `id-token: write`. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+}
 /**
  * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
  */
@@ -737,6 +779,7 @@ type SettingsReviewThreadResolutionOptions = SettingsOptions;
  */
 interface CheckOptionsByName {
   readonly "aggregate-mappers": AggregateMappersOptions;
+  readonly "codec-pairs": CodecPairsOptions;
   readonly "command-types": CommandTypesOptions;
   readonly "derived-types": DerivedTypesOptions;
   readonly "import-uphill": ImportGraphOptions;
@@ -755,6 +798,7 @@ interface CheckOptionsByName {
   readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
   readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
   readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-release-job": WorkflowReleaseJobOptions;
   readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
   readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
   readonly "workflow-merge-group": WorkflowMergeGroupOptions;
@@ -776,6 +820,14 @@ type CheckName = keyof CheckOptionsByName;
  */
 export declare const aggregateMappers: CheckFunction<AggregateMappersOptions>;
 //#endregion
+//#region src/checks/codec-pairs.d.ts
+/**
+ * Every encoder a codec file exports has the decoder its name implies, exported by the same file, and every decoder the encoder. A name is an encoder or a decoder when it fits that template; other exports are not codecs and are not judged. A half re-exported from another file counts, and is reported where it is declared.
+ *
+ * It checks that the counterpart is exported, not that the two round-trip: that is a property test of the repository's own.
+ */
+export declare const codecPairs: CheckFunction<CodecPairsOptions>;
+//#endregion
 //#region src/checks/command-types.d.ts
 /**
  * The last names of the generics that turn a schema into its type, used when the options name none: `z.infer`, `z.input`, `z.output`, `z.TypeOf` and Valibot's `InferInput` and `InferOutput`.
@@ -1054,6 +1106,18 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  */
 export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
 //#endregion
+//#region src/checks/workflow-release-job.d.ts
+/**
+ * npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+ *
+ * In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+ *
+ * In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+ *
+ * Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+ */
+export declare const workflowReleaseJob: CheckFunction<WorkflowReleaseJobOptions>;
+//#endregion
 //#region src/checks/workflow-repository-dispatch.d.ts
 /**
  * A workflow that handles `repository_dispatch` can be started by anyone with write access through the API, so what it does with the repository is held to a higher bar.
@@ -1322,4 +1386,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.d.ts

@@ -255,6 +255,10 @@ interface Job {
   readonly needs: readonly string[];
   readonly condition: string | undefined;
   readonly permissions: Permissions;
+  /**
+   * The name of the deployment environment the job runs in, written as `environment: <name>` or `environment: { name: <name> }`; `undefined` when it names none.
+   */
+  readonly environment: string | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly runsOn: RunsOn;
   readonly timeoutMinutes: string | undefined;
@@ -282,6 +286,10 @@ interface Workflow {
    */
   readonly triggerLocations: ReadonlyMap<string, SourceLocation>;
   readonly permissions: Permissions;
+  /**
+   * Where the workflow's `permissions` is written; `undefined` when it declares none.
+   */
+  readonly permissionsLocation: SourceLocation | undefined;
   readonly env: Readonly<Record<string, string>>;
   readonly jobs: readonly Job[];
   /**
@@ -376,6 +384,31 @@ interface AggregateMappersOptions {
    */
   readonly tsConfig?: string;
 }
+/**
+ * Options of the `codec-pairs` check: every encoder a codec file exports has a decoder it also exports, and every decoder an encoder.
+ */
+interface CodecPairsOptions {
+  /**
+   * Globs of the codec files, relative to the directory the checks run in. Each file is judged on its own exports, re-exports included.
+   */
+  readonly codecs: readonly string[];
+  /**
+   * The name of an encoder, with `{name}` standing for the name it shares with its decoder, such as `encode{name}` or `{name}Encoder`. `{name}` appears exactly once, beside other text, and is the only placeholder.
+   */
+  readonly encoder: string;
+  /**
+   * The name of a decoder, in the same form as `encoder` and different from it.
+   */
+  readonly decoder: string;
+  /**
+   * Names of exported encoders and decoders that need no counterpart, such as an encoder for a format that is only ever written.
+   */
+  readonly exclude?: readonly string[];
+  /**
+   * The tsconfig that supplies compiler options and module resolution; `tsconfig.json` when omitted.
+   */
+  readonly tsConfig?: string;
+}
 /**
  * Options of the `command-types` check: every command type a file exports is derived from a schema.
  */
@@ -642,6 +675,15 @@ type WorkflowVersionSingleSourceOptions = WorkflowSelection;
  * Options of the `workflow-credentials` check.
  */
 type WorkflowCredentialsOptions = WorkflowSelection;
+/**
+ * Options of the `workflow-release-job` check: the job that publishes is the only one that can mint the OIDC identity, runs in an environment and leaves no credentials behind.
+ */
+interface WorkflowReleaseJobOptions extends WorkflowSelection {
+  /**
+   * Ids of release jobs: the jobs that publish, and the only ones that may hold `id-token: write`. `release` when omitted.
+   */
+  readonly releaseJobs?: readonly string[];
+}
 /**
  * Options of the `workflow-repository-dispatch` check: what a handler of `repository_dispatch` may do.
  */
@@ -737,6 +779,7 @@ type SettingsReviewThreadResolutionOptions = SettingsOptions;
  */
 interface CheckOptionsByName {
   readonly "aggregate-mappers": AggregateMappersOptions;
+  readonly "codec-pairs": CodecPairsOptions;
   readonly "command-types": CommandTypesOptions;
   readonly "derived-types": DerivedTypesOptions;
   readonly "import-uphill": ImportGraphOptions;
@@ -755,6 +798,7 @@ interface CheckOptionsByName {
   readonly "workflow-runner-resolution": WorkflowRunnerResolutionOptions;
   readonly "workflow-version-single-source": WorkflowVersionSingleSourceOptions;
   readonly "workflow-credentials": WorkflowCredentialsOptions;
+  readonly "workflow-release-job": WorkflowReleaseJobOptions;
   readonly "workflow-repository-dispatch": WorkflowRepositoryDispatchOptions;
   readonly "workflow-update-bot-cooldown": WorkflowUpdateBotCooldownOptions;
   readonly "workflow-merge-group": WorkflowMergeGroupOptions;
@@ -776,6 +820,14 @@ type CheckName = keyof CheckOptionsByName;
  */
 export declare const aggregateMappers: CheckFunction<AggregateMappersOptions>;
 //#endregion
+//#region src/checks/codec-pairs.d.ts
+/**
+ * Every encoder a codec file exports has the decoder its name implies, exported by the same file, and every decoder the encoder. A name is an encoder or a decoder when it fits that template; other exports are not codecs and are not judged. A half re-exported from another file counts, and is reported where it is declared.
+ *
+ * It checks that the counterpart is exported, not that the two round-trip: that is a property test of the repository's own.
+ */
+export declare const codecPairs: CheckFunction<CodecPairsOptions>;
+//#endregion
 //#region src/checks/command-types.d.ts
 /**
  * The last names of the generics that turn a schema into its type, used when the options name none: `z.infer`, `z.input`, `z.output`, `z.TypeOf` and Valibot's `InferInput` and `InferOutput`.
@@ -1054,6 +1106,18 @@ export declare const workflowJobOrdering: CheckFunction<WorkflowJobOrderingOptio
  */
 export declare const workflowMergeGroup: CheckFunction<WorkflowMergeGroupOptions>;
 //#endregion
+//#region src/checks/workflow-release-job.d.ts
+/**
+ * npm binds a trusted publisher to the repository and the workflow file, not to a branch, so anyone who can push a branch can edit that branch's copy of the workflow, drop an `if` that keeps publishing to the default branch, and publish. What stops that has to live outside the file: a protected environment that only the default branch may deploy to, named in npm's trusted publisher too. This check holds the release job to the shape that makes that protection hold.
+ *
+ * In a workflow with a release job (by id, `releaseJobs`, `release` by default): `workflow-release-job/id-token-workflow-level`, the workflow's own `permissions` grant `id-token: write` (directly or through `write-all`), which every job that declares none inherits; `id-token-outside-release`, a job that is not a release job declares `id-token: write` itself, a job that calls a reusable workflow included; `missing-environment`, a release job declares no `environment`; `persisted-credentials`, a release job runs `actions/checkout` without `persist-credentials: false` (literally; an expression is unknown and reported), so the job token, a `token` input or an `ssh-key` stays in git config for every later step. A release job that pushes as a deploy key provisions the key in a step and hands it to git through that step's `GIT_SSH_COMMAND`, after a checkout that persists nothing, and is accepted as written; semantic-release authenticates its own push (`repositoryUrl` as written, else the URL with `GITHUB_TOKEN` or `GH_TOKEN` from the environment), so it needs nothing from the checkout.
+ *
+ * In every workflow: `token-beside-oidc`, a job whose effective permissions grant `id-token: write` sets `NODE_AUTH_TOKEN` or `NPM_TOKEN` from the `secrets` context in its workflow, job or step `env`.
+ *
+ * Limits: the environment's protection rules and npm's trusted publisher settings are not visible in the file and are not read; a release job that calls a reusable workflow is judged only for `id-token`, since `environment` and steps belong to the called workflow; a token passed through `with`, written to an `.npmrc` by a script, or inherited through a composite action is not seen.
+ */
+export declare const workflowReleaseJob: CheckFunction<WorkflowReleaseJobOptions>;
+//#endregion
 //#region src/checks/workflow-repository-dispatch.d.ts
 /**
  * A workflow that handles `repository_dispatch` can be started by anyone with write access through the API, so what it does with the repository is held to a higher bar.
@@ -1322,4 +1386,4 @@ export declare function proveExhaustive(input: {
   readonly compilerOptions?: CompilerOptions;
 }): ExhaustivenessProof;
 //#endregion
-export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };
+export type { AggregateMappersOptions, BranchRules, CaseRemoval, CheckContext, CheckFunction, CheckName, CheckOptionsByName, CheckResult, ChecksConfig, CodecPairsOptions, CommandTypesOptions, CommitTypesOptions, ConformanceConfig, DeployDirectory, DeploySelector, DeployToolAdapter, DeployToolName, DerivedTypesOptions, DerivedTypesPair, DiscoveredPackage, DockerfilePackageManagerOptions, EslintOptions, EslintRequiredSeverity, EslintSample, ExhaustivenessProof, GeneratorAdapter, GeneratorName, GitHubCheckContext, GitHubCheckFunction, GitHubClient, GitHubClientOptions, ImportGraphOptions, InstructionSymlinksOptions, Job, LayoutCheckContext, LayoutCheckFunction, MigrationsDirectoryOptions, PermissionAccess, Permissions, PinningLevel, RegisteredCheck, RepositorySettings, RepositorySlug, RunChecksOptions, RunResult, RunsOn, SettingsMergeMethodsOptions, SettingsOptions, SettingsRequiredChecksOptions, SettingsReviewThreadResolutionOptions, SingleStorybookOptions, SourceLocation, Step, TypeErrorReport, UsesReference, Violation, Workflow, WorkflowActionPinningOptions, WorkflowCredentialsOptions, WorkflowJobOrderingOptions, WorkflowMergeGroupOptions, WorkflowReleaseJobOptions, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };