Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

👷 Enforce feature folder conventions in CI (#2555)

Luke Vellaac292ffc5dbf
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9d4a43cb9..04cef39d8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -47,6 +47,9 @@ jobs:
- name: Check linting rules
run: pnpm turbo check
+ - name: Check feature folder structure
+ run: pnpm check:structure
+
unit-tests:
name: Unit tests
runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index d8fc90b9f..eb7c63a2e 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,7 @@
"test:unit": "turbo test:unit",
"check": "biome check .",
"check:fix": "biome check . --write",
+ "check:structure": "node scripts/check-feature-structure.mjs && node scripts/check-feature-cycles.mjs",
"i18n:scan": "turbo i18n:scan",
"type-check": "turbo type-check",
"release": "./scripts/create-release.sh",
diff --git a/scripts/check-feature-cycles.mjs b/scripts/check-feature-cycles.mjs
new file mode 100644
index 000000000..b5b194b99
--- /dev/null
+++ b/scripts/check-feature-cycles.mjs
@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * Fails on circular imports between features in apps/web/src/features/.
+ *
+ * Builds a feature-level import graph from `@/features/<name>/...` specifiers
+ * (and relative imports that cross a feature boundary), then reports any
+ * strongly connected component involving more than one feature.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FEATURES_DIR = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ "../apps/web/src/features",
+);
+
+// Feature pairs that are currently cyclic. This list only shrinks — do not
+// add to it. Tracked by RAL-1287 / RAL-1288. Each entry is a sorted
+// "a <-> b" pair; only NEW cycles fail the check.
+const GRANDFATHERED_CYCLES = new Set([
+ "billing <-> space",
+ "branding <-> space",
+]);
+
+const SOURCE_FILE_PATTERN = /\.(ts|tsx)$/;
+const IMPORT_PATTERN =
+ /(?:from|import\s*\(|require\s*\(|^\s*import)\s*["']([^"']+)["']/gm;
+
+function collectSourceFiles(dir, files = []) {
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name.startsWith(".")) {
+ continue;
+ }
+ const absolutePath = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ collectSourceFiles(absolutePath, files);
+ } else if (SOURCE_FILE_PATTERN.test(entry.name)) {
+ files.push(absolutePath);
+ }
+ }
+ return files;
+}
+
+function featureOfPath(absolutePath) {
+ const relativePath = path.relative(FEATURES_DIR, absolutePath);
+ if (relativePath.startsWith("..")) {
+ return null;
+ }
+ return relativePath.split(path.sep)[0];
+}
+
+function featureOfImport({ specifier, importerDir }) {
+ const aliasMatch = specifier.match(/^@\/features\/([^/]+)/);
+ if (aliasMatch) {
+ return aliasMatch[1];
+ }
+ if (specifier.startsWith(".")) {
+ return featureOfPath(path.resolve(importerDir, specifier));
+ }
+ return null;
+}
+
+const edges = new Map();
+
+for (const file of collectSourceFiles(FEATURES_DIR)) {
+ const importerFeature = featureOfPath(file);
+ const source = fs.readFileSync(file, "utf8");
+ for (const match of source.matchAll(IMPORT_PATTERN)) {
+ const importedFeature = featureOfImport({
+ specifier: match[1],
+ importerDir: path.dirname(file),
+ });
+ if (importedFeature && importedFeature !== importerFeature) {
+ if (!edges.has(importerFeature)) {
+ edges.set(importerFeature, new Set());
+ }
+ edges.get(importerFeature).add(importedFeature);
+ }
+ }
+}
+
+// Tarjan's strongly connected components
+let index = 0;
+const nodeIndex = new Map();
+const lowLink = new Map();
+const onStack = new Set();
+const stack = [];
+const cyclicGroups = [];
+
+function strongConnect(node) {
+ nodeIndex.set(node, index);
+ lowLink.set(node, index);
+ index += 1;
+ stack.push(node);
+ onStack.add(node);
+
+ for (const neighbor of edges.get(node) ?? []) {
+ if (!edges.has(neighbor) && !nodeIndex.has(neighbor)) {
+ nodeIndex.set(neighbor, index);
+ lowLink.set(neighbor, index);
+ index += 1;
+ continue;
+ }
+ if (!nodeIndex.has(neighbor)) {
+ strongConnect(neighbor);
+ lowLink.set(node, Math.min(lowLink.get(node), lowLink.get(neighbor)));
+ } else if (onStack.has(neighbor)) {
+ lowLink.set(node, Math.min(lowLink.get(node), nodeIndex.get(neighbor)));
+ }
+ }
+
+ if (lowLink.get(node) === nodeIndex.get(node)) {
+ const group = [];
+ let member;
+ do {
+ member = stack.pop();
+ onStack.delete(member);
+ group.push(member);
+ } while (member !== node);
+ if (group.length > 1) {
+ cyclicGroups.push(group.sort());
+ }
+ }
+}
+
+for (const node of edges.keys()) {
+ if (!nodeIndex.has(node)) {
+ strongConnect(node);
+ }
+}
+
+const newCycles = [];
+for (const group of cyclicGroups) {
+ const pairs = [];
+ for (const a of group) {
+ for (const b of edges.get(a) ?? []) {
+ if (group.includes(b)) {
+ pairs.push([a, b].sort().join(" <-> "));
+ }
+ }
+ }
+ const isGrandfathered = pairs.every((pair) => GRANDFATHERED_CYCLES.has(pair));
+ const label = `[${group.join(", ")}]`;
+ if (isGrandfathered) {
+ console.warn(`Grandfathered feature cycle (tracked by RAL-1287): ${label}`);
+ } else {
+ newCycles.push(label);
+ }
+}
+
+if (newCycles.length > 0) {
+ console.error("Found circular imports between features:\n");
+ for (const cycle of newCycles) {
+ console.error(` ${cycle}`);
+ }
+ console.error(
+ "\nFeatures must not import from each other in both directions.",
+ );
+ console.error(
+ "Break the cycle by extracting shared code or inverting the dependency.",
+ );
+ process.exit(1);
+}
+
+console.log("No new circular imports between features");
diff --git a/scripts/check-feature-structure.mjs b/scripts/check-feature-structure.mjs
new file mode 100644
index 000000000..71e50e11a
--- /dev/null
+++ b/scripts/check-feature-structure.mjs
@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Enforces the file vocabulary for apps/web/src/features/.
+ *
+ * Every feature directory (and any sub-concern directory within it) may only
+ * contain the allowed file names below, co-located tests, and the directories
+ * `components/` and `assets/` (whose contents are unrestricted).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FEATURES_DIR = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ "../apps/web/src/features",
+);
+
+const ALLOWED_FILES = new Set([
+ "data.ts",
+ "mutations.ts",
+ "actions.ts",
+ "schema.ts",
+ "types.ts",
+ "ability.ts",
+ "constants.ts",
+ "utils.ts",
+ "client.tsx",
+]);
+
+const TEST_FILE_PATTERN = /\.test\.tsx?$/;
+
+const UNRESTRICTED_DIRS = new Set(["components", "assets"]);
+
+// Grandfathered exceptions. This list only shrinks — do not add to it.
+// Tracked by RAL-1287 / RAL-1288. Paths are relative to
+// apps/web/src/features/; entries ending in "/" exempt a whole directory.
+const GRANDFATHERED = [
+ "analytics/posthog.ts",
+ "api-keys/api-key.ts",
+ "billing/paywall-store.ts",
+ "billing/portal.ts",
+ "branding/brand-style.tsx",
+ "branding/color.ts",
+ "branding/queries.ts",
+ "calendars/queries.ts",
+ "calendars/service.ts",
+ "calendars/services/",
+ "credentials/queries.ts",
+ "event-types/hooks.ts",
+ "google/service.ts",
+ "instance-settings/queries.ts",
+ "licensing/helpers/",
+ "licensing/lib/",
+ "licensing/server.ts",
+ "moderation/index.ts",
+ "moderation/libs/",
+ "navigation/command-menu/",
+ "navigation/config.tsx",
+ "notifications/queries.ts",
+ "poll/helpers.ts",
+ "poll/query.ts",
+ "quick-create/index.ts",
+ "quick-create/lib/",
+ "quick-create/quick-create-button.tsx",
+ "quick-create/quick-create-widget.tsx",
+ "scheduled-event/predicates.ts",
+ "scheduled-event/registration.ts",
+ "user/queries.ts",
+];
+
+const usedGrandfatherEntries = new Set();
+
+function isGrandfathered(relativePath) {
+ for (const entry of GRANDFATHERED) {
+ if (
+ entry === relativePath ||
+ (entry.endsWith("/") && relativePath.startsWith(entry))
+ ) {
+ usedGrandfatherEntries.add(entry);
+ return true;
+ }
+ }
+ return false;
+}
+
+const offenders = [];
+
+function walk(dir) {
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name.startsWith(".")) {
+ continue;
+ }
+ const absolutePath = path.join(dir, entry.name);
+ const relativePath = path
+ .relative(FEATURES_DIR, absolutePath)
+ .split(path.sep)
+ .join("/");
+ if (entry.isDirectory()) {
+ if (UNRESTRICTED_DIRS.has(entry.name)) {
+ continue;
+ }
+ if (isGrandfathered(`${relativePath}/`)) {
+ continue;
+ }
+ walk(absolutePath);
+ } else if (
+ !ALLOWED_FILES.has(entry.name) &&
+ !TEST_FILE_PATTERN.test(entry.name) &&
+ !isGrandfathered(relativePath)
+ ) {
+ offenders.push(relativePath);
+ }
+ }
+}
+
+for (const entry of fs.readdirSync(FEATURES_DIR, { withFileTypes: true })) {
+ if (entry.name.startsWith(".")) {
+ continue;
+ }
+ if (entry.isDirectory()) {
+ walk(path.join(FEATURES_DIR, entry.name));
+ } else {
+ offenders.push(entry.name);
+ }
+}
+
+const staleEntries = GRANDFATHERED.filter(
+ (entry) => !usedGrandfatherEntries.has(entry),
+);
+if (staleEntries.length > 0) {
+ console.warn(
+ "Warning: stale grandfather entries in scripts/check-feature-structure.mjs (remove them):",
+ );
+ for (const entry of staleEntries) {
+ console.warn(` ${entry}`);
+ }
+}
+
+if (offenders.length > 0) {
+ console.error(
+ `Found ${offenders.length} file(s) in apps/web/src/features/ that don't match the feature folder vocabulary:\n`,
+ );
+ for (const offender of offenders.sort()) {
+ console.error(` apps/web/src/features/${offender}`);
+ }
+ console.error(
+ `\nAllowed files: ${[...ALLOWED_FILES].join(", ")}, *.test.ts, *.test.tsx`,
+ );
+ console.error(
+ "Allowed directories: components/, assets/, or a sub-concern directory following the same vocabulary.",
+ );
+ console.error(
+ "Move the file into components/, rename it to a vocabulary file, or extract it out of features/.",
+ );
+ process.exit(1);
+}
+
+console.log("Feature folder structure OK");