@a11yfred/neighbor 0.3.0 → 1.0.1

package/neighbor-content.mjs

@@ -0,0 +1,80 @@
+/**
+ * @a11yfred/neighbor  -  Content linting plugin
+ *
+ * Flags accessibility and inclusion problems in web and app copy: ableist
+ * language, disability metaphors, English idioms that exclude ESL readers,
+ * vague link text, directional layout references, unexplained abbreviations,
+ * ALL CAPS prose, and vague error messages.
+ *
+ * These rules operate on string literals and JSX text in JavaScript,
+ * TypeScript, JSX, and TSX files. They target the gap between markup
+ * accessibility (jsx-a11y, neighbor ESLint) and prose accessibility  - 
+ * no existing a11y linting tool covers this space.
+ *
+ * Entry point: @a11yfred/neighbor/content
+ *
+ * ─── Rule methodology ────────────────────────────────────────────────────────
+ *
+ * A rule is included only when all three conditions hold:
+ *   1. A WCAG Success Criterion directly applies, OR the rule appears in ≥3
+ *      independent authoritative style guides.
+ *   2. The rule can be expressed as a finite, deterministic pattern (string
+ *      match, token count, or AST shape)  -  no NLP, no runtime context.
+ *   3. Expert consensus is unambiguous across sources. No credible authority
+ *      argues the opposite.
+ *
+ * Rules that require subjective reading (tone, full cultural sensitivity
+ * beyond a term list) or are under active community debate are excluded.
+ *
+ * ─── Sources ────────────────────────────────────────────────────────────────
+ *
+ * International accessible writing guides:
+ *   United States   plain language.gov, digital.gov/guides/plain-language
+ *   United States   advocacy.sba.gov  -  SBA Content Style Guide
+ *   United Kingdom  gov.uk/guidance/publishing-accessible-documents
+ *   United Kingdom  accessibility-manual.dwp.gov.uk/best-practice/writing-content
+ *   Australia       stylemanual.gov.au/accessible-and-inclusive-content
+ *   Canada          accessible.canada.ca/guidelines-creating-accessible-documents
+ *   Global (W3C)    w3.org/WAI/tips/writing/  -  primary authority
+ *   Global (W3C)    wcag.com/authors/
+ *
+ * Disability language authorities:
+ *   NCDJ            cronkite.asu.edu/ncdj/disability-language-style-guide
+ *   AP Stylebook    amdisrights.org/ap-stylebook-primer-on-disability
+ *   ADA Nat. Network adata.org/factsheet/ADANN-writing
+ *   APA Style       apastyle.apa.org/style-grammar-guidelines/bias-free-language/disability
+ *   SIGACCESS       sigaccess.org/…/accessible-writing-guide/
+ *   Nicolas Steenhout incl.ca/disability-language-is-a-nuanced-thing/  -  Nothing About Us Without Us; language as community choice
+ *   Léonie Watson      tink.uk  -  "There is no right or wrong answer because it is a matter of personal choice, and the choice depends on context." (cited by Steenhout)
+ *
+ * Technical writing:
+ *   Google Dev Style developers.google.com/style/accessibility
+ *   Section 508     section508.gov/create/alternative-text/
+ *
+ * UX and content design:
+ *   UX Content Co.  uxcontent.com/accessible-ux-writing-a-guide-for-inclusive-content-design/
+ *   A11y Collective  a11y-collective.com/blog/accessible-writing/
+ *   SJSU Writing Ctr sjsu.edu/writingcenter/docs/handouts/Accessible Writing Strategies.pdf
+ */
+
+import { CONTENT_RULE_FACTORIES, buildContentRecommendedRules } from './lib/content-rules.js'
+
+const NS = '@a11yfred/neighbor/content'
+
+const rules = Object.fromEntries(
+  Object.entries(CONTENT_RULE_FACTORIES).map(([name, factory]) => [name, factory()])
+)
+
+const plugin = { meta: { name: NS }, rules }
+
+export default {
+  ...plugin,
+  configs: {
+    recommended: {
+      plugins: {
+        [NS]: plugin,
+      },
+      rules: buildContentRecommendedRules(NS),
+    },
+  },
+}

package/neighbor-eslint-angular.mjs

