@planningcenter/eslint-plugin-tapestry 0.1.0 → 1.0.1

package/.eslintrc.js

@@ -0,0 +1,33 @@
+module.exports = {
+  env: {
+    node: true,
+    es2022: true,
+    jest: true,
+  },
+  extends: ["eslint:recommended", "plugin:prettier/recommended"],
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: "module",
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+  rules: {
+    // Prevent common errors
+    "no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+    "no-console": "warn",
+
+    // ESLint plugin specific
+    "prefer-const": "error",
+    "no-var": "error",
+  },
+  overrides: [
+    {
+      // Test files can be more lenient
+      files: ["tests/**/*.js", "**/*.test.js"],
+      rules: {
+        "no-console": "off",
+      },
+    },
+  ],
+}

package/.prettierignore

@@ -0,0 +1,24 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+build/
+
+# Lock files
+yarn.lock
+package-lock.json
+
+# Logs
+*.log
+
+# Coverage reports
+coverage/
+
+# IDE files
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db

package/.prettierrc.js

@@ -0,0 +1,32 @@
+module.exports = {
+  // Use double quotes to match ESLint config
+  singleQuote: false,
+
+  // No semicolons to match ESLint config
+  semi: false,
+
+  // Trailing commas where valid in ES5 (objects, arrays, etc.)
+  trailingComma: "es5",
+
+  // 2 space indentation
+  tabWidth: 2,
+  useTabs: false,
+
+  // Line length
+  printWidth: 80,
+
+  // Bracket spacing
+  bracketSpacing: true,
+
+  // Arrow function parentheses
+  arrowParens: "avoid",
+
+  // End of line
+  endOfLine: "lf",
+
+  // JSX quotes
+  jsxSingleQuote: false,
+
+  // Bracket same line for JSX
+  bracketSameLine: false,
+}

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+**Changes that are visual in nature are not considered breaking and will typically only result in a minor version bump.**
+However, when those changes are made, there will be a specific **VISUAL CHANGES** section within the version notes.
+If you are a designer or otherwise need to be pixel-perfect, please pay special attention to those sections.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## [v1.0.1](https://github.com/planningcenter/eslint-plugin-tapestry/releases/tag/v1.0.1) - 2025-08-11
+
+### Dependencies
+
+-  update package.json scripts for build and formatting
+
+## [v1.0.0](https://github.com/planningcenter/eslint-plugin-tapestry/releases/tag/v1.0.0) - 2025-08-11
+
+<!--
+### VISUAL CHANGES
+
+- `Component`: Looks different
+
+### Fixed
+
+- `Broken`: description of the fix
+
+### Added
+
+- List of the feature
+
+### Security
+
+- bump library from 1.0.0 to 1.1.1
+
+### Dependencies
+
+- bump @planningcenter/dep from 2.0.1 to 2.1.0
+-->
+
+### Dependencies
+
+- Add, configure, and run eslint and prettier
+
+## [v1.0.0](https://github.com/planningcenter/eslint-plugin-tapestry/releases/tag/v1.0.0) - 2025-08-11
+
+...

package/README.md

@@ -15,15 +15,15 @@ yarn add @planningcenter/eslint-plugin-tapestry --dev
 ### Recommended Configuration
 
 #### Flat Config
+
 ```javascript
-import tapestry from '@planningcenter/eslint-plugin-tapestry';
+import tapestry from "@planningcenter/eslint-plugin-tapestry"
 
-export default [
-  tapestry.configs.recommended,
-];
+export default [tapestry.configs.recommended]
 ```
 
 #### Legacy Config
+
 ```json
 "plugins": [
   "tapestry"
@@ -37,7 +37,7 @@ export default [
 ### ESLint Flat Config (eslint.config.js)
 
 ```javascript
