@augmenting-integrations/eslint-plugin 4.0.1

package/README.md

@@ -0,0 +1,58 @@
+# @augmenting-integrations/eslint-plugin
+
+ESLint rules for Augmenting Integrations Next.js apps under path-routing.
+
+## Install
+
+```bash
+pnpm add -D @augmenting-integrations/eslint-plugin
+```
+
+## Use (flat config, ESLint 9+)
+
+```js
+// eslint.config.mjs
+import auginiPlugin from "@augmenting-integrations/eslint-plugin";
+
+export default [
+  // ... your other configs
+  {
+    plugins: { "@augmenting-integrations": auginiPlugin },
+    rules: {
+      "@augmenting-integrations/no-hardcoded-internal-paths": [
+        "error",
+        { basePath: "/leads-marketplace" },
+      ],
+    },
+  },
+];
+```
+
+For an apex app with no basePath, omit the option (or pass `basePath: "/"`) — the rule becomes a no-op.
+
+## Rules
+
+### `no-hardcoded-internal-paths`
+
+Flags hardcoding the current app's basePath in `href` attributes. Under Next.js `basePath`, `<Link>` prepends it automatically; a raw `<a>` for an in-app link is wrong and a `<Link href>` that includes the basePath produces a doubled-prefix path.
+
+```jsx
+// App with basePath: "/leads-marketplace"
+
+// ❌ Flagged: <Link> would render /leads-marketplace/leads-marketplace/foo
+<Link href="/leads-marketplace/foo">In-app</Link>
+
+// ❌ Flagged: raw <a> won't get basePath, so it's wrong for in-app
+<a href="/leads-marketplace/foo">In-app</a>
+
+// ✅ Allowed: <Link> renders /leads-marketplace/foo
+<Link href="/foo">In-app</Link>
+
+// ✅ Allowed: cross-app link to peer app's basePath; raw <a> is correct here
+<a href="/quotes/dashboard">Cross-app</a>
+
+// ✅ Allowed: external URL
+<a href="https://example.com/external">External</a>
+```
+
+The rule is configurable per-app: each tenant repo passes its own `basePath` in `eslint.config.mjs`.

package/dist/index.cjs

