@antelopejs/tooling-configs 0.0.6 → 0.0.7

package/README.md

@@ -222,6 +222,38 @@ The front end is left out of `project` rather than ignored, so a repository that
 `frontend-vue/` analysed can add it under Knip's `workspaces` without the preset
 overriding the choice.
 
+## Interface ranges
+
+`@antelopejs/core` keeps one copy of each `@antelopejs/interface-*` package at startup, the
+one its implementing module installed, and refuses to start when a loaded module declares a
+range that copy falls outside. An exact pin (`0.1.7`) or a 0.x caret (`^0.1.2` stops at
+`0.2.0`) therefore breaks a module's startup at the next interface release, with no change to
+the module.
+
+`antelopejs-check-interface-ranges` fails on such a range in `dependencies` or
+`optionalDependencies`, in every `package.json` git tracks in the repository (playgrounds and
+front-end layers included), whatever directory it runs from:
+
+| The package…                                      | must declare                                 |
+| ------------------------------------------------- | -------------------------------------------- |
+| consumes the interface                            | `>=<floor> <1.0.0` (`<next major>` from 1.0) |
+| implements it (listed in `antelopeJs.implements`) | `>=<floor> <0.<minor + 1>.0` while it is 0.x |
+
+An implementer is the opposite case on purpose: it must never be handed a breaking minor it
+does not implement. When the implemented interface sits in the same repository, its version is
+the floor to use. `workspace:`, `file:` and `link:` specs are left alone.
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "lint": "oxlint && antelopejs-check-interface-ranges",
+  },
+}
+```
+
+Pass paths to check only those manifests.
+
 ## Vendored anti-slop
 
 `src/oxc/anti-slop/` is a copy of upstream, kept byte-identical so it can be diffed

package/dist/bin/check-interface-ranges.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin/check-interface-ranges.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+//#region src/interface-ranges.ts
+/**
+* At startup `@antelopejs/core` keeps one copy of each interface package, the
+* one its implementing module installed, and refuses to start when any loaded
+* module declares a range that copy falls outside. An exact pin (`0.1.7`) or a
+* 0.x caret (`^0.1.2` means `<0.2.0`) therefore stops a module from starting
+* as soon as the implementer resolves the next interface release, with no
+* change to the module itself.
+*
+* A consumer accepts every release from its floor up to the next breaking one
+* (`>=0.1.7 <1.0.0`). The module that implements an interface is the opposite
+* case: it must never be handed a breaking minor it does not implement, so it
+* caps the range below the next minor (`>=0.3.0 <0.4.0`) while the interface
+* is 0.x.
+*/
+const INTERFACE_PACKAGE_PREFIX = "@antelopejs/interface-";
+const LOCAL_SPEC_PREFIXES = [
+	"workspace:",
+	"file:",
+	"link:"
+];
+const CHECKED_FIELDS = ["dependencies", "optionalDependencies"];
+const BOUNDED_RANGE = /^>=(\d+)\.(\d+)\.(\d+) <(\d+)\.(\d+)\.(\d+)$/;
+const SINGLE_VERSION = /^[\^~=]?v?(\d+)\.(\d+)\.(\d+)$/;
+const formatVersion = ([major, minor, patch]) => `${major}.${minor}.${patch}`;
+const sameVersion = (a, b) => a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+/** The first release a module declaring `floor` must not be handed. */
+function rangeCeiling(floor, role) {
+	const [major, minor] = floor;
+	if (major > 0) return [
+		major + 1,
+		0,
+		0
+	];
+	return role === "implementer" ? [
+		0,
+		minor + 1,
+		0
+	] : [
+		1,
+		0,
+		0
+	];
+}
+function expectedRange(floor, role) {
+	return `>=${formatVersion(floor)} <${formatVersion(rangeCeiling(floor, role))}`;
+}
+function toVersion(match, offset) {
+	return [
+		Number(match[offset]),
+		Number(match[offset + 1]),
+		Number(match[offset + 2])
+	];
+}
+/** The lowest release `spec` accepts, when it is a shape this check reads. */
+function readFloor(spec) {
+	const bounded = BOUNDED_RANGE.exec(spec);
+	if (bounded) return toVersion(bounded, 1);
+	const single = SINGLE_VERSION.exec(spec);
+	return single ? toVersion(single, 1) : void 0;
+}
+function compareVersions(a, b) {
+	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+function isAcceptedRange(spec, role, local) {
+	const bounded = BOUNDED_RANGE.exec(spec);
+	if (!bounded) return false;
+	const floor = toVersion(bounded, 1);
+	const ceiling = toVersion(bounded, 4);
+	if (!sameVersion(ceiling, rangeCeiling(floor, role))) return false;
+	return local === void 0 || compareVersions(local, floor) >= 0 && compareVersions(local, ceiling) < 0;
+}
+function isLocalSpec(spec) {
+	return LOCAL_SPEC_PREFIXES.some((prefix) => spec.startsWith(prefix));
+}
+/**
+* `localVersions` holds the versions of the packages that sit in the same
+* repository. An implemented interface is usually one of them, and its
+* version, rather than the declared floor, decides the minor to stop below.
+*/
+function checkInterfaceRanges(manifest, localVersions = /* @__PURE__ */ new Map()) {
+	const implemented = new Set(manifest.antelopeJs?.implements ?? []);
+	const violations = [];
+	for (const field of CHECKED_FIELDS) for (const [name, spec] of Object.entries(manifest[field] ?? {})) {
+		if (!name.startsWith(INTERFACE_PACKAGE_PREFIX) || isLocalSpec(spec)) continue;
+		const role = implemented.has(name) ? "implementer" : "consumer";
+		const localVersion = localVersions.get(name);
+		const local = role === "implementer" && localVersion !== void 0 ? readFloor(localVersion) : void 0;
+		if (isAcceptedRange(spec, role, local)) continue;
+		const floor = local ?? readFloor(spec);
+		violations.push({
+			field,
+			name,
+			spec,
+			role,
+			expected: floor ? expectedRange(floor, role) : void 0
+		});
+	}
+	return violations;
+}
+function describeViolation(violation) {
+	const { field, name, spec, role, expected } = violation;
+	const fix = expected ? `use "${expected}"` : role === "implementer" ? "declare it as >=<floor> <next minor>" : "declare it as >=<floor> <1.0.0";
+	return `${field}["${name}"] is "${spec}": ${role === "implementer" ? "this package implements it, so it must stop below the next minor" : "it must accept every release up to the next breaking one"}; ${fix}`;
+}
+//#endregion
+//#region src/bin/check-interface-ranges.ts
+function trackedManifests() {
+	const git = (args) => execFileSync("git", args, { encoding: "utf8" }).trim();
+	const root = git(["rev-parse", "--show-toplevel"]);
+	return git([
+		"-C",
+		root,
+		"ls-files",
+		"--",
+		"package.json",
+		"**/package.json"
+	]).split("\n").filter((line) => line.length > 0).map((file) => relative(process.cwd(), join(root, file)));
+}
+function main() {
+	const manifests = (process.argv.length > 2 ? process.argv.slice(2) : trackedManifests()).map((path) => ({
+		path,
+		manifest: JSON.parse(readFileSync(path, "utf8"))
+	}));
+	const localVersions = /* @__PURE__ */ new Map();
+	for (const { manifest } of manifests) if (manifest.name && manifest.version) localVersions.set(manifest.name, manifest.version);
+	let failures = 0;
+	for (const { path, manifest } of manifests) for (const violation of checkInterfaceRanges(manifest, localVersions)) {
+		console.error(`${path}: ${describeViolation(violation)}`);
+		failures += 1;
+	}
+	if (failures > 0) {
+		console.error(`\n${failures} interface range(s) would stop a module from starting at the next interface release.`);
+		return 1;
+	}
+	return 0;
+}
+process.exitCode = main();
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/tooling-configs",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Shared tooling presets for AntelopeJS projects: oxlint (incl. vendored anti-slop) and Knip",
   "keywords": [
     "antelopejs",
@@ -14,6 +14,9 @@
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/tooling-configs.git"
   },
+  "bin": {
+    "antelopejs-check-interface-ranges": "./dist/bin/check-interface-ranges.mjs"
+  },
   "files": [
     "dist"
   ],
@@ -37,7 +40,7 @@
     "prepack": "pnpm run build",
     "release": "pnpm run lint && pnpm run prepack && release-it",
     "typecheck": "tsc --noEmit",
-    "test": "node --test \"src/oxc/anti-slop/rules/*.test.ts\"",
+    "test": "node --test \"src/oxc/anti-slop/rules/*.test.ts\" \"src/*.test.ts\"",
     "checks": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm run test",
     "format:check": "oxfmt --check ."
   },