-import tapestry from '@planningcenter/eslint-plugin-tapestry';
+import tapestry from "@planningcenter/eslint-plugin-tapestry"
 
 export default [
   {
@@ -45,10 +45,10 @@ export default [
       tapestry,
     },
     rules: {
-      'tapestry/valid-href': 'error',
+      "tapestry/valid-href": "error",
     },
   },
-];
+]
 ```
 
 ### Legacy Config (.eslintrc.json)
@@ -64,8 +64,8 @@ export default [
 
 ## Rules
 
-| Rule | Category | Description |
-| ---- | -------- | ----------- |
+| Rule                                   | Category      | Description                                                                         |
+| -------------------------------------- | ------------- | ----------------------------------------------------------------------------------- |
 | [valid-href](docs/rules/valid-href.md) | Accessibility | Ensures that `BaseLink`, `Link`, and `IconLink` components have valid `href` values |
 
 ## Development
@@ -78,18 +78,21 @@ yarn test --watch  # Run tests in watch mode
 ## Setup for initial release testing
 
 ### Tapestry
+
 1. Open a terminal to this repo and run `yarn && yalc publish`
 2. Open a new terminal to Tapestry and create a temp test branch from `main`
 3. Run `yalc add @planningcenter/eslint-plugin-tapestry@1.0.0 --dev`
-5. In `eslint.config.mjs`, add or modify
-  * `import tapestry from "@planningcenter/eslint-plugin-tapestry"`
-  * `plugins: {tapestry}`
-  * `rules: {"tapestry/valid-href": "error"}`
+4. In `eslint.config.mjs`, add or modify
+
+- `import tapestry from "@planningcenter/eslint-plugin-tapestry"`
+- `plugins: {tapestry}`
+- `rules: {"tapestry/valid-href": "error"}`
+
 6. Restart the ESLint server (`cmd` + `shift` + `P` > `ESLint: Restart Eslint Server`)
 7. Open `packages/tapestry/src/components/link/index.stories.tsx` and notice that the `tapestry-react` `Link` isn't reporting any lint errors (no red squiggle lines)
 8. Comment out the `Link` import and add a line to `import { Link } from "@planningcenter/tapestry"`
-    * You should get red squiggle lines on the `Link`
-    * Test out different variations of `href` to see the lint errors
+   - You should get red squiggle lines on the `Link`
+   - Test out different variations of `href` to see the lint errors
 9. In your terminal, run `yarn lint`, notice you'll see `tapestry/valid-href` errors
 
 ### Groups
@@ -97,14 +100,16 @@ yarn test --watch  # Run tests in watch mode
 1. Open a terminal to this repo and run `yarn && yalc publish`
 2. Open a new terminal to Groups and create a temp test branch from `main`
 3. Run `yalc add @planningcenter/eslint-plugin-tapestry@1.0.0 --dev`
-5. In `eslint.config.mjs`, add or modify
-  * `import tapestry from "@planningcenter/eslint-plugin-tapestry"`
-  * `plugins: {tapestry}`
-  * `rules: {"tapestry/valid-href": "error"}`
-  * `files: ["**/*.ts", "**/*.tsx", "**/*.jsx", "**/*.js"],`
+4. In `eslint.config.mjs`, add or modify
+
+- `import tapestry from "@planningcenter/eslint-plugin-tapestry"`
+- `plugins: {tapestry}`
+- `rules: {"tapestry/valid-href": "error"}`
+- `files: ["**/*.ts", "**/*.tsx", "**/*.jsx", "**/*.js"],`
+
 6. Restart the ESLint server (`cmd` + `shift` + `P` > `ESLint: Restart Eslint Server`)
 7. Open `app/javascript/staff_only/staff_only_nav_links.tsx` and notice that the `tapestry-react` `Link` isn't reporting any lint errors (no red squiggle lines)
 8. Comment out the `Link` import and add a line to `import { Link } from "@planningcenter/tapestry"`
-    * You should get red squiggle lines on the `Link`
-    * Test out different variations of `href` to see the lint errors
-9. In your terminal, run `yarn lint`, notice you'll see `tapestry/valid-href` errors
+   - You should get red squiggle lines on the `Link`
+   - Test out different variations of `href` to see the lint errors
+9. In your terminal, run `yarn lint`, notice you'll see `tapestry/valid-href` errors

package/docs/development.md

@@ -0,0 +1,255 @@
+# Development Guide
+
+This guide helps you create new ESLint rules for the Tapestry plugin.
+
+## Shared Utilities
+
+The plugin provides shared utilities in `/utils/index.js` to maintain consistency across rules and avoid code duplication.
+
+### Import Tracking
+
+Use `createImportTracker` to automatically handle both scoped and relative imports:
+
+```javascript
+const { createImportTracker } = require("../utils")
+
+module.exports = {
+  create(context) {
+    const targetComponents = new Set(["MyComponent", "AnotherComponent"])
+    const importTracker = createImportTracker(context, targetComponents)
+
+    return {
+      ImportDeclaration(node) {
+        importTracker.processImport(node)
+      },
+
+      JSXOpeningElement(node) {
+        if (node.name.type === "JSXIdentifier") {
+          const componentName = node.name.name
+
+          if (
+            targetComponents.has(componentName) &&
+            importTracker.isTapestryComponent(componentName)
+          ) {
+            // Your rule logic here
+          }
+        }
+      },
+    }
+  },
+}
+```
+
+#### Import Tracker Methods
+
+- `processImport(node)` - Process an ImportDeclaration node
+- `isTapestryComponent(componentName)` - Check if component is tracked Tapestry component
+- `getTrackedComponents()` - Get Set of all tracked component names
+- `isInTapestryProject()` - Check if running in Tapestry project
+
+### Project Detection
+
+Use `isTapestryProject(filename)` to detect if ESLint is running within the Tapestry project:
+
+```javascript
+const { isTapestryProject } = require("../utils")
+
+// In your rule
+const filename = context.getFilename()
+const isInTapestryProject = isTapestryProject(filename)
+```
+
+### JSX Utilities
+
+Use `jsxUtils` for common JSX operations:
+
+```javascript
+const { jsxUtils } = require("../utils")
+
+// Extract attribute value
+const hrefProp = jsxUtils.findAttribute(node, "href")
+const hrefValue = hrefProp ? jsxUtils.extractAttributeValue(hrefProp) : null
+
+// Check for spread props
+const hasSpreadProps = jsxUtils.hasSpreadProps(node)
+```
+
+#### JSX Utils Methods
+
+- `findAttribute(node, attributeName)` - Find JSX attribute by name
+- `extractAttributeValue(prop)` - Extract value from JSX attribute
+- `hasSpreadProps(node)` - Check if JSX element has spread props
+
+## Creating a New Rule
+
+1. **Create the rule file**: `rules/my-new-rule.js`
+2. **Use shared utilities**: Import and use utilities for consistency
+3. **Add tests**: Create `tests/my-new-rule.test.js`
+4. **Register the rule**: Add to `index.js`
+5. **Document the rule**: Create `docs/rules/my-new-rule.md`
+
+### Example Rule Structure
+
+```javascript
+const { createImportTracker, jsxUtils } = require("../utils")
+
+module.exports = {
+  meta: {
+    type: "problem", // or 'suggestion', 'layout'
+    docs: {
+      description: "Description of what the rule does",
+      category: "Best Practices", // or 'Accessibility', 'Stylistic Issues'
+      recommended: true,
+      url: "https://github.com/planningcenter/eslint-plugin-tapestry/blob/main/docs/rules/my-new-rule.md",
+    },
+    fixable: null, // or 'code', 'whitespace'
+    schema: [], // JSON schema for rule options
+    messages: {
+      messageId: "Error message with {{placeholder}}",
+    },
+  },
+
+  create(context) {
+    const targetComponents = new Set(["ComponentName"])
+    const importTracker = createImportTracker(context, targetComponents)
+
+    return {
+      ImportDeclaration(node) {
+        importTracker.processImport(node)
+      },
+
+      JSXOpeningElement(node) {
+        if (node.name.type === "JSXIdentifier") {
+          const componentName = node.name.name
+
+          if (
+            targetComponents.has(componentName) &&
+            importTracker.isTapestryComponent(componentName)
+          ) {
+            // Your validation logic here
+            context.report({
+              node,
+              messageId: "messageId",
+              data: { placeholder: "value" },
+            })
+          }
+        }
+      },
+    }
+  },
+}
+```
+
+## Testing Strategy
+
+### Rule Tests
+
+Use the existing test patterns:
+
+```javascript
+const { RuleTester } = require("eslint")
+const rule = require("../rules/my-new-rule")
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 2018,
+    sourceType: "module",
+    ecmaFeatures: { jsx: true },
+  },
+})
+
+ruleTester.run("my-new-rule", rule, {
+  valid: [
+    // External project tests
+    {
+      code: `
+        import { Component } from '@planningcenter/tapestry';
+        <Component validProp="value">Valid</Component>
+      `,
+    },
+    // Tapestry project tests with filename
+    {
+      code: `
+        import { Component } from './components/component';
+        <Component validProp="value">Valid</Component>
+      `,
+      filename: "/packages/tapestry/src/test.tsx",
+    },
+  ],
+  invalid: [
+    {
+      code: `
+        import { Component } from '@planningcenter/tapestry';
+        <Component>Invalid</Component>
+      `,
+      errors: [{ messageId: "messageId" }],
+    },
+  ],
+})
+```
+
+### Utility Tests
+
+Test your utilities separately if you create new ones:
+
+```javascript
+const { myNewUtility } = require("../utils")
+
+describe("myNewUtility", () => {
+  test("does what it should", () => {
+    expect(myNewUtility("input")).toBe("expected output")
+  })
+})
+```
+
+## Rule Registration
+
+Add your rule to `index.js`:
+
+```javascript
+const myNewRule = require("./rules/my-new-rule")
+
+module.exports = {
+  rules: {
+    "my-new-rule": myNewRule,
+    // ... existing rules
+  },
+  configs: {
+    recommended: {
+      rules: {
+        "tapestry/my-new-rule": "error",
+        // ... existing rules
+      },
+    },
+  },
+}
+```
+
+## Best Practices
+
+1. **Use shared utilities** for consistency and maintainability
+2. **Test both contexts** (external projects and Tapestry project)
+3. **Document behavior clearly** in rule documentation
+4. **Follow existing patterns** for rule structure and naming
+5. **Add comprehensive tests** covering edge cases
+6. **Use descriptive error messages** with helpful context
+
+## File Structure
+
+```
+├── rules/
+│   ├── valid-href.js          # Example rule
+│   └── my-new-rule.js         # Your new rule
+├── tests/
+│   ├── valid-href.test.js     # Rule tests
+│   ├── utils.test.js          # Utility tests
+│   └── my-new-rule.test.js    # Your rule tests
+├── utils/
+│   └── index.js               # Shared utilities
+├── docs/
+│   ├── rules/
+│   │   ├── valid-href.md      # Rule documentation
+│   │   └── my-new-rule.md     # Your rule docs
+│   └── development.md         # This file
+└── index.js                   # Main plugin file
+```

package/docs/rules/valid-href.md

@@ -6,6 +6,11 @@ Ensures that `BaseLink`, `Link`, `IconLink` components have valid `href` values.
 
 This rule enforces that Tapestry link components (`BaseLink`, `Link`, and `IconLink`) have valid `href` values to ensure proper accessibility support for keyboard navigation and screen readers.
 
+The rule automatically detects whether it's running within the Tapestry project itself or in an external project that consumes Tapestry:
+
+- **In external projects**: Only checks components imported from `@planningcenter/tapestry`
+- **In the Tapestry project**: Also checks components imported via relative paths (e.g., `./components/link`, `../link/index`)
+
 ### Requirements
 
 - ✅ `href` must be specified as a direct prop (not in spread props)
@@ -15,29 +20,64 @@ This rule enforces that Tapestry link components (`BaseLink`, `Link`, and `IconL
 
 ## Examples
 
