@stardeck-customer-apps/eslint-plugin 1.5.0 → 1.6.0

package/SKILL.md

@@ -116,6 +116,28 @@ install rail. Only the direct specifier is checked — it does not prove the
 entry's full import graph never reaches server code (that's the real Next
 client-build seam's job) — so do not add exemptions here to work around it.
 
+### `rail-marker-congruent`
+
+A `// @stardeck-module-rail-generated ...` first line means the module install
+rail owns the file. The marker's kind must match the file's path shape:
+`scope=root` / `scope=enhancement:<peer>` only on `src/app/api/**/route.ts`,
+`scope=route path=<route>` only on `src/app/<route>/page.tsx` with a matching
+`path=`, and the ownerless scopes only on their `src/*.gen.ts` file. The five `src/*.gen.ts`
+files must always carry their marker; a marker-less one is reported too.
+
+```ts
+// src/app/(admin)/admin/finance/assets/page.tsx — Bad
+// @stardeck-module-rail-generated owner=finance scope=root
+
+// src/app/(admin)/admin/finance/assets/page.tsx — Good
+// @stardeck-module-rail-generated owner=finance scope=route path=(admin)/admin/finance/assets
+```
+
+**Why?** Blueprint publish regenerates module artifacts and fails closed on a
+swapped marker ("incongruent marker at ... refusing to reconcile"). Catching it
+at lint time is faster than a failed publish. Fix by deleting the marker line if
+the file is hand-written, or restoring the generated stub.
+
 ## Disable for a Line
 
 ```tsx

package/dist/index.cjs

@@ -560,12 +560,157 @@ var rule4 = {
 };
 var no_server_import_in_conventional_entry_default = rule4;
 
+// src/rules/rail-marker-congruent.ts
+var import_node_path3 = __toESM(require("path"), 1);
+var MARKER = "@stardeck-module-rail-generated";
+var MARKER_RE = new RegExp(
+  `^//\\s*${MARKER}\\s+(?:owner=([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\\s+)?scope=(\\S+)(?:\\s+path=(.+))?$`
+);
+var OWNERLESS_SCOPES = {
+  registry: "registry",
+  contributions: "contributions",
+  datastores: "datastores",
+  i18n: "i18n",
+  init: "init"
+};
+var GEN_FILE_KINDS = {
+  "modules.gen.ts": "registry",
+  "module-contributions.gen.ts": "contributions",
+  "module-datastores.gen.ts": "datastores",
+  "module-i18n.gen.ts": "i18n",
+  "module-init.server.gen.ts": "init"
+};
+var METHODS = "GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS";
+var OWNER = "[a-z][a-z0-9]*(?:-[a-z0-9]+)*";
+function isLegacyApiAdapterBody(source, owner) {
+  const lines = source.replace(/\r\n/g, "\n").split("\n").slice(1).map((line) => line.trim()).filter(Boolean);
+  const importMatch = lines[0]?.match(
+    new RegExp(
+      `^import \\{ (endpointHandlers|production(?:[A-Z][A-Za-z0-9]*)?Handlers) \\} from "(@/modules/${owner}/server|@/modules/${owner}/enhancements/${OWNER}|@/lib/${owner}-wiring)";$`
+    )
+  );
+  if (!importMatch) return false;
+  const binding = importMatch[1];
+  const exports2 = lines.slice(1);
+  return exports2.length > 0 && exports2.every(
+    (line) => new RegExp(`^export const (${METHODS}) = ${binding}\\.\\1_[A-Za-z0-9_]+;$`).test(line)
+  );
+}
+function isLegacyRouteAdapterBody(source, routePath) {
+  return new RegExp(
+    `^// ${MARKER} scope=routes
+/\\*\\* DO NOT EDIT \u2014 owned by the module install rail\\. \\*/
+export \\{ default \\} from "@/modules/${OWNER}/routes/${routePath.replace(/[.*+?^$()[\]{}|]/g, "\\$&")}/page";
+?$`
+  ).test(source.replace(/\r\n/g, "\n"));
+}
+function parseMarker(source) {
+  const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  const match = firstLine.match(MARKER_RE);
+  if (!match) return null;
+  const [, owner, scope, routePath] = match;
+  const ownerless = OWNERLESS_SCOPES[scope];
+  if (ownerless) return owner ? null : { kind: ownerless };
+  if (scope === "routes") return owner ? null : { kind: "route", legacyRoute: true };
+  if (!owner) return null;
+  if (scope === "route") {
+    const trimmed = routePath?.trim();
+    return trimmed ? { kind: "route", routePath: trimmed, owner } : null;
+  }
+  if (scope === "root" || scope.startsWith("enhancement:")) return { kind: "endpoint", owner };
+  return null;
+}
+function shapeForPath(filename) {
+  const posix = filename.split(import_node_path3.default.sep).join("/");
+  const gen = posix.match(/\/src\/([^/]+\.gen\.ts)$/);
+  if (gen) {
+    const kind = GEN_FILE_KINDS[gen[1]];
+    return kind ? { kind } : null;
+  }
+  const idx = posix.lastIndexOf("/src/app/");
+  if (idx < 0) return null;
+  const rest = posix.slice(idx + "/src/app/".length);
+  if (rest.startsWith("api/")) {
+    const m2 = rest.match(/^(.+)\/route\.ts$/);
+    return m2 ? { kind: "endpoint", routePath: m2[1] } : null;
+  }
+  const m = rest.match(/^(?:(.*)\/)?page\.(?:tsx|ts|jsx|js)$/);
+  return m ? { kind: "route", routePath: m[1] ?? "" } : null;
+}
+var rule5 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require a @stardeck-module-rail-generated marker to match the file's path shape, so Blueprint publish can reconcile the file",
+      recommended: true
+    },
+    messages: {
+      wrongKind: "Found a {{found}} rail marker on a path shaped for {{expected}} artifacts. Blueprint publish will refuse to reconcile a swapped marker. Delete the marker line if this file is hand-written, or restore the generated stub.",
+      missingMarker: "Generated file {{file}} has no @stardeck-module-rail-generated marker on line 1. Blueprint publish will refuse to overwrite it as unmanaged. Restore the marker line (or the whole generated file) rather than editing it by hand.",
+      legacyRouteBody: "Rail marker scope=routes is only valid with its original body: the DO NOT EDIT line and a single default re-export of this route's page from its Module. Blueprint publish treats anything else as unmanaged. Delete the marker line if this file is hand-written, or restore the generated stub.",
+      wrongRoutePath: 'Rail route marker claims path="{{claimed}}" but this file serves "{{actual}}". Blueprint publish will refuse to reconcile it. Delete the marker line if this file is hand-written, or restore the generated stub.'
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = context.filename;
+    if (!filename || filename === "<input>" || filename === "<text>") return {};
+    const shape = shapeForPath(filename);
+    if (!shape) return {};
+    return {
+      Program(node) {
+        const marker = parseMarker(context.sourceCode.text);
+        const loc = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
+        if (!marker) {
+          if (GEN_FILE_KINDS[import_node_path3.default.basename(filename)]) {
+            context.report({
+              node,
+              loc,
+              messageId: "missingMarker",
+              data: { file: import_node_path3.default.basename(filename) }
+            });
+          }
+          return;
+        }
+        if (marker.kind !== shape.kind) {
+          if (shape.kind === "endpoint" && marker.kind === "route" && marker.routePath === shape.routePath && isLegacyApiAdapterBody(context.sourceCode.text, marker.owner)) {
+            return;
+          }
+          context.report({
+            node,
+            loc,
+            messageId: "wrongKind",
+            data: { found: marker.kind, expected: shape.kind }
+          });
+          return;
+        }
+        if (marker.legacyRoute) {
+          if (!isLegacyRouteAdapterBody(context.sourceCode.text, shape.routePath ?? "")) {
+            context.report({ node, loc, messageId: "legacyRouteBody" });
+          }
+          return;
+        }
+        if (marker.kind === "route" && marker.routePath !== shape.routePath) {
+          context.report({
+            node,
+            loc,
+            messageId: "wrongRoutePath",
+            data: { claimed: marker.routePath ?? "", actual: shape.routePath ?? "" }
+          });
+        }
+      }
+    };
+  }
+};
+var rail_marker_congruent_default = rule5;
+
 // src/rules/index.ts
 var rules = {
   "no-template-literal-classname": no_template_literal_classname_default,
   "no-kysely-interactive-transaction": no_kysely_interactive_transaction_default,
   "no-module-internal-import": no_module_internal_import_default,
-  "no-server-import-in-conventional-entry": no_server_import_in_conventional_entry_default
+  "no-server-import-in-conventional-entry": no_server_import_in_conventional_entry_default,
+  "rail-marker-congruent": rail_marker_congruent_default
 };
 
 // src/configs/recommended.ts
