workspace-conformance 1.4.0 → 1.6.0

package/dist/index.js

@@ -99,6 +99,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
 /**
@@ -212,6 +229,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) => !Node.isInterfaceDeclaration(declaration) && !Node.isTypeAliasDeclaration(declaration) && !Node.isModuleDeclaration(declaration) && !Node.isSourceFile(declaration));
+		if (value !== void 0) found.set(`${prefix}${name}`, value);
+		for (const member of declarations) if (Node.isModuleDeclaration(member)) collect(member, `${prefix}${name}.`, found, entered);
+		else if (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 = 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(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.
@@ -2019,6 +2127,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,
@@ -2051,6 +2162,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`),
@@ -2086,6 +2198,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`) ?? ""]))
@@ -2264,6 +2377,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
 /**
@@ -2414,10 +2535,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.
@@ -2441,7 +2558,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 [];
@@ -2449,9 +2566,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)];
 	});
 }
 /**
@@ -2469,7 +2586,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";
@@ -2617,6 +2733,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;
@@ -3070,6 +3251,10 @@ function compiles(source) {
 */
 const pattern = z.string().min(1).refine(compiles, "not a valid regular expression");
 const patterns = z.array(pattern);
+/**
+* A name template of `codec-pairs`.
+*/
+const nameTemplate = z.string().refine((template) => parseNameTemplate(template) !== void 0, NAME_TEMPLATE_REQUIREMENT);
 const severity = z.enum(["warn", "error"]);
 const requiredRules = z.record(z.string().min(1), severity);
 const selection = {
@@ -3102,6 +3287,16 @@ const checks = z.strictObject({
 		exclude: z.exactOptional(names),
 		tsConfig: z.exactOptional(path)
 	}))),
+	"codec-pairs": z.exactOptional(enabled(z.strictObject({
+		codecs: paths,
+		encoder: nameTemplate,
+		decoder: nameTemplate,
+		exclude: z.exactOptional(names),
+		tsConfig: 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": z.exactOptional(enabled(z.strictObject({
 		commands: paths,
 		exclude: z.exactOptional(names),
@@ -3179,6 +3374,10 @@ const checks = z.strictObject({
 	}))),
 	"workflow-version-single-source": z.exactOptional(enabled(z.strictObject(selection))),
 	"workflow-credentials": z.exactOptional(enabled(z.strictObject(selection))),
+	"workflow-release-job": z.exactOptional(enabled(z.strictObject({
+		...selection,
+		releaseJobs: z.exactOptional(names)
+	}))),
 	"workflow-repository-dispatch": z.exactOptional(enabled(z.strictObject({
 		...selection,
 		defaultBranches: z.exactOptional(names),
@@ -3358,6 +3557,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",
@@ -3466,6 +3671,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",
@@ -3717,4 +3928,4 @@ function proveExhaustive(input) {
 	}) };
 }
 //#endregion
-export { ConformanceError, DEFAULT_DERIVED_TYPE_INFERENCES, DEFAULT_INFERENCES, DEFAULT_WORKFLOWS, EXIT_CODES, ExhaustivenessError, PRESET_COMMIT_TYPES, accessOf, aggregateMappers, checkNames, classifyPackages, commandTypes, commitTypes, conformanceSchema, conformanceSection, createGitHubClient, crossSliceRules, cycleRule, deployTools, derivedTypes, dockerfilePackageManager, effectiveEnv, effectivePermissions, eslint, generators, handlerCases, importCrossSlice, importCycles, importIsolatedGroups, importRankSkip, importUphill, instructionSymlinks, isCheckName, isolatedGroupRules, loadWorkflows, migrationsDirectory, packagesPattern, parseUses, parseWorkflow, proveExhaustive, rankSkipRules, registry, removeCase, runChecks, settingsMergeMethods, settingsRequiredChecks, settingsReviewThreadResolution, singleStorybook, transitiveNeeds, typeErrors, uphillRules, workflowActionPinning, workflowCredentials, workflowJobOrdering, workflowMergeGroup, workflowRepositoryDispatch, workflowRunnerResolution, workflowSkippableJobs, workflowUpdateBotCooldown, workflowVersionSingleSource };
+export { ConformanceError, DEFAULT_DERIVED_TYPE_INFERENCES, DEFAULT_INFERENCES, DEFAULT_WORKFLOWS, EXIT_CODES, ExhaustivenessError, PRESET_COMMIT_TYPES, accessOf, aggregateMappers, checkNames, classifyPackages, codecPairs, commandTypes, commitTypes, conformanceSchema, conformanceSection, createGitHubClient, crossSliceRules, cycleRule, deployTools, derivedTypes, dockerfilePackageManager, effectiveEnv, effectivePermissions, eslint, generators, handlerCases, importCrossSlice, importCycles, importIsolatedGroups, importRankSkip, importUphill, instructionSymlinks, isCheckName, isolatedGroupRules, loadWorkflows, migrationsDirectory, packagesPattern, parseUses, parseWorkflow, proveExhaustive, rankSkipRules, registry, removeCase, runChecks, settingsMergeMethods, settingsRequiredChecks, settingsReviewThreadResolution, singleStorybook, transitiveNeeds, typeErrors, uphillRules, workflowActionPinning, workflowCredentials, workflowJobOrdering, workflowMergeGroup, workflowReleaseJob, workflowRepositoryDispatch, workflowRunnerResolution, workflowSkippableJobs, workflowUpdateBotCooldown, workflowVersionSingleSource };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "workspace-conformance",
   "description": "Conformance checks for a pnpm workspace that ESLint cannot express: type-graph, import-graph and cross-file checks driven by the shared layout section of @exadev/config",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "bin": {
     "workspace-conformance": "./dist/cli.js"
   },