@via-ds/stylelint-plugin 0.0.1-canary.0

package/README.md

@@ -0,0 +1,62 @@
+# @via-ds/stylelint-plugin
+
+Stylelint plugin for the Via Design System.
+
+## Installation
+
+```bash
+pnpm add -D @via-ds/stylelint-plugin stylelint
+```
+
+## Usage
+
+### Using the Recommended Config
+
+The easiest way to get started is to extend the recommended configuration:
+
+```js
+// stylelint.config.mjs
+export default {
+  extends: ['@via-ds/stylelint-plugin/recommended'],
+};
+```
+
+This enables all recommended rules with sensible defaults.
+
+### Manual Configuration
+
+You can also configure the plugin manually:
+
+```js
+// stylelint.config.mjs
+export default {
+  plugins: ['@via-ds/stylelint-plugin'],
+  rules: {
+    'via/example-rule': true,
+  },
+};
+```
+
+## Rules
+
+| Rule               | Description                                          |
+| ------------------ | ---------------------------------------------------- |
+| `via/example-rule` | Example rule that reports selectors containing "foobar" |
+
+---
+
+## Creating New Rules
+
+1. Create a new file in `src/rules/` (using `example-rule.ts` as a template)
+2. Register the rule in `src/rules/index.ts`
+
+The `createRule` helper provides walk callbacks for different CSS node types:
+
+- `walkRules` - Selectors (`.class`, `#id`)
+- `walkDecls` - Declarations (`property: value`)
+- `walkAtRules` - At-rules (`@media`, `@import`)
+- `walkComments` - CSS comments
+
+Each callback receives the node and a context with `messages`, `report()`, and `fix`.
+
+For more, see the [Stylelint Plugins documentation](https://stylelint.io/developer-guide/plugins/)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import stylelint from "stylelint";
+declare const rulesPlugins: stylelint.Plugin[];
+export default rulesPlugins;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,WAAW,CAAC;AAKlC,QAAA,MAAM,YAAY,oBAEhB,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+import e from"stylelint";function t(e,t){(null==t||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r<t;r++)n[r]=e[r];return n}function r(e,t,r){return(t=function(e){var t=function(e,t){if("object"!=typeof e||!e)return e;var r=e[Symbol.toPrimitive];if(void 0!==r){var n=r.call(e,t);if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===t?String:Number)(e)}(e,"string");return"symbol"==typeof t?t:t+""}(t))in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter(function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable})),r.push.apply(r,n)}return r}function o(e){for(var t=1;t<arguments.length;t++){var o=null!=arguments[t]?arguments[t]:{};t%2?n(Object(o),!0).forEach(function(t){r(e,t,o[t])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(o)):n(Object(o)).forEach(function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(o,t))})}return e}function a(e,r){return function(e){if(Array.isArray(e))return e}(e)||function(e,t){var r=null==e?null:"undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(null!=r){var n,o,a,i,l=[],u=!0,c=!1;try{if(a=(r=r.call(e)).next,0===t);else for(;!(u=(n=a.call(r)).done)&&(l.push(n.value),l.length!==t);u=!0);}catch(e){c=!0,o=e}finally{try{if(!u&&null!=r.return&&(i=r.return(),Object(i)!==i))return}finally{if(c)throw o}}return l}}(e,r)||function(e,r){if(e){if("string"==typeof e)return t(e,r);var n={}.toString.call(e).slice(8,-1);return"Object"===n&&e.constructor&&(n=e.constructor.name),"Map"===n||"Set"===n?Array.from(e):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?t(e,r):void 0}}(e,r)||function(){throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()}var i=e.utils,l=i.report,u=i.ruleMessages,c=i.validateOptions;function s(e){var t=e.meta,r=e.ruleName,n=e.walkAtRules,a=e.walkComments,i=e.walkDecls,s=e.walkRoot,f=e.walkRules,m="".concat("via","/").concat(r),p=u(m,e.messages),b=function(e,t,r){return function(t,u){var b;if(c(u,m,{actual:e,possible:[!0]})){var g={messages:p,fix:null!==(b=null==r?void 0:r.fix)&&void 0!==b&&b,report:function(e){l(o(o({},e),{},{result:u,ruleName:m}))}};s&&s(t,g),f&&t.walkRules(function(e){return f(e,g)}),i&&t.walkDecls(function(e){return i(e,g)}),n&&t.walkAtRules(function(e){return n(e,g)}),a&&t.walkComments(function(e){return a(e,g)})}}};return b.ruleName=r,b.messages=p,t&&(b.meta=t),b}var f=s({ruleName:"example-rule",messages:{rejected:function(e){return'Example rule violation in selector "'.concat(e,'"')}},meta:{url:"https://github.com/10gen/lg/blob/main/packages/tools/stylelint-plugin/README.md"},walkRules:function(e,t){var r=t.messages,n=t.report,o=e.selector;o.includes("foobar")&&n({message:r.rejected(o),node:e,word:o})}}),m=/\battr\s*\(/i,p=s({ruleName:"no-attr-function",messages:{rejected:function(e){return'Unexpected "attr()" in "'.concat(e,'". The attr() function has limited browser support outside of the "content" property (https://caniuse.com/?search=attr()).')}},meta:{url:"https://github.com/10gen/lg/blob/main/packages/tools/stylelint-plugin/README.md"},walkDecls:function(e,t){var r=t.messages,n=t.report;"content"!==e.prop&&m.test(e.value)&&n({message:r.rejected(e.prop),node:e,word:"attr("})}}),b=r(r({},f.ruleName,f),p.ruleName,p),g=Object.entries(b).map(function(t){var r=a(t,2),n=r[0],o=r[1];return e.createPlugin("".concat("via","/").concat(n),o)});export{g as default};

package/dist/plugin-namespace.d.ts

@@ -0,0 +1,3 @@
+/** Namespace prefix for rule IDs in config and warning output (e.g. `via/example-rule`). */
+export declare const PLUGIN_NAMESPACE = "via";
+//# sourceMappingURL=plugin-namespace.d.ts.map

package/dist/plugin-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-namespace.d.ts","sourceRoot":"","sources":["../src/plugin-namespace.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,QAAQ,CAAC"}

package/dist/recommended.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "stylelint";
+/**
+ * Recommended Via stylelint configuration.
+ *
+ * Enforces design token usage by prohibiting:
+ * - Named colors and hex values (use CSS variables instead)
+ * - Hard-coded spacing values (use token variables instead)
+ *
+ * Usage:
+ * ```js
+ * // stylelint.config.mjs
+ * export default {
+ *   extends: ['@via-ds/stylelint-plugin/recommended'],
+ * };
+ * ```
+ */
+declare const recommended: Config;
+export default recommended;
+//# sourceMappingURL=recommended.d.ts.map

package/dist/recommended.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommended.d.ts","sourceRoot":"","sources":["../src/recommended.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,WAAW,EAAE,MAMlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/recommended.js

@@ -0,0 +1 @@
+var a={plugins:["@via-ds/stylelint-plugin"],rules:{"via/example-rule":!0,"via/no-attr-function":!0}};export{a as default};

package/dist/rules/example-rule.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Example rule that reports any selector containing "foobar".
+ *
+ * This demonstrates the simplified createRule API where you
+ * just provide walk callbacks - no boilerplate required.
+ */
+declare const _default: import("stylelint").Rule<true, unknown, {
+    rejected: (selector: string) => string;
+}>;
+export default _default;
+//# sourceMappingURL=example-rule.d.ts.map

package/dist/rules/example-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-rule.d.ts","sourceRoot":"","sources":["../../src/rules/example-rule.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;;yBAKsB,MAAM;;AAJ/B,wBAuBG"}

package/dist/rules/index.d.ts

@@ -0,0 +1,15 @@
+import type { Rule } from "stylelint";
+/**
+ * Registry of all Via stylelint rules.
+ *
+ * To add a new rule:
+ * 1. Create a new file in this directory (e.g., `no-invalid-token.ts`)
+ * 2. Export the rule function as default
+ * 3. Import and add it to this object
+ *
+ * Rule names will be prefixed with "via/" when registered.
+ * Example: A rule named "no-invalid-token" becomes "via/no-invalid-token"
+ */
+declare const rules: Record<string, Rule>;
+export default rules;
+//# sourceMappingURL=index.d.ts.map

package/dist/rules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKtC;;;;;;;;;;GAUG;AACH,QAAA,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAG/B,CAAC;AAEF,eAAe,KAAK,CAAC"}

package/dist/rules/no-attr-function.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Disallows `attr()` in CSS declaration values due to limited browser support.
+ *
+ * While `attr()` works in the `content` property across all browsers,
+ * its use on other CSS properties (CSS Values Level 5) lacks broad support.
+ * This rule flags all usage to ensure cross-browser compatibility.
+ *
+ * @see https://caniuse.com/?search=attr()
+ */
+declare const _default: import("stylelint").Rule<true, unknown, {
+    rejected: (property: string) => string;
+}>;
+export default _default;
+//# sourceMappingURL=no-attr-function.d.ts.map

package/dist/rules/no-attr-function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-attr-function.d.ts","sourceRoot":"","sources":["../../src/rules/no-attr-function.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;;yBAKsB,MAAM;;AAJ/B,wBAuBG"}

package/dist/rules/no-attr-function.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=no-attr-function.spec.d.ts.map

package/dist/rules/no-attr-function.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-attr-function.spec.d.ts","sourceRoot":"","sources":["../../src/rules/no-attr-function.spec.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export stylelint types for convenience
+ */
+export type { Rule, RuleContext, RuleMessages, RuleMeta } from "stylelint";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/utils/create-rule.d.ts

@@ -0,0 +1,79 @@
+import type { AtRule, Comment, Declaration, Root, Rule as CssRule } from "postcss";
+import type { PostcssResult, Problem, ProblemLocation, Rule, RuleMessages, RuleMeta } from "stylelint";
+import stylelint from "stylelint";
+declare const report: (problem: Problem) => void, ruleMessages: <T extends RuleMessages, R extends { [K in keyof T]: T[K]; }>(ruleName: string, messages: T) => R, validateOptions: (result: PostcssResult, ruleName: string, ...optionDescriptions: stylelint.RuleOptions[]) => boolean;
+/**
+ * Problem report type for the `report` function.
+ * Excludes `result` and `ruleName` which are automatically
+ * provided by the createRule wrapper.
+ */
+export type ReportProblem = Omit<Problem, "result" | "ruleName" | keyof ProblemLocation> & ProblemLocation;
+/**
+ * Context passed to walk callbacks.
+ */
+export interface WalkContext<M extends RuleMessages = RuleMessages> {
+    /** Rule messages with ruleName suffix applied */
+    messages: M;
+    /** Whether autofix is enabled */
+    fix: boolean;
+    /**
+     * Report a problem. `result` and the namespaced rule id (`via/...`) are automatically provided.
+     */
+    report: (problem: ReportProblem) => void;
+}
+/**
+ * Generic walk callback type for PostCSS nodes.
+ */
+export type WalkCallback<N, M extends RuleMessages> = (node: N, context: WalkContext<M>) => void;
+/**
+ * Rule definition with simplified walk callbacks.
+ * Just provide the walk callback(s) you need - no boilerplate required.
+ */
+export interface RuleDefinition<M extends RuleMessages = RuleMessages> {
+    /** The rule name (without namespace prefix) */
+    ruleName: string;
+    /** Rule messages object */
+    messages: M;
+    /** Optional rule metadata */
+    meta?: RuleMeta;
+    /** Walk CSS rules (selectors) */
+    walkRules?: WalkCallback<CssRule, M>;
+    /** Walk declarations (property: value pairs) */
+    walkDecls?: WalkCallback<Declaration, M>;
+    /** Walk at-rules (@media, @import, etc.) */
+    walkAtRules?: WalkCallback<AtRule, M>;
+    /** Walk comments */
+    walkComments?: WalkCallback<Comment, M>;
+    /** Process the root node directly (for custom traversal) */
+    walkRoot?: WalkCallback<Root, M>;
+}
+/**
+ * Factory function to create a stylelint rule with minimal boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { createRule } from "../utils/create-rule.js";
+ *
+ * export default createRule({
+ *   ruleName: "no-foobar-selector",
+ *   messages: {
+ *     rejected: (selector) => `Unexpected "foobar" in selector "${selector}"`,
+ *   },
+ *   meta: {
+ *     url: "https://example.com/rules/no-foobar-selector",
+ *   },
+ *   walkRules(ruleNode, { report, messages }) {
+ *     if (ruleNode.selector.includes("foobar")) {
+ *       report({
+ *         message: messages.rejected(ruleNode.selector),
+ *         node: ruleNode,
+ *         word: ruleNode.selector,
+ *       });
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export declare function createRule<M extends RuleMessages = RuleMessages>(definition: RuleDefinition<M>): Rule<true, unknown, M>;
+export { report, ruleMessages, validateOptions };
+//# sourceMappingURL=create-rule.d.ts.map

package/dist/utils/create-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-rule.d.ts","sourceRoot":"","sources":["../../src/utils/create-rule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,OAAO,EACP,WAAW,EACX,IAAI,EACJ,IAAI,IAAI,OAAO,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EACV,aAAa,EACb,OAAO,EACP,eAAe,EACf,IAAI,EACJ,YAAY,EACZ,QAAQ,EACT,MAAM,WAAW,CAAC;AACnB,OAAO,SAAS,MAAM,WAAW,CAAC;AAIlC,QAAA,MACW,MAAM,8BAAE,YAAY,qGAAE,eAAe,sGACnC,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,eAAe,CAAC,GACtF,eAAe,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IAChE,iDAAiD;IACjD,QAAQ,EAAE,CAAC,CAAC;IAEZ,iCAAiC;IACjC,GAAG,EAAE,OAAO,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,YAAY,IAAI,CACpD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,KACpB,IAAI,CAAC;AAEV;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACnE,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IAEjB,2BAA2B;IAC3B,QAAQ,EAAE,CAAC,CAAC;IAEZ,6BAA6B;IAC7B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB,iCAAiC;IACjC,SAAS,CAAC,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAErC,gDAAgD;IAChD,SAAS,CAAC,EAAE,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAEzC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAEtC,oBAAoB;IACpB,YAAY,CAAC,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAExC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAC9D,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,GAC5B,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CA0DxB;AAED,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export { createRule, report, type ReportProblem, type RuleDefinition, ruleMessages, validateOptions, type WalkContext, } from "./create-rule.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,MAAM,EACN,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@via-ds/stylelint-plugin",
+  "version": "0.0.1-canary.0",
+  "description": "Stylelint plugin for Via Design System",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/10gen/via.git",
+    "directory": "packages/tools/stylelint-plugin"
+  },
+  "keywords": [
+    "stylelint",
+    "stylelint-plugin",
+    "stylelint-config",
+    "via",
+    "mongodb"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@via-ds/tokens": "0.0.1-canary.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/node": "24.1.0",
+    "postcss": "^8.0.0",
+    "rollup": "4.55.1",
+    "rollup-plugin-node-externals": "^8.1.2",
+    "rollup-plugin-postcss": "^4.0.2",
+    "stylelint": "^17.0.0",
+    "typescript": "5.9.3",
+    "@via-ds/config": "^0.0.0"
+  },
+  "peerDependencies": {
+    "stylelint": "^16.0.0 || ^17.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./recommended": {
+      "types": "./dist/recommended.d.ts",
+      "import": "./dist/recommended.js",
+      "default": "./dist/recommended.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup --config ./rollup.config.js",
+    "tsc": "tsc --project ./tsconfig.json",
+    "test": "vitest run"
+  }
+}