@@ -580,7 +725,8 @@ var recommended = {
     [`${pluginName}/no-template-literal-classname`]: "error",
     [`${pluginName}/no-kysely-interactive-transaction`]: "error",
     [`${pluginName}/no-module-internal-import`]: "error",
-    [`${pluginName}/no-server-import-in-conventional-entry`]: "error"
+    [`${pluginName}/no-server-import-in-conventional-entry`]: "error",
+    [`${pluginName}/rail-marker-congruent`]: "error"
   }
 };
 

package/dist/index.d.cts

@@ -6,6 +6,7 @@ declare const rules: {
     "no-kysely-interactive-transaction": eslint.Rule.RuleModule;
     "no-module-internal-import": eslint.Rule.RuleModule;
     "no-server-import-in-conventional-entry": eslint.Rule.RuleModule;
+    "rail-marker-congruent": eslint.Rule.RuleModule;
 };
 
 declare const configs: Record<string, Linter.Config>;

package/dist/index.d.ts

@@ -6,6 +6,7 @@ declare const rules: {
     "no-kysely-interactive-transaction": eslint.Rule.RuleModule;
     "no-module-internal-import": eslint.Rule.RuleModule;
     "no-server-import-in-conventional-entry": eslint.Rule.RuleModule;
+    "rail-marker-congruent": eslint.Rule.RuleModule;
 };
 
 declare const configs: Record<string, Linter.Config>;