@@ -1,68 +1,68 @@
-/**
- * @a11yfred/neighbor — ESLint plugin (Angular templates)
- *
- * Flags the same ARIA anti-patterns as neighbor-eslint.mjs but for Angular
- * component templates. Requires @angular-eslint/template-parser.
- *
- * Rules that require ancestor walking (no-log-with-interactive-children,
- * no-menu-role-on-nav, no-heading-inside-interactive) are limited because
- * @angular-eslint/template-parser does not attach parent references to nodes.
- * Those rules will still fire for direct matches but cannot walk the tree.
- *
- * Usage in eslint.config.js:
- *   import angularTemplateParser from '@angular-eslint/template-parser'
- *   import neighbor from '@a11yfred/neighbor/angular'
- *
- *   export default [
- *     {
- *       files: ['**\/*.html'],
- *       languageOptions: { parser: angularTemplateParser },
- *       plugins: { '@a11yfred/neighbor': neighbor },
- *       rules: neighbor.configs.recommended.rules,
- *     },
- *   ]
- */
-
-import { h } from './lib/helpers-angular.js'
-import { buildRules, buildRecommendedRules, buildPortabilityRules } from './lib/rules.js'
-import { buildUlamRulesAngular, buildUlamRecommendedRulesFramework } from './lib/ulam-rules.js'
-
-const NS = '@a11yfred/neighbor'
-const rules = { ...buildRules(h), ...buildUlamRulesAngular() }
-const plugin = { meta: { name: `${NS}/angular` }, rules }
-
-let angularA11y = null
-try { angularA11y = (await import('@angular-eslint/eslint-plugin-template')).default } catch {}
-
-const ANGULAR_A11Y_RULES = [
-  'alt-text', 'click-events-have-key-events', 'elements-content',
-  'interactive-supports-focus', 'label-has-associated-control',
-  'mouse-events-have-key-events', 'no-autofocus', 'no-distracting-elements',
-  'no-positive-tabindex', 'role-has-required-aria', 'table-scope', 'valid-aria',
-]
-
-function getAngularA11yRules(plugin) {
-  const out = {}
-  for (const rule of ANGULAR_A11Y_RULES) {
-    if (plugin.rules?.[rule]) out[`@angular-eslint/template/${rule}`] = 'error'
-  }
-  return out
-}
-
-export default {
-  ...plugin,
-  configs: {
-    recommended: {
-      plugins: {
-        [NS]: plugin,
-        ...(angularA11y ? { '@angular-eslint/template': angularA11y } : {}),
-      },
-      rules: {
-        ...(angularA11y ? getAngularA11yRules(angularA11y) : {}),
-        ...buildRecommendedRules(NS),
-        ...buildPortabilityRules(NS),
-        ...buildUlamRecommendedRulesFramework(NS),
-      },
-    },
-  },
-}
+/**
+ * @a11yfred/neighbor  -  ESLint plugin (Angular templates)
+ *
+ * Flags the same ARIA anti-patterns as neighbor-eslint.mjs but for Angular
+ * component templates. Requires @angular-eslint/template-parser.
+ *
+ * Rules that require ancestor walking (no-log-with-interactive-children,
+ * no-menu-role-on-nav, no-heading-inside-interactive) are limited because
+ * @angular-eslint/template-parser does not attach parent references to nodes.
+ * Those rules will still fire for direct matches but cannot walk the tree.
+ *
+ * Usage in eslint.config.js:
+ *   import angularTemplateParser from '@angular-eslint/template-parser'
+ *   import neighbor from '@a11yfred/neighbor/angular'
+ *
+ *   export default [
+ *     {
+ *       files: ['**\/*.html'],
+ *       languageOptions: { parser: angularTemplateParser },
+ *       plugins: { '@a11yfred/neighbor': neighbor },
+ *       rules: neighbor.configs.recommended.rules,
+ *     },
+ *   ]
+ */
+
+import { h } from './lib/helpers-angular.js'
+import { buildRules, buildRecommendedRules, buildPortabilityRules } from './lib/rules.js'
+import { buildUlamRulesAngular, buildUlamRecommendedRulesFramework } from './lib/ulam-rules.js'
+
+const NS = '@a11yfred/neighbor'
+const rules = { ...buildRules(h), ...buildUlamRulesAngular() }
+const plugin = { meta: { name: `${NS}/angular` }, rules }
+
+let angularA11y = null
+try { angularA11y = (await import('@angular-eslint/eslint-plugin-template')).default } catch {}
+
+const ANGULAR_A11Y_RULES = [
+  'alt-text', 'click-events-have-key-events', 'elements-content',
+  'interactive-supports-focus', 'label-has-associated-control',
+  'mouse-events-have-key-events', 'no-autofocus', 'no-distracting-elements',
+  'no-positive-tabindex', 'role-has-required-aria', 'table-scope', 'valid-aria',
+]
+
+function getAngularA11yRules(plugin) {
+  const out = {}
+  for (const rule of ANGULAR_A11Y_RULES) {
+    if (plugin.rules?.[rule]) out[`@angular-eslint/template/${rule}`] = 'error'
+  }
+  return out
+}
+
+export default {
+  ...plugin,
+  configs: {
+    recommended: {
+      plugins: {
+        [NS]: plugin,
+        ...(angularA11y ? { '@angular-eslint/template': angularA11y } : {}),
+      },
+      rules: {
+        ...(angularA11y ? getAngularA11yRules(angularA11y) : {}),
+        ...buildRecommendedRules(NS),
+        ...buildPortabilityRules(NS),
+        ...buildUlamRecommendedRulesFramework(NS),
+      },
+    },
+  },
+}

