Initial commit

This commit is contained in:
fraqtal
2026-07-12 08:15:46 +00:00
commit ee0fec0691
1397 changed files with 127242 additions and 0 deletions

View File

@@ -0,0 +1,69 @@
# AGENTS.md — core-eslint
**Tag:** tooling
Shared ESLint 9 flat configs (rules, plugins, parser settings) consumed by all packages via `eslint.config.js`. Enforces boundary rules alongside Turborepo's `boundaries` feature (which validates the workspace dependency graph at build time).
## What it owns
- **`base.js`** — Core ESLint rules: no `console`, no `debugger`, strict `@typescript-eslint` config
- **`next.js`** — Next.js-specific rules: `"use client"` boundaries, `next/no-img-element`
- **`react-internal.js`** — React library rules: component display names, hook rules
- **`boundaries.js`** — `eslint-plugin-boundaries` config enforcing vertical feature architecture:
- Features may only import `core-*` and tooling packages
- Core packages may only import other core packages (with composition exceptions for `core-cms`, `core-api`)
- No cross-feature imports
- No deep source path imports (only public subpath exports)
## How packages consume them
Each package creates `eslint.config.js` at its root:
```javascript
// packages/blog/eslint.config.js
import baseConfig from "@repo/core-eslint/base";
import boundariesConfig from "@repo/core-eslint/boundaries";
export default [
...baseConfig,
...boundariesConfig,
{
files: ["src/**/*.tsx"],
rules: {
"react/display-name": "off",
},
},
];
```
Apps may add Next.js-specific rules:
```javascript
// apps/web-next/eslint.config.js
import baseConfig from "@repo/core-eslint/base";
import nextConfig from "@repo/core-eslint/next";
import boundariesConfig from "@repo/core-eslint/boundaries";
export default [
...baseConfig,
...nextConfig,
...boundariesConfig,
];
```
## Test conventions
- No unit tests (config validation via lint pass/fail in other packages)
- Verify at CI: `pnpm lint` succeeds across all packages
- ESLint should catch boundary violations: `pnpm lint` fails on feature→feature imports or deep imports
## Structure
```
src/
base.js # Core TypeScript + ESLint config
next.js # Next.js additions
react-internal.js # React library rules
boundaries.js # Feature boundaries + composition rules
index.js # Re-exports all configs
```

View File

@@ -0,0 +1,42 @@
import { describe, it, expect } from "vitest";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
const __dirname = dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = join(__dirname, "..", "..");
const FEATURES = ["auth", "blog", "media", "marketing-pages", "navigation"];
const ANCHORS = {
"src/index.ts": ["// <gen:events>", "// <gen:realtime-channels>"],
"src/di/symbols.ts": ["// <gen:event-handler-symbols>", "// <gen:job-symbols>", "// <gen:realtime-handler-symbols>"],
"src/di/bind-production.ts": ["// <gen:event-handlers>", "// <gen:jobs>", "// <gen:realtime-handlers>"],
"src/di/bind-dev-seed.ts": ["// <gen:event-handlers>", "// <gen:jobs>", "// <gen:realtime-handlers>"],
"src/integrations/cms/index.ts": ["// <gen:job-tasks>"],
};
describe("// <gen:*> anchor presence in core-eslint/base.js", () => {
it("base.js contains realtime-rules-imports anchor", () => {
const baseSource = readFileSync(join(REPO_ROOT, "packages/core-eslint/base.js"), "utf8");
expect(baseSource).toContain("// <gen:realtime-rules-imports>");
expect(baseSource).toContain("// <gen:realtime-rules>");
});
it("base.js contains events-rules anchor", () => {
const baseSource = readFileSync(join(REPO_ROOT, "packages/core-eslint/base.js"), "utf8");
expect(baseSource).toContain("// <gen:events-rules>");
});
});
describe("// <gen:*> anchor presence in feature packages", () => {
for (const feature of FEATURES) {
for (const [relPath, anchors] of Object.entries(ANCHORS)) {
it(`packages/${feature}/${relPath} contains all required anchors`, () => {
const path = join(REPO_ROOT, "packages", feature, relPath);
const content = readFileSync(path, "utf8");
for (const anchor of anchors) {
expect(content).toContain(anchor);
}
});
}
}
});

View File

@@ -0,0 +1,195 @@
import js from "@eslint/js";
import eslintConfigPrettier from "eslint-config-prettier";
import tseslint from "typescript-eslint";
import turboPlugin from "eslint-plugin-turbo";
import boundaries from "eslint-plugin-boundaries";
import globals from "globals";
import conformancePlugin from "./plugin.js";
import path from "node:path";
import { fileURLToPath } from "node:url";
// <gen:realtime-rules-imports>
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const repoRoot = path.resolve(__dirname, "..", "..");
export default [
{
ignores: [
"dist/**",
"node_modules/**",
".next/**",
".turbo/**",
"storybook-static/**",
],
},
js.configs.recommended,
{
files: ["**/*.{mjs,cjs,js}", "**/*.config.{ts,tsx}"],
languageOptions: {
globals: { ...globals.node },
},
},
...tseslint.configs.recommended,
eslintConfigPrettier,
{
plugins: { turbo: turboPlugin },
rules: {
"turbo/no-undeclared-env-vars": "warn",
},
},
{
plugins: { conformance: conformancePlugin },
rules: {
// Structural conformance rules (milestone iii.a).
// All 5 features now have manifests; promoted to ERROR.
"conformance/feature-must-have-manifest": ["error", { repoRoot }],
"conformance/usecase-must-have-test-file": "error",
"conformance/required-cores-installed": ["error", { repoRoot }],
"conformance/no-undeclared-event-publish": ["warn", { repoRoot }],
"conformance/no-undeclared-audit": ["warn", { repoRoot }],
"conformance/no-undeclared-analytics-event": ["warn", { repoRoot }],
"conformance/usecase-must-be-wired": ["error", { repoRoot }],
"conformance/component-must-have-story": "warn",
"conformance/component-must-have-test": "warn",
"conformance/atomic-tier-import-direction": "warn",
"conformance/pii-declaration-must-be-complete": "warn",
"conformance/no-undeclared-consent-check": ["warn", { repoRoot }],
"conformance/no-undeclared-rate-limit": ["warn", { repoRoot }],
"conformance/entity-must-have-test": "warn",
"conformance/no-relative-parent-import-in-tests": "warn",
},
},
{
rules: {
// Honour the leading-underscore convention for intentionally-unused params/vars.
"@typescript-eslint/no-unused-vars": [
"error",
{
argsIgnorePattern: "^_",
varsIgnorePattern: "^_",
caughtErrorsIgnorePattern: "^_",
},
],
},
},
{
plugins: { boundaries },
settings: {
"boundaries/elements": [
{ type: "app", pattern: "apps/*" },
{ type: "tooling", pattern: "packages/core-eslint" },
{ type: "tooling", pattern: "packages/core-typescript" },
{ type: "tooling", pattern: "packages/core-testing" },
{ type: "core-composition", pattern: "packages/core-api" },
{ type: "core-composition", pattern: "packages/core-cms" },
{ type: "core", pattern: "packages/core-*" },
{ type: "feature", pattern: "packages/!(core-*)" },
],
},
rules: {
"boundaries/element-types": [
2,
{
default: "disallow",
rules: [
{
from: "app",
allow: ["app", "core", "core-composition", "feature", "tooling"],
},
{ from: "feature", allow: ["core", "feature", "tooling"] },
{ from: "core", allow: ["core", "tooling"] },
{ from: "core-composition", allow: ["core", "feature", "tooling"] },
{ from: "tooling", allow: ["tooling"] },
],
},
],
},
},
// Block direct @sentry/* imports outside the allowlisted instrumentation paths.
{
files: ["**/*.{ts,tsx,mjs,cjs,js}"],
rules: {
"no-restricted-imports": [
"error",
{
patterns: [
{
group: ["@sentry/*"],
message:
"Import from @repo/core-shared/instrumentation instead — feature packages must not depend on Sentry directly.",
},
],
},
],
},
},
// Allowlist — the only paths permitted to import @sentry/*.
// Per ADR-017, server-side Sentry SDK usage is limited to the OTel bridge
// and browser/client init files. Patterns are double-star prefixed so they
// match whether eslint runs from the repo root or from inside a sub-package.
{
files: [
// OTel bridge — the only server-side file that may import @sentry/opentelemetry
"**/instrumentation/otel/sentry-bridge.{ts,js}",
"**/instrumentation/otel/sentry-bridge.test.{ts,js}",
// OTel DI binder — may import @sentry/opentelemetry via sentry-bridge
"**/instrumentation/di/bind-otel-instrumentation.{ts,js}",
"**/instrumentation/di/bind-otel-instrumentation.test.{ts,js}",
// Browser-side Sentry init helpers (server-only migration — browser keeps Sentry SDK directly)
"**/instrumentation/sentry/init-client.{ts,js}",
"**/instrumentation/sentry/init-client.test.{ts,js}",
"**/instrumentation/sentry/init-client-react.{ts,js}",
"**/instrumentation/sentry/init-client-react.test.{ts,js}",
// Server-side Sentry SDK init still used by apps (calls Sentry.init with DSN)
"**/instrumentation/sentry/init-server.{ts,js}",
"**/instrumentation/sentry/init-server.test.{ts,js}",
"**/instrumentation/sentry/init-server-node.{ts,js}",
"**/instrumentation/sentry/init-server-node.test.{ts,js}",
// Test guard — mocks Sentry + OTel SDKs to prevent real init in test processes
"**/setup/no-instrumentation.{ts,js}",
"**/setup/no-instrumentation.test.{ts,js}",
// Legacy alias for one release cycle
"**/setup/no-sentry.{ts,js}",
"**/setup/no-sentry.test.{ts,js}",
// App-level instrumentation entry points and build config
"**/instrumentation.{ts,js,mjs}",
"**/instrumentation-client.{ts,js,mjs}",
"**/next.config.{mjs,ts,js}",
"**/vite.config.{ts,mjs,js}",
"**/sentry.*.config.{ts,mjs,js}",
],
rules: {
"no-restricted-imports": "off",
},
},
// OTel SDK packages (@opentelemetry/sdk-*, @opentelemetry/resources,
// @opentelemetry/semantic-conventions, @opentelemetry/instrumentation-*,
// @sentry/opentelemetry) are restricted to core-shared/instrumentation/otel/
// and app-level init paths.
// The vendor-neutral API packages (@opentelemetry/api, @opentelemetry/api-logs)
// are unrestricted within core-shared/instrumentation/ — features use them for
// advanced tracing without coupling to the SDK.
{
files: [
"**/instrumentation/otel/**/*.{ts,tsx,mjs,cjs,js}",
// App-level init and build config also allowed to import OTel SDK packages
"**/instrumentation.{ts,js,mjs}",
"**/next.config.{mjs,ts,js}",
"**/vite.config.{ts,mjs,js}",
],
rules: {
"no-restricted-imports": "off",
},
},
// E1 — Event handlers must not be re-exported. Wire them only inside the
// consumer feature's bind-production / bind-dev-seed (spec § 2.2 Rule E1).
// J — Direct `payload.jobs.*` access is forbidden outside the integration
// layer. Use IJobQueue (from @repo/core-shared/jobs) instead.
// Events + jobs rules are added here when @repo/core-events is scaffolded
// via `pnpm turbo gen core-package events`.
// <gen:events-rules>
// R2 / R1 (ADR-016) — realtime-specific ESLint rules (no-direct-socket-io,
// no-realtime-handler-reexport) are added here when @repo/core-realtime is
// scaffolded via `pnpm turbo gen core-package realtime`.
// <gen:realtime-rules>
];

View File

@@ -0,0 +1,3 @@
import baseConfig from "./base.js";
export default baseConfig;

View File

@@ -0,0 +1,6 @@
import baseConfig from "./base.js";
export default [
...baseConfig,
{ ignores: [".next/**", "out/**"] },
];

View File

