workspace-conformance 1.3.0 → 1.5.0

package/dist/index.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { dirname, extname, join, posix, relative, resolve, sep } from "node:path";
 import { escapePath, glob, isDynamicPattern } from "tinyglobby";
-import { ModuleKind, ModuleResolutionKind, Node, Project, ScriptTarget, ts } from "ts-morph";
+import { ModuleKind, ModuleResolutionKind, Node, Project, ScriptTarget, SyntaxKind, ts } from "ts-morph";
 import { createJitiLoader, validateStandard } from "cosmiconfig-extends";
 import { readFile, realpath } from "node:fs/promises";
 import { LineCounter, isMap, isNode, isScalar, isSeq, parse, parseDocument } from "yaml";
@@ -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,123 @@ 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.
+*/
+function lastIdentifier(reference) {
+	if (Node.isQualifiedName(reference)) return reference.getRight();
+	if (Node.isPropertyAccessExpression(reference)) return reference.getNameNode();
+	return reference;
+}
+/**
+* The declarations the identifier refers to, through any imports and re-exports.
+*/
+function declarationsOf(identifier) {
+	const symbol = identifier.getSymbol();
+	return (symbol?.getAliasedSymbol() ?? symbol)?.getDeclarations() ?? [];
+}
+/**
+* The names a reference goes by: the last name as written, and the name it was declared with when that differs, as for `Infer` in `import type { infer as Infer } from 'zod'`, which is also `infer`. A library may itself re-export a generic under another name, so both count.
+*/
+function referenceNames(reference) {
+	const identifier = lastIdentifier(reference);
+	const symbol = identifier.getSymbol();
+	const declared = (symbol?.getAliasedSymbol() ?? symbol)?.getName();
+	return declared === void 0 ? [identifier.getText()] : [.../* @__PURE__ */ new Set([identifier.getText(), declared])];
+}
+//#endregion
 //#region src/checks/command-types.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`.
