workspace-conformance 1.4.0 → 1.5.0

package/README.md

@@ -117,6 +117,18 @@ The type-graph checks build a ts-morph program from the files their options sele
 
 Codes: `aggregate-mappers/missing-mapper` (reported at the aggregate's declaration), `aggregate-mappers/no-adapters`. Limits: it checks that a file exists, not what is in it; a type re-exported by the contract counts as an aggregate, and a type re-exported under another name (`export type { Created as CreatedAlias }`) counts once for each name it is exported as, each needing a mapper, so helper types and aliases need `exclude`; a type in an exported namespace, or in a module re-exported as a namespace (`export * as ns`), is an aggregate under its qualified name (`ns.Type`, which is also what `{name}` and `exclude` use); a placeholder with no value, a glob that matches no contract and a missing tsconfig are configuration errors, which name the option (`checks.aggregate-mappers.contracts`) and not the value written in it.
 
+**`codec-pairs`** verifies that 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 option's template: with `encoder: 'encode{name}'` and `decoder: 'decode{name}'`, `encodeInvoice` needs `decodeInvoice` and `decodeReceipt` needs `encodeReceipt`. It checks only that both halves exist; that each pair round-trips is a property test (decode after encode gives back the value) and stays the repository's own, since a type graph cannot run code.
+
+| Option | Meaning |
+|---|---|
+| `codecs` | Globs of codec files. Each file is judged on its own exports, re-exports included. |
+| `encoder` | Name template of an encoder, such as `encode{name}` or `{name}Encoder`. `{name}` appears exactly once, beside other text, and is the only placeholder, or the section fails to load. |
+| `decoder` | Name template of a decoder, in the same form and different from `encoder`. |
+| `exclude` | Names of exported encoders and decoders that need no counterpart, such as an encoder for a format that is only ever written. |
+| `tsConfig` | See above. |
+
+Codes: `codec-pairs/missing-decoder` and `codec-pairs/missing-encoder`, each reported at the declaration of the half that exists. An export whose name fits neither template is not a codec and is ignored, not reported, so a codec file may also export its helpers, schemas and types without listing them in `exclude`; `exclude` is for a half that deliberately has no counterpart. Limits: only values count (functions, constants, destructured constants, classes and enums), so an interface or type alias whose name fits a template is ignored; the counterpart is looked up by name among the same file's exports, not by signature, and a value re-exported under another name counts under each name it is exported as; a value in an exported namespace, or in a module re-exported as a namespace (`export * as ns`), is judged under its qualified name (`ns.encodeInvoice`, which is also what `exclude` uses) and pairs only with a counterpart in the same namespace; a glob that matches no codec file and a missing tsconfig are configuration errors.
+
 **`command-types`** verifies that every command type is derived from a schema and not written by hand. An exported alias must apply a generic named in `inferences` (`infer`, `input`, `output`, `TypeOf`, `InferInput` and `InferOutput` by default, the last name of the reference, so `z.infer` and Valibot's `v.InferOutput` both count) to `typeof schema`, where the type of `schema` has the `~standard` member every Standard Schema has. The schema is recognised by type, so it may be imported or renamed and need not come from Zod. The generic may be imported under another name (`import type { infer as Infer }`), and an alias may stand between the export and the inference (`type Base = z.infer<typeof schema>; export type Created = Base;`): a local alias without type parameters is judged by the type it is written as. An alias with type parameters is not followed and is hand-written.
 
 | Option | Meaning |
@@ -294,7 +306,7 @@ it('conforms to the workspace layout', async () => {
 });
 ```
 
-Every check is also exported as a function taking `{ cwd, options }` (and `layout` for the import checks): `aggregateMappers`, `commandTypes`, `derivedTypes`, `importUphill`, `importRankSkip`, `importCrossSlice`, `importIsolatedGroups`, `importCycles`, `instructionSymlinks`, `singleStorybook`, `commitTypes`, `dockerfilePackageManager`, `migrationsDirectory`, `eslint`, the workflow checks (`workflowJobOrdering`, `workflowSkippableJobs`, `workflowRunnerResolution`, `workflowVersionSingleSource`, `workflowCredentials`, `workflowRepositoryDispatch`, `workflowUpdateBotCooldown`, `workflowMergeGroup` and `workflowActionPinning`) and, taking `{ cwd, options, github }`, the settings checks (`settingsMergeMethods`, `settingsRequiredChecks` and `settingsReviewThreadResolution`). These take options and a layout as already validated and do not check them again; go through `runChecks` for validation. `parseWorkflow` and `loadWorkflows` expose the workflow model the workflow checks read. A check is a function that returns `Promise<readonly Violation[]>`, where a `Violation` is `{ code, message, file, location? }`.
+Every check is also exported as a function taking `{ cwd, options }` (and `layout` for the import checks): `aggregateMappers`, `codecPairs`, `commandTypes`, `derivedTypes`, `importUphill`, `importRankSkip`, `importCrossSlice`, `importIsolatedGroups`, `importCycles`, `instructionSymlinks`, `singleStorybook`, `commitTypes`, `dockerfilePackageManager`, `migrationsDirectory`, `eslint`, the workflow checks (`workflowJobOrdering`, `workflowSkippableJobs`, `workflowRunnerResolution`, `workflowVersionSingleSource`, `workflowCredentials`, `workflowRepositoryDispatch`, `workflowUpdateBotCooldown`, `workflowMergeGroup` and `workflowActionPinning`) and, taking `{ cwd, options, github }`, the settings checks (`settingsMergeMethods`, `settingsRequiredChecks` and `settingsReviewThreadResolution`). These take options and a layout as already validated and do not check them again; go through `runChecks` for validation. `parseWorkflow` and `loadWorkflows` expose the workflow model the workflow checks read. A check is a function that returns `Promise<readonly Violation[]>`, where a `Violation` is `{ code, message, file, location? }`.
 
 ### Proving a handler map is exhaustive
 

package/dist/cli.js

@@ -171,6 +171,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
 /**
@@ -284,6 +301,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.
@@ -3158,6 +3266,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",
@@ -3337,6 +3451,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 = {
@@ -3369,6 +3487,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),

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.
@@ -3071,6 +3179,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 +3215,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),
@@ -3359,6 +3481,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",
@@ -3729,6 +3857,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;

package/dist/index.d.cts

@@ -376,6 +376,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.
  */
@@ -737,6 +762,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;
@@ -776,6 +802,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`.
@@ -1322,4 +1356,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, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

package/dist/index.d.ts

@@ -376,6 +376,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.
  */
@@ -737,6 +762,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;
@@ -776,6 +802,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`.
@@ -1322,4 +1356,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, WorkflowRepositoryDispatchOptions, WorkflowRunnerResolutionOptions, WorkflowSelection, WorkflowSkippableJobsOptions, WorkflowUpdateBotCooldownOptions, WorkflowVersionSingleSourceOptions, WorkspacePackage };

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.
@@ -3070,6 +3178,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 +3214,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),
@@ -3358,6 +3480,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",
@@ -3717,4 +3845,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, 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.5.0",
   "bin": {
     "workspace-conformance": "./dist/cli.js"
   },