package/neighbor-eslint-vue.mjs

@@ -1,48 +1,48 @@
-/**
- * @a11yfred/neighbor — ESLint plugin (Vue SFCs)
- *
- * Flags the same ARIA anti-patterns as neighbor-eslint.mjs but for Vue templates.
- * Requires vue-eslint-parser as the project's ESLint parser for .vue files.
- *
- * Usage in eslint.config.js:
- *   import vueParser from 'vue-eslint-parser'
- *   import neighbor from '@a11yfred/neighbor/vue'
- *
- *   export default [
- *     {
- *       files: ['**\/*.vue'],
- *       languageOptions: { parser: vueParser },
- *       plugins: { '@a11yfred/neighbor': neighbor },
- *       rules: neighbor.configs.recommended.rules,
- *     },
- *   ]
- */
-
-import { h } from './lib/helpers-vue.js'
-import { buildRules, buildRecommendedRules, buildPortabilityRules } from './lib/rules.js'
-import { buildUlamRulesVue, buildUlamRecommendedRulesFramework } from './lib/ulam-rules.js'
-
-const NS = '@a11yfred/neighbor'
-const rules = { ...buildRules(h), ...buildUlamRulesVue() }
-const plugin = { meta: { name: `${NS}/vue` }, rules }
-
-let vueA11y = null
-try { vueA11y = (await import('eslint-plugin-vuejs-accessibility')).default } catch {}
-
-export default {
-  ...plugin,
-  configs: {
-    recommended: {
-      plugins: {
-        [NS]: plugin,
-        ...(vueA11y ? { 'vuejs-accessibility': vueA11y } : {}),
-      },
-      rules: {
-        ...(vueA11y ? vueA11y.configs['flat/recommended'].rules : {}),
-        ...buildRecommendedRules(NS),
-        ...buildPortabilityRules(NS),
-        ...buildUlamRecommendedRulesFramework(NS),
-      },
-    },
-  },
-}
+/**
+ * @a11yfred/neighbor  -  ESLint plugin (Vue SFCs)
+ *
+ * Flags the same ARIA anti-patterns as neighbor-eslint.mjs but for Vue templates.
+ * Requires vue-eslint-parser as the project's ESLint parser for .vue files.
+ *
+ * Usage in eslint.config.js:
+ *   import vueParser from 'vue-eslint-parser'
+ *   import neighbor from '@a11yfred/neighbor/vue'
+ *
+ *   export default [
+ *     {
+ *       files: ['**\/*.vue'],
+ *       languageOptions: { parser: vueParser },
+ *       plugins: { '@a11yfred/neighbor': neighbor },
+ *       rules: neighbor.configs.recommended.rules,
+ *     },
+ *   ]
+ */
+
+import { h } from './lib/helpers-vue.js'
+import { buildRules, buildRecommendedRules, buildPortabilityRules } from './lib/rules.js'
+import { buildUlamRulesVue, buildUlamRecommendedRulesFramework } from './lib/ulam-rules.js'
+
+const NS = '@a11yfred/neighbor'
+const rules = { ...buildRules(h), ...buildUlamRulesVue() }
+const plugin = { meta: { name: `${NS}/vue` }, rules }
+
+let vueA11y = null
+try { vueA11y = (await import('eslint-plugin-vuejs-accessibility')).default } catch {}
+
+export default {
+  ...plugin,
+  configs: {
+    recommended: {
+      plugins: {
+        [NS]: plugin,
+        ...(vueA11y ? { 'vuejs-accessibility': vueA11y } : {}),
+      },
+      rules: {
+        ...(vueA11y ? vueA11y.configs['flat/recommended'].rules : {}),
+        ...buildRecommendedRules(NS),
+        ...buildPortabilityRules(NS),
+        ...buildUlamRecommendedRulesFramework(NS),
+      },
+    },
+  },
+}

package/neighbor-eslint.mjs

