@ethisyscore/eslint-plugin-coreconnect 1.109.0 → 1.111.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethisyscore/eslint-plugin-coreconnect",
-  "version": "1.109.0",
+  "version": "1.111.0",
   "description": "ESLint rules enforcing EthisysCore plugin frontend conventions. Published so a new rule reaches every plugin on a version bump, rather than being copied into each scaffold and drifting.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -9,6 +9,9 @@ import noLocalInProgressBanner from "./rules/no-local-in-progress-banner.js";
 import noLocalMappingEditor from "./rules/no-local-mapping-editor.js";
 import noLocalSearchInput from "./rules/no-local-search-input.js";
 import noParamInNavPath from "./rules/no-param-in-nav-path.js";
+import noSecondMarkdownRenderer, {
+  MARKDOWN_RESTRICTED_IMPORTS,
+} from "./rules/no-second-markdown-renderer.js";
 
 const rules = {
   "no-hardcoded-colors": noHardcodedColors,
@@ -22,6 +25,7 @@ const rules = {
   "no-local-mapping-editor": noLocalMappingEditor,
   "no-local-search-input": noLocalSearchInput,
   "no-param-in-nav-path": noParamInNavPath,
+  "no-second-markdown-renderer": noSecondMarkdownRenderer,
 };
 
 /**
@@ -58,5 +62,30 @@ plugin.configs.recommended = {
   rules: Object.fromEntries(Object.keys(rules).map((name) => [`coreconnect/${name}`, "error"])),
 };
 
+/**
+ * The markdown import bans ship as `coreconnect/no-second-markdown-renderer`, and reach
+ * `recommended` through the mapping above like every other rule — so a plugin still receives them
+ * on a version bump, which was the point of shipping them here at all.
+ *
+ * AT "error", LIKE EVERY OTHER RULE, and deliberately so. The question was asked: a rule that
+ * bans five specifiers outright could turn a repo outside the migration red on its next bump.
+ * Swept the estate for the five before release — hr, legal, timesheets and the plugin template —
+ * and no source file in any of them imports one (hr declares `hast-util-sanitize` and
+ * `rehype-sanitize` in package.json and imports neither, which this rule does not police). The
+ * opt-out is the one every rule here has and which the config comment above describes: turn the
+ * rule off after the spread, where the exemption is visible in the repo that took it.
+ *
+ * They used to be assigned here as the CORE `no-restricted-imports` rule, and that was a foot-gun.
+ * Flat-config rule entries REPLACE, they do not merge: a consumer configuring `no-restricted-imports`
+ * for its own import policy silently dropped all five bans, and a file turning that rule off for an
+ * unrelated reason turned the markdown bans off with it. The cost was visible downstream as the same
+ * five paths restated in three config blocks with a comment explaining the collision.
+ *
+ * The paths list is still exported, unchanged, for a consumer that wants these as core
+ * `no-restricted-imports` paths alongside its own. The rule module owns it, so the list a consumer
+ * restates and the list the rule enforces cannot name different modules.
+ */
+export { MARKDOWN_RESTRICTED_IMPORTS };
+
 export default plugin;
 export { rules };

package/src/rules/no-second-markdown-renderer.js

@@ -0,0 +1,131 @@
+/**
+ * Disallow importing any module that would build a second markdown renderer.
+ *
+ * The markdown renderer is a single shared component, and the property that makes it safe is that
+ * `rehype-sanitize` runs LAST in its rehype chain. That ordering is structurally enforced inside
+ * `@ethisyscore/plugin-ui/markdown` - the only module permitted to import the sanitizer.
+ *
+ * These bans exist because the historical failure mode was not "someone reordered the chain"; it
+ * was "someone wrote a sixth renderer". Five renderers and five copies of a sanitize schema had
+ * drifted across six repositories before this consolidation. A lint rule is what stops the next one
+ * being written, since the shared component cannot police code that never calls it.
+ *
+ * WHY THIS IS A NAMESPACED RULE AND NOT CORE `no-restricted-imports`. Flat-config rule entries
+ * REPLACE, they do not merge: shipping the bans as the core rule meant any consumer that configured
+ * `no-restricted-imports` for its own import policy silently dropped all five, and any file that
+ * turned that rule off - `src/icons/index.ts` in the web host, for one - turned the markdown bans
+ * off with it. The cost was already visible downstream as the same five paths restated in three
+ * config blocks with a comment explaining the collision. Under its own name the rule composes with
+ * whatever import policy a consumer writes, instead of racing it.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+
+/**
+ * The banned module ids and why each is banned. Data, not prose: the same list drives the rule's
+ * reports and is exported for a consumer that still wants these as core `no-restricted-imports`
+ * paths, so the two cannot name different modules.
+ */
+export const MARKDOWN_RESTRICTED_IMPORTS = [
+  {
+    name: "react-markdown",
+    message:
+      "Render markdown through MarkdownView from @ethisyscore/plugin-ui/markdown. A local react-markdown call site owns its own plugin ordering, which is the bug this package removes.",
+  },
+  {
+    name: "rehype-sanitize",
+    message:
+      "The sanitize chain is owned by @ethisyscore/plugin-ui/markdown (pipeline.ts). Widen it with a MarkdownCapability.extendSchema instead of assembling a second chain.",
+  },
+  {
+    name: "hast-util-sanitize",
+    message:
+      "The sanitize schema is owned by @ethisyscore/plugin-ui/markdown. Import MarkdownSanitizeSchema from there if you need the type.",
+  },
+  {
+    name: "rehype-raw",
+    message: "Never. Raw HTML is not rendered - MarkdownView sets skipHtml and has no raw-HTML seam.",
+  },
+  {
+    name: "ds-markdown",
+    message:
+      "Removed. Use MarkdownView from @ethisyscore/plugin-ui/markdown; ds-markdown routed sanitize through an ordered plugins array and dragged react-router-dom into the bundle.",
+  },
+];
+
+/**
+ * A subpath counts. `react-markdown/lib/ast-to-react` is the same renderer reached the long way
+ * round, and core `no-restricted-imports` `paths` would have walked past it.
+ */
+function bannedEntry(source) {
+  return MARKDOWN_RESTRICTED_IMPORTS.find(
+    (entry) => source === entry.name || source.startsWith(`${entry.name}/`),
+  );
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing react-markdown, rehype-sanitize, hast-util-sanitize, rehype-raw or ds-markdown - render through MarkdownView",
+    },
+    // One id carrying the entry's own message, so the reason a module is banned lives beside the
+    // ban rather than in a parallel table that drifts from it.
+    messages: { noSecondMarkdownRenderer: "{{why}}" },
+    schema: [],
+  },
+  create(context) {
+    const report = (node, source) => {
+      const entry = bannedEntry(source);
+      if (entry) {
+        context.report({ node, messageId: "noSecondMarkdownRenderer", data: { why: entry.message } });
+      }
+    };
+
+    // `export { x } from` has a null source when it re-exports nothing; a non-literal source is a
+    // computed specifier, which cannot be resolved statically and would be a guess to report.
+    const fromSource = (node) => {
+      if (node.source && node.source.type === "Literal" && typeof node.source.value === "string") {
+        report(node.source, node.source.value);
+      }
+    };
+
+    return {
+      ImportDeclaration: fromSource,
+      ExportNamedDeclaration: fromSource,
+      ExportAllDeclaration: fromSource,
+      // `await import("react-markdown")`. Espree parses this as an ImportExpression, NOT a
+      // CallExpression with an `Import` callee, so a CallExpression-only rule walks past the one
+      // form a call site reaches for when it wants to dodge a static-import lint rule.
+      ImportExpression: fromSource,
+      // `import md = require("react-markdown")`. Under @typescript-eslint/parser this is a
+      // TSImportEqualsDeclaration holding a TSExternalModuleReference, so it is neither an
+      // ImportDeclaration nor a CallExpression and every other visitor here walks past it. The
+      // SDK's own structural guard (singleImporter.test.ts) reads this form; that guard only
+      // scans the SDK's own source, and this rule is the half of the pair that faces the
+      // consumer repositories — so it must not be the weaker half. Narrow in practice (the form
+      // is unusable in an ESM package) and wide in principle, which is the cheapest kind of gap
+      // to close.
+      TSImportEqualsDeclaration(node) {
+        const reference = node.moduleReference;
+        if (!reference || reference.type !== "TSExternalModuleReference") return;
+
+        const { expression } = reference;
+        if (expression && expression.type === "Literal" && typeof expression.value === "string") {
+          report(expression, expression.value);
+        }
+      },
+      // `require("react-markdown")`. Reaching the module at runtime has the same ordering problem
+      // as reaching it statically.
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || node.callee.name !== "require") return;
+
+        const [argument] = node.arguments;
+        if (argument && argument.type === "Literal" && typeof argument.value === "string") {
+          report(argument, argument.value);
+        }
+      },
+    };
+  },
+};