@@ -0,0 +1,29 @@
{
"name": "@repo/core-eslint",
"private": true,
"version": "0.0.0",
"type": "module",
"exports": {
"./base": "./base.js",
"./next": "./next.js",
"./react-internal": "./react-internal.js",
"./plugin": "./plugin.js"
},
"scripts": {
"test": "vitest run --passWithNoTests"
},
"devDependencies": {
"@eslint/js": "^9.20.0",
"@typescript-eslint/eslint-plugin": "^8.25.0",
"@typescript-eslint/parser": "^8.25.0",
"eslint": "^9.20.0",
"eslint-config-prettier": "^10.1.0",
"eslint-plugin-boundaries": "^4.2.2",
"eslint-plugin-turbo": "^2.4.0",
"typescript-eslint": "^8.25.0",
"vitest": "^3.1.0"
},
"dependencies": {
"globals": "^17.6.0"
}
}

View File

@@ -0,0 +1,51 @@
import featureMustHaveManifest from "./rules/feature-must-have-manifest.js";
import usecaseMustHaveTestFile from "./rules/usecase-must-have-test-file.js";
import requiredCoresInstalled from "./rules/required-cores-installed.js";
import noUndeclaredEventPublish from "./rules/no-undeclared-event-publish.js";
import noUndeclaredAudit from "./rules/no-undeclared-audit.js";
import noUndeclaredAnalyticsEvent from "./rules/no-undeclared-analytics-event.js";
import usecaseMustBeWired from "./rules/usecase-must-be-wired.js";
import componentMustHaveStory from "./rules/component-must-have-story.js";
import componentMustHaveTest from "./rules/component-must-have-test.js";
import atomicTierImportDirection from "./rules/atomic-tier-import-direction.js";
import piiDeclarationMustBeComplete from "./rules/pii-declaration-must-be-complete.js";
import noUndeclaredConsentCheck from "./rules/no-undeclared-consent-check.js";
import noUndeclaredRateLimit from "./rules/no-undeclared-rate-limit.js";
import entityMustHaveTest from "./rules/entity-must-have-test.js";
import noRelativeParentImportInTests from "./rules/no-relative-parent-import-in-tests.js";
/**
* The `@repo/core-eslint` conformance plugin. Aggregates custom rules that
* enforce feature-conformance contracts (manifest presence, sibling tests,
* required-cores ↔ workspace consistency).
*
* Registered as the `conformance` plugin in flat config:
*
* import conformancePlugin from "@repo/core-eslint/plugin";
* export default [
* { plugins: { conformance: conformancePlugin } },
* { rules: { "conformance/feature-must-have-manifest": ["warn", { repoRoot: import.meta.dirname }] } },
* ];
*/
const plugin = {
meta: { name: "conformance", version: "0.4.0" },
rules: {
"feature-must-have-manifest": featureMustHaveManifest,
"usecase-must-have-test-file": usecaseMustHaveTestFile,
"required-cores-installed": requiredCoresInstalled,
"no-undeclared-event-publish": noUndeclaredEventPublish,
"no-undeclared-audit": noUndeclaredAudit,
"no-undeclared-analytics-event": noUndeclaredAnalyticsEvent,
"usecase-must-be-wired": usecaseMustBeWired,
"component-must-have-story": componentMustHaveStory,
"component-must-have-test": componentMustHaveTest,
"atomic-tier-import-direction": atomicTierImportDirection,
"pii-declaration-must-be-complete": piiDeclarationMustBeComplete,
"no-undeclared-consent-check": noUndeclaredConsentCheck,
"no-undeclared-rate-limit": noUndeclaredRateLimit,
"entity-must-have-test": entityMustHaveTest,
"no-relative-parent-import-in-tests": noRelativeParentImportInTests,
},
};
export default plugin;

View File

@@ -0,0 +1,3 @@
import baseConfig from "./base.js";
export default [...baseConfig];

View File

@@ -0,0 +1,99 @@
import fs from "node:fs";
import path from "node:path";
import { parse } from "@typescript-eslint/parser";
/** Unwrap `as`/`satisfies` expressions, return a string literal's value. */
function stringFromNode(node) {
if (!node) return null;
if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") {
return stringFromNode(node.expression);
}
if (node.type === "Literal" && typeof node.value === "string") {
return node.value;
}
return null;
}
/**
* Extract the event `name` from an event-descriptor initializer. Handles the
* two shapes the codebase and `pnpm turbo gen event` produce:
* - `defineEvent("feature.event", schema)` — the core-events helper
* - `{ name: "feature.event" as const, schema }` — the inline descriptor
* (used when core-events is not installed)
*/
function nameFromInit(init) {
if (!init) return null;
if (init.type === "TSAsExpression" || init.type === "TSSatisfiesExpression") {
return nameFromInit(init.expression);
}
if (
init.type === "CallExpression" &&
init.callee.type === "Identifier" &&
init.callee.name === "defineEvent" &&
init.arguments.length > 0
) {
return stringFromNode(init.arguments[0]);
}
if (init.type === "ObjectExpression") {
const nameProp = init.properties.find(
(p) =>
p.type === "Property" &&
p.key.type === "Identifier" &&
p.key.name === "name",
);
return nameProp ? stringFromNode(nameProp.value) : null;
}
return null;
}
/**
* Resolve a relative import source (evaluated from `fromFile`) to a `.ts`
* file on disk. Returns null for bare/package specifiers or paths that don't
* resolve — callers treat null as "can't analyse, skip".
*/
export function resolveRelativeImport(source, fromFile) {
if (typeof source !== "string" || !source.startsWith(".")) return null;
const base = path.resolve(path.dirname(fromFile), source);
for (const candidate of [`${base}.ts`, path.join(base, "index.ts")]) {
if (fs.existsSync(candidate)) return candidate;
}
return null;
}
/**
* Read an event-contract file and return the `name` of the event descriptor
* exported under `exportName`. Returns null when the file can't be read or
* parsed, or doesn't export a recognised descriptor under that name.
*/
export function eventNameFromFile(filePath, exportName) {
let source;
try {
source = fs.readFileSync(filePath, "utf8");
} catch {
return null;
}
let ast;
try {
ast = parse(source, { loc: false, range: false });
} catch {
return null;
}
for (const stmt of ast.body) {
let varDecl = null;
if (
stmt.type === "ExportNamedDeclaration" &&
stmt.declaration?.type === "VariableDeclaration"
) {
varDecl = stmt.declaration;
} else if (stmt.type === "VariableDeclaration") {
varDecl = stmt;
}
if (!varDecl) continue;
for (const d of varDecl.declarations) {
if (d.id.type === "Identifier" && d.id.name === exportName) {
return nameFromInit(d.init);
}
}
}
return null;
}

View File

@@ -0,0 +1,270 @@
import fs from "node:fs";
import { parse } from "@typescript-eslint/parser";
function extractStringLiterals(arrayExpr) {
return arrayExpr.elements
.filter((el) => el && el.type === "Literal" && typeof el.value === "string")
.map((el) => el.value);
}
/**
* Extract budget names from a rateLimit array that contains either string
* literals ("ip") or RateLimitBudget objects ({ name: "ip", window: "1m", budget: 5 }).
*/
function extractRateLimitNames(arrayExpr) {
const names = [];
for (const el of arrayExpr.elements) {
if (!el) continue;
if (el.type === "Literal" && typeof el.value === "string") {
names.push(el.value);
} else if (el.type === "ObjectExpression") {
const nameProp = el.properties.find(
(p) =>
p.type === "Property" &&
p.key.type === "Identifier" &&
p.key.name === "name" &&
p.value.type === "Literal" &&
typeof p.value.value === "string",
);
if (nameProp) names.push(nameProp.value.value);
}
}
return names;
}
/**
* Parse a feature.manifest.ts file and extract per-use-case attributes.
* Walks the AST to find the `defineFeature({...} as const)` call expression
* and reads literal values from its argument object.
*
* Returns: { [useCaseName]: { mutates, audits[], publishes[], consumes[] } }
* Returns null if the file is missing or doesn't match the expected shape.
*/
export function parseManifestUseCases(manifestPath) {
let src;
try {
src = fs.readFileSync(manifestPath, "utf8");
} catch {
return null;
}
let ast;
try {
ast = parse(src, {
sourceType: "module",
ecmaVersion: "latest",
loc: false,
range: false,
});
} catch {
return null;
}
const defineCall = findDefineFeatureCall(ast);
if (!defineCall) return null;
const arg = unwrapAsConst(defineCall.arguments[0]);
if (!arg || arg.type !== "ObjectExpression") return null;
const useCasesProp = arg.properties.find(
(p) =>
p.type === "Property" &&
p.key.type === "Identifier" &&
p.key.name === "useCases",
);
if (!useCasesProp || useCasesProp.value.type !== "ObjectExpression")
return {};
const result = {};
for (const entry of useCasesProp.value.properties) {
if (entry.type !== "Property" || entry.value.type !== "ObjectExpression")
continue;
const name =
entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
result[name] = extractUseCaseEntry(entry.value);
}
return result;
}
function findDefineFeatureCall(ast) {
for (const node of ast.body) {
if (node.type !== "ExportNamedDeclaration" || !node.declaration) continue;
if (node.declaration.type !== "VariableDeclaration") continue;
for (const decl of node.declaration.declarations) {
const init = decl.init;
if (!init) continue;
if (
init.type === "CallExpression" &&
init.callee.type === "Identifier" &&
init.callee.name === "defineFeature"
) {
return init;
}
}
}
return null;
}
function unwrapAsConst(node) {
if (node && node.type === "TSAsExpression") return node.expression;
return node;
}
function extractUseCaseEntry(objExpr) {
const entry = {
mutates: false,
audits: [],
publishes: [],
consumes: [],
analyticsEvents: [],
rateLimit: [],
};
for (const prop of objExpr.properties) {
if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
const key = prop.key.name;
if (key === "mutates" && prop.value.type === "Literal") {
entry.mutates = prop.value.value === true;
} else if (
(key === "audits" ||
key === "publishes" ||
key === "consumes" ||
key === "analyticsEvents") &&
prop.value.type === "ArrayExpression"
) {
entry[key] = extractStringLiterals(prop.value);
} else if (key === "rateLimit" && prop.value.type === "ArrayExpression") {
entry[key] = extractRateLimitNames(prop.value);
}
}
return entry;
}
/**
* Parse a feature.manifest.ts and return the full manifest shape:
* { name, requiredCores: string[], useCases: { [name]: {...} } }
*
* Same AST walking as parseManifestUseCases but additionally extracts
* the top-level name + requiredCores fields. Returns null on parse failure.
*/
export function parseManifestFully(manifestPath) {
// Reuse the AST parser used by parseManifestUseCases by inlining the
// file-read + AST walk. We need access to the manifest's top-level
// argument object beyond just useCases.
let src;
try {
src = fs.readFileSync(manifestPath, "utf8");
} catch {
return null;
}
let ast;
try {
ast = parse(src, {
sourceType: "module",
ecmaVersion: "latest",
loc: false,
range: false,
});
} catch {
return null;
}
const defineCall = findDefineFeatureCallFromBody(ast);
if (!defineCall) return null;
const arg = unwrapAsConstNode(defineCall.arguments[0]);
if (!arg || arg.type !== "ObjectExpression") return null;
let name = null;
let requiredCores = [];
let requiresConsent = [];
let useCases = {};
for (const prop of arg.properties) {
if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
if (
prop.key.name === "name" &&
prop.value.type === "Literal" &&
typeof prop.value.value === "string"
) {
name = prop.value.value;
} else if (
prop.key.name === "requiredCores" &&
prop.value.type === "ArrayExpression"
) {
requiredCores = extractStringLiterals(prop.value);
} else if (
prop.key.name === "requiresConsent" &&
prop.value.type === "ArrayExpression"
) {
requiresConsent = extractStringLiterals(prop.value);
} else if (
prop.key.name === "useCases" &&
prop.value.type === "ObjectExpression"
) {
useCases = extractUseCasesMap(prop.value);
}
}
if (name === null) return null;
return { name, requiredCores, requiresConsent, useCases };
}
function extractUseCasesMap(useCasesObjExpr) {
const result = {};
for (const entry of useCasesObjExpr.properties) {
if (entry.type !== "Property" || entry.value.type !== "ObjectExpression")
continue;
const ucName =
entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
result[ucName] = extractUseCaseEntryFromObj(entry.value);
}
return result;
}
// Helper aliases for the existing private functions — exposed under
// different names to avoid touching existing code paths.
function findDefineFeatureCallFromBody(ast) {
for (const node of ast.body) {
if (node.type !== "ExportNamedDeclaration" || !node.declaration) continue;
if (node.declaration.type !== "VariableDeclaration") continue;
for (const decl of node.declaration.declarations) {
const init = decl.init;
if (!init) continue;
if (
init.type === "CallExpression" &&
init.callee.type === "Identifier" &&
init.callee.name === "defineFeature"
) {
return init;
}
}
}
return null;
}
function unwrapAsConstNode(node) {
if (node && node.type === "TSAsExpression") return node.expression;
return node;
}
function extractUseCaseEntryFromObj(objExpr) {
const entry = {
mutates: false,
audits: [],
publishes: [],
consumes: [],
analyticsEvents: [],
rateLimit: [],
};
for (const prop of objExpr.properties) {
if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
const key = prop.key.name;
if (key === "mutates" && prop.value.type === "Literal") {
entry.mutates = prop.value.value === true;
} else if (
(key === "audits" ||
key === "publishes" ||
key === "consumes" ||
key === "analyticsEvents") &&
prop.value.type === "ArrayExpression"
) {
entry[key] = extractStringLiterals(prop.value);
} else if (key === "rateLimit" && prop.value.type === "ArrayExpression") {
entry[key] = extractRateLimitNames(prop.value);
}
}
return entry;
}

