@terpjs/eslint-boundaries 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/eslint-boundaries",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "description": "Terp frontend boundary rules (as data) + the ESLint adapter: no cross-module imports, no package internals, design-token-only styling (no style/className/module stylesheets), token-styled components for raw HTML tags, router-only in-app links, generated-client-only, and browser XSS/navigation sink bans. Strict-only (no modes); governed opt-outs via terp-allow markers + the escape-hatch budget ratchet (terp-boundaries-budget).",
   "main": "./src/index.js",
@@ -22,12 +22,12 @@
     "eslint": ">=9"
   },
   "dependencies": {
-    "typescript-eslint": "^8.20.0"
+    "typescript-eslint": "^8.69.0"
   },
   "devDependencies": {
-    "@terpjs/spec": "0.31.0",
-    "eslint": "^10.8.0",
-    "vitest": "^4.1.9"
+    "@terpjs/spec": "0.33.0",
+    "eslint": "^10.10.0",
+    "vitest": "^5.0.0"
   },
   "license": "Apache-2.0",
   "repository": {

package/src/i18n.test.js

@@ -241,6 +241,36 @@ describe("untranslated UI coverage", () => {
     expect(messages.map((message) => message.ruleId)).toContain("terp/no-untranslated-ui");
   });
 
+  it.each([
+    ['<Text>{status === "paused" && <Trans id="w.p" message="Paused" />}</Text>', "==="],
+    ['<Text>{status !== "archived" && <Trans id="w.a" message="Live" />}</Text>', "!=="],
+    ['<Text>{kind == "draft" && <Trans id="w.d" message="Draft" />}</Text>', "=="],
+    ['<Text>{kind != "draft" && <Trans id="w.f" message="Final" />}</Text>', "!="],
+    ['<Text>{stage > "Stage 2" && <Trans id="w.l" message="Late" />}</Text>', ">"],
+    ['<Text>{"paused" === status && <Trans id="w.r" message="Paused" />}</Text>', "reversed"],
+    ['<Page title={"Loading widgets" && loading} />', "&& left operand"],
+  ])("accepts a state token compared in a guard (%s)", async (jsx) => {
+    const messages = await lintWithCatalog(
+      declaration,
+      `export const W = ({ status, kind, stage, loading }) => ${jsx};`,
+    );
+    expect(messages.filter((message) => message.ruleId === "terp/no-untranslated-ui"))
+      .toHaveLength(0);
+  });
+
+  it.each([
+    ['<Page title={loading && "Loading widgets"} />', "&& right operand renders"],
+    ['<Page title={label || "Untitled widget"} />', "|| renders either side"],
+    ['<Page title={label ?? "Untitled widget"} />', "?? renders either side"],
+    ['<Page title={"Page " + index} />', "+ concatenates into copy"],
+  ])("still refuses copy the operator does render (%s)", async (jsx) => {
+    const messages = await lintWithCatalog(
+      declaration,
+      `export const W = ({ loading, label, index }) => ${jsx};`,
+    );
+    expect(messages.map((message) => message.ruleId)).toContain("terp/no-untranslated-ui");
+  });
+
   it("refuses conditional object-property copy and unwraps TypeScript const assertions", async () => {
     const conditional = await lintWithCatalog(
       declaration,

package/src/index.js

@@ -451,6 +451,25 @@ function isStaticDescriptor(node) {
   return staticString(named("id")?.value) !== null && staticString(named("message")?.value) !== null;
 }
 
+/**
+ * Binary operators whose operands are never rendered. The result is a boolean, so an
+ * authored-looking literal on either side is a value being *tested* -- the rule's subject
+ * is "static app-authored UI copy", and a state token compared against is neither authored
+ * copy nor rendered.
+ */
+const NON_RENDERING_COMPARISONS = new Set([
+  "===",
+  "!==",
+  "==",
+  "!=",
+  "<",
+  "<=",
+  ">",
+  ">=",
+  "in",
+  "instanceof",
+]);
+
 /** Authored string fragments in expressions that render or feed a known UiText property. */
 function containsStaticAuthoredCopy(node) {
   const value = unwrapExpression(node);
@@ -465,7 +484,21 @@ function containsStaticAuthoredCopy(node) {
   if (value.type === "ConditionalExpression") {
     return containsStaticAuthoredCopy(value.consequent) || containsStaticAuthoredCopy(value.alternate);
   }
-  if (value.type === "LogicalExpression" || value.type === "BinaryExpression") {
+  if (value.type === "BinaryExpression") {
+    // A comparison renders neither operand: the expression evaluates to a boolean, so the
+    // literal in `status === "paused"` is a state token being tested and never reaches a
+    // screen in any locale. Every other binary operator keeps the broad reading -- `+` is
+    // string concatenation and can render either side.
+    if (NON_RENDERING_COMPARISONS.has(value.operator)) return false;
+    return containsStaticAuthoredCopy(value.left) || containsStaticAuthoredCopy(value.right);
+  }
+  if (value.type === "LogicalExpression") {
+    // `&&` is the same story on one side only: the left operand is the test and the right
+    // is what renders, so `{loading && "Loading"}` is copy and `{"Loading" && loading}`
+    // evaluates to `loading` and is not. `||` and `??` can render either side and keep the
+    // broad reading. This is the distinction the ConditionalExpression branch above already
+    // draws by walking `consequent` / `alternate` and not `test`.
+    if (value.operator === "&&") return containsStaticAuthoredCopy(value.right);
     return containsStaticAuthoredCopy(value.left) || containsStaticAuthoredCopy(value.right);
   }
   if (value.type === "ArrayExpression") {
@@ -879,6 +912,12 @@ const terpPlugin = {
   },
 };
 
+const clipboardMessage =
+  "navigator.clipboard is absent outside a secure context and lib.dom types it as always " +
+  "present, so on an http origin this is a property access on undefined -- a SYNCHRONOUS " +
+  "TypeError that no .catch and no try around an await ever sees. Use copyText or " +
+  "useCopyToClipboard from @terpjs/react-core, which feature-detect, fall back, and " +
+  "report a refusal instead of failing silently.";
 const deepImportMessage =
   "Import from the package root (@terpjs/react-core, @terpjs/contract), not its internals.";
 const styleImportMessage =
@@ -937,10 +976,33 @@ function restrictedSyntaxWithCatalogIds() {
         },
       ]
     : [];
+  const rawClipboard = BOUNDARY_SPEC.restrictRawClipboard
+    ? [
+        {
+          // Any ACCESS, not just a call: `navigator.clipboard.writeText(...)` throws on
+          // the property lookup, so `const c = navigator.clipboard` is the same defect
+          // one line earlier. Matching the member expression covers both, and covers
+          // `readText` and anything else the API grows without naming methods here.
+          catalogId: "frontend/no-raw-clipboard",
+          selector:
+            "MemberExpression[object.name='navigator'][property.name='clipboard'], MemberExpression[object.name='navigator'][computed=true][property.value='clipboard'], MemberExpression[object.type='MemberExpression'][object.object.name=/^(window|globalThis)$/][object.property.name='navigator'][property.name='clipboard'], MemberExpression[object.type='MemberExpression'][object.object.name=/^(window|globalThis)$/][object.computed=true][object.property.value='navigator'][property.name='clipboard']",
+          message: clipboardMessage,
+        },
+        {
+          // The destructuring spelling, which no member-expression selector reaches:
+          // `const { clipboard } = navigator` binds the same undefined under a new name.
+          catalogId: "frontend/no-raw-clipboard",
+          selector:
+            "VariableDeclarator[init.name='navigator'] ObjectPattern > Property[key.name='clipboard'], VariableDeclarator[init.type='MemberExpression'][init.property.name='navigator'] ObjectPattern > Property[key.name='clipboard']",
+          message: clipboardMessage,
+        },
+      ]
+    : [];
   return [
     ...rawElements,
     ...rawAttributes,
     ...inAppAnchors,
+    ...rawClipboard,
     {
       catalogId: "frontend/no-dom-html-injection",
       selector: "JSXAttribute[name.name='dangerouslySetInnerHTML']",

package/src/index.test.js

@@ -152,6 +152,67 @@ describe("terpBoundaries", () => {
     );
   });
 
+  it("flags raw navigator.clipboard (the seam feature-detects; the API does not)", async () => {
+    // Every spelling reaches the same undefined on an http origin. The direct call is
+    // the one that gets written; the others are what it becomes when someone "tidies"
+    // it, and a rule that missed them would push the defect around rather than out.
+    expect(await lint('export const c = () => navigator.clipboard.writeText("x");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint("export const c = () => navigator.clipboard.readText();")).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint('export const c = () => navigator["clipboard"].writeText("x");')).toContain(
+      "no-restricted-syntax",
+    );
+    expect(
+      await lint('export const c = () => window.navigator.clipboard.writeText("x");'),
+    ).toContain("no-restricted-syntax");
+    expect(
+      await lint('export const c = () => globalThis["navigator"].clipboard.writeText("x");'),
+    ).toContain("no-restricted-syntax");
+    // Bound to a name rather than called: the throw already happened on the lookup.
+    expect(await lint("export const c = navigator.clipboard;")).toContain(
+      "no-restricted-syntax",
+    );
+    expect(await lint("export const { clipboard } = navigator;")).toContain(
+      "no-restricted-syntax",
+    );
+  });
+
+  it("accepts the react-core clipboard seam", async () => {
+    // The other half of the rule: it must be satisfiable. A rule whose only compliant
+    // program is one that does not copy anything would be obeyed by dropping the
+    // feature -- so this asserts the sanctioned import is clean, not merely unflagged
+    // by the clipboard selector.
+    expect(
+      await lint(
+        'import { useCopyToClipboard } from "@terpjs/react-core";\n' +
+          "export const useCopy = () => useCopyToClipboard();",
+      ),
+    ).toEqual([]);
+    // A property named `clipboard` on something that is not `navigator` is not this
+    // defect, and flagging it would make the rule a word filter.
+    expect(await lint("export const pick = (o) => o.clipboard;")).toEqual([]);
+  });
+
+  it("honours the clipboard rule's declared escape hatch, and only its own name", async () => {
+    // The catalog entry declares `// terp-allow-no-raw-clipboard: <reason>`, and a
+    // declared opt-out that does not actually suppress is a false promise in the
+    // Standard. Asserted here rather than trusted: the marker resolves through the
+    // catalog rule name, not the ESLint rule id, and several catalog rules share
+    // `no-restricted-syntax` — so this could have silently waived a sibling or nothing.
+    const call = 'export const c = () => navigator.clipboard.writeText("x");';
+    expect(await lint(`// terp-allow-no-raw-clipboard: legacy embed target\n${call}`)).toEqual(
+      [],
+    );
+    // A near-miss name must not waive it, and is itself reported as an unjustified
+    // marker — otherwise a typo would read as compliance.
+    const wrong = await lint(`// terp-allow-no-clipboard: typo\n${call}`);
+    expect(wrong).toContain("no-restricted-syntax");
+    expect(wrong).toContain("terp/escape-hatch");
+  });
+
   it("flags raw browser streaming/beacon request primitives (generated client only)", async () => {
     expect(await lint('export const open = () => new WebSocket("wss://example.com");')).toContain(
       "no-restricted-globals",

package/src/spec.js

@@ -16,7 +16,7 @@
  * NOT by this package's own suite, which certification runs against candidate spec releases
  * whose version is allowed to be newer).
  */
-export const SPEC_VERSION = "0.31.0";
+export const SPEC_VERSION = "0.33.0";
 
 export const BOUNDARY_SPEC = {
   /** Every app-authored TypeScript source file whose user-facing copy must be cataloged. */
@@ -110,6 +110,16 @@ export const BOUNDARY_SPEC = {
   ],
   /** Browser request/stream globals that would skip the audited, typed client. */
   restrictedGlobals: ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"],
+  /**
+   * Refuse `navigator.clipboard` in app code, in every spelling.
+   *
+   * A flag rather than a list because it is one API with one defect, the way
+   * `restrictInAppAnchors` is: the DOM lib types the property as always present and it is
+   * absent outside a secure context, so an access on a plain-http origin is a property
+   * lookup on `undefined` -- a synchronous throw the type checker cannot see. The stack's
+   * `copyText` / `useCopyToClipboard` feature-detect and report a refusal instead.
+   */
+  restrictRawClipboard: true,
   /**
    * The governed escape hatch (the frontend analog of the backend's `# arch-allow-*`): a
    * justified `// terp-allow-<rule>: <reason>` comment on (or immediately above) a violating