+### Import Context
+
+The rule behavior depends on the import source:
+
+```jsx
+// External projects - checks only scoped imports
+import { Link } from "@planningcenter/tapestry"
+;<Link href="/page">Valid</Link>
+
+// Legacy components are ignored
+import { Link } from "tapestry-react"
+;<Link href="#">Ignored</Link>
+
+// In Tapestry project - checks both scoped AND relative imports
+import { Link } from "@planningcenter/tapestry" // Checked
+import { BaseLink } from "./components/link" // Also checked
+import { IconLink } from "../link/index" // Also checked
+```
+
 ### ❌ Invalid
 
 ```jsx
 // Missing href
+import { BaseLink } from '@planningcenter/tapestry';
 <BaseLink>Click me</BaseLink>
 
 // Invalid href values
+import { Link } from '@planningcenter/tapestry';
 <Link href="">Empty</Link>
 <Link href="#">Hash only</Link>
 <Link href="javascript:void(0)">JS void</Link>
 
 // href in spread props
+import { IconLink } from '@planningcenter/tapestry';
 <IconLink {...props}>Icon</IconLink>
+
+// In Tapestry project - relative imports also checked
+import { BaseLink } from './components/link';
+<BaseLink href="#">Also invalid</BaseLink>
 ```
 
 ### ✅ Valid
 
 ```jsx
+// External projects
+import { BaseLink } from '@planningcenter/tapestry';
 <BaseLink href="/page">Click me</BaseLink>
 <Link href="https://example.com">External</Link>
 <IconLink href="/dashboard">Dashboard</IconLink>
 <Link href="mailto:test@example.com">Email</Link>
 <IconLink href="tel:555-1234">Call</IconLink>
+
+// In Tapestry project - relative imports work too
+import { BaseLink } from './components/link';
+<BaseLink href="/settings">Settings</BaseLink>
+
+import { Link } from '../link/index';
+<Link href="https://example.com">External</Link>
 ```
 
 ## Configuration