View File

@@ -0,0 +1,154 @@
import { describe, it, expect } from "vitest";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import { parseManifestUseCases, parseManifestFully } from "./_manifest-ast.js";
function writeManifest(content) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "manifest-ast-"));
const fp = path.join(dir, "feature.manifest.ts");
fs.writeFileSync(fp, content);
return fp;
}
describe("parseManifestUseCases", () => {
it("returns an empty object for a manifest with no useCases", () => {
const fp = writeManifest(`export const xManifest = defineFeature({
name: "x",
requiredCores: [],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`);
expect(parseManifestUseCases(fp)).toEqual({});
});
it("extracts per-use-case publishes/audits/consumes arrays", () => {
const fp = writeManifest(`export const authManifest = defineFeature({
name: "auth",
requiredCores: [],
useCases: {
signIn: { mutates: false, audits: [], publishes: [], consumes: [] },
signUp: { mutates: true, audits: ["user.created"], publishes: ["auth.signed-up"], consumes: [] },
signOut: { mutates: true, audits: ["session.ended"], publishes: [], consumes: [] },
},
realtimeChannels: [],
jobs: [],
} as const);`);
expect(parseManifestUseCases(fp)).toEqual({
signIn: {
mutates: false,
audits: [],
publishes: [],
consumes: [],
analyticsEvents: [],
rateLimit: [],
},
signUp: {
mutates: true,
audits: ["user.created"],
publishes: ["auth.signed-up"],
consumes: [],
analyticsEvents: [],
rateLimit: [],
},
signOut: {
mutates: true,
audits: ["session.ended"],
publishes: [],
consumes: [],
analyticsEvents: [],
rateLimit: [],
},
});
});
it("returns null when file does not exist", () => {
expect(parseManifestUseCases("/nonexistent/manifest.ts")).toBeNull();
});
it("returns null when the file has no defineFeature call", () => {
const fp = writeManifest(`export const x = 1;`);
expect(parseManifestUseCases(fp)).toBeNull();
});
});
describe("parseManifestFully", () => {
it("returns name + requiredCores + useCases for a complete manifest", () => {
// Use the writeManifest helper that already exists in the test file
const fp = writeManifest(`export const authManifest = defineFeature({
name: "auth",
requiredCores: ["audit", "events"],
useCases: {
signIn: { mutates: false, audits: [], publishes: [], consumes: [] },
signUp: { mutates: true, audits: ["user.created"], publishes: [], consumes: [] },
},
realtimeChannels: [],
jobs: [],
} as const);`);
expect(parseManifestFully(fp)).toEqual({
name: "auth",
requiredCores: ["audit", "events"],
requiresConsent: [],
useCases: {
signIn: {
mutates: false,
audits: [],
publishes: [],
consumes: [],
analyticsEvents: [],
rateLimit: [],
},
signUp: {
mutates: true,
audits: ["user.created"],
publishes: [],
consumes: [],
analyticsEvents: [],
rateLimit: [],
},
},
});
});
it("extracts requiresConsent categories from the manifest", () => {
const fp = writeManifest(`export const consentManifest = defineFeature({
name: "consent",
requiredCores: [],
requiresConsent: ["analytics", "marketing"],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`);
expect(parseManifestFully(fp)).toEqual({
name: "consent",
requiredCores: [],
requiresConsent: ["analytics", "marketing"],
useCases: {},
});
});
it("returns null when the manifest has no name", () => {
const fp = writeManifest(`export const x = 1;`);
expect(parseManifestFully(fp)).toBeNull();
});
it("is not fooled by 'name:' inside a JSDoc comment (regex would false-match)", () => {
const fp = writeManifest(`/**
* Sample comment with name: "fake" embedded in it.
*/
export const realManifest = defineFeature({
name: "real",
requiredCores: [],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`);
expect(parseManifestFully(fp)).toEqual({
name: "real",
requiredCores: [],
requiresConsent: [],
useCases: {},
});
});
});

View File

@@ -0,0 +1,38 @@
import path from "node:path";
import { parseManifestFully } from "./_manifest-ast.js";
/**
* Reads a feature.manifest.ts and returns { name, requiredCores }.
* Backed by the AST parser from _manifest-ast.js — no longer uses regex.
*
* Returns: { name: string, requiredCores: string[] } | null
*/
export function readManifestSource(manifestPath) {
const full = parseManifestFully(manifestPath);
if (!full) return null;
return { name: full.name, requiredCores: full.requiredCores };
}
/**
* Canonical manifest path for a given feature package root.
*/
export function manifestPathForFeature(featureRoot) {
return path.join(featureRoot, "src", "feature.manifest.ts");
}
/**
* Given an absolute file path and the monorepo root, returns the feature
* package root that contains the file (e.g. /repo/packages/auth). Returns
* null when the file lives outside the packages/ tree.
*
* Assumes the conventional layout `packages/<feature>/src/...`.
*/
export function featureRootForFile(filepath, repoRoot) {
const packagesDir = path.join(repoRoot, "packages");
if (!filepath.startsWith(packagesDir + path.sep)) return null;
const rel = filepath.slice(packagesDir.length + 1); // e.g. "auth/src/..."
const slash = rel.indexOf(path.sep);
if (slash === -1) return null;
const featureName = rel.slice(0, slash);
return path.join(packagesDir, featureName);
}

View File

@@ -0,0 +1,74 @@
import { describe, it, expect } from "vitest";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import { readManifestSource, manifestPathForFeature, featureRootForFile } from "./_manifest-source.js";
function writeTempFile(filename, contents) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "manifest-source-"));
const filepath = path.join(dir, filename);
fs.writeFileSync(filepath, contents);
return { dir, filepath };
}
describe("_manifest-source", () => {
describe("readManifestSource", () => {
it("returns { name, requiredCores: [] } for a minimal manifest", () => {
const { filepath } = writeTempFile(
"feature.manifest.ts",
`import { defineFeature } from "@repo/core-shared/conformance";
export const xManifest = defineFeature({
name: "test",
requiredCores: [],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`
);
expect(readManifestSource(filepath)).toEqual({ name: "test", requiredCores: [] });
});
it("extracts multi-element requiredCores", () => {
const { filepath } = writeTempFile(
"feature.manifest.ts",
`export const xManifest = defineFeature({
name: "auth",
requiredCores: ["audit", "events"],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`
);
expect(readManifestSource(filepath)).toEqual({ name: "auth", requiredCores: ["audit", "events"] });
});
it("returns null when the file does not exist", () => {
expect(readManifestSource("/nonexistent/path/feature.manifest.ts")).toBeNull();
});
it("returns null when the file is unreadable as a manifest (no name field)", () => {
const { filepath } = writeTempFile("feature.manifest.ts", `export const x = 1;`);
expect(readManifestSource(filepath)).toBeNull();
});
});
describe("manifestPathForFeature", () => {
it("returns the canonical manifest path for a feature root", () => {
expect(manifestPathForFeature("/repo/packages/auth")).toBe(
path.join("/repo/packages/auth", "src", "feature.manifest.ts"),
);
});
});
describe("featureRootForFile", () => {
it("returns the package root containing a use-case file", () => {
const file = "/repo/packages/auth/src/application/use-cases/sign-in.use-case.ts";
expect(featureRootForFile(file, "/repo")).toBe("/repo/packages/auth");
});
it("returns null for files outside the packages tree", () => {
const file = "/repo/apps/web-next/src/app/page.tsx";
expect(featureRootForFile(file, "/repo")).toBeNull();
});
});
});

View File

@@ -0,0 +1,18 @@
import { useCaseNameFromFile } from "./_usecase-name.js";
import { featureRootForFile } from "./_manifest-source.js";
/**
* Resolves the rule execution context from an ESLint context object.
* Returns null when the file is not a use-case file or not inside a
* recognised feature package — callers should return {} immediately.
*/
export function resolveRuleContext(context) {
const opts = context.options[0] ?? {};
const repoRoot = opts.repoRoot ?? context.cwd ?? process.cwd();
const filename = context.filename;
const useCaseName = useCaseNameFromFile(filename);
if (!useCaseName) return null;
const featureRoot = featureRootForFile(filename, repoRoot);
if (!featureRoot) return null;
return { useCaseName, featureRoot, repoRoot };
}

View File

@@ -0,0 +1,8 @@
/** Shared repoRoot option schema used by conformance rules that need to locate feature roots. */
export const repoRootSchema = [
{
type: "object",
properties: { repoRoot: { type: "string" } },
additionalProperties: false,
},
];

View File

@@ -0,0 +1,17 @@
/**
* Derive the manifest use-case key from a use-case file path.
*
* Convention: `packages/<feature>/src/application/use-cases/<kebab-slug>.use-case.ts`
* → manifest.useCases.<camelCaseSlug>
*
* Returns null for non-use-case files.
*/
export function useCaseNameFromFile(filepath) {
if (!filepath.endsWith(".use-case.ts")) return null;
if (!filepath.includes("/application/use-cases/") && !filepath.includes("\\application\\use-cases\\")) {
return null;
}
const base = filepath.split(/[\\/]/).pop();
const slug = base.replace(/\.use-case\.ts$/, "");
return slug.split("-").map((part, i) => i === 0 ? part : part[0].toUpperCase() + part.slice(1)).join("");
}

View File

@@ -0,0 +1,19 @@
import { describe, it, expect } from "vitest";
import { useCaseNameFromFile } from "./_usecase-name.js";
describe("useCaseNameFromFile", () => {
it("converts kebab-case slug to camelCase", () => {
expect(useCaseNameFromFile("/repo/packages/auth/src/application/use-cases/sign-in.use-case.ts")).toBe("signIn");
expect(useCaseNameFromFile("/repo/packages/auth/src/application/use-cases/sign-up.use-case.ts")).toBe("signUp");
expect(useCaseNameFromFile("/repo/packages/blog/src/application/use-cases/get-article-by-slug.use-case.ts")).toBe("getArticleBySlug");
});
it("handles single-word slugs", () => {
expect(useCaseNameFromFile("/repo/packages/x/src/application/use-cases/login.use-case.ts")).toBe("login");
});
it("returns null for non-use-case files", () => {
expect(useCaseNameFromFile("/repo/packages/auth/src/index.ts")).toBeNull();
expect(useCaseNameFromFile("/repo/packages/auth/src/feature.manifest.ts")).toBeNull();
});
});

View File