@@ -0,0 +1,99 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rules/no-hardcoded-internal-paths.ts
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow hardcoding the current app's basePath in href attributes. Under Next.js basePath, <Link> prepends it automatically; raw <a> with the basePath in it produces a doubled-prefix path.",
+      recommended: true
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          basePath: {
+            type: "string",
+            description: "The current app's basePath, e.g. '/leads-marketplace'. The rule is a no-op for apex apps (basePath unset or '/')."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      hardcodedBasePath: "Hardcoded basePath '{{ basePath }}' in href '{{ path }}'. For in-app navigation, use <Link href='{{ stripped }}'> \u2014 Next.js prepends '{{ basePath }}' automatically. For cross-app navigation, the href should NOT start with '{{ basePath }}'."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const basePath = options.basePath;
+    if (!basePath || basePath === "/" || basePath === "") {
+      return {};
+    }
+    const prefix = basePath.endsWith("/") ? basePath : basePath + "/";
+    return {
+      JSXAttribute(node) {
+        const attr = node;
+        if (attr.name?.name !== "href") return;
+        const value = attr.value;
+        if (!value || value.type !== "Literal") return;
+        const v = value.value;
+        if (typeof v !== "string") return;
+        if (v !== basePath && !v.startsWith(prefix)) return;
+        const stripped = v === basePath ? "/" : "/" + v.slice(prefix.length);
+        context.report({
+          node: value,
+          messageId: "hardcodedBasePath",
+          data: { basePath, path: v, stripped }
+        });
+      }
+    };
+  }
+};
+var no_hardcoded_internal_paths_default = rule;
+
+// src/index.ts
+var plugin = {
+  meta: {
+    name: "@augmenting-integrations/eslint-plugin",
+    version: "4.0.1"
+  },
+  rules: {
+    "no-hardcoded-internal-paths": no_hardcoded_internal_paths_default
+  },
+  configs: {}
+};
+plugin.configs = {
+  recommended: {
+    plugins: { "@augmenting-integrations": plugin },
+    rules: {
+      "@augmenting-integrations/no-hardcoded-internal-paths": "error"
+    }
+  }
+};
+var index_default = plugin;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/rules/no-hardcoded-internal-paths.ts"],"sourcesContent":["// ESLint plugin for Augmenting Integrations Next.js apps.\n//\n// The flagship rule, `no-hardcoded-internal-paths`, prevents the most common\n// subpath-routing failure mode: a contributor writes `<a href=\"/leads/foo\">`\n// thinking it'll be a normal link, but under Next.js basePath=\"/leads\" that\n// renders as `/leads/leads/foo` and 404s. Worse, in dev (basePath often \"/\")\n// it works fine, so the bug only surfaces in deployed environments.\n//\n// The fix in source is to use <Link> from next/link or useRouter().push(),\n// both of which are basePath-aware. This rule flags the raw-anchor pattern\n// at lint time so it never reaches review.\n\nimport noHardcodedInternalPaths from \"./rules/no-hardcoded-internal-paths.js\";\n\nconst plugin = {\n  meta: {\n    name: \"@augmenting-integrations/eslint-plugin\",\n    version: \"4.0.1\",\n  },\n  rules: {\n    \"no-hardcoded-internal-paths\": noHardcodedInternalPaths,\n  },\n  configs: {} as Record<string, unknown>,\n};\n\n// Recommended config (flat config style — ESLint 9+).\nplugin.configs = {\n  recommended: {\n    plugins: { \"@augmenting-integrations\": plugin },\n    rules: {\n      \"@augmenting-integrations/no-hardcoded-internal-paths\": \"error\",\n    },\n  },\n};\n\nexport default plugin;\n","import type { Rule } from \"eslint\";\n\n// Renamed conceptually: the bug isn't \"hardcoded internal paths\" — raw\n// <a href=\"/peer-app\"> is correct for cross-app navigation under path-routing\n// (next/link's <Link> would prepend basePath, which we don't want for cross-app).\n// The actual bug is hardcoding THE CURRENT APP'S basePath in any href, because\n// <Link> prepends it automatically and <a> for an in-app link is wrong anyway.\n\ninterface Options {\n  basePath?: string;\n}\n\nconst rule: Rule.RuleModule = {\n  meta: {\n    type: \"problem\",\n    docs: {\n      description:\n        \"Disallow hardcoding the current app's basePath in href attributes. Under Next.js basePath, <Link> prepends it automatically; raw <a> with the basePath in it produces a doubled-prefix path.\",\n      recommended: true,\n    },\n    schema: [\n      {\n        type: \"object\",\n        properties: {\n          basePath: {\n            type: \"string\",\n            description:\n              \"The current app's basePath, e.g. '/leads-marketplace'. The rule is a no-op for apex apps (basePath unset or '/').\",\n          },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      hardcodedBasePath:\n        \"Hardcoded basePath '{{ basePath }}' in href '{{ path }}'. For in-app navigation, use <Link href='{{ stripped }}'> — Next.js prepends '{{ basePath }}' automatically. For cross-app navigation, the href should NOT start with '{{ basePath }}'.\",\n    },\n  },\n  create(context) {\n    const options: Options = (context.options[0] as Options) ?? {};\n    const basePath = options.basePath;\n    if (!basePath || basePath === \"/\" || basePath === \"\") {\n      // Apex app or unconfigured — rule is a no-op.\n      return {};\n    }\n    const prefix = basePath.endsWith(\"/\") ? basePath : basePath + \"/\";\n\n    return {\n      JSXAttribute(node: Rule.Node) {\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        const attr = node as any;\n        if (attr.name?.name !== \"href\") return;\n\n        const value = attr.value;\n        if (!value || value.type !== \"Literal\") return;\n        const v = value.value;\n        if (typeof v !== \"string\") return;\n        if (v !== basePath && !v.startsWith(prefix)) return;\n\n        const stripped = v === basePath ? \"/\" : \"/\" + v.slice(prefix.length);\n        context.report({\n          node: value,\n          messageId: \"hardcodedBasePath\",\n          data: { basePath, path: v, stripped },\n        });\n      },\n    } as Rule.RuleListener;\n  },\n};\n\nexport default rule;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACYA,IAAM,OAAwB;AAAA,EAC5B,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,MAAM;AAAA,MACJ,aACE;AAAA,MACF,aAAa;AAAA,IACf;AAAA,IACA,QAAQ;AAAA,MACN;AAAA,QACE,MAAM;AAAA,QACN,YAAY;AAAA,UACV,UAAU;AAAA,YACR,MAAM;AAAA,YACN,aACE;AAAA,UACJ;AAAA,QACF;AAAA,QACA,sBAAsB;AAAA,MACxB;AAAA,IACF;AAAA,IACA,UAAU;AAAA,MACR,mBACE;AAAA,IACJ;AAAA,EACF;AAAA,EACA,OAAO,SAAS;AACd,UAAM,UAAoB,QAAQ,QAAQ,CAAC,KAAiB,CAAC;AAC7D,UAAM,WAAW,QAAQ;AACzB,QAAI,CAAC,YAAY,aAAa,OAAO,aAAa,IAAI;AAEpD,aAAO,CAAC;AAAA,IACV;AACA,UAAM,SAAS,SAAS,SAAS,GAAG,IAAI,WAAW,WAAW;AAE9D,WAAO;AAAA,MACL,aAAa,MAAiB;AAE5B,cAAM,OAAO;AACb,YAAI,KAAK,MAAM,SAAS,OAAQ;AAEhC,cAAM,QAAQ,KAAK;AACnB,YAAI,CAAC,SAAS,MAAM,SAAS,UAAW;AACxC,cAAM,IAAI,MAAM;AAChB,YAAI,OAAO,MAAM,SAAU;AAC3B,YAAI,MAAM,YAAY,CAAC,EAAE,WAAW,MAAM,EAAG;AAE7C,cAAM,WAAW,MAAM,WAAW,MAAM,MAAM,EAAE,MAAM,OAAO,MAAM;AACnE,gBAAQ,OAAO;AAAA,UACb,MAAM;AAAA,UACN,WAAW;AAAA,UACX,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS;AAAA,QACtC,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,sCAAQ;;;ADxDf,IAAM,SAAS;AAAA,EACb,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,SAAS;AAAA,EACX;AAAA,EACA,OAAO;AAAA,IACL,+BAA+B;AAAA,EACjC;AAAA,EACA,SAAS,CAAC;AACZ;AAGA,OAAO,UAAU;AAAA,EACf,aAAa;AAAA,IACX,SAAS,EAAE,4BAA4B,OAAO;AAAA,IAC9C,OAAO;AAAA,MACL,wDAAwD;AAAA,IAC1D;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/index.js