@@ -229,20 +363,10 @@ const DEFAULT_INFERENCES = [
 */
 const STANDARD_SCHEMA_MEMBER = "~standard";
 /**
-* The names a type reference goes by: the last name as written, and the name it was declared with when that differs, as for `Infer` in `import type { infer as Infer } from 'zod'`, which is also `infer`. A library may itself re-export a generic under another name, so both count.
-*/
-function namesOf(typeName) {
-	const identifier = Node.isQualifiedName(typeName) ? typeName.getRight() : typeName;
-	const symbol = identifier.getSymbol();
-	const declared = (symbol?.getAliasedSymbol() ?? symbol)?.getName();
-	return declared === void 0 ? [identifier.getText()] : [.../* @__PURE__ */ new Set([identifier.getText(), declared])];
-}
-/**
 * The local alias without type parameters that a type reference names, or `undefined` when it names anything else. Such an alias is a name for the type it is written as, so it is judged by that.
 */
 function aliasNamed(typeName) {
-	const symbol = typeName.getSymbol();
-	const declaration = (symbol?.getAliasedSymbol() ?? symbol)?.getDeclarations().find(Node.isTypeAliasDeclaration);
+	const declaration = declarationsOf(lastIdentifier(typeName)).find(Node.isTypeAliasDeclaration);
 	return declaration?.getTypeParameters().length === 0 ? declaration : void 0;
 }
 /**
@@ -255,7 +379,7 @@ function problem$1(declaration, name, inferences, followed = /* @__PURE__ */ new
 	};
 	const written = declaration.getTypeNode();
 	if (Node.isTypeReference(written)) {
-		const inference = namesOf(written.getTypeName()).find((candidate) => inferences.includes(candidate));
+		const inference = referenceNames(written.getTypeName()).find((candidate) => inferences.includes(candidate));
 		if (inference !== void 0) {
 			const [argument] = written.getTypeArguments();
 			if (argument !== void 0 && Node.isTypeQuery(argument) && argument.getExprName().getType().getProperty(STANDARD_SCHEMA_MEMBER) !== void 0) return;
@@ -451,6 +575,120 @@ const commitTypes = async ({ cwd, options, configFiles }) => {
 	return violations;
 };
 //#endregion
+//#region src/checks/derived-types.ts
+/**
+* The last names that count as inference when the options name none: those of `command-types`, Drizzle's `InferSelectModel` and `InferInsertModel` generics, and the `$inferSelect` and `$inferInsert` members of a Drizzle table, read as `typeof table.$inferSelect`.
+*/
+const DEFAULT_DERIVED_TYPE_INFERENCES = [
+	...DEFAULT_INFERENCES,
+	"InferSelectModel",
+	"InferInsertModel",
+	"$inferSelect",
+	"$inferInsert"
+];
+/**
+* Whether the node names something declared in one of the schema files.
+*/
+function declaredInSchema(name, derivation) {
+	const identifier = Node.isIdentifier(name) ? name : Node.isQualifiedName(name) ? name.getRight() : void 0;
+	return identifier !== void 0 && declarationsOf(identifier).some((declaration) => derivation.schemaFiles.has(relativePosix(derivation.cwd, declaration.getSourceFile().getFilePath())));
+}
+/**
+* The interface or type alias without type parameters a reference names, when it has not been followed yet. Such a declaration is a name for what it is written as, so it is judged by that.
+*/
+function followable(reference, derivation) {
+	const name = Node.isTypeReference(reference) ? reference.getTypeName() : reference.getExpression();
+	if (!Node.isIdentifier(name) && !Node.isQualifiedName(name) && !Node.isPropertyAccessExpression(name)) return;
+	const declaration = declarationsOf(lastIdentifier(name)).find((found) => Node.isTypeAliasDeclaration(found) || Node.isInterfaceDeclaration(found));
+	return declaration?.getTypeParameters().length === 0 && !derivation.followed.has(declaration) ? declaration : void 0;
+}
+function isNullish(node) {
+	return node.getKind() === SyntaxKind.UndefinedKeyword || Node.isLiteralTypeNode(node) && node.getLiteral().getKind() === SyntaxKind.NullKeyword;
+}
+/**
+* Whether a reference is derived: an inference applied to `typeof schema`, an alias or interface that is itself derived, or another generic given a derived type, as `Partial<Order>` is.
+*/
+function derivedReference(reference, derivation) {
+	const name = Node.isTypeReference(reference) ? reference.getTypeName() : reference.getExpression();
+	if ((Node.isIdentifier(name) || Node.isQualifiedName(name) || Node.isPropertyAccessExpression(name)) && referenceNames(name).some((candidate) => derivation.inferences.has(candidate))) {
+		const [argument] = reference.getTypeArguments();
+		return argument !== void 0 && Node.isTypeQuery(argument) && declaredInSchema(argument.getExprName(), derivation);
+	}
+	const declaration = followable(reference, derivation);
+	if (declaration !== void 0) return derivedDeclaration(declaration, {
+		...derivation,
+		followed: /* @__PURE__ */ new Set([...derivation.followed, declaration])
+	});
+	return reference.getTypeArguments().some((argument) => derivedType(argument, derivation));
+}
+/**
+* Whether a type, as written, is derived from a schema. A type literal is written by hand whatever its members are.
+*/
+function derivedType(node, derivation) {
+	if (Node.isTypeReference(node) || Node.isExpressionWithTypeArguments(node)) return derivedReference(node, derivation);
+	if (Node.isTypeQuery(node)) {
+		const name = node.getExprName();
+		return Node.isQualifiedName(name) && referenceNames(name).some((candidate) => derivation.inferences.has(candidate)) && declaredInSchema(name.getLeft(), derivation);
+	}
+	if (Node.isParenthesizedTypeNode(node) || Node.isTypeOperatorTypeNode(node)) return derivedType(node.getTypeNode(), derivation);
+	if (Node.isArrayTypeNode(node)) return derivedType(node.getElementTypeNode(), derivation);
+	if (Node.isIndexedAccessTypeNode(node)) return derivedType(node.getObjectTypeNode(), derivation);
+	if (Node.isIntersectionTypeNode(node)) return node.getTypeNodes().some((member) => derivedType(member, derivation));
+	if (Node.isUnionTypeNode(node)) {
+		const members = node.getTypeNodes().filter((member) => !isNullish(member));
+		return members.length > 0 && members.every((member) => derivedType(member, derivation));
+	}
+	return false;
+}
+/**
+* Whether an interface or type alias is derived: an alias by the type it is written as, an interface by whether it extends a derived type.
+*/
+function derivedDeclaration(declaration, derivation) {
+	if (Node.isInterfaceDeclaration(declaration)) return declaration.getExtends().some((heritage) => derivedReference(heritage, derivation));
+	return derivedType(declaration.getTypeNodeOrThrow(), derivation);
+}
+async function pairViolations(cwd, options, pair, index) {
+	const { project, files } = await createProject(cwd, options.tsConfig, pair.types, {
+		check: "derived-types",
+		files: `pairs.${String(index)}.types`
+	});
+	const schemaFiles = await findFiles(cwd, pair.schemas);
+	if (schemaFiles.length === 0) throw new ConformanceError(`checks.derived-types.pairs.${String(index)}.schemas: no file matches`);
+	const excluded = new Set(options.exclude);
+	const derivation = {
+		inferences: new Set(options.inferences ?? DEFAULT_DERIVED_TYPE_INFERENCES),
+		schemaFiles: new Set(schemaFiles),
+		cwd,
+		followed: /* @__PURE__ */ new Set()
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const violations = [];
+	for (const file of files) for (const [name, declaration] of exportedTypes(project.getSourceFileOrThrow(resolve(cwd, file)))) {
+		if (excluded.has(name) || seen.has(declaration)) continue;
+		seen.add(declaration);
+		if (!derivedDeclaration(declaration, {
+			...derivation,
+			followed: /* @__PURE__ */ new Set([declaration])
+		})) violations.push({
+			code: "derived-types/not-derived",
+			message: `${name} is not derived from a schema in ${pair.schemas.join(", ")}: nothing in its definition applies an inference generic to one`,
+			file: relativePosix(cwd, declaration.getSourceFile().getFilePath()),
+			location: declarationLocation(declaration)
+		});
+	}
+	return violations;
+}
+/**
+* For each pair, every exported interface and type alias of its type files is derived from a schema declared in its schema files: somewhere in its definition an inference (a generic in `inferences`, such as `z.infer` or `InferSelectModel`) is applied to `typeof schema`, or an inference member is read from it (`typeof table.$inferSelect`).
+*
+* The definition is followed through aliases and interfaces without type parameters, in any file, and through the arguments of other generics, intersections, unions whose members are all derived (`null` and `undefined` aside), arrays, type operators and indexed access. A type literal, and a schema passed to a generic that is not an inference, are written by hand.
+*/
+const derivedTypes = async ({ cwd, options }) => {
+	const violations = [];
+	for (const [index, pair] of options.pairs.entries()) violations.push(...await pairViolations(cwd, options, pair, index));
+	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/dockerfile-package-manager.ts
 const DEFAULT_DOCKERFILES = [
 	"**/Dockerfile",
@@ -2940,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 = {
@@ -2972,12 +3214,31 @@ 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),
 		inferences: z.exactOptional(paths),
 		tsConfig: z.exactOptional(path)
 	}))),
+	"derived-types": z.exactOptional(enabled(z.strictObject({
+		pairs: z.array(z.strictObject({
+			schemas: paths,
+			types: paths
+		})).min(1),
+		exclude: z.exactOptional(names),
+		inferences: z.exactOptional(paths),
+		tsConfig: z.exactOptional(path)
+	}))),
 	"import-uphill": z.exactOptional(enabled(importGraph)),
 	"import-rank-skip": z.exactOptional(enabled(importGraph)),
 	"import-cross-slice": z.exactOptional(enabled(importGraph)),
@@ -3219,12 +3480,24 @@ 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",
 		select: (checks) => enabledOptions(checks["command-types"]),
 		check: commandTypes
 	}),
+	"derived-types": plain({
+		name: "derived-types",
+		description: "Every exported type in a file paired with schema files is derived from one of those schemas, not hand-written",
+		select: (checks) => enabledOptions(checks["derived-types"]),
+		check: derivedTypes
+	}),
 	"import-uphill": importCheck({
 		name: "import-uphill",
 		description: "No package imports a package of a higher rank",
@@ -3572,4 +3845,4 @@ function proveExhaustive(input) {
 	}) };
 }
 //#endregion
-export { ConformanceError, DEFAULT_INFERENCES, DEFAULT_WORKFLOWS, EXIT_CODES, ExhaustivenessError, PRESET_COMMIT_TYPES, accessOf, aggregateMappers, checkNames, classifyPackages, commandTypes, commitTypes, conformanceSchema, conformanceSection, createGitHubClient, crossSliceRules, cycleRule, deployTools, 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.3.0",
+  "version": "1.5.0",
   "bin": {
     "workspace-conformance": "./dist/cli.js"
   },