@@ -0,0 +1,28 @@
import fs from "node:fs";
import path from "node:path";
/**
* Reads the `packages:` list from `pnpm-workspace.yaml` at the given repo
* root. Returns an array of package glob strings (e.g. ["apps/*", "packages/*"]).
* Returns [] when the file is missing or has no `packages:` key.
*
* Uses regex extraction over YAML parsing to avoid a `js-yaml` dependency;
* the `packages:` block in pnpm-workspace.yaml has a stable, well-known
* shape and this approach is sufficient.
*/
export function readWorkspacePackages(repoRoot) {
const yamlPath = path.join(repoRoot, "pnpm-workspace.yaml");
let src;
try {
src = fs.readFileSync(yamlPath, "utf8");
} catch {
return [];
}
const blockMatch = src.match(/^packages:\s*\n((?:\s+-\s+.+\n?)+)/m);
if (!blockMatch) return [];
return blockMatch[1]
.split("\n")
.map((line) => line.match(/^\s+-\s+"?([^"]+?)"?\s*$/))
.filter((m) => m !== null)
.map((m) => m[1]);
}

View File

@@ -0,0 +1,34 @@
import { describe, it, expect } from "vitest";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import { readWorkspacePackages } from "./_workspace.js";
function writeWorkspaceYaml(contents) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "workspace-"));
const filepath = path.join(dir, "pnpm-workspace.yaml");
fs.writeFileSync(filepath, contents);
return { dir, filepath };
}
describe("_workspace", () => {
it("returns the list of declared package globs", () => {
const { dir } = writeWorkspaceYaml(
`packages:
- "apps/*"
- "packages/*"
`,
);
expect(readWorkspacePackages(dir)).toEqual(["apps/*", "packages/*"]);
});
it("returns [] when pnpm-workspace.yaml is missing", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "workspace-"));
expect(readWorkspacePackages(dir)).toEqual([]);
});
it("returns [] when packages key is absent", () => {
const { dir } = writeWorkspaceYaml(`# empty\n`);
expect(readWorkspacePackages(dir)).toEqual([]);
});
});

View File

@@ -0,0 +1,47 @@
const TIERS = ["atoms", "molecules", "organisms", "templates", "pages"];
function tierOf(filepath) {
for (let i = 0; i < TIERS.length; i++) {
const tier = TIERS[i];
if (filepath.includes(`/${tier}/`) || filepath.includes(`\\${tier}\\`)) {
return { name: tier, index: i };
}
}
return null;
}
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Atomic-design tier imports respect direction: atoms ← molecules ← organisms ← templates ← pages.",
},
schema: [],
messages: {
wrongDirection:
"{{fromTier}} cannot import from {{toTier}} ({{importPath}}). Tier direction: atoms ← molecules ← organisms ← templates ← pages.",
},
},
create(context) {
const filename = context.filename;
const from = tierOf(filename);
if (!from) return {};
return {
ImportDeclaration(node) {
const source = node.source.value;
if (typeof source !== "string") return;
const to = tierOf(source);
if (!to) return;
if (to.index > from.index) {
context.report({
node,
messageId: "wrongDirection",
data: { fromTier: from.name, toTier: to.name, importPath: source },
});
}
},
};
},
};

View File

@@ -0,0 +1,55 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import rule from "./atomic-tier-import-direction.js";
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
parserOptions: { ecmaFeatures: { jsx: true } },
},
});
describe("atomic-tier-import-direction", () => {
it("passes when an organism imports from atoms", () => {
tester.run("atomic-tier-import-direction", rule, {
valid: [{
filename: "/repo/packages/core-ui/src/organisms/Card/Card.tsx",
code: `import { Button } from "../../atoms/Button/Button";`,
}],
invalid: [],
});
});
it("fires when an atom imports from organisms", () => {
tester.run("atomic-tier-import-direction", rule, {
valid: [],
invalid: [{
filename: "/repo/packages/core-ui/src/atoms/Button/Button.tsx",
code: `import { Card } from "../../organisms/Card/Card";`,
errors: [{ messageId: "wrongDirection", data: { fromTier: "atoms", toTier: "organisms", importPath: "../../organisms/Card/Card" } }],
}],
});
});
it("is a no-op for files outside any tier folder", () => {
tester.run("atomic-tier-import-direction", rule, {
valid: [{
filename: "/repo/packages/auth/src/application/use-cases/sign-in.use-case.ts",
code: `export const x = 1;`,
}],
invalid: [],
});
});
it("passes for same-tier imports", () => {
tester.run("atomic-tier-import-direction", rule, {
valid: [{
filename: "/repo/packages/core-ui/src/molecules/SearchBar/SearchBar.tsx",
code: `import { FormField } from "../FormField/FormField";`,
}],
invalid: [],
});
});
});

View File

@@ -0,0 +1,59 @@
import fs from "node:fs";
import path from "node:path";
/**
* Identifies "component files" by location + extension:
* - `.tsx` extension
* - Inside `packages/core-ui/src/` OR `packages/<feature>/src/ui/`
* - NOT a test, stories, spec, or barrel file
*/
function isComponentFile(filename) {
if (!filename.endsWith(".tsx")) return false;
const base = path.basename(filename);
if (
base === "index.tsx" ||
base.endsWith(".test.tsx") ||
base.endsWith(".stories.tsx") ||
base.endsWith(".spec.tsx")
) {
return false;
}
return (
filename.includes("/packages/core-ui/src/") ||
/\/packages\/[^/]+\/src\/ui\//.test(filename)
);
}
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Every component file must have a sibling *.stories.tsx for Storybook coverage.",
},
schema: [],
messages: {
missingStory:
"Component {{filename}} has no sibling Storybook story at {{expected}}. Stories are the spec for visual conformance.",
},
},
create(context) {
return {
Program(node) {
const filename = context.filename;
if (!isComponentFile(filename)) return;
const expected = filename.replace(/\.tsx$/, ".stories.tsx");
if (fs.existsSync(expected)) return;
context.report({
node,
messageId: "missingStory",
data: {
filename: path.basename(filename),
expected: path.basename(expected),
},
});
},
};
},
};

View File

@@ -0,0 +1,84 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./component-must-have-story.js";
function makeFixture({ withStory, location = "core-ui" }) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmhs-"));
const dir =
location === "core-ui"
? path.join(root, "packages", "core-ui", "src", "atoms", "Button")
: path.join(root, "packages", "demo", "src", "ui", "atoms", "Button");
fs.mkdirSync(dir, { recursive: true });
const component = path.join(dir, "Button.tsx");
fs.writeFileSync(component, `export const Button = () => <button>x</button>;`);
if (withStory) {
fs.writeFileSync(path.join(dir, "Button.stories.tsx"), `export default { title: "Button" };`);
}
return { component };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
parserOptions: { ecmaFeatures: { jsx: true } },
},
});
describe("component-must-have-story", () => {
it("passes for a core-ui component with a sibling .stories.tsx", () => {
const { component } = makeFixture({ withStory: true });
tester.run("component-must-have-story", rule, {
valid: [{ filename: component, code: fs.readFileSync(component, "utf8") }],
invalid: [],
});
});
it("fires for a core-ui component without a sibling .stories.tsx", () => {
const { component } = makeFixture({ withStory: false });
tester.run("component-must-have-story", rule, {
valid: [],
invalid: [{
filename: component,
code: fs.readFileSync(component, "utf8"),
errors: [{ messageId: "missingStory" }],
}],
});
});
it("passes for a feature ui component with a sibling .stories.tsx", () => {
const { component } = makeFixture({ withStory: true, location: "feature" });
tester.run("component-must-have-story", rule, {
valid: [{ filename: component, code: fs.readFileSync(component, "utf8") }],
invalid: [],
});
});
it("is a no-op for index.tsx", () => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmhs-"));
const dir = path.join(root, "packages", "core-ui", "src", "atoms", "Button");
fs.mkdirSync(dir, { recursive: true });
const file = path.join(dir, "index.tsx");
fs.writeFileSync(file, `export * from "./Button";`);
tester.run("component-must-have-story", rule, {
valid: [{ filename: file, code: fs.readFileSync(file, "utf8") }],
invalid: [],
});
});
it("is a no-op for files outside packages/core-ui/ and packages/*/src/ui/", () => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmhs-"));
const dir = path.join(root, "packages", "auth", "src", "application", "use-cases");
fs.mkdirSync(dir, { recursive: true });
const file = path.join(dir, "sign-in.use-case.tsx");
fs.writeFileSync(file, `export const x = 1;`);
tester.run("component-must-have-story", rule, {
valid: [{ filename: file, code: fs.readFileSync(file, "utf8") }],
invalid: [],
});
});
});

View File

@@ -0,0 +1,53 @@
import fs from "node:fs";
import path from "node:path";
function isComponentFile(filename) {
if (!filename.endsWith(".tsx")) return false;
const base = path.basename(filename);
if (
base === "index.tsx" ||
base.endsWith(".test.tsx") ||
base.endsWith(".stories.tsx") ||
base.endsWith(".spec.tsx")
) {
return false;
}
return (
filename.includes("/packages/core-ui/src/") ||
/\/packages\/[^/]+\/src\/ui\//.test(filename)
);
}
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Every component file must have a sibling *.test.tsx for behavioural coverage.",
},
schema: [],
messages: {
missingTest:
"Component {{filename}} has no sibling test at {{expected}}. Write the red test first.",
},
},
create(context) {
return {
Program(node) {
const filename = context.filename;
if (!isComponentFile(filename)) return;
const expected = filename.replace(/\.tsx$/, ".test.tsx");
if (fs.existsSync(expected)) return;
context.report({
node,
messageId: "missingTest",
data: {
filename: path.basename(filename),
expected: path.basename(expected),
},
});
},
};
},
};

View File

@@ -0,0 +1,49 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./component-must-have-test.js";
function makeFixture({ withTest }) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "cmht-"));
const dir = path.join(root, "packages", "core-ui", "src", "atoms", "Button");
fs.mkdirSync(dir, { recursive: true });
const component = path.join(dir, "Button.tsx");
fs.writeFileSync(component, `export const Button = () => <button>x</button>;`);
if (withTest) {
fs.writeFileSync(path.join(dir, "Button.test.tsx"), `import { it } from "vitest"; it("works", () => {});`);
}
return { component };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
parserOptions: { ecmaFeatures: { jsx: true } },
},
});
describe("component-must-have-test", () => {
it("passes when sibling .test.tsx exists", () => {
const { component } = makeFixture({ withTest: true });
tester.run("component-must-have-test", rule, {
valid: [{ filename: component, code: fs.readFileSync(component, "utf8") }],
invalid: [],
});
});
it("fires when no sibling .test.tsx exists", () => {
const { component } = makeFixture({ withTest: false });
tester.run("component-must-have-test", rule, {
valid: [],
invalid: [{
filename: component,
code: fs.readFileSync(component, "utf8"),
errors: [{ messageId: "missingTest" }],
}],
});
});
});

View File

@@ -0,0 +1,55 @@
import fs from "node:fs";
import path from "node:path";
/**
* Entity models (`entities/models/<x>.ts`) are pure domain logic — schemas,
* invariants, derivations. They are the cheapest layer to test and the most
* expensive to get wrong, so every model file must carry a sibling test.
*
* Scope is `entities/models/` only. Error classes (`entities/errors/`) are
* conventionally covered by a consolidated `errors.test.ts`, and barrels
* (`index.ts`) hold no logic — both are excluded.
*/
function isEntityModelFile(filename) {
const normalized = filename.replace(/\\/g, "/");
if (!normalized.includes("/entities/models/")) return false;
if (!normalized.endsWith(".ts")) return false;
if (normalized.endsWith(".test.ts")) return false;
if (normalized.endsWith(".d.ts")) return false;
if (normalized.endsWith("/index.ts")) return false;
return true;
}
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Every entity model file (entities/models/<x>.ts) must have a sibling <x>.test.ts.",
},
schema: [],
messages: {
missingTest:
"Entity model {{filename}} has no sibling test at {{expected}}. Entity models are pure domain logic — cover them with a unit test.",
},
},
create(context) {
return {
Program(node) {
const filename = context.filename;
if (!isEntityModelFile(filename)) return;
const expected = filename.replace(/\.ts$/, ".test.ts");
if (fs.existsSync(expected)) return;
context.report({
node,
messageId: "missingTest",
data: {
filename: path.basename(filename),
expected: path.basename(expected),
},
});
},
};
},
};

View File