@@ -0,0 +1,76 @@
+// src/rules/no-hardcoded-internal-paths.ts
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow hardcoding the current app's basePath in href attributes. Under Next.js basePath, <Link> prepends it automatically; raw <a> with the basePath in it produces a doubled-prefix path.",
+      recommended: true
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          basePath: {
+            type: "string",
+            description: "The current app's basePath, e.g. '/leads-marketplace'. The rule is a no-op for apex apps (basePath unset or '/')."
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      hardcodedBasePath: "Hardcoded basePath '{{ basePath }}' in href '{{ path }}'. For in-app navigation, use <Link href='{{ stripped }}'> \u2014 Next.js prepends '{{ basePath }}' automatically. For cross-app navigation, the href should NOT start with '{{ basePath }}'."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const basePath = options.basePath;
+    if (!basePath || basePath === "/" || basePath === "") {
+      return {};
+    }
+    const prefix = basePath.endsWith("/") ? basePath : basePath + "/";
+    return {
+      JSXAttribute(node) {
+        const attr = node;
+        if (attr.name?.name !== "href") return;
+        const value = attr.value;
+        if (!value || value.type !== "Literal") return;
+        const v = value.value;
+        if (typeof v !== "string") return;
+        if (v !== basePath && !v.startsWith(prefix)) return;
+        const stripped = v === basePath ? "/" : "/" + v.slice(prefix.length);
+        context.report({
+          node: value,
+          messageId: "hardcodedBasePath",
+          data: { basePath, path: v, stripped }
+        });
+      }
+    };
+  }
+};
+var no_hardcoded_internal_paths_default = rule;
+
+// src/index.ts
+var plugin = {
+  meta: {
+    name: "@augmenting-integrations/eslint-plugin",
+    version: "4.0.1"
+  },
+  rules: {
+    "no-hardcoded-internal-paths": no_hardcoded_internal_paths_default
+  },
+  configs: {}
+};
+plugin.configs = {
+  recommended: {
+    plugins: { "@augmenting-integrations": plugin },
+    rules: {
+      "@augmenting-integrations/no-hardcoded-internal-paths": "error"
+    }
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rules/no-hardcoded-internal-paths.ts","../src/index.ts"],"sourcesContent":["import type { Rule } from \"eslint\";\n\n// Renamed conceptually: the bug isn't \"hardcoded internal paths\" — raw\n// <a href=\"/peer-app\"> is correct for cross-app navigation under path-routing\n// (next/link's <Link> would prepend basePath, which we don't want for cross-app).\n// The actual bug is hardcoding THE CURRENT APP'S basePath in any href, because\n// <Link> prepends it automatically and <a> for an in-app link is wrong anyway.\n\ninterface Options {\n  basePath?: string;\n}\n\nconst rule: Rule.RuleModule = {\n  meta: {\n    type: \"problem\",\n    docs: {\n      description:\n        \"Disallow hardcoding the current app's basePath in href attributes. Under Next.js basePath, <Link> prepends it automatically; raw <a> with the basePath in it produces a doubled-prefix path.\",\n      recommended: true,\n    },\n    schema: [\n      {\n        type: \"object\",\n        properties: {\n          basePath: {\n            type: \"string\",\n            description:\n              \"The current app's basePath, e.g. '/leads-marketplace'. The rule is a no-op for apex apps (basePath unset or '/').\",\n          },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      hardcodedBasePath:\n        \"Hardcoded basePath '{{ basePath }}' in href '{{ path }}'. For in-app navigation, use <Link href='{{ stripped }}'> — Next.js prepends '{{ basePath }}' automatically. For cross-app navigation, the href should NOT start with '{{ basePath }}'.\",\n    },\n  },\n  create(context) {\n    const options: Options = (context.options[0] as Options) ?? {};\n    const basePath = options.basePath;\n    if (!basePath || basePath === \"/\" || basePath === \"\") {\n      // Apex app or unconfigured — rule is a no-op.\n      return {};\n    }\n    const prefix = basePath.endsWith(\"/\") ? basePath : basePath + \"/\";\n\n    return {\n      JSXAttribute(node: Rule.Node) {\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        const attr = node as any;\n        if (attr.name?.name !== \"href\") return;\n\n        const value = attr.value;\n        if (!value || value.type !== \"Literal\") return;\n        const v = value.value;\n        if (typeof v !== \"string\") return;\n        if (v !== basePath && !v.startsWith(prefix)) return;\n\n        const stripped = v === basePath ? \"/\" : \"/\" + v.slice(prefix.length);\n        context.report({\n          node: value,\n          messageId: \"hardcodedBasePath\",\n          data: { basePath, path: v, stripped },\n        });\n      },\n    } as Rule.RuleListener;\n  },\n};\n\nexport default rule;\n","// ESLint plugin for Augmenting Integrations Next.js apps.\n//\n// The flagship rule, `no-hardcoded-internal-paths`, prevents the most common\n// subpath-routing failure mode: a contributor writes `<a href=\"/leads/foo\">`\n// thinking it'll be a normal link, but under Next.js basePath=\"/leads\" that\n// renders as `/leads/leads/foo` and 404s. Worse, in dev (basePath often \"/\")\n// it works fine, so the bug only surfaces in deployed environments.\n//\n// The fix in source is to use <Link> from next/link or useRouter().push(),\n// both of which are basePath-aware. This rule flags the raw-anchor pattern\n// at lint time so it never reaches review.\n\nimport noHardcodedInternalPaths from \"./rules/no-hardcoded-internal-paths.js\";\n\nconst plugin = {\n  meta: {\n    name: \"@augmenting-integrations/eslint-plugin\",\n    version: \"4.0.1\",\n  },\n  rules: {\n    \"no-hardcoded-internal-paths\": noHardcodedInternalPaths,\n  },\n  configs: {} as Record<string, unknown>,\n};\n\n// Recommended config (flat config style — ESLint 9+).\nplugin.configs = {\n  recommended: {\n    plugins: { \"@augmenting-integrations\": plugin },\n    rules: {\n      \"@augmenting-integrations/no-hardcoded-internal-paths\": \"error\",\n    },\n  },\n};\n\nexport default plugin;\n"],"mappings":";AAYA,IAAM,OAAwB;AAAA,EAC5B,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,MAAM;AAAA,MACJ,aACE;AAAA,MACF,aAAa;AAAA,IACf;AAAA,IACA,QAAQ;AAAA,MACN;AAAA,QACE,MAAM;AAAA,QACN,YAAY;AAAA,UACV,UAAU;AAAA,YACR,MAAM;AAAA,YACN,aACE;AAAA,UACJ;AAAA,QACF;AAAA,QACA,sBAAsB;AAAA,MACxB;AAAA,IACF;AAAA,IACA,UAAU;AAAA,MACR,mBACE;AAAA,IACJ;AAAA,EACF;AAAA,EACA,OAAO,SAAS;AACd,UAAM,UAAoB,QAAQ,QAAQ,CAAC,KAAiB,CAAC;AAC7D,UAAM,WAAW,QAAQ;AACzB,QAAI,CAAC,YAAY,aAAa,OAAO,aAAa,IAAI;AAEpD,aAAO,CAAC;AAAA,IACV;AACA,UAAM,SAAS,SAAS,SAAS,GAAG,IAAI,WAAW,WAAW;AAE9D,WAAO;AAAA,MACL,aAAa,MAAiB;AAE5B,cAAM,OAAO;AACb,YAAI,KAAK,MAAM,SAAS,OAAQ;AAEhC,cAAM,QAAQ,KAAK;AACnB,YAAI,CAAC,SAAS,MAAM,SAAS,UAAW;AACxC,cAAM,IAAI,MAAM;AAChB,YAAI,OAAO,MAAM,SAAU;AAC3B,YAAI,MAAM,YAAY,CAAC,EAAE,WAAW,MAAM,EAAG;AAE7C,cAAM,WAAW,MAAM,WAAW,MAAM,MAAM,EAAE,MAAM,OAAO,MAAM;AACnE,gBAAQ,OAAO;AAAA,UACb,MAAM;AAAA,UACN,WAAW;AAAA,UACX,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS;AAAA,QACtC,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,sCAAQ;;;ACxDf,IAAM,SAAS;AAAA,EACb,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,SAAS;AAAA,EACX;AAAA,EACA,OAAO;AAAA,IACL,+BAA+B;AAAA,EACjC;AAAA,EACA,SAAS,CAAC;AACZ;AAGA,OAAO,UAAU;AAAA,EACf,aAAa;AAAA,IACX,SAAS,EAAE,4BAA4B,OAAO;AAAA,IAC9C,OAAO;AAAA,MACL,wDAAwD;AAAA,IAC1D;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@augmenting-integrations/eslint-plugin",
+  "version": "4.0.1",
+  "description": "Shared ESLint rules for Augmenting Integrations Next.js apps.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/eslint": "^9.6.1",
+    "eslint": "^9.16.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.5"
+  }
+}