@@ -1,56 +1,56 @@
-/**
- * @a11yfred/neighbor — ESLint plugin (React / JSX)
- *
- * Flags ARIA patterns that are widely derided, semantically wrong, or have
- * poor/no AT support — but are not caught by eslint-plugin-jsx-a11y recommended.
- *
- * Sources and credits:
- *   Adrian Roselli         adrianroselli.com
- *   Heydon Pickering       heydonworks.com, inclusive-components.design
- *   Scott O'Hara           scottohara.me
- *   Patrick Lauke          splintered.co.uk, patrickhlauke.github.io/aria
- *   Karl Groves            karlgroves.com
- *   Marcy Sutton           marcysutton.com
- *   Eric Eggert            yatil.net
- *   WAI-ARIA APG           w3.org/WAI/ARIA/apg
- *   ARIA 1.2 spec          w3.org/TR/wai-aria-1.2
- *
- * Rules already covered by jsx-a11y recommended (not duplicated here):
- *   aria-hidden on focusable           → jsx-a11y/no-aria-hidden-on-focusable
- *   presentation/none on interactive   → jsx-a11y/no-interactive-element-to-noninteractive-role
- *   redundant role                     → jsx-a11y/no-redundant-roles
- *   prefer semantic element            → jsx-a11y/prefer-tag-over-role
- *   invalid role value                 → jsx-a11y/aria-role
- *   invalid aria prop                  → jsx-a11y/aria-props
- *   tabindex > 0                       → jsx-a11y/tabindex-no-positive
- *   tabindex on non-interactive        → jsx-a11y/no-noninteractive-tabindex
- *   img missing alt                    → jsx-a11y/alt-text
- *   input missing label                → jsx-a11y/label-has-associated-control
- */
-
-import jsxA11y from 'eslint-plugin-jsx-a11y'
-import { h } from './lib/helpers-jsx.js'
-import { buildRules, buildRecommendedRules } from './lib/rules.js'
-import { buildUlamRules, buildUlamRecommendedRules } from './lib/ulam-rules.js'
-
-const NS = '@a11yfred/neighbor'
-const rules = { ...buildRules(h), ...buildUlamRules() }
-
-const plugin = { meta: { name: NS }, rules }
-
-export default {
-  ...plugin,
-  configs: {
-    recommended: {
-      plugins: {
-        [NS]: plugin,
-        'jsx-a11y': jsxA11y,
-      },
-      rules: {
-        ...jsxA11y.configs.recommended.rules,
-        ...buildRecommendedRules(NS),
-        ...buildUlamRecommendedRules(NS),
-      },
-    },
-  },
-}
+/**
+ * @a11yfred/neighbor  -  ESLint plugin (React / JSX)
+ *
+ * Flags ARIA patterns that are widely derided, semantically wrong, or have
+ * poor/no AT support  -  but are not caught by eslint-plugin-jsx-a11y recommended.
+ *
+ * Sources and credits:
+ *   Adrian Roselli         adrianroselli.com
+ *   Heydon Pickering       heydonworks.com, inclusive-components.design
+ *   Scott O'Hara           scottohara.me
+ *   Patrick Lauke          splintered.co.uk, patrickhlauke.github.io/aria
+ *   Karl Groves            karlgroves.com
+ *   Marcy Sutton           marcysutton.com
+ *   Eric Eggert            yatil.net
+ *   WAI-ARIA APG           w3.org/WAI/ARIA/apg
+ *   ARIA 1.2 spec          w3.org/TR/wai-aria-1.2
+ *
+ * Rules already covered by jsx-a11y recommended (not duplicated here):
+ *   aria-hidden on focusable           → jsx-a11y/no-aria-hidden-on-focusable
+ *   presentation/none on interactive   → jsx-a11y/no-interactive-element-to-noninteractive-role
+ *   redundant role                     → jsx-a11y/no-redundant-roles
+ *   prefer semantic element            → jsx-a11y/prefer-tag-over-role
+ *   invalid role value                 → jsx-a11y/aria-role
+ *   invalid aria prop                  → jsx-a11y/aria-props
+ *   tabindex > 0                       → jsx-a11y/tabindex-no-positive
+ *   tabindex on non-interactive        → jsx-a11y/no-noninteractive-tabindex
+ *   img missing alt                    → jsx-a11y/alt-text
+ *   input missing label                → jsx-a11y/label-has-associated-control
+ */
+
+import jsxA11y from 'eslint-plugin-jsx-a11y'
+import { h } from './lib/helpers-jsx.js'
+import { buildRules, buildRecommendedRules } from './lib/rules.js'
+import { buildUlamRules, buildUlamRecommendedRules } from './lib/ulam-rules.js'
+
+const NS = '@a11yfred/neighbor'
+const rules = { ...buildRules(h), ...buildUlamRules() }
+
+const plugin = { meta: { name: NS }, rules }
+
+export default {
+  ...plugin,
+  configs: {
+    recommended: {
+      plugins: {
+        [NS]: plugin,
+        'jsx-a11y': jsxA11y,
+      },
+      rules: {
+        ...jsxA11y.configs.recommended.rules,
+        ...buildRecommendedRules(NS),
+        ...buildUlamRecommendedRules(NS),
+      },
+    },
+  },
+}