@@ -0,0 +1,74 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./entity-must-have-test.js";
function makeModelsDir() {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "emht-"));
const modelsDir = path.join(dir, "src", "entities", "models");
fs.mkdirSync(modelsDir, { recursive: true });
return modelsDir;
}
function makeEntityFixture({ withTest }) {
const modelsDir = makeModelsDir();
const entity = path.join(modelsDir, "cookie.ts");
fs.writeFileSync(entity, `export const cookie = {};`);
if (withTest) {
fs.writeFileSync(
path.join(modelsDir, "cookie.test.ts"),
`import { it } from "vitest"; it("works", () => {});`,
);
}
return { entity };
}
const tester = new RuleTester({
languageOptions: { ecmaVersion: "latest", sourceType: "module" },
});
describe("entity-must-have-test", () => {
it("passes when a sibling .test.ts exists", () => {
const { entity } = makeEntityFixture({ withTest: true });
tester.run("entity-must-have-test", rule, {
valid: [{ filename: entity, code: fs.readFileSync(entity, "utf8") }],
invalid: [],
});
});
it("fires when no sibling test file exists", () => {
const { entity } = makeEntityFixture({ withTest: false });
tester.run("entity-must-have-test", rule, {
valid: [],
invalid: [
{
filename: entity,
code: fs.readFileSync(entity, "utf8"),
errors: [{ messageId: "missingTest" }],
},
],
});
});
it("ignores files outside entities/models", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "emht-"));
const other = path.join(dir, "helper.ts");
fs.writeFileSync(other, `export const x = 1;`);
tester.run("entity-must-have-test", rule, {
valid: [{ filename: other, code: "export const x = 1;" }],
invalid: [],
});
});
it("ignores the index.ts barrel inside entities/models", () => {
const modelsDir = makeModelsDir();
const index = path.join(modelsDir, "index.ts");
fs.writeFileSync(index, `export {};`);
tester.run("entity-must-have-test", rule, {
valid: [{ filename: index, code: "export {};" }],
invalid: [],
});
});
});

View File

@@ -0,0 +1,49 @@
import fs from "node:fs";
import { manifestPathForFeature, featureRootForFile } from "./_manifest-source.js";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Every feature with use-case files must declare a feature.manifest.ts at its src/ root.",
},
schema: [
{
type: "object",
properties: {
repoRoot: { type: "string" },
},
additionalProperties: false,
},
],
messages: {
missingManifest:
"Feature {{feature}} has use cases but no feature.manifest.ts. Run `pnpm turbo gen feature {{feature}}` or scaffold the manifest manually at {{expected}}.",
},
},
create(context) {
const opts = context.options[0] ?? {};
const repoRoot = opts.repoRoot ?? context.cwd ?? process.cwd();
return {
Program(node) {
const filename = context.filename;
const featureRoot = featureRootForFile(filename, repoRoot);
if (!featureRoot) return;
// Only check use-case files
if (!filename.includes("/application/use-cases/") || !filename.endsWith(".use-case.ts")) {
return;
}
const manifestPath = manifestPathForFeature(featureRoot);
if (fs.existsSync(manifestPath)) return;
const featureName = featureRoot.split("/").pop();
context.report({
node,
messageId: "missingManifest",
data: { feature: featureName, expected: manifestPath },
});
},
};
},
};

View File