@@ -79,4 +119,4 @@ The `href` attribute is a critical component of HTML anchor tags for several rea
 ## Further Reading
 
 - [Web Content Accessibility Guidelines (WCAG) on Links](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html)
-- [MDN: HTMLAnchorElement.href](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/href)
+- [MDN: HTMLAnchorElement.href](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/href)

package/index.js

@@ -1,27 +1,29 @@
-const validHrefRule = require('./rules/valid-href');
+const validHrefRule = require("./rules/valid-href")
+const utils = require("./utils")
 
 module.exports = {
   rules: {
-    'valid-href': validHrefRule,
+    "valid-href": validHrefRule,
   },
+  utils,
   configs: {
     recommended: {
-      plugins: ['tapestry'],
+      plugins: ["tapestry"],
       rules: {
-        'tapestry/valid-href': 'error',
+        "tapestry/valid-href": "error",
       },
     },
     // Legacy configuration for .eslintrc.json
     legacy: {
-      plugins: ['tapestry'],
+      plugins: ["tapestry"],
       rules: {
-        'tapestry/valid-href': 'error',
+        "tapestry/valid-href": "error",
       },
     },
   },
   // Flat config support for eslint.config.js
   meta: {
-    name: 'eslint-plugin-tapestry',
-    version: '1.0.0',
+    name: "eslint-plugin-tapestry",
+    version: "1.0.0",
   },
-};
+}

package/jest.config.js

@@ -1,8 +1,5 @@
 module.exports = {
-  testEnvironment: 'node',
-  testMatch: ['**/tests/**/*.test.js'],
-  collectCoverageFrom: [
-    'rules/**/*.js',
-    'index.js',
-  ],
-};
+  testEnvironment: "node",
+  testMatch: ["**/tests/**/*.test.js"],
+  collectCoverageFrom: ["rules/**/*.js", "index.js"],
+}

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@planningcenter/eslint-plugin-tapestry",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "ESLint plugin for Tapestry React components",
   "repository": "https://github.com/planningcenter/eslint-plugin-tapestry.git",
   "main": "index.js",
   "scripts": {
+    "build": "echo 'No build step needed for this package'",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "jest",
     "test:watch": "jest --watch"
   },
@@ -23,12 +28,16 @@
     "@babel/preset-env": "^7.23.0",
     "@babel/preset-react": "^7.22.0",
     "eslint": "^8.50.0",
-    "jest": "^29.7.0"
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^29.7.0",
+    "prettier": "^3.6.2"
   },
   "peerDependencies": {
     "eslint": ">=8.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
-  }
-}
+  },
+  "dependencies": {}
+}