package/dist/index.js

@@ -522,12 +522,157 @@ var rule4 = {
 };
 var no_server_import_in_conventional_entry_default = rule4;
 
+// src/rules/rail-marker-congruent.ts
+import path3 from "path";
+var MARKER = "@stardeck-module-rail-generated";
+var MARKER_RE = new RegExp(
+  `^//\\s*${MARKER}\\s+(?:owner=([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\\s+)?scope=(\\S+)(?:\\s+path=(.+))?$`
+);
+var OWNERLESS_SCOPES = {
+  registry: "registry",
+  contributions: "contributions",
+  datastores: "datastores",
+  i18n: "i18n",
+  init: "init"
+};
+var GEN_FILE_KINDS = {
+  "modules.gen.ts": "registry",
+  "module-contributions.gen.ts": "contributions",
+  "module-datastores.gen.ts": "datastores",
+  "module-i18n.gen.ts": "i18n",
+  "module-init.server.gen.ts": "init"
+};
+var METHODS = "GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS";
+var OWNER = "[a-z][a-z0-9]*(?:-[a-z0-9]+)*";
+function isLegacyApiAdapterBody(source, owner) {
+  const lines = source.replace(/\r\n/g, "\n").split("\n").slice(1).map((line) => line.trim()).filter(Boolean);
+  const importMatch = lines[0]?.match(
+    new RegExp(
+      `^import \\{ (endpointHandlers|production(?:[A-Z][A-Za-z0-9]*)?Handlers) \\} from "(@/modules/${owner}/server|@/modules/${owner}/enhancements/${OWNER}|@/lib/${owner}-wiring)";$`
+    )
+  );
+  if (!importMatch) return false;
+  const binding = importMatch[1];
+  const exports = lines.slice(1);
+  return exports.length > 0 && exports.every(
+    (line) => new RegExp(`^export const (${METHODS}) = ${binding}\\.\\1_[A-Za-z0-9_]+;$`).test(line)
+  );
+}
+function isLegacyRouteAdapterBody(source, routePath) {
+  return new RegExp(
+    `^// ${MARKER} scope=routes
+/\\*\\* DO NOT EDIT \u2014 owned by the module install rail\\. \\*/
+export \\{ default \\} from "@/modules/${OWNER}/routes/${routePath.replace(/[.*+?^$()[\]{}|]/g, "\\$&")}/page";
+?$`
+  ).test(source.replace(/\r\n/g, "\n"));
+}
+function parseMarker(source) {
+  const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  const match = firstLine.match(MARKER_RE);
+  if (!match) return null;
+  const [, owner, scope, routePath] = match;
+  const ownerless = OWNERLESS_SCOPES[scope];
+  if (ownerless) return owner ? null : { kind: ownerless };
+  if (scope === "routes") return owner ? null : { kind: "route", legacyRoute: true };
+  if (!owner) return null;
+  if (scope === "route") {
+    const trimmed = routePath?.trim();
+    return trimmed ? { kind: "route", routePath: trimmed, owner } : null;
+  }
+  if (scope === "root" || scope.startsWith("enhancement:")) return { kind: "endpoint", owner };
+  return null;
+}
+function shapeForPath(filename) {
+  const posix = filename.split(path3.sep).join("/");
+  const gen = posix.match(/\/src\/([^/]+\.gen\.ts)$/);
+  if (gen) {
+    const kind = GEN_FILE_KINDS[gen[1]];
+    return kind ? { kind } : null;
+  }
+  const idx = posix.lastIndexOf("/src/app/");
+  if (idx < 0) return null;
+  const rest = posix.slice(idx + "/src/app/".length);
+  if (rest.startsWith("api/")) {
+    const m2 = rest.match(/^(.+)\/route\.ts$/);
+    return m2 ? { kind: "endpoint", routePath: m2[1] } : null;
+  }
+  const m = rest.match(/^(?:(.*)\/)?page\.(?:tsx|ts|jsx|js)$/);
+  return m ? { kind: "route", routePath: m[1] ?? "" } : null;
+}
+var rule5 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require a @stardeck-module-rail-generated marker to match the file's path shape, so Blueprint publish can reconcile the file",
+      recommended: true
+    },
+    messages: {
+      wrongKind: "Found a {{found}} rail marker on a path shaped for {{expected}} artifacts. Blueprint publish will refuse to reconcile a swapped marker. Delete the marker line if this file is hand-written, or restore the generated stub.",
+      missingMarker: "Generated file {{file}} has no @stardeck-module-rail-generated marker on line 1. Blueprint publish will refuse to overwrite it as unmanaged. Restore the marker line (or the whole generated file) rather than editing it by hand.",
+      legacyRouteBody: "Rail marker scope=routes is only valid with its original body: the DO NOT EDIT line and a single default re-export of this route's page from its Module. Blueprint publish treats anything else as unmanaged. Delete the marker line if this file is hand-written, or restore the generated stub.",
+      wrongRoutePath: 'Rail route marker claims path="{{claimed}}" but this file serves "{{actual}}". Blueprint publish will refuse to reconcile it. Delete the marker line if this file is hand-written, or restore the generated stub.'
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = context.filename;
+    if (!filename || filename === "<input>" || filename === "<text>") return {};
+    const shape = shapeForPath(filename);
+    if (!shape) return {};
+    return {
+      Program(node) {
+        const marker = parseMarker(context.sourceCode.text);
+        const loc = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
+        if (!marker) {
+          if (GEN_FILE_KINDS[path3.basename(filename)]) {
+            context.report({
+              node,
+              loc,
+              messageId: "missingMarker",
+              data: { file: path3.basename(filename) }
+            });
+          }
+          return;
+        }
+        if (marker.kind !== shape.kind) {
+          if (shape.kind === "endpoint" && marker.kind === "route" && marker.routePath === shape.routePath && isLegacyApiAdapterBody(context.sourceCode.text, marker.owner)) {
+            return;
+          }
+          context.report({
+            node,
+            loc,
+            messageId: "wrongKind",
+            data: { found: marker.kind, expected: shape.kind }
+          });
+          return;
+        }
+        if (marker.legacyRoute) {
+          if (!isLegacyRouteAdapterBody(context.sourceCode.text, shape.routePath ?? "")) {
+            context.report({ node, loc, messageId: "legacyRouteBody" });
+          }
+          return;
+        }
+        if (marker.kind === "route" && marker.routePath !== shape.routePath) {
+          context.report({
+            node,
+            loc,
+            messageId: "wrongRoutePath",
+            data: { claimed: marker.routePath ?? "", actual: shape.routePath ?? "" }
+          });
+        }
+      }
+    };
+  }
+};
+var rail_marker_congruent_default = rule5;
+
 // src/rules/index.ts
 var rules = {
   "no-template-literal-classname": no_template_literal_classname_default,
   "no-kysely-interactive-transaction": no_kysely_interactive_transaction_default,
   "no-module-internal-import": no_module_internal_import_default,
-  "no-server-import-in-conventional-entry": no_server_import_in_conventional_entry_default
+  "no-server-import-in-conventional-entry": no_server_import_in_conventional_entry_default,
+  "rail-marker-congruent": rail_marker_congruent_default
 };
 
 // src/configs/recommended.ts
@@ -542,7 +687,8 @@ var recommended = {
     [`${pluginName}/no-template-literal-classname`]: "error",
     [`${pluginName}/no-kysely-interactive-transaction`]: "error",
     [`${pluginName}/no-module-internal-import`]: "error",
-    [`${pluginName}/no-server-import-in-conventional-entry`]: "error"
+    [`${pluginName}/no-server-import-in-conventional-entry`]: "error",
+    [`${pluginName}/rail-marker-congruent`]: "error"
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/eslint-plugin",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Custom ESLint rules for Stardeck customer apps",
   "type": "module",
   "main": "dist/index.js",