@@ -0,0 +1,54 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./feature-must-have-manifest.js";
function makeFeatureFixture({ withManifest }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "fmm-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), { recursive: true });
if (withManifest) {
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({ name: "demo", requiredCores: [], useCases: {}, realtimeChannels: [], jobs: [] } as const);`,
);
}
const useCaseFile = path.join(featureDir, "src", "application", "use-cases", "do-thing.use-case.ts");
fs.writeFileSync(useCaseFile, `export const doThingUseCase = () => async () => {};`);
return { repoRoot, useCaseFile };
}
const tester = new RuleTester({ languageOptions: { ecmaVersion: "latest", sourceType: "module" } });
describe("feature-must-have-manifest", () => {
it("passes when the feature has a manifest", () => {
const { repoRoot, useCaseFile } = makeFeatureFixture({ withManifest: true });
tester.run("feature-must-have-manifest", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when the feature has no manifest", () => {
const { repoRoot, useCaseFile } = makeFeatureFixture({ withManifest: false });
tester.run("feature-must-have-manifest", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [{ messageId: "missingManifest" }],
},
],
});
});
});

View File

@@ -0,0 +1,49 @@
/**
* Feature test files import from `src/` through the `@/` alias, never via
* `../` parent traversal (CLAUDE.md "Key Conventions"). A `../` import in a
* test file is always reaching across `src/` directories — `@/` keeps those
* imports stable under file moves and makes the test's dependencies legible.
*
* Scoped to feature packages (`packages/<name>/src/`, excluding `core-*`):
* the convention is part of the feature template's contract. Core packages
* are generated and governed by their own templates, and tooling packages
* (turbo/generators, scripts) legitimately use relative paths.
*/
function isFeatureSrcTestFile(filename) {
const normalized = filename.replace(/\\/g, "/");
if (!normalized.endsWith(".test.ts") && !normalized.endsWith(".test.tsx")) {
return false;
}
return /\/packages\/(?!core-)[^/]+\/src\//.test(normalized);
}
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Feature test files must import src modules via the @/ alias, not ../ parent paths.",
},
schema: [],
messages: {
relativeParentImport:
'Test file imports "{{source}}" with a ../ parent path. Use the "@/" alias for src imports (e.g. "@/application/...").',
},
},
create(context) {
if (!isFeatureSrcTestFile(context.filename)) return {};
return {
ImportDeclaration(node) {
const source = node.source.value;
if (typeof source === "string" && source.startsWith("../")) {
context.report({
node: node.source,
messageId: "relativeParentImport",
data: { source },
});
}
},
};
},
};

View File

@@ -0,0 +1,73 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import rule from "./no-relative-parent-import-in-tests.js";
const tester = new RuleTester({
languageOptions: { ecmaVersion: "latest", sourceType: "module" },
});
const featureTest = "/repo/packages/auth/src/di/container.test.ts";
const featureSrc = "/repo/packages/auth/src/di/container.ts";
const coreTest = "/repo/packages/core-audit/src/di/bind-audit.test.ts";
describe("no-relative-parent-import-in-tests", () => {
it("passes when a feature test uses the @/ alias", () => {
tester.run("no-relative-parent-import-in-tests", rule, {
valid: [
{
filename: featureTest,
code: `import { x } from "@/infrastructure/x";`,
},
],
invalid: [],
});
});
it("passes for same-directory ./ imports", () => {
tester.run("no-relative-parent-import-in-tests", rule, {
valid: [
{ filename: featureTest, code: `import { x } from "./container";` },
],
invalid: [],
});
});
it("fires when a feature test imports via ../", () => {
tester.run("no-relative-parent-import-in-tests", rule, {
valid: [],
invalid: [
{
filename: featureTest,
code: `import { x } from "../infrastructure/x";`,
errors: [
{
messageId: "relativeParentImport",
data: { source: "../infrastructure/x" },
},
],
},
],
});
});
it("ignores ../ imports in non-test source files", () => {
tester.run("no-relative-parent-import-in-tests", rule, {
valid: [
{
filename: featureSrc,
code: `import { x } from "../infrastructure/x";`,
},
],
invalid: [],
});
});
it("ignores core-package test files (governed by their own templates)", () => {
tester.run("no-relative-parent-import-in-tests", rule, {
valid: [
{ filename: coreTest, code: `import { x } from "../noop-audit-log";` },
],
invalid: [],
});
});
});

View File

@@ -0,0 +1,51 @@
import { parseManifestUseCases } from "./_manifest-ast.js";
import { manifestPathForFeature } from "./_manifest-source.js";
import { repoRootSchema } from "./_rule-schema.js";
import { resolveRuleContext } from "./_rule-context.js";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
'analytics.track("X") inside a use-case factory must declare X in manifest.useCases[name].analyticsEvents.',
},
schema: repoRootSchema,
messages: {
undeclared:
'{{useCase}} calls analytics.track("{{event}}") but {{event}} is not declared in manifest.useCases.{{useCase}}.analyticsEvents. Add it to the manifest or remove the call.',
},
},
create(context) {
const rc = resolveRuleContext(context);
if (!rc) return {};
const { useCaseName, featureRoot } = rc;
const manifest = parseManifestUseCases(manifestPathForFeature(featureRoot));
if (!manifest || !manifest[useCaseName]) return {};
const declared = new Set(manifest[useCaseName].analyticsEvents ?? []);
return {
CallExpression(node) {
if (
node.callee.type === "MemberExpression" &&
node.callee.object.type === "Identifier" &&
node.callee.object.name === "analytics" &&
node.callee.property.type === "Identifier" &&
node.callee.property.name === "track" &&
node.arguments.length > 0 &&
node.arguments[0].type === "Literal" &&
typeof node.arguments[0].value === "string"
) {
const event = node.arguments[0].value;
if (!declared.has(event)) {
context.report({
node,
messageId: "undeclared",
data: { event, useCase: useCaseName },
});
}
}
},
};
},
};

View File

@@ -0,0 +1,155 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./no-undeclared-analytics-event.js";
function makeFixture({ manifestUseCases, useCaseBody }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nuae-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), {
recursive: true,
});
const useCasesObj = Object.entries(manifestUseCases)
.map(
([name, uc]) =>
` ${name}: { mutates: ${uc.mutates}, audits: [], publishes: [], consumes: [], analyticsEvents: [${uc.analyticsEvents.map((e) => `"${e}"`).join(", ")}] },`,
)
.join("\n");
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
useCases: {
${useCasesObj}
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
const useCaseFile = path.join(
featureDir,
"src",
"application",
"use-cases",
"sign-up.use-case.ts",
);
fs.writeFileSync(useCaseFile, useCaseBody);
return { repoRoot, useCaseFile };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("no-undeclared-analytics-event", () => {
it("passes when analytics.track slug matches manifest analyticsEvents[]", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, analyticsEvents: ["user.signed-up"] },
},
useCaseBody: `export const signUpUseCase = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
});
tester.run("no-undeclared-analytics-event", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when analytics.track slug is not in manifest", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: { signUp: { mutates: true, analyticsEvents: [] } },
useCaseBody: `export const signUpUseCase = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
});
tester.run("no-undeclared-analytics-event", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "undeclared",
data: { event: "user.signed-up", useCase: "signUp" },
},
],
},
],
});
});
it("is a no-op when analytics.track is called with a non-literal argument", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: { signUp: { mutates: true, analyticsEvents: [] } },
useCaseBody: `export const signUpUseCase = (analytics, slug) => async () => { analytics.track(slug, {}); };`,
});
tester.run("no-undeclared-analytics-event", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("is a no-op for files that are not use-case files", () => {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nuae-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application"), {
recursive: true,
});
const controllerFile = path.join(
featureDir,
"src",
"application",
"sign-up.controller.ts",
);
fs.writeFileSync(
controllerFile,
`export const signUpController = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
);
tester.run("no-undeclared-analytics-event", rule, {
valid: [
{
filename: controllerFile,
code: fs.readFileSync(controllerFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("is a no-op when manifest has no entry for the use case", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {},
useCaseBody: `export const signUpUseCase = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
});
tester.run("no-undeclared-analytics-event", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
});

View File

@@ -0,0 +1,62 @@
import { parseManifestUseCases } from "./_manifest-ast.js";
import { manifestPathForFeature } from "./_manifest-source.js";
import { repoRootSchema } from "./_rule-schema.js";
import { resolveRuleContext } from "./_rule-context.js";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
'auditLog.record({ type: "X" }) inside a use-case factory must declare X in manifest.useCases[name].audits.',
},
schema: repoRootSchema,
messages: {
undeclared:
'{{useCase}} calls auditLog.record with type "{{event}}" but {{event}} is not declared in manifest.useCases.{{useCase}}.audits. Add it to the manifest or remove the call.',
},
},
create(context) {
const rc = resolveRuleContext(context);
if (!rc) return {};
const { useCaseName, featureRoot } = rc;
const manifest = parseManifestUseCases(manifestPathForFeature(featureRoot));
if (!manifest || !manifest[useCaseName]) return {};
const declared = new Set(manifest[useCaseName].audits);
return {
CallExpression(node) {
if (
node.callee.type === "MemberExpression" &&
node.callee.object.type === "Identifier" &&
node.callee.object.name === "auditLog" &&
node.callee.property.type === "Identifier" &&
node.callee.property.name === "record" &&
node.arguments.length > 0 &&
node.arguments[0].type === "ObjectExpression"
) {
const typeProp = node.arguments[0].properties.find(
(p) =>
p.type === "Property" &&
p.key.type === "Identifier" &&
p.key.name === "type",
);
if (
typeProp &&
typeProp.value.type === "Literal" &&
typeof typeProp.value.value === "string"
) {
const event = typeProp.value.value;
if (!declared.has(event)) {
context.report({
node,
messageId: "undeclared",
data: { event, useCase: useCaseName },
});
}
}
}
},
};
},
};

View File

@@ -0,0 +1,80 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./no-undeclared-audit.js";
function makeFixture({ manifestUseCases, useCaseBody }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nua-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), { recursive: true });
const useCasesObj = Object.entries(manifestUseCases)
.map(([name, uc]) =>
` ${name}: { mutates: ${uc.mutates}, audits: [${uc.audits.map((a) => `"${a}"`).join(", ")}], publishes: [], consumes: [] },`,
)
.join("\n");
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
useCases: {
${useCasesObj}
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
const useCaseFile = path.join(featureDir, "src", "application", "use-cases", "sign-up.use-case.ts");
fs.writeFileSync(useCaseFile, useCaseBody);
return { repoRoot, useCaseFile };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("no-undeclared-audit", () => {
it("passes when auditLog.record type matches manifest audits[]", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: { signUp: { mutates: true, audits: ["user.created"] } },
useCaseBody: `export const signUpUseCase = (auditLog) => async () => { auditLog.record({ type: "user.created", subject: "x", actor: "y" }); };`,
});
tester.run("no-undeclared-audit", rule, {
valid: [{ filename: useCaseFile, code: fs.readFileSync(useCaseFile, "utf8"), options: [{ repoRoot }] }],
invalid: [],
});
});
it("fires when auditLog.record type is not in manifest", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: { signUp: { mutates: true, audits: [] } },
useCaseBody: `export const signUpUseCase = (auditLog) => async () => { auditLog.record({ type: "user.created", subject: "x" }); };`,
});
tester.run("no-undeclared-audit", rule, {
valid: [],
invalid: [{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [{ messageId: "undeclared", data: { event: "user.created", useCase: "signUp" } }],
}],
});
});
it("is a no-op when auditLog.record is called with a non-literal type", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: { signUp: { mutates: true, audits: [] } },
useCaseBody: `export const signUpUseCase = (auditLog, type) => async () => { auditLog.record({ type, subject: "x" }); };`,
});
tester.run("no-undeclared-audit", rule, {
valid: [{ filename: useCaseFile, code: fs.readFileSync(useCaseFile, "utf8"), options: [{ repoRoot }] }],
invalid: [],
});
});
});

View File

@@ -0,0 +1,68 @@
import { parseManifestFully } from "./_manifest-ast.js";
import { manifestPathForFeature } from "./_manifest-source.js";
import { repoRootSchema } from "./_rule-schema.js";
import { resolveRuleContext } from "./_rule-context.js";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "suggestion",
docs: {
description:
'consent.isGranted("X") inside a use-case file must match a category declared in manifest.requiresConsent.',
},
schema: repoRootSchema,
messages: {
undeclared:
'{{useCase}} calls consent.isGranted("{{category}}") but "{{category}}" is not declared in manifest.requiresConsent. Add it to the manifest or remove the call.',
unusedDeclaration:
"{{useCase}} manifest declares requiresConsent but no consent.isGranted() call found in this file. Add consent checks or clear the manifest declaration.",
},
},
create(context) {
const rc = resolveRuleContext(context);
if (!rc) return {};
const { useCaseName, featureRoot } = rc;
const manifest = parseManifestFully(manifestPathForFeature(featureRoot));
if (!manifest) return {};
const requiresConsent = manifest.requiresConsent ?? [];
if (requiresConsent.length === 0) return {};
const declared = new Set(requiresConsent);
let hasConsentCall = false;
return {
CallExpression(node) {
if (
node.callee.type === "MemberExpression" &&
node.callee.object.type === "Identifier" &&
node.callee.object.name === "consent" &&
node.callee.property.type === "Identifier" &&
node.callee.property.name === "isGranted" &&
node.arguments.length > 0 &&
node.arguments[0].type === "Literal" &&
typeof node.arguments[0].value === "string"
) {
hasConsentCall = true;
const category = node.arguments[0].value;
if (!declared.has(category)) {
context.report({
node,
messageId: "undeclared",
data: { category, useCase: useCaseName },
});
}
}
},
"Program:exit"(node) {
if (!hasConsentCall) {
context.report({
node,
messageId: "unusedDeclaration",
data: { useCase: useCaseName },
});
}
},
};
},
};

View File

@@ -0,0 +1,132 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./no-undeclared-consent-check.js";
function makeFixture({ requiresConsent, useCaseBody }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nucc-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), {
recursive: true,
});
const consentField =
requiresConsent.length > 0
? ` requiresConsent: [${requiresConsent.map((c) => `"${c}"`).join(", ")}],\n`
: "";
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
${consentField} useCases: {
checkData: { mutates: false, audits: [], publishes: [], consumes: [] },
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
const useCaseFile = path.join(
featureDir,
"src",
"application",
"use-cases",
"check-data.use-case.ts",
);
fs.writeFileSync(useCaseFile, useCaseBody);
return { repoRoot, useCaseFile };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("no-undeclared-consent-check", () => {
it("passes when consent.isGranted category matches manifest requiresConsent", () => {
const { repoRoot, useCaseFile } = makeFixture({
requiresConsent: ["analytics"],
useCaseBody: `export const checkDataUseCase = (consent) => async () => { if (!consent.isGranted("analytics")) throw new Error(); };`,
});
tester.run("no-undeclared-consent-check", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when category is undeclared or manifest declaration is unused", () => {
const { repoRoot: rootA, useCaseFile: fileA } = makeFixture({
requiresConsent: ["analytics"],
useCaseBody: `export const checkDataUseCase = (consent) => async () => { if (!consent.isGranted("marketing")) throw new Error(); };`,
});
const { repoRoot: rootB, useCaseFile: fileB } = makeFixture({
requiresConsent: ["analytics"],
useCaseBody: `export const checkDataUseCase = () => async () => { return { ok: true }; };`,
});
tester.run("no-undeclared-consent-check", rule, {
valid: [],
invalid: [
{
filename: fileA,
code: fs.readFileSync(fileA, "utf8"),
options: [{ repoRoot: rootA }],
errors: [
{
messageId: "undeclared",
data: { category: "marketing", useCase: "checkData" },
},
],
},
{
filename: fileB,
code: fs.readFileSync(fileB, "utf8"),
options: [{ repoRoot: rootB }],
errors: [
{ messageId: "unusedDeclaration", data: { useCase: "checkData" } },
],
},
],
});
});
it("is a no-op for non-use-case files", () => {
const { repoRoot } = makeFixture({
requiresConsent: ["analytics"],
useCaseBody: `export const checkDataUseCase = (consent) => async () => { consent.isGranted("unknown"); };`,
});
const serviceFile = path.join(
repoRoot,
"packages",
"demo",
"src",
"application",
"services",
"data.service.ts",
);
fs.mkdirSync(path.dirname(serviceFile), { recursive: true });
fs.writeFileSync(
serviceFile,
`export function doWork(consent) { consent.isGranted("unknown"); }`,
);
tester.run("no-undeclared-consent-check", rule, {
valid: [
{
filename: serviceFile,
code: fs.readFileSync(serviceFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
});

View File

@@ -0,0 +1,87 @@
import { parseManifestUseCases } from "./_manifest-ast.js";
import { manifestPathForFeature } from "./_manifest-source.js";
import { repoRootSchema } from "./_rule-schema.js";
import { resolveRuleContext } from "./_rule-context.js";
import { eventNameFromFile, resolveRelativeImport } from "./_event-ast.js";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"bus.publish(event) inside a use-case factory must declare the event in manifest.useCases[name].publishes. Resolves both a string-literal event name and an imported event descriptor (defineEvent(...) or an inline { name } object).",
},
schema: repoRootSchema,
messages: {
undeclared:
'{{useCase}} publishes "{{event}}" via bus.publish but {{event}} is not declared in manifest.useCases.{{useCase}}.publishes. Add it to the manifest or remove the call.',
},
},
create(context) {
const rc = resolveRuleContext(context);
if (!rc) return {};
const { useCaseName, featureRoot } = rc;
const manifest = parseManifestUseCases(manifestPathForFeature(featureRoot));
if (!manifest || !manifest[useCaseName]) return {};
const declared = new Set(manifest[useCaseName].publishes);
// Local import name -> import source string. Populated as `ImportDeclaration`
// nodes are visited; imports always precede the use-case body, so the map
// is complete by the time a `bus.publish` call is reached.
const importSources = new Map();
/**
* Resolve a `bus.publish()` first argument to its event name. Returns null
* when the argument can't be statically analysed — an unresolvable case is
* skipped rather than reported, so the rule never false-positives.
*/
function eventNameFor(arg) {
if (arg.type === "Literal" && typeof arg.value === "string") {
return arg.value;
}
if (arg.type === "Identifier") {
const source = importSources.get(arg.name);
if (!source) return null;
const file = resolveRelativeImport(source, context.filename);
if (!file) return null;
return eventNameFromFile(file, arg.name);
}
return null;
}
return {
ImportDeclaration(node) {
const source = node.source.value;
for (const spec of node.specifiers) {
if (
spec.type === "ImportSpecifier" ||
spec.type === "ImportDefaultSpecifier"
) {
importSources.set(spec.local.name, source);
}
}
},
CallExpression(node) {
if (
node.callee.type === "MemberExpression" &&
node.callee.object.type === "Identifier" &&
node.callee.object.name === "bus" &&
node.callee.property.type === "Identifier" &&
node.callee.property.name === "publish" &&
node.arguments.length > 0
) {
const event = eventNameFor(node.arguments[0]);
if (event === null) return;
if (!declared.has(event)) {
context.report({
node,
messageId: "undeclared",
data: { event, useCase: useCaseName },
});
}
}
},
};
},
};

View File

@@ -0,0 +1,206 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./no-undeclared-event-publish.js";
function makeFixture({ manifestUseCases, useCaseBody, eventFile }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nuep-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), {
recursive: true,
});
const useCasesObj = Object.entries(manifestUseCases)
.map(
([name, uc]) =>
` ${name}: { mutates: ${uc.mutates}, audits: [${uc.audits.map((a) => `"${a}"`).join(", ")}], publishes: [${uc.publishes.map((p) => `"${p}"`).join(", ")}], consumes: [] },`,
)
.join("\n");
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
useCases: {
${useCasesObj}
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
if (eventFile) {
const eventsDir = path.join(featureDir, "src", "events");
fs.mkdirSync(eventsDir, { recursive: true });
fs.writeFileSync(
path.join(eventsDir, eventFile.filename),
eventFile.contents,
);
}
const useCaseFile = path.join(
featureDir,
"src",
"application",
"use-cases",
"sign-up.use-case.ts",
);
fs.writeFileSync(useCaseFile, useCaseBody);
return { repoRoot, useCaseFile };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("no-undeclared-event-publish", () => {
it("passes when bus.publish event name matches manifest publishes[]", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, audits: [], publishes: ["demo.signed-up"] },
},
useCaseBody: `export const signUpUseCase = (bus) => async () => { bus.publish("demo.signed-up", {}); };`,
});
tester.run("no-undeclared-event-publish", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when bus.publish event name is not in manifest", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, audits: [], publishes: [] },
},
useCaseBody: `export const signUpUseCase = (bus) => async () => { bus.publish("demo.signed-up", {}); };`,
});
tester.run("no-undeclared-event-publish", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "undeclared",
data: { event: "demo.signed-up", useCase: "signUp" },
},
],
},
],
});
});
it("is a no-op when bus.publish is called with an unresolvable identifier", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, audits: [], publishes: [] },
},
useCaseBody: `export const signUpUseCase = (bus, name) => async () => { bus.publish(name, {}); };`,
});
tester.run("no-undeclared-event-publish", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("passes when an imported inline event descriptor is declared", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, audits: [], publishes: ["demo.signed-up"] },
},
eventFile: {
filename: "signed-up.event.ts",
contents: `export const signedUpEvent = { name: "demo.signed-up" as const, schema: {} };`,
},
useCaseBody: `import { signedUpEvent } from "../../events/signed-up.event";
export const signUpUseCase = (bus) => async () => { bus.publish(signedUpEvent, {}); };`,
});
tester.run("no-undeclared-event-publish", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when an imported inline event descriptor is not declared", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, audits: [], publishes: [] },
},
eventFile: {
filename: "signed-up.event.ts",
contents: `export const signedUpEvent = { name: "demo.signed-up" as const, schema: {} };`,
},
useCaseBody: `import { signedUpEvent } from "../../events/signed-up.event";
export const signUpUseCase = (bus) => async () => { bus.publish(signedUpEvent, {}); };`,
});
tester.run("no-undeclared-event-publish", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "undeclared",
data: { event: "demo.signed-up", useCase: "signUp" },
},
],
},
],
});
});
it("fires when an imported defineEvent() descriptor is not declared", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestUseCases: {
signUp: { mutates: true, audits: [], publishes: [] },
},
eventFile: {
filename: "signed-up.event.ts",
contents: `export const signedUpEvent = defineEvent("demo.signed-up", {});`,
},
useCaseBody: `import { signedUpEvent } from "../../events/signed-up.event";
export const signUpUseCase = (bus) => async () => { bus.publish(signedUpEvent, {}); };`,
});
tester.run("no-undeclared-event-publish", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "undeclared",
data: { event: "demo.signed-up", useCase: "signUp" },
},
],
},
],
});
});
});

View File

@@ -0,0 +1,67 @@
import { parseManifestUseCases } from "./_manifest-ast.js";
import { manifestPathForFeature } from "./_manifest-source.js";
import { repoRootSchema } from "./_rule-schema.js";
import { resolveRuleContext } from "./_rule-context.js";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "suggestion",
docs: {
description:
'rateLimit.consume("X", _) inside a use-case file must match a budget declared in manifest.useCases[name].rateLimit.',
},
schema: repoRootSchema,
messages: {
undeclared:
'{{useCase}} calls rateLimit.consume("{{budget}}") but "{{budget}}" is not declared in manifest.useCases.{{useCase}}.rateLimit. Add it to the manifest or remove the call.',
unusedDeclaration:
'{{useCase}} declares rateLimit budget "{{budget}}" in the manifest but rateLimit.consume("{{budget}}") is never called in this file. Add the consume call or remove the manifest declaration.',
},
},
create(context) {
const rc = resolveRuleContext(context);
if (!rc) return {};
const { useCaseName, featureRoot } = rc;
const manifest = parseManifestUseCases(manifestPathForFeature(featureRoot));
if (!manifest || !manifest[useCaseName]) return {};
const declared = new Set(manifest[useCaseName].rateLimit ?? []);
const consumed = new Set();
return {
CallExpression(node) {
if (
node.callee.type === "MemberExpression" &&
node.callee.object.type === "Identifier" &&
node.callee.object.name === "rateLimit" &&
node.callee.property.type === "Identifier" &&
node.callee.property.name === "consume" &&
node.arguments.length > 0 &&
node.arguments[0].type === "Literal" &&
typeof node.arguments[0].value === "string"
) {
const budget = node.arguments[0].value;
consumed.add(budget);
if (!declared.has(budget)) {
context.report({
node,
messageId: "undeclared",
data: { budget, useCase: useCaseName },
});
}
}
},
"Program:exit"(node) {
for (const budget of declared) {
if (!consumed.has(budget)) {
context.report({
node,
messageId: "unusedDeclaration",
data: { budget, useCase: useCaseName },
});
}
}
},
};
},
};

View File

@@ -0,0 +1,187 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./no-undeclared-rate-limit.js";
function makeFixture({ manifestRateLimit, useCaseBody }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nurl-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), {
recursive: true,
});
const rateLimitField =
manifestRateLimit.length > 0
? `, rateLimit: [${manifestRateLimit.map((b) => `"${b}"`).join(", ")}]`
: "";
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
useCases: {
signUp: { mutates: true, audits: [], publishes: [], consumes: []${rateLimitField} },
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
const useCaseFile = path.join(
featureDir,
"src",
"application",
"use-cases",
"sign-up.use-case.ts",
);
fs.writeFileSync(useCaseFile, useCaseBody);
return { repoRoot, useCaseFile };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("no-undeclared-rate-limit", () => {
it("passes when rateLimit.consume budget matches manifest rateLimit[]", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestRateLimit: ["signUp.ip"],
useCaseBody: `export const signUpUseCase = (rateLimit) => async (input) => { await rateLimit.consume("signUp.ip", input.ip); };`,
});
tester.run("no-undeclared-rate-limit", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when rateLimit.consume budget is not declared in manifest", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestRateLimit: [],
useCaseBody: `export const signUpUseCase = (rateLimit) => async (input) => { await rateLimit.consume("signUp.ip", input.ip); };`,
});
tester.run("no-undeclared-rate-limit", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "undeclared",
data: { budget: "signUp.ip", useCase: "signUp" },
},
],
},
],
});
});
it("fires when a declared budget is never consumed in the use-case body", () => {
const { repoRoot, useCaseFile } = makeFixture({
manifestRateLimit: ["signUp.ip"],
useCaseBody: `export const signUpUseCase = () => async () => { return { ok: true }; };`,
});
tester.run("no-undeclared-rate-limit", rule, {
valid: [],
invalid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "unusedDeclaration",
data: { budget: "signUp.ip", useCase: "signUp" },
},
],
},
],
});
});
it("passes when rateLimit.consume budget matches a RateLimitBudget object in manifest rateLimit[]", () => {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nurl-obj-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), {
recursive: true,
});
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
useCases: {
signUp: { mutates: true, audits: [], publishes: [], consumes: [], rateLimit: [{ name: "ip", window: "1m", budget: 5 }, { name: "account", window: "1h", budget: 10 }] },
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
const useCaseFile = path.join(
featureDir,
"src",
"application",
"use-cases",
"sign-up.use-case.ts",
);
fs.writeFileSync(
useCaseFile,
`export const signUpUseCase = (rateLimit) => async (input) => {
await rateLimit.consume("ip", input.clientIp);
await rateLimit.consume("account", input.username);
};`,
);
tester.run("no-undeclared-rate-limit", rule, {
valid: [
{
filename: useCaseFile,
code: fs.readFileSync(useCaseFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("is a no-op for non-use-case files", () => {
const { repoRoot } = makeFixture({
manifestRateLimit: ["signUp.ip"],
useCaseBody: `export const signUpUseCase = (rateLimit) => async (input) => { await rateLimit.consume("signUp.ip", input.ip); };`,
});
const serviceFile = path.join(
repoRoot,
"packages",
"demo",
"src",
"application",
"services",
"sign-up.service.ts",
);
fs.mkdirSync(path.dirname(serviceFile), { recursive: true });
fs.writeFileSync(
serviceFile,
`export function doWork(rateLimit) { rateLimit.consume("undeclared", "x"); }`,
);
tester.run("no-undeclared-rate-limit", rule, {
valid: [
{
filename: serviceFile,
code: fs.readFileSync(serviceFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
});

View File

@@ -0,0 +1,57 @@
const REQUIRED_FIELDS = ["category", "purpose", "exportable", "restrictable"];
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"custom.pii blocks in Payload config files must declare all required sub-fields: category, purpose, exportable, restrictable.",
},
schema: [],
messages: {
missingField:
"custom.pii block is missing required field '{{field}}'. Incomplete PII declarations can produce incorrect audit reports.",
},
},
create(context) {
return {
Property(node) {
if (
node.key.type !== "Identifier" ||
node.key.name !== "custom" ||
node.value.type !== "ObjectExpression"
) {
return;
}
const piiProp = node.value.properties.find(
(p) =>
p.type === "Property" &&
p.key.type === "Identifier" &&
p.key.name === "pii",
);
if (!piiProp || piiProp.value.type !== "ObjectExpression") {
return;
}
const presentFields = new Set(
piiProp.value.properties
.filter((p) => p.type === "Property" && p.key.type === "Identifier")
.map((p) => p.key.name),
);
for (const field of REQUIRED_FIELDS) {
if (!presentFields.has(field)) {
context.report({
node: piiProp,
messageId: "missingField",
data: { field },
});
}
}
},
};
},
};

View File

@@ -0,0 +1,163 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import rule from "./pii-declaration-must-be-complete.js";
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("pii-declaration-must-be-complete", () => {
it("passes when custom.pii has all required fields", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [
{
code: `
const field = {
slug: "email",
type: "email",
custom: {
pii: {
category: "contact",
purpose: "authentication",
exportable: false,
restrictable: true,
},
},
};
`,
},
],
invalid: [],
});
});
it("fires when category is missing", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [],
invalid: [
{
code: `
const field = {
custom: {
pii: {
purpose: "authentication",
exportable: false,
restrictable: true,
},
},
};
`,
errors: [{ messageId: "missingField", data: { field: "category" } }],
},
],
});
});
it("fires when purpose is missing", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [],
invalid: [
{
code: `
const field = {
custom: {
pii: {
category: "contact",
exportable: false,
restrictable: true,
},
},
};
`,
errors: [{ messageId: "missingField", data: { field: "purpose" } }],
},
],
});
});
it("fires when exportable is missing", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [],
invalid: [
{
code: `
const field = {
custom: {
pii: {
category: "contact",
purpose: "authentication",
restrictable: true,
},
},
};
`,
errors: [
{ messageId: "missingField", data: { field: "exportable" } },
],
},
],
});
});
it("fires when restrictable is missing", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [],
invalid: [
{
code: `
const field = {
custom: {
pii: {
category: "contact",
purpose: "authentication",
exportable: false,
},
},
};
`,
errors: [
{ messageId: "missingField", data: { field: "restrictable" } },
],
},
],
});
});
it("is a no-op when custom has no pii property", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [
{
code: `
const field = {
custom: {
someOtherProperty: "value",
},
};
`,
},
],
invalid: [],
});
});
it("is a no-op when custom.pii is not an object", () => {
tester.run("pii-declaration-must-be-complete", rule, {
valid: [
{
code: `
const field = {
custom: {
pii: true,
},
};
`,
},
],
invalid: [],
});
});
});

View File

@@ -0,0 +1,68 @@
import fs from "node:fs";
import path from "node:path";
import { readManifestSource } from "./_manifest-source.js";
import { readWorkspacePackages } from "./_workspace.js";
/**
* Check whether `packages/core-<name>` exists under any of the workspace
* globs. The glob set is small and predictable (e.g. ["apps/*", "packages/*"]);
* we simulate matching by checking each glob's directory portion + verifying
* `core-<name>` exists in that directory.
*/
function coreExistsInWorkspace(coreName, repoRoot, packageGlobs) {
for (const glob of packageGlobs) {
const slashStar = glob.endsWith("/*") ? glob.slice(0, -2) : null;
if (!slashStar) continue;
const candidate = path.join(repoRoot, slashStar, `core-${coreName}`);
if (fs.existsSync(candidate)) return true;
}
return false;
}
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Cores declared in a feature.manifest.ts's requiredCores must exist as core-<name> packages within a workspace glob.",
},
schema: [
{
type: "object",
properties: {
repoRoot: { type: "string" },
},
additionalProperties: false,
},
],
messages: {
coreNotInstalled:
"Manifest declares requiredCores: [..., \"{{core}}\", ...] but `core-{{core}}` is not present in any workspace glob. Run `pnpm turbo gen core-package {{core}}` or drop the entry.",
},
},
create(context) {
const opts = context.options[0] ?? {};
const repoRoot = opts.repoRoot ?? context.cwd ?? process.cwd();
return {
Program(node) {
const filename = context.filename;
if (!filename.endsWith("/feature.manifest.ts") && !filename.endsWith("\\feature.manifest.ts")) {
return;
}
const manifest = readManifestSource(filename);
if (!manifest) return;
const globs = readWorkspacePackages(repoRoot);
for (const core of manifest.requiredCores) {
if (!coreExistsInWorkspace(core, repoRoot, globs)) {
context.report({
node,
messageId: "coreNotInstalled",
data: { core },
});
}
}
},
};
},
};

View File

@@ -0,0 +1,95 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./required-cores-installed.js";
function makeFixture({ workspacePackages, manifestCores }) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "rci-"));
fs.writeFileSync(
path.join(repoRoot, "pnpm-workspace.yaml"),
`packages:\n${workspacePackages.map((p) => ` - "${p}"`).join("\n")}\n`,
);
const manifestDir = path.join(repoRoot, "packages", "demo", "src");
fs.mkdirSync(manifestDir, { recursive: true });
// We also need each declared core to exist as a package directory for the glob to resolve.
for (const core of manifestCores) {
fs.mkdirSync(path.join(repoRoot, "packages", `core-${core}`), { recursive: true });
}
const manifest = path.join(manifestDir, "feature.manifest.ts");
fs.writeFileSync(
manifest,
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [${manifestCores.map((c) => `"${c}"`).join(", ")}],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`,
);
return { repoRoot, manifest };
}
const tester = new RuleTester({ languageOptions: { ecmaVersion: "latest", sourceType: "module" } });
describe("required-cores-installed", () => {
it("passes when all declared cores are present as core-<x> packages under a workspace glob", () => {
const { repoRoot, manifest } = makeFixture({
workspacePackages: ["packages/*"],
manifestCores: ["audit", "events"],
});
tester.run("required-cores-installed", rule, {
valid: [
{
filename: manifest,
code: fs.readFileSync(manifest, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires for any declared core that has no matching package", () => {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "rci-"));
fs.writeFileSync(path.join(repoRoot, "pnpm-workspace.yaml"), `packages:\n - "packages/*"\n`);
const manifestDir = path.join(repoRoot, "packages", "demo", "src");
fs.mkdirSync(manifestDir, { recursive: true });
// NB: do NOT create packages/core-realtime — that's the missing one.
fs.mkdirSync(path.join(repoRoot, "packages", "core-audit"), { recursive: true });
const manifest = path.join(manifestDir, "feature.manifest.ts");
fs.writeFileSync(
manifest,
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: ["audit", "realtime"],
useCases: {},
realtimeChannels: [],
jobs: [],
} as const);`,
);
tester.run("required-cores-installed", rule, {
valid: [],
invalid: [
{
filename: manifest,
code: fs.readFileSync(manifest, "utf8"),
options: [{ repoRoot }],
errors: [{ messageId: "coreNotInstalled", data: { core: "realtime" } }],
},
],
});
});
it("is a no-op for files that are not feature.manifest.ts", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rci-"));
const other = path.join(dir, "not-a-manifest.ts");
fs.writeFileSync(other, `export const x = 1;`);
tester.run("required-cores-installed", rule, {
valid: [{ filename: other, code: fs.readFileSync(other, "utf8"), options: [{ repoRoot: dir }] }],
invalid: [],
});
});
});

View File

@@ -0,0 +1,96 @@
import path from "node:path";
import { parseManifestUseCases } from "./_manifest-ast.js";
import {
manifestPathForFeature,
featureRootForFile,
} from "./_manifest-source.js";
/**
* Every manifest-declared use case must be bound through `wireUseCase(...)` in
* the feature's `bind-production.ts` and `bind-dev-seed.ts`. `wireUseCase` is
* the canonical helper that wraps factories with `withSpan` + `withCapture`
* (+ `withAudit` for mutating use cases) and attaches the corresponding
* brands. Skipping it produces an unbranded binding that `assertFeatureConformance`
* will reject at boot — this rule shifts that check from ~3s (boot) to <1s
* (lint), so drift is caught while typing.
*
* Lint-time complement to:
* - the TypeScript brand check (`ProductionUseCase<I,O>` slot type) — compile time
* - the boot-time assertion (`assertFeatureConformance`) — runtime
* - the smoke test (`bind-production.smoke.test.ts`) — CI
*/
const BINDER_BASENAMES = new Set(["bind-production.ts", "bind-dev-seed.ts"]);
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Every manifest use case must be bound through wireUseCase(...) in the feature's bind-production.ts / bind-dev-seed.ts.",
},
schema: [
{
type: "object",
properties: { repoRoot: { type: "string" } },
additionalProperties: false,
},
],
messages: {
missing:
'Use case "{{useCase}}" is declared in {{feature}}.manifest.ts but not wired through wireUseCase({ name: "{{useCase}}", ... }) in this binder. Add the wireUseCase call or remove the manifest entry.',
},
},
create(context) {
const opts = context.options[0] ?? {};
const repoRoot = opts.repoRoot ?? context.cwd ?? process.cwd();
const filename = context.filename;
if (!BINDER_BASENAMES.has(path.basename(filename))) return {};
const featureRoot = featureRootForFile(filename, repoRoot);
if (!featureRoot) return {};
const manifest = parseManifestUseCases(manifestPathForFeature(featureRoot));
if (!manifest) return {};
const declaredNames = Object.keys(manifest);
if (declaredNames.length === 0) return {};
const featureName = path.basename(featureRoot);
const wired = new Set();
return {
CallExpression(node) {
if (
node.callee.type !== "Identifier" ||
node.callee.name !== "wireUseCase"
) {
return;
}
const arg = node.arguments[0];
if (!arg || arg.type !== "ObjectExpression") return;
const nameProp = arg.properties.find(
(p) =>
p.type === "Property" &&
p.key.type === "Identifier" &&
p.key.name === "name",
);
if (
nameProp &&
nameProp.value.type === "Literal" &&
typeof nameProp.value.value === "string"
) {
wired.add(nameProp.value.value);
}
},
"Program:exit"(programNode) {
for (const useCase of declaredNames) {
if (!wired.has(useCase)) {
context.report({
node: programNode,
messageId: "missing",
data: { useCase, feature: featureName },
});
}
}
},
};
},
};

View File

@@ -0,0 +1,172 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./usecase-must-be-wired.js";
function makeFixture({
manifestUseCases,
binderBody,
binderName = "bind-production.ts",
}) {
const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "umbw-"));
const featureDir = path.join(repoRoot, "packages", "demo");
fs.mkdirSync(path.join(featureDir, "src", "di"), { recursive: true });
const useCasesObj = Object.entries(manifestUseCases)
.map(
([name, uc]) =>
` ${name}: { mutates: ${uc.mutates}, audits: [${uc.audits.map((a) => `"${a}"`).join(", ")}], publishes: [], consumes: [] },`,
)
.join("\n");
fs.writeFileSync(
path.join(featureDir, "src", "feature.manifest.ts"),
`export const demoManifest = defineFeature({
name: "demo",
requiredCores: [],
useCases: {
${useCasesObj}
},
realtimeChannels: [],
jobs: [],
} as const);`,
);
const binderFile = path.join(featureDir, "src", "di", binderName);
fs.writeFileSync(binderFile, binderBody);
return { repoRoot, binderFile };
}
const tester = new RuleTester({
languageOptions: {
parser: await import("@typescript-eslint/parser"),
ecmaVersion: "latest",
sourceType: "module",
},
});
describe("usecase-must-be-wired", () => {
it("passes when every manifest use case has a wireUseCase call", () => {
const { repoRoot, binderFile } = makeFixture({
manifestUseCases: {
signIn: { mutates: false, audits: [] },
signUp: { mutates: true, audits: ["user.created"] },
},
binderBody: `
export function bindProductionDemo(ctx) {
wireUseCase({ name: "signIn", factory: signInUseCase });
wireUseCase({ name: "signUp", factory: signUpUseCase });
}
`,
});
tester.run("usecase-must-be-wired", rule, {
valid: [
{
filename: binderFile,
code: fs.readFileSync(binderFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("fires when a manifest use case is missing a wireUseCase call", () => {
const { repoRoot, binderFile } = makeFixture({
manifestUseCases: {
signIn: { mutates: false, audits: [] },
signUp: { mutates: true, audits: [] },
},
binderBody: `
export function bindProductionDemo(ctx) {
wireUseCase({ name: "signIn", factory: signInUseCase });
}
`,
});
tester.run("usecase-must-be-wired", rule, {
valid: [],
invalid: [
{
filename: binderFile,
code: fs.readFileSync(binderFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "missing",
data: { useCase: "signUp", feature: "demo" },
},
],
},
],
});
});
it("also applies to bind-dev-seed.ts", () => {
const { repoRoot, binderFile } = makeFixture({
binderName: "bind-dev-seed.ts",
manifestUseCases: { signIn: { mutates: false, audits: [] } },
binderBody: `
export async function bindDevSeedDemo(ctx) {
// forgot to call wireUseCase
}
`,
});
tester.run("usecase-must-be-wired", rule, {
valid: [],
invalid: [
{
filename: binderFile,
code: fs.readFileSync(binderFile, "utf8"),
options: [{ repoRoot }],
errors: [
{
messageId: "missing",
data: { useCase: "signIn", feature: "demo" },
},
],
},
],
});
});
it("is a no-op on files outside src/di/bind-*.ts", () => {
const { repoRoot } = makeFixture({
manifestUseCases: { signIn: { mutates: false, audits: [] } },
binderBody: `// not a binder`,
});
const otherFile = path.join(
repoRoot,
"packages",
"demo",
"src",
"other.ts",
);
fs.writeFileSync(otherFile, `export const x = 1;`);
tester.run("usecase-must-be-wired", rule, {
valid: [
{
filename: otherFile,
code: fs.readFileSync(otherFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
it("is a no-op when the feature manifest declares no use cases", () => {
const { repoRoot, binderFile } = makeFixture({
manifestUseCases: {},
binderBody: `export function bindProductionDemo(ctx) {}`,
});
tester.run("usecase-must-be-wired", rule, {
valid: [
{
filename: binderFile,
code: fs.readFileSync(binderFile, "utf8"),
options: [{ repoRoot }],
},
],
invalid: [],
});
});
});

View File

@@ -0,0 +1,32 @@
import fs from "node:fs";
/** @type {import("eslint").Rule.RuleModule} */
export default {
meta: {
type: "problem",
docs: {
description:
"Every *.use-case.ts file must have a sibling *.use-case.test.ts (TDD discipline).",
},
schema: [],
messages: {
missingTestFile:
"Use case {{filename}} has no sibling test file at {{expected}}. Write the red test first.",
},
},
create(context) {
return {
Program(node) {
const filename = context.filename;
if (!filename.endsWith(".use-case.ts")) return;
const expected = filename.replace(/\.use-case\.ts$/, ".use-case.test.ts");
if (fs.existsSync(expected)) return;
context.report({
node,
messageId: "missingTestFile",
data: { filename: filename.split("/").pop(), expected: expected.split("/").pop() },
});
},
};
},
};

View File

@@ -0,0 +1,42 @@
import { describe, it } from "vitest";
import { RuleTester } from "eslint";
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import rule from "./usecase-must-have-test-file.js";
function makeUseCaseFixture({ withTest }) {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "umht-"));
const useCase = path.join(dir, "sign-in.use-case.ts");
fs.writeFileSync(useCase, `export const signInUseCase = () => async () => {};`);
if (withTest) {
fs.writeFileSync(path.join(dir, "sign-in.use-case.test.ts"), `import { it } from "vitest"; it("works", () => {});`);
}
return { useCase };
}
const tester = new RuleTester({ languageOptions: { ecmaVersion: "latest", sourceType: "module" } });
describe("usecase-must-have-test-file", () => {
it("passes when a sibling .test.ts exists", () => {
const { useCase } = makeUseCaseFixture({ withTest: true });
tester.run("usecase-must-have-test-file", rule, {
valid: [{ filename: useCase, code: fs.readFileSync(useCase, "utf8") }],
invalid: [],
});
});
it("fires when no sibling test file exists", () => {
const { useCase } = makeUseCaseFixture({ withTest: false });
tester.run("usecase-must-have-test-file", rule, {
valid: [],
invalid: [
{
filename: useCase,
code: fs.readFileSync(useCase, "utf8"),
errors: [{ messageId: "missingTestFile" }],
},
],
});
});
});

View File

@@ -0,0 +1,4 @@
{
"extends": ["//"],
"tags": ["tooling"]
}

View File

@@ -0,0 +1,9 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
globals: true,
environment: "node",
include: ["*.test.js", "rules/*.test.js"],
},
});