@terra-symposium/hygiene 0.0.0-stage → 2.4.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +70 -2
- package/dist/accessibility.d.ts +39 -0
- package/dist/accessibility.d.ts.map +1 -0
- package/dist/accessibility.js +524 -0
- package/dist/accessibility.js.map +1 -0
- package/dist/app/workspace-test-runner.d.ts +6 -0
- package/dist/app/workspace-test-runner.d.ts.map +1 -0
- package/dist/app/workspace-test-runner.js +39 -0
- package/dist/app/workspace-test-runner.js.map +1 -0
- package/dist/capabilities/core/analysis.d.ts +22 -0
- package/dist/capabilities/core/analysis.d.ts.map +1 -0
- package/dist/capabilities/core/analysis.js +44 -0
- package/dist/capabilities/core/analysis.js.map +1 -0
- package/dist/capabilities/core/cli.d.ts +19 -0
- package/dist/capabilities/core/cli.d.ts.map +1 -0
- package/dist/capabilities/core/cli.js +58 -0
- package/dist/capabilities/core/cli.js.map +1 -0
- package/dist/capabilities/core/config.d.ts +49 -0
- package/dist/capabilities/core/config.d.ts.map +1 -0
- package/dist/capabilities/core/config.js +88 -0
- package/dist/capabilities/core/config.js.map +1 -0
- package/dist/capabilities/core/index.d.ts +11 -0
- package/dist/capabilities/core/index.d.ts.map +1 -0
- package/dist/capabilities/core/index.js +11 -0
- package/dist/capabilities/core/index.js.map +1 -0
- package/dist/capabilities/core/lib/files.d.ts +55 -0
- package/dist/capabilities/core/lib/files.d.ts.map +1 -0
- package/dist/capabilities/core/lib/files.js +287 -0
- package/dist/capabilities/core/lib/files.js.map +1 -0
- package/dist/capabilities/core/lib/progress.d.ts +25 -0
- package/dist/capabilities/core/lib/progress.d.ts.map +1 -0
- package/dist/capabilities/core/lib/progress.js +40 -0
- package/dist/capabilities/core/lib/progress.js.map +1 -0
- package/dist/capabilities/core/lib/source-kind.d.ts +14 -0
- package/dist/capabilities/core/lib/source-kind.d.ts.map +1 -0
- package/dist/capabilities/core/lib/source-kind.js +29 -0
- package/dist/capabilities/core/lib/source-kind.js.map +1 -0
- package/dist/capabilities/core/types.d.ts +156 -0
- package/dist/capabilities/core/types.d.ts.map +1 -0
- package/dist/capabilities/core/types.js +35 -0
- package/dist/capabilities/core/types.js.map +1 -0
- package/dist/capabilities/documentation/cli.d.ts +3 -0
- package/dist/capabilities/documentation/cli.d.ts.map +1 -0
- package/dist/capabilities/documentation/cli.js +14 -0
- package/dist/capabilities/documentation/cli.js.map +1 -0
- package/dist/capabilities/documentation/index.d.ts +5 -0
- package/dist/capabilities/documentation/index.d.ts.map +1 -0
- package/dist/capabilities/documentation/index.js +5 -0
- package/dist/capabilities/documentation/index.js.map +1 -0
- package/dist/capabilities/documentation/lib/documentation.d.ts +108 -0
- package/dist/capabilities/documentation/lib/documentation.d.ts.map +1 -0
- package/dist/capabilities/documentation/lib/documentation.js +1007 -0
- package/dist/capabilities/documentation/lib/documentation.js.map +1 -0
- package/dist/capabilities/formatting/cli.d.ts +3 -0
- package/dist/capabilities/formatting/cli.d.ts.map +1 -0
- package/dist/capabilities/formatting/cli.js +15 -0
- package/dist/capabilities/formatting/cli.js.map +1 -0
- package/dist/capabilities/formatting/index.d.ts +8 -0
- package/dist/capabilities/formatting/index.d.ts.map +1 -0
- package/dist/capabilities/formatting/index.js +8 -0
- package/dist/capabilities/formatting/index.js.map +1 -0
- package/dist/capabilities/formatting/lib/collapse.d.ts +13 -0
- package/dist/capabilities/formatting/lib/collapse.d.ts.map +1 -0
- package/dist/capabilities/formatting/lib/collapse.js +179 -0
- package/dist/capabilities/formatting/lib/collapse.js.map +1 -0
- package/dist/capabilities/formatting/lib/inline-if.d.ts +13 -0
- package/dist/capabilities/formatting/lib/inline-if.d.ts.map +1 -0
- package/dist/capabilities/formatting/lib/inline-if.js +49 -0
- package/dist/capabilities/formatting/lib/inline-if.js.map +1 -0
- package/dist/capabilities/formatting/lib/run-formatting.d.ts +14 -0
- package/dist/capabilities/formatting/lib/run-formatting.d.ts.map +1 -0
- package/dist/capabilities/formatting/lib/run-formatting.js +134 -0
- package/dist/capabilities/formatting/lib/run-formatting.js.map +1 -0
- package/dist/capabilities/imports/cli.d.ts +3 -0
- package/dist/capabilities/imports/cli.d.ts.map +1 -0
- package/dist/capabilities/imports/cli.js +9 -0
- package/dist/capabilities/imports/cli.js.map +1 -0
- package/dist/capabilities/imports/index.d.ts +6 -0
- package/dist/capabilities/imports/index.d.ts.map +1 -0
- package/dist/capabilities/imports/index.js +6 -0
- package/dist/capabilities/imports/index.js.map +1 -0
- package/dist/capabilities/imports/lib/imports.d.ts +19 -0
- package/dist/capabilities/imports/lib/imports.d.ts.map +1 -0
- package/dist/capabilities/imports/lib/imports.js +88 -0
- package/dist/capabilities/imports/lib/imports.js.map +1 -0
- package/dist/capabilities/languages/cli.d.ts +3 -0
- package/dist/capabilities/languages/cli.d.ts.map +1 -0
- package/dist/capabilities/languages/cli.js +9 -0
- package/dist/capabilities/languages/cli.js.map +1 -0
- package/dist/capabilities/languages/index.d.ts +6 -0
- package/dist/capabilities/languages/index.d.ts.map +1 -0
- package/dist/capabilities/languages/index.js +6 -0
- package/dist/capabilities/languages/index.js.map +1 -0
- package/dist/capabilities/languages/lib/language-profiles.d.ts +110 -0
- package/dist/capabilities/languages/lib/language-profiles.d.ts.map +1 -0
- package/dist/capabilities/languages/lib/language-profiles.js +509 -0
- package/dist/capabilities/languages/lib/language-profiles.js.map +1 -0
- package/dist/capabilities/languages/lib/run-language-checks.d.ts +12 -0
- package/dist/capabilities/languages/lib/run-language-checks.d.ts.map +1 -0
- package/dist/capabilities/languages/lib/run-language-checks.js +109 -0
- package/dist/capabilities/languages/lib/run-language-checks.js.map +1 -0
- package/dist/capabilities/naming/cli.d.ts +3 -0
- package/dist/capabilities/naming/cli.d.ts.map +1 -0
- package/dist/capabilities/naming/cli.js +15 -0
- package/dist/capabilities/naming/cli.js.map +1 -0
- package/dist/capabilities/naming/index.d.ts +5 -0
- package/dist/capabilities/naming/index.d.ts.map +1 -0
- package/dist/capabilities/naming/index.js +5 -0
- package/dist/capabilities/naming/index.js.map +1 -0
- package/dist/capabilities/naming/lib/naming.d.ts +169 -0
- package/dist/capabilities/naming/lib/naming.d.ts.map +1 -0
- package/dist/capabilities/naming/lib/naming.js +908 -0
- package/dist/capabilities/naming/lib/naming.js.map +1 -0
- package/dist/capabilities/patterns/cli.d.ts +3 -0
- package/dist/capabilities/patterns/cli.d.ts.map +1 -0
- package/dist/capabilities/patterns/cli.js +30 -0
- package/dist/capabilities/patterns/cli.js.map +1 -0
- package/dist/capabilities/patterns/index.d.ts +5 -0
- package/dist/capabilities/patterns/index.d.ts.map +1 -0
- package/dist/capabilities/patterns/index.js +5 -0
- package/dist/capabilities/patterns/index.js.map +1 -0
- package/dist/capabilities/patterns/lib/patterns.d.ts +102 -0
- package/dist/capabilities/patterns/lib/patterns.d.ts.map +1 -0
- package/dist/capabilities/patterns/lib/patterns.js +1584 -0
- package/dist/capabilities/patterns/lib/patterns.js.map +1 -0
- package/dist/capabilities/refactoring/cli.d.ts +3 -0
- package/dist/capabilities/refactoring/cli.d.ts.map +1 -0
- package/dist/capabilities/refactoring/cli.js +15 -0
- package/dist/capabilities/refactoring/cli.js.map +1 -0
- package/dist/capabilities/refactoring/index.d.ts +6 -0
- package/dist/capabilities/refactoring/index.d.ts.map +1 -0
- package/dist/capabilities/refactoring/index.js +6 -0
- package/dist/capabilities/refactoring/index.js.map +1 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.d.ts +42 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.d.ts.map +1 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.js +166 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.js.map +1 -0
- package/dist/capabilities/refactoring/lib/single-use.d.ts +61 -0
- package/dist/capabilities/refactoring/lib/single-use.d.ts.map +1 -0
- package/dist/capabilities/refactoring/lib/single-use.js +1791 -0
- package/dist/capabilities/refactoring/lib/single-use.js.map +1 -0
- package/dist/capabilities/reports/cli.d.ts +3 -0
- package/dist/capabilities/reports/cli.d.ts.map +1 -0
- package/dist/capabilities/reports/cli.js +34 -0
- package/dist/capabilities/reports/cli.js.map +1 -0
- package/dist/capabilities/reports/index.d.ts +10 -0
- package/dist/capabilities/reports/index.d.ts.map +1 -0
- package/dist/capabilities/reports/index.js +10 -0
- package/dist/capabilities/reports/index.js.map +1 -0
- package/dist/capabilities/reports/lib/github-report.d.ts +94 -0
- package/dist/capabilities/reports/lib/github-report.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/github-report.js +499 -0
- package/dist/capabilities/reports/lib/github-report.js.map +1 -0
- package/dist/capabilities/reports/lib/history-report.d.ts +58 -0
- package/dist/capabilities/reports/lib/history-report.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/history-report.js +300 -0
- package/dist/capabilities/reports/lib/history-report.js.map +1 -0
- package/dist/capabilities/reports/lib/node-reporter.d.ts +79 -0
- package/dist/capabilities/reports/lib/node-reporter.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/node-reporter.js +244 -0
- package/dist/capabilities/reports/lib/node-reporter.js.map +1 -0
- package/dist/capabilities/reports/lib/playwright-reporter.d.ts +100 -0
- package/dist/capabilities/reports/lib/playwright-reporter.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/playwright-reporter.js +122 -0
- package/dist/capabilities/reports/lib/playwright-reporter.js.map +1 -0
- package/dist/capabilities/security/cli.d.ts +3 -0
- package/dist/capabilities/security/cli.d.ts.map +1 -0
- package/dist/capabilities/security/cli.js +9 -0
- package/dist/capabilities/security/cli.js.map +1 -0
- package/dist/capabilities/security/index.d.ts +5 -0
- package/dist/capabilities/security/index.d.ts.map +1 -0
- package/dist/capabilities/security/index.js +5 -0
- package/dist/capabilities/security/index.js.map +1 -0
- package/dist/capabilities/security/lib/security.d.ts +19 -0
- package/dist/capabilities/security/lib/security.d.ts.map +1 -0
- package/dist/capabilities/security/lib/security.js +115 -0
- package/dist/capabilities/security/lib/security.js.map +1 -0
- package/dist/capabilities/ui/cli.d.ts +3 -0
- package/dist/capabilities/ui/cli.d.ts.map +1 -0
- package/dist/capabilities/ui/cli.js +22 -0
- package/dist/capabilities/ui/cli.js.map +1 -0
- package/dist/capabilities/ui/index.d.ts +8 -0
- package/dist/capabilities/ui/index.d.ts.map +1 -0
- package/dist/capabilities/ui/index.js +8 -0
- package/dist/capabilities/ui/index.js.map +1 -0
- package/dist/capabilities/ui/lib/accessibility.d.ts +37 -0
- package/dist/capabilities/ui/lib/accessibility.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/accessibility.js +676 -0
- package/dist/capabilities/ui/lib/accessibility.js.map +1 -0
- package/dist/capabilities/ui/lib/display-name.d.ts +42 -0
- package/dist/capabilities/ui/lib/display-name.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/display-name.js +277 -0
- package/dist/capabilities/ui/lib/display-name.js.map +1 -0
- package/dist/capabilities/ui/lib/error-boundaries.d.ts +30 -0
- package/dist/capabilities/ui/lib/error-boundaries.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/error-boundaries.js +401 -0
- package/dist/capabilities/ui/lib/error-boundaries.js.map +1 -0
- package/dist/capabilities/ui/lib/ui-recommendations.d.ts +45 -0
- package/dist/capabilities/ui/lib/ui-recommendations.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/ui-recommendations.js +183 -0
- package/dist/capabilities/ui/lib/ui-recommendations.js.map +1 -0
- package/dist/display-name.d.ts +44 -0
- package/dist/display-name.d.ts.map +1 -0
- package/dist/display-name.js +256 -0
- package/dist/display-name.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/accessibility.d.ts +5 -0
- package/dist/lib/accessibility.d.ts.map +1 -0
- package/dist/lib/accessibility.js +5 -0
- package/dist/lib/accessibility.js.map +1 -0
- package/dist/lib/collapse.d.ts +5 -0
- package/dist/lib/collapse.d.ts.map +1 -0
- package/dist/lib/collapse.js +5 -0
- package/dist/lib/collapse.js.map +1 -0
- package/dist/lib/dev.d.ts +3 -0
- package/dist/lib/dev.d.ts.map +1 -0
- package/dist/lib/dev.js +126 -0
- package/dist/lib/dev.js.map +1 -0
- package/dist/lib/display-name.d.ts +5 -0
- package/dist/lib/display-name.d.ts.map +1 -0
- package/dist/lib/display-name.js +5 -0
- package/dist/lib/display-name.js.map +1 -0
- package/dist/lib/documentation.d.ts +5 -0
- package/dist/lib/documentation.d.ts.map +1 -0
- package/dist/lib/documentation.js +5 -0
- package/dist/lib/documentation.js.map +1 -0
- package/dist/lib/error-boundaries-astro.d.ts +6 -0
- package/dist/lib/error-boundaries-astro.d.ts.map +1 -0
- package/dist/lib/error-boundaries-astro.js +6 -0
- package/dist/lib/error-boundaries-astro.js.map +1 -0
- package/dist/lib/error-boundaries-react.d.ts +6 -0
- package/dist/lib/error-boundaries-react.d.ts.map +1 -0
- package/dist/lib/error-boundaries-react.js +6 -0
- package/dist/lib/error-boundaries-react.js.map +1 -0
- package/dist/lib/error-boundaries.d.ts +5 -0
- package/dist/lib/error-boundaries.d.ts.map +1 -0
- package/dist/lib/error-boundaries.js +5 -0
- package/dist/lib/error-boundaries.js.map +1 -0
- package/dist/lib/eslint-api.d.ts +13 -0
- package/dist/lib/eslint-api.d.ts.map +1 -0
- package/dist/lib/eslint-api.js +24 -0
- package/dist/lib/eslint-api.js.map +1 -0
- package/dist/lib/files.d.ts +5 -0
- package/dist/lib/files.d.ts.map +1 -0
- package/dist/lib/files.js +5 -0
- package/dist/lib/files.js.map +1 -0
- package/dist/lib/formatting.d.ts +5 -0
- package/dist/lib/formatting.d.ts.map +1 -0
- package/dist/lib/formatting.js +5 -0
- package/dist/lib/formatting.js.map +1 -0
- package/dist/lib/github-report.d.ts +5 -0
- package/dist/lib/github-report.d.ts.map +1 -0
- package/dist/lib/github-report.js +5 -0
- package/dist/lib/github-report.js.map +1 -0
- package/dist/lib/history-report.d.ts +5 -0
- package/dist/lib/history-report.d.ts.map +1 -0
- package/dist/lib/history-report.js +5 -0
- package/dist/lib/history-report.js.map +1 -0
- package/dist/lib/imports.d.ts +5 -0
- package/dist/lib/imports.d.ts.map +1 -0
- package/dist/lib/imports.js +5 -0
- package/dist/lib/imports.js.map +1 -0
- package/dist/lib/index.d.ts +20 -0
- package/dist/lib/index.d.ts.map +1 -0
- package/dist/lib/index.js +20 -0
- package/dist/lib/index.js.map +1 -0
- package/dist/lib/inline-if.d.ts +5 -0
- package/dist/lib/inline-if.d.ts.map +1 -0
- package/dist/lib/inline-if.js +5 -0
- package/dist/lib/inline-if.js.map +1 -0
- package/dist/lib/language-checks.d.ts +5 -0
- package/dist/lib/language-checks.d.ts.map +1 -0
- package/dist/lib/language-checks.js +5 -0
- package/dist/lib/language-checks.js.map +1 -0
- package/dist/lib/language-profiles.d.ts +5 -0
- package/dist/lib/language-profiles.d.ts.map +1 -0
- package/dist/lib/language-profiles.js +5 -0
- package/dist/lib/language-profiles.js.map +1 -0
- package/dist/lib/naming.d.ts +5 -0
- package/dist/lib/naming.d.ts.map +1 -0
- package/dist/lib/naming.js +5 -0
- package/dist/lib/naming.js.map +1 -0
- package/dist/lib/node-reporter.d.ts +6 -0
- package/dist/lib/node-reporter.d.ts.map +1 -0
- package/dist/lib/node-reporter.js +6 -0
- package/dist/lib/node-reporter.js.map +1 -0
- package/dist/lib/object-forwarding.d.ts +5 -0
- package/dist/lib/object-forwarding.d.ts.map +1 -0
- package/dist/lib/object-forwarding.js +5 -0
- package/dist/lib/object-forwarding.js.map +1 -0
- package/dist/lib/patterns.d.ts +5 -0
- package/dist/lib/patterns.d.ts.map +1 -0
- package/dist/lib/patterns.js +5 -0
- package/dist/lib/patterns.js.map +1 -0
- package/dist/lib/playwright-reporter.d.ts +6 -0
- package/dist/lib/playwright-reporter.d.ts.map +1 -0
- package/dist/lib/playwright-reporter.js +6 -0
- package/dist/lib/playwright-reporter.js.map +1 -0
- package/dist/lib/port.d.ts +21 -0
- package/dist/lib/port.d.ts.map +1 -0
- package/dist/lib/port.js +81 -0
- package/dist/lib/port.js.map +1 -0
- package/dist/lib/progress.d.ts +5 -0
- package/dist/lib/progress.d.ts.map +1 -0
- package/dist/lib/progress.js +5 -0
- package/dist/lib/progress.js.map +1 -0
- package/dist/lib/reports.d.ts +5 -0
- package/dist/lib/reports.d.ts.map +1 -0
- package/dist/lib/reports.js +5 -0
- package/dist/lib/reports.js.map +1 -0
- package/dist/lib/runner.d.ts +150 -0
- package/dist/lib/runner.d.ts.map +1 -0
- package/dist/lib/runner.js +4522 -0
- package/dist/lib/runner.js.map +1 -0
- package/dist/lib/security.d.ts +5 -0
- package/dist/lib/security.d.ts.map +1 -0
- package/dist/lib/security.js +5 -0
- package/dist/lib/security.js.map +1 -0
- package/dist/lib/single-use.d.ts +6 -0
- package/dist/lib/single-use.d.ts.map +1 -0
- package/dist/lib/single-use.js +5 -0
- package/dist/lib/single-use.js.map +1 -0
- package/dist/lib/source-kind.d.ts +5 -0
- package/dist/lib/source-kind.d.ts.map +1 -0
- package/dist/lib/source-kind.js +5 -0
- package/dist/lib/source-kind.js.map +1 -0
- package/dist/lib/spinner-worker.d.ts +6 -0
- package/dist/lib/spinner-worker.d.ts.map +1 -0
- package/dist/lib/spinner-worker.js +33 -0
- package/dist/lib/spinner-worker.js.map +1 -0
- package/dist/lib/ui-quality.d.ts +5 -0
- package/dist/lib/ui-quality.d.ts.map +1 -0
- package/dist/lib/ui-quality.js +5 -0
- package/dist/lib/ui-quality.js.map +1 -0
- package/dist/lib/ui-recommendations.d.ts +5 -0
- package/dist/lib/ui-recommendations.d.ts.map +1 -0
- package/dist/lib/ui-recommendations.js +5 -0
- package/dist/lib/ui-recommendations.js.map +1 -0
- package/dist/spinner-worker.d.ts +6 -0
- package/dist/spinner-worker.d.ts.map +1 -0
- package/dist/spinner-worker.js +39 -0
- package/dist/spinner-worker.js.map +1 -0
- package/package.json +160 -5
- package/quality-configs/checkstyle.xml +29 -0
- package/quality-configs/pmd-rules.xml +11 -0
- package/quality.schema.json +392 -0
package/README.md
CHANGED
|
@@ -1,3 +1,71 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Quality
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Quality helps teams find and safely fix problems in their source code.
|
|
4
|
+
|
|
5
|
+
## Get started
|
|
6
|
+
|
|
7
|
+
Use Node.js 18.18 or later. Install the package and create a `quality.json` at the repository root (or under `config/`):
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
pnpm add -D @terra-symposium/hygiene
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"$schema": "./node_modules/@terra-symposium/hygiene/quality.schema.json",
|
|
16
|
+
"sourceRoots": ["src"],
|
|
17
|
+
"extensions": [".js", ".jsx", ".ts", ".tsx"],
|
|
18
|
+
"enabledChecks": { "format": false, "lint": false, "knip": false, "dead-code": false }
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Enable external checks after installing and configuring their native tools in the consuming repository. Run Quality, then review any edits:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
pnpm exec hygiene
|
|
26
|
+
git diff --check
|
|
27
|
+
git diff
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Usage
|
|
31
|
+
|
|
32
|
+
| Command | Scope | Writes fixes? |
|
|
33
|
+
| ---------------------------------------------- | --------------------------- | ------------- |
|
|
34
|
+
| `pnpm exec hygiene` | Changed and untracked files | Yes |
|
|
35
|
+
| `pnpm exec hygiene quality --all` | All configured files | Yes |
|
|
36
|
+
| `pnpm exec hygiene quality --all --warn` | All configured files | No |
|
|
37
|
+
|
|
38
|
+
The package exports focused APIs under `/core`, `/reports`, `/ui`, `/languages`, `/documentation`, `/formatting`, `/imports`, `/naming`, `/patterns`, `/refactoring`, and `/security`. See the [package map](../../docs/hygiene/1-packages/package-map.mdx) for contracts and CLI bins.
|
|
39
|
+
|
|
40
|
+
## Configuration
|
|
41
|
+
|
|
42
|
+
`quality.json` selects source roots, checks, autofixes, tools, and repository-owned static commands. Keep builds and functional tests in separate scripts. Put secrets in the consuming environment, never in config or Quality reports. The React and Astro error-boundary check is mandatory.
|
|
43
|
+
|
|
44
|
+
For a specific declaration whose identity or evaluation order must remain, place a `// hygiene-ignore single-use -- <concrete reason>` comment immediately before it or its TSDoc. The exemption applies only to that declaration's single-use finding.
|
|
45
|
+
|
|
46
|
+
## Validation
|
|
47
|
+
|
|
48
|
+
| Command | Checks |
|
|
49
|
+
| ---------------------- | ----------------------------- |
|
|
50
|
+
| `pnpm run quality:all` | Full configured Quality scope |
|
|
51
|
+
| `pnpm run test` | Unit or project tests |
|
|
52
|
+
| `pnpm run build` | Build output |
|
|
53
|
+
|
|
54
|
+
Quality can apply safe fixes; review the diff before committing. No separate browser or Playwright test command is defined here.
|
|
55
|
+
|
|
56
|
+
## Contributing
|
|
57
|
+
|
|
58
|
+
`src/capabilities/` owns focused checks and core utilities; `src/lib/` owns aggregate orchestration. Add positive and negative fixtures for transforms, verify syntax and rollback behavior, and review autofix diffs. Published changes need a Changeset.
|
|
59
|
+
|
|
60
|
+
Open changes through the repository pull-request workflow; see the [root README](../../README.md).
|
|
61
|
+
|
|
62
|
+
## Documentation
|
|
63
|
+
|
|
64
|
+
- [Setup and configuration](../../docs/hygiene/0-getting-started/overview.mdx)
|
|
65
|
+
- [Check reference](../../docs/hygiene/3-checks/check-reference.mdx)
|
|
66
|
+
- [Migration from former packages](../../docs/hygiene/5-operations/migration.mdx)
|
|
67
|
+
- [Troubleshooting](../../docs/hygiene/5-operations/troubleshooting.mdx)
|
|
68
|
+
|
|
69
|
+
## License
|
|
70
|
+
|
|
71
|
+
See the repository [LICENSE](../../LICENSE).
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/quality/src/accessibility.ts
|
|
3
|
+
* Finds JSX controls without a source-evident accessible name and applies only
|
|
4
|
+
* title-to-aria-label fixes whose meaning can be copied without inference.
|
|
5
|
+
*/
|
|
6
|
+
import type { QualityAnalysis, QualityCfg } from './runner.js';
|
|
7
|
+
/** A source location whose interactive JSX element has no known accessible name. */
|
|
8
|
+
export type AccessibilityFinding = {
|
|
9
|
+
file: string;
|
|
10
|
+
line: number;
|
|
11
|
+
column: number;
|
|
12
|
+
element: string;
|
|
13
|
+
message: string;
|
|
14
|
+
fixable: boolean;
|
|
15
|
+
};
|
|
16
|
+
/** Counts safe accessible-name attributes added by the source fixer. */
|
|
17
|
+
export type AccessibilityFixResult = {
|
|
18
|
+
fixed: number;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Finds JSX native controls and elements with explicit interactive roles that have no known accessible name.
|
|
22
|
+
* Dynamic child output, dynamic ARIA values, hidden controls, and components without explicit roles are skipped.
|
|
23
|
+
*
|
|
24
|
+
* @param cfg Quality configuration selecting source roots and extensions.
|
|
25
|
+
* @param analysis Optional shared parse context for the current quality run.
|
|
26
|
+
*
|
|
27
|
+
* @return Accessible-name findings with a flag for title-based fixes that can be applied safely.
|
|
28
|
+
*/
|
|
29
|
+
export declare function accessibilityFindings(cfg: QualityCfg, analysis?: QualityAnalysis): AccessibilityFinding[];
|
|
30
|
+
/**
|
|
31
|
+
* Adds aria-label only when a non-empty literal title is the sole source-evident name for an icon-only control.
|
|
32
|
+
* Existing visible text, labels, ARIA names, and uncertain component output are left unchanged.
|
|
33
|
+
*
|
|
34
|
+
* @param cfg Quality configuration selecting source roots and extensions.
|
|
35
|
+
*
|
|
36
|
+
* @return Result containing the number of aria-label attributes added or repaired.
|
|
37
|
+
*/
|
|
38
|
+
export declare function fixAccessibleNames(cfg: QualityCfg): AccessibilityFixResult;
|
|
39
|
+
//# sourceMappingURL=accessibility.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"accessibility.d.ts","sourceRoot":"","sources":["../src/accessibility.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM/D,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtI,wEAAwE;AACxE,MAAM,MAAM,sBAAsB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA0avD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,oBAAoB,EAAE,CAKzG;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,sBAAsB,CA8B1E"}
|
|
@@ -0,0 +1,524 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/quality/src/accessibility.ts
|
|
3
|
+
* Finds JSX controls without a source-evident accessible name and applies only
|
|
4
|
+
* title-to-aria-label fixes whose meaning can be copied without inference.
|
|
5
|
+
*/
|
|
6
|
+
/*//////////////////////////////////////////////////
|
|
7
|
+
IMPORTS
|
|
8
|
+
//////////////////////////////////////////////////*/
|
|
9
|
+
// API
|
|
10
|
+
import ts from 'typescript';
|
|
11
|
+
import { readFileSync, writeFileSync } from 'node:fs';
|
|
12
|
+
import { displayPath, srcFiles } from './files.js';
|
|
13
|
+
/*//////////////////////////////////////////////////
|
|
14
|
+
CONSTANTS
|
|
15
|
+
//////////////////////////////////////////////////*/
|
|
16
|
+
const JSX_EXTS = /\.(?:jsx|tsx|js|ts)$/i;
|
|
17
|
+
const NATIVE_LABELABLE = new Set(['button', 'input', 'select', 'textarea']);
|
|
18
|
+
const INPUT_BUTTON_TYPES = new Set(['button', 'submit', 'reset']);
|
|
19
|
+
const INTERACTIVE_ROLES = new Set([
|
|
20
|
+
'button',
|
|
21
|
+
'checkbox',
|
|
22
|
+
'combobox',
|
|
23
|
+
'gridcell',
|
|
24
|
+
'link',
|
|
25
|
+
'listbox',
|
|
26
|
+
'menuitem',
|
|
27
|
+
'menuitemcheckbox',
|
|
28
|
+
'menuitemradio',
|
|
29
|
+
'option',
|
|
30
|
+
'radio',
|
|
31
|
+
'searchbox',
|
|
32
|
+
'slider',
|
|
33
|
+
'spinbutton',
|
|
34
|
+
'progressbar',
|
|
35
|
+
'switch',
|
|
36
|
+
'tab',
|
|
37
|
+
'textbox',
|
|
38
|
+
'treeitem',
|
|
39
|
+
]);
|
|
40
|
+
const INTERACTIVE_NATIVE = new Set(['button', 'input', 'select', 'textarea', 'summary']);
|
|
41
|
+
/*//////////////////////////////////////////////////
|
|
42
|
+
HELPERS
|
|
43
|
+
//////////////////////////////////////////////////*/
|
|
44
|
+
/** Selects a TypeScript parser mode for a JSX-capable source path. */
|
|
45
|
+
function scriptKind(fileName) {
|
|
46
|
+
if (/\.tsx?$/i.test(fileName))
|
|
47
|
+
return ts.ScriptKind.TSX;
|
|
48
|
+
return ts.ScriptKind.JSX;
|
|
49
|
+
}
|
|
50
|
+
/** Returns JSX attributes from either an element or self-closing element. */
|
|
51
|
+
function attributesOf(element) {
|
|
52
|
+
return ts.isJsxElement(element) ? element.openingElement.attributes : element.attributes;
|
|
53
|
+
}
|
|
54
|
+
/** Returns JSX child nodes from either an element or self-closing element. */
|
|
55
|
+
function childrenOf(element) {
|
|
56
|
+
return ts.isJsxElement(element) ? element.children : [];
|
|
57
|
+
}
|
|
58
|
+
/** Returns the JSX tag name as written in source. */
|
|
59
|
+
function tagOf(element) {
|
|
60
|
+
return ts.isJsxElement(element) ? element.openingElement.tagName.getText() : element.tagName.getText();
|
|
61
|
+
}
|
|
62
|
+
/** Finds a named JSX attribute without interpreting spreads. */
|
|
63
|
+
function attributeOf(element, name) {
|
|
64
|
+
return attributesOf(element).properties.find((property) => ts.isJsxAttribute(property) && ts.isIdentifier(property.name) && property.name.text === name);
|
|
65
|
+
}
|
|
66
|
+
/** Reads a statically available string-like JSX attribute and preserves its expression source for safe copying. */
|
|
67
|
+
function staticAttribute(attribute) {
|
|
68
|
+
if (!attribute?.initializer)
|
|
69
|
+
return { state: 'empty' };
|
|
70
|
+
if (ts.isStringLiteral(attribute.initializer)) {
|
|
71
|
+
const value = attribute.initializer.text;
|
|
72
|
+
return meaningful(value) ? { state: 'static', value, source: attribute.initializer.getText() } : { state: 'empty' };
|
|
73
|
+
}
|
|
74
|
+
if (!ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression)
|
|
75
|
+
return { state: 'unknown' };
|
|
76
|
+
const expression = attribute.initializer.expression;
|
|
77
|
+
if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression) || ts.isNumericLiteral(expression)) {
|
|
78
|
+
const value = expression.text;
|
|
79
|
+
return meaningful(value) ? { state: 'static', value, source: attribute.initializer.getText() } : { state: 'empty' };
|
|
80
|
+
}
|
|
81
|
+
if (expression.kind === ts.SyntaxKind.TrueKeyword)
|
|
82
|
+
return { state: 'static', value: 'true', source: attribute.initializer.getText() };
|
|
83
|
+
if (expression.kind === ts.SyntaxKind.FalseKeyword || expression.kind === ts.SyntaxKind.NullKeyword)
|
|
84
|
+
return { state: 'empty' };
|
|
85
|
+
return { state: 'unknown' };
|
|
86
|
+
}
|
|
87
|
+
/** Reads a title only when its source is a string literal or a template literal without substitutions. */
|
|
88
|
+
function literalTitle(attribute) {
|
|
89
|
+
if (!attribute?.initializer)
|
|
90
|
+
return { state: 'empty' };
|
|
91
|
+
if (ts.isStringLiteral(attribute.initializer)) {
|
|
92
|
+
const value = attribute.initializer.text;
|
|
93
|
+
return meaningful(value) ? { state: 'static', value, source: attribute.initializer.getText() } : { state: 'empty' };
|
|
94
|
+
}
|
|
95
|
+
if (!ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression)
|
|
96
|
+
return { state: 'unknown' };
|
|
97
|
+
const expression = attribute.initializer.expression;
|
|
98
|
+
if (!ts.isStringLiteral(expression) && !ts.isNoSubstitutionTemplateLiteral(expression))
|
|
99
|
+
return { state: 'unknown' };
|
|
100
|
+
return meaningful(expression.text) ? { state: 'static', value: expression.text, source: attribute.initializer.getText() } : { state: 'empty' };
|
|
101
|
+
}
|
|
102
|
+
/** Checks for meaningful text after trimming whitespace and zero-width padding. */
|
|
103
|
+
function meaningful(value) {
|
|
104
|
+
return value.replace(/[\s\u00a0\u200b\ufeff]/g, '').replace(/&(?:nbsp|#0*160|#x0*a0);/gi, '').length > 0;
|
|
105
|
+
}
|
|
106
|
+
/** Returns whether the HTML hidden attribute is present, false, or uncertain. */
|
|
107
|
+
function hiddenAttributeState(element) {
|
|
108
|
+
const attribute = attributeOf(element, 'hidden');
|
|
109
|
+
if (!attribute)
|
|
110
|
+
return 'empty';
|
|
111
|
+
if (!attribute.initializer)
|
|
112
|
+
return 'named';
|
|
113
|
+
if (ts.isStringLiteral(attribute.initializer))
|
|
114
|
+
return 'named';
|
|
115
|
+
if (!ts.isJsxExpression(attribute.initializer) || !attribute.initializer.expression)
|
|
116
|
+
return 'unknown';
|
|
117
|
+
const expression = attribute.initializer.expression;
|
|
118
|
+
if (expression.kind === ts.SyntaxKind.TrueKeyword)
|
|
119
|
+
return 'named';
|
|
120
|
+
if (expression.kind === ts.SyntaxKind.FalseKeyword || expression.kind === ts.SyntaxKind.NullKeyword)
|
|
121
|
+
return 'empty';
|
|
122
|
+
if (ts.isNumericLiteral(expression))
|
|
123
|
+
return Number(expression.text) === 0 ? 'empty' : 'named';
|
|
124
|
+
return 'unknown';
|
|
125
|
+
}
|
|
126
|
+
/** Determines whether an element or an ancestor is hidden from the accessibility tree. */
|
|
127
|
+
function hiddenState(element) {
|
|
128
|
+
const hidden = hiddenAttributeState(element);
|
|
129
|
+
const ariaHiddenAttribute = attributeOf(element, 'aria-hidden');
|
|
130
|
+
const ariaHidden = ariaHiddenAttribute && !ariaHiddenAttribute.initializer ? { state: 'static', value: 'true', source: 'true' } : staticAttribute(ariaHiddenAttribute);
|
|
131
|
+
if (hidden === 'named' || (ariaHidden.state === 'static' && ariaHidden.value.toLowerCase() === 'true'))
|
|
132
|
+
return 'named';
|
|
133
|
+
if (hidden === 'unknown' || ariaHidden.state === 'unknown')
|
|
134
|
+
return 'unknown';
|
|
135
|
+
return 'empty';
|
|
136
|
+
}
|
|
137
|
+
/** Reads the static value of an input type, using HTML's default text type. */
|
|
138
|
+
function inputType(element) {
|
|
139
|
+
const type = attributeOf(element, 'type');
|
|
140
|
+
return type ? staticAttribute(type) : { state: 'static', value: 'text', source: '"text"' };
|
|
141
|
+
}
|
|
142
|
+
/** Identifies JSX elements that are native controls or explicitly assigned an interactive ARIA role. */
|
|
143
|
+
function targetKind(element) {
|
|
144
|
+
const tag = tagOf(element);
|
|
145
|
+
if (/^[a-z][a-z\d-]*$/.test(tag) && (INTERACTIVE_NATIVE.has(tag) || tag === 'progress')) {
|
|
146
|
+
if (tag === 'input') {
|
|
147
|
+
const type = inputType(element);
|
|
148
|
+
if (type.state === 'unknown' || (type.state === 'static' && type.value.toLowerCase() === 'hidden'))
|
|
149
|
+
return undefined;
|
|
150
|
+
}
|
|
151
|
+
return { element: `<${tag}>`, labelable: NATIVE_LABELABLE.has(tag) };
|
|
152
|
+
}
|
|
153
|
+
if (/^[a-z][a-z\d-]*$/.test(tag) && tag === 'a' && attributeOf(element, 'href'))
|
|
154
|
+
return { element: '<a>', labelable: false };
|
|
155
|
+
if (/^[a-z][a-z\d-]*$/.test(tag) && tag === 'area' && attributeOf(element, 'href'))
|
|
156
|
+
return { element: '<area>', labelable: false };
|
|
157
|
+
const role = staticAttribute(attributeOf(element, 'role'));
|
|
158
|
+
if (role.state === 'static' && INTERACTIVE_ROLES.has(role.value.toLowerCase()))
|
|
159
|
+
return { element: `<${tag}>[role="${role.value}"]`, labelable: false };
|
|
160
|
+
return undefined;
|
|
161
|
+
}
|
|
162
|
+
/** Combines child text evidence; a definite name takes precedence over uncertain extra children. */
|
|
163
|
+
function combine(states) {
|
|
164
|
+
if (states.includes('named'))
|
|
165
|
+
return 'named';
|
|
166
|
+
if (states.includes('unknown'))
|
|
167
|
+
return 'unknown';
|
|
168
|
+
return 'empty';
|
|
169
|
+
}
|
|
170
|
+
/** Determines whether a JSX element has static text or image alternative text in its children. */
|
|
171
|
+
function contentState(element, forLabel = false) {
|
|
172
|
+
const children = childrenOf(element);
|
|
173
|
+
if (!children.length)
|
|
174
|
+
return 'empty';
|
|
175
|
+
return combine(children.map((child) => childContentState(child, forLabel)));
|
|
176
|
+
}
|
|
177
|
+
/** Examines one JSX child for visible static text without guessing about component output. */
|
|
178
|
+
function childContentState(child, forLabel) {
|
|
179
|
+
if (ts.isJsxText(child))
|
|
180
|
+
return meaningful(child.text) ? 'named' : 'empty';
|
|
181
|
+
if (ts.isJsxExpression(child)) {
|
|
182
|
+
const expression = child.expression;
|
|
183
|
+
if (!expression)
|
|
184
|
+
return 'empty';
|
|
185
|
+
if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression) || ts.isNumericLiteral(expression))
|
|
186
|
+
return meaningful(expression.text) ? 'named' : 'empty';
|
|
187
|
+
if (expression.kind === ts.SyntaxKind.TrueKeyword || expression.kind === ts.SyntaxKind.FalseKeyword || expression.kind === ts.SyntaxKind.NullKeyword)
|
|
188
|
+
return 'empty';
|
|
189
|
+
return 'unknown';
|
|
190
|
+
}
|
|
191
|
+
if (ts.isJsxElement(child))
|
|
192
|
+
return elementContentState(child, forLabel);
|
|
193
|
+
if (ts.isJsxSelfClosingElement(child))
|
|
194
|
+
return elementContentState(child, forLabel);
|
|
195
|
+
if (ts.isJsxFragment(child))
|
|
196
|
+
return combine(child.children.map((nested) => childContentState(nested, forLabel)));
|
|
197
|
+
return 'unknown';
|
|
198
|
+
}
|
|
199
|
+
/** Examines a nested element, honoring hidden content, image alt, SVG names, and custom components. */
|
|
200
|
+
function elementContentState(element, forLabel) {
|
|
201
|
+
const hidden = hiddenState(element);
|
|
202
|
+
if (hidden === 'named')
|
|
203
|
+
return 'empty';
|
|
204
|
+
if (hidden === 'unknown')
|
|
205
|
+
return 'unknown';
|
|
206
|
+
const tag = tagOf(element);
|
|
207
|
+
if (tag === 'img') {
|
|
208
|
+
const alt = staticAttribute(attributeOf(element, 'alt'));
|
|
209
|
+
return alt.state === 'static' ? 'named' : alt.state === 'unknown' ? 'unknown' : 'empty';
|
|
210
|
+
}
|
|
211
|
+
if (!/^[a-z][a-z\d-]*$/.test(tag))
|
|
212
|
+
return 'unknown';
|
|
213
|
+
if (INTERACTIVE_NATIVE.has(tag))
|
|
214
|
+
return forLabel ? 'empty' : 'unknown';
|
|
215
|
+
if (tag === 'svg') {
|
|
216
|
+
const label = staticAttribute(attributeOf(element, 'aria-label'));
|
|
217
|
+
if (label.state === 'static')
|
|
218
|
+
return 'named';
|
|
219
|
+
if (label.state === 'unknown')
|
|
220
|
+
return 'unknown';
|
|
221
|
+
const title = literalTitle(attributeOf(element, 'title'));
|
|
222
|
+
if (title.state === 'static')
|
|
223
|
+
return 'named';
|
|
224
|
+
if (title.state === 'unknown')
|
|
225
|
+
return 'unknown';
|
|
226
|
+
}
|
|
227
|
+
return contentState(element, forLabel);
|
|
228
|
+
}
|
|
229
|
+
/** Determines whether a source element supplies a usable name through ARIA attributes. */
|
|
230
|
+
function ariaNameState(element) {
|
|
231
|
+
const label = staticAttribute(attributeOf(element, 'aria-label'));
|
|
232
|
+
if (label.state !== 'empty')
|
|
233
|
+
return label.state === 'static' ? 'named' : 'unknown';
|
|
234
|
+
return 'empty';
|
|
235
|
+
}
|
|
236
|
+
/** Extracts text from an aria-labelledby target, even when the target itself is hidden. */
|
|
237
|
+
function referencedContentState(element) {
|
|
238
|
+
const tag = tagOf(element);
|
|
239
|
+
if (!/^[a-z][a-z\d-]*$/.test(tag) || tag.includes('-'))
|
|
240
|
+
return 'unknown';
|
|
241
|
+
const label = staticAttribute(attributeOf(element, 'aria-label'));
|
|
242
|
+
if (label.state === 'static')
|
|
243
|
+
return 'named';
|
|
244
|
+
if (label.state === 'unknown')
|
|
245
|
+
return 'unknown';
|
|
246
|
+
if (tag === 'img') {
|
|
247
|
+
const alt = staticAttribute(attributeOf(element, 'alt'));
|
|
248
|
+
return alt.state === 'static' ? 'named' : alt.state === 'unknown' ? 'unknown' : 'empty';
|
|
249
|
+
}
|
|
250
|
+
const labelledBy = staticAttribute(attributeOf(element, 'aria-labelledby'));
|
|
251
|
+
if (labelledBy.state !== 'empty')
|
|
252
|
+
return 'unknown';
|
|
253
|
+
return combine(childrenOf(element).map((child) => childContentState(child, false)));
|
|
254
|
+
}
|
|
255
|
+
/** Builds conservative source evidence for literal JSX ids and their referenced text. */
|
|
256
|
+
function idContentStates(source) {
|
|
257
|
+
const ids = new Map();
|
|
258
|
+
const duplicates = new Set();
|
|
259
|
+
const visit = (node) => {
|
|
260
|
+
if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
|
|
261
|
+
const id = staticAttribute(attributeOf(node, 'id'));
|
|
262
|
+
if (id.state === 'static') {
|
|
263
|
+
if (ids.has(id.value))
|
|
264
|
+
duplicates.add(id.value);
|
|
265
|
+
else
|
|
266
|
+
ids.set(id.value, referencedContentState(node));
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
ts.forEachChild(node, visit);
|
|
270
|
+
};
|
|
271
|
+
visit(source);
|
|
272
|
+
for (const id of duplicates)
|
|
273
|
+
ids.set(id, 'unknown');
|
|
274
|
+
return ids;
|
|
275
|
+
}
|
|
276
|
+
/** Resolves a literal aria-labelledby value only when its source references establish a name. */
|
|
277
|
+
function labelledByState(element, ids) {
|
|
278
|
+
const value = staticAttribute(attributeOf(element, 'aria-labelledby'));
|
|
279
|
+
if (value.state !== 'static')
|
|
280
|
+
return value.state;
|
|
281
|
+
const references = value.value.trim().split(/\s+/).filter(Boolean);
|
|
282
|
+
if (!references.length)
|
|
283
|
+
return 'empty';
|
|
284
|
+
return combine(references.map((id) => ids.get(id) ?? 'empty'));
|
|
285
|
+
}
|
|
286
|
+
/** Finds labels associated by a literal id and records whether each label has meaningful text. */
|
|
287
|
+
function associatedLabels(source) {
|
|
288
|
+
const labels = new Map();
|
|
289
|
+
const visit = (node, hidden) => {
|
|
290
|
+
if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
|
|
291
|
+
const state = hiddenState(node);
|
|
292
|
+
const isHidden = hidden || state === 'named' || state === 'unknown';
|
|
293
|
+
if (!isHidden && tagOf(node) === 'label') {
|
|
294
|
+
const target = staticAttribute(attributeOf(node, 'htmlFor') ?? attributeOf(node, 'for'));
|
|
295
|
+
if (target.state === 'static') {
|
|
296
|
+
const content = contentState(node, true);
|
|
297
|
+
const previous = labels.get(target.value);
|
|
298
|
+
labels.set(target.value, previous === 'named' || content === 'named' ? 'named' : previous === 'unknown' || content === 'unknown' ? 'unknown' : 'empty');
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
const currentHidden = hidden || ((ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) && hiddenState(node) !== 'empty');
|
|
303
|
+
ts.forEachChild(node, (child) => visit(child, currentHidden));
|
|
304
|
+
};
|
|
305
|
+
visit(source, false);
|
|
306
|
+
return labels;
|
|
307
|
+
}
|
|
308
|
+
/** Returns accessible-name evidence for one control, including nested and id-associated labels. */
|
|
309
|
+
function elementNameState(element, kind, labels, nestedLabel) {
|
|
310
|
+
const aria = ariaNameState(element);
|
|
311
|
+
if (aria !== 'empty')
|
|
312
|
+
return { state: aria, iconOnly: false };
|
|
313
|
+
const id = kind.labelable ? staticAttribute(attributeOf(element, 'id')) : { state: 'empty' };
|
|
314
|
+
if (id.state === 'static') {
|
|
315
|
+
const label = labels.get(id.value) ?? 'empty';
|
|
316
|
+
if (label !== 'empty')
|
|
317
|
+
return { state: label, iconOnly: false };
|
|
318
|
+
}
|
|
319
|
+
else if (id.state === 'unknown')
|
|
320
|
+
return { state: 'unknown', iconOnly: false };
|
|
321
|
+
if (kind.labelable && nestedLabel !== 'empty')
|
|
322
|
+
return { state: nestedLabel, iconOnly: false };
|
|
323
|
+
const tag = tagOf(element);
|
|
324
|
+
if (tag === 'input') {
|
|
325
|
+
const type = inputType(element);
|
|
326
|
+
if (type.state === 'unknown')
|
|
327
|
+
return { state: 'unknown', iconOnly: false };
|
|
328
|
+
const inputTypeValue = type.state === 'static' ? type.value.toLowerCase() : 'text';
|
|
329
|
+
if (inputTypeValue === 'image') {
|
|
330
|
+
const alt = staticAttribute(attributeOf(element, 'alt'));
|
|
331
|
+
if (alt.state === 'static')
|
|
332
|
+
return { state: 'named', iconOnly: false };
|
|
333
|
+
if (alt.state === 'unknown')
|
|
334
|
+
return { state: 'unknown', iconOnly: false };
|
|
335
|
+
}
|
|
336
|
+
else if (INPUT_BUTTON_TYPES.has(inputTypeValue)) {
|
|
337
|
+
const value = staticAttribute(attributeOf(element, 'value'));
|
|
338
|
+
if (value.state === 'static')
|
|
339
|
+
return { state: 'named', iconOnly: false };
|
|
340
|
+
if (value.state === 'unknown')
|
|
341
|
+
return { state: 'unknown', iconOnly: false };
|
|
342
|
+
if ((inputTypeValue === 'submit' || inputTypeValue === 'reset') && !attributeOf(element, 'value'))
|
|
343
|
+
return { state: 'named', iconOnly: false };
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
if (tag === 'area') {
|
|
347
|
+
const alt = staticAttribute(attributeOf(element, 'alt'));
|
|
348
|
+
if (alt.state === 'static')
|
|
349
|
+
return { state: 'named', iconOnly: false };
|
|
350
|
+
if (alt.state === 'unknown')
|
|
351
|
+
return { state: 'unknown', iconOnly: false };
|
|
352
|
+
}
|
|
353
|
+
const role = staticAttribute(attributeOf(element, 'role'));
|
|
354
|
+
const nameFromContent = tag !== 'progress' && !(role.state === 'static' && role.value.toLowerCase() === 'progressbar');
|
|
355
|
+
const childState = nameFromContent ? contentState(element) : 'empty';
|
|
356
|
+
if (childState === 'named' || childState === 'unknown')
|
|
357
|
+
return { state: childState, iconOnly: false };
|
|
358
|
+
const spreads = attributesOf(element).properties.some(ts.isJsxSpreadAttribute);
|
|
359
|
+
if (spreads)
|
|
360
|
+
return { state: 'unknown', iconOnly: false };
|
|
361
|
+
const title = literalTitle(attributeOf(element, 'title'));
|
|
362
|
+
if (title.state === 'unknown')
|
|
363
|
+
return { state: 'unknown', title, iconOnly: false };
|
|
364
|
+
const emptyAriaLabel = attributeOf(element, 'aria-label');
|
|
365
|
+
return { state: 'empty', title, emptyAriaLabel, iconOnly: true };
|
|
366
|
+
}
|
|
367
|
+
/** Finds unnamed, non-focusable inline SVG images inside a named native control. */
|
|
368
|
+
function decorativeIcons(element) {
|
|
369
|
+
const icons = [];
|
|
370
|
+
const visit = (node) => {
|
|
371
|
+
if (!ts.isJsxElement(node) && !ts.isJsxSelfClosingElement(node)) {
|
|
372
|
+
ts.forEachChild(node, visit);
|
|
373
|
+
return;
|
|
374
|
+
}
|
|
375
|
+
const tag = tagOf(node);
|
|
376
|
+
if (tag === 'svg') {
|
|
377
|
+
const role = staticAttribute(attributeOf(node, 'role'));
|
|
378
|
+
const ownName = ariaNameState(node);
|
|
379
|
+
const title = literalTitle(attributeOf(node, 'title'));
|
|
380
|
+
const hidden = hiddenState(node);
|
|
381
|
+
const hasUncertainAttributes = attributesOf(node).properties.some(ts.isJsxSpreadAttribute) || ['focusable', 'tabIndex'].some((name) => attributeOf(node, name));
|
|
382
|
+
if (role.state === 'empty' && ownName === 'empty' && title.state === 'empty' && contentState(node) === 'empty' && hidden === 'empty' && !hasUncertainAttributes)
|
|
383
|
+
icons.push(node);
|
|
384
|
+
return;
|
|
385
|
+
}
|
|
386
|
+
if (!/^[a-z][a-z\d-]*$/.test(tag) || hiddenState(node) !== 'empty')
|
|
387
|
+
return;
|
|
388
|
+
if (ts.isJsxElement(node))
|
|
389
|
+
node.children.forEach(visit);
|
|
390
|
+
};
|
|
391
|
+
childrenOf(element).forEach(visit);
|
|
392
|
+
return icons;
|
|
393
|
+
}
|
|
394
|
+
/** Collects findings and candidate source edits for one parsed source file. */
|
|
395
|
+
function inspectFile(cfg, file, parsed) {
|
|
396
|
+
const parseDiagnostics = parsed.parseDiagnostics;
|
|
397
|
+
if (parseDiagnostics?.length)
|
|
398
|
+
return { findings: [], candidates: [], decorativeCandidates: [] };
|
|
399
|
+
const labels = associatedLabels(parsed);
|
|
400
|
+
const ids = idContentStates(parsed);
|
|
401
|
+
const findings = [];
|
|
402
|
+
const candidates = [];
|
|
403
|
+
const decorativeCandidates = [];
|
|
404
|
+
const visit = (node, hidden, nestedLabel) => {
|
|
405
|
+
if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
|
|
406
|
+
const elementHidden = hiddenState(node);
|
|
407
|
+
const currentHidden = hidden || elementHidden !== 'empty';
|
|
408
|
+
const tag = tagOf(node);
|
|
409
|
+
let childLabel = nestedLabel;
|
|
410
|
+
if (tag === 'label')
|
|
411
|
+
childLabel = contentState(node, true);
|
|
412
|
+
const kind = targetKind(node);
|
|
413
|
+
if (!currentHidden && kind) {
|
|
414
|
+
const ariaLabel = ariaNameState(node);
|
|
415
|
+
const ariaName = ariaLabel === 'empty' ? labelledByState(node, ids) : ariaLabel;
|
|
416
|
+
const name = ariaName === 'empty' ? elementNameState(node, kind, labels, nestedLabel) : { state: ariaName, iconOnly: false };
|
|
417
|
+
if (name.state === 'empty') {
|
|
418
|
+
const titleCanFix = name.title?.state === 'static' && name.iconOnly;
|
|
419
|
+
const position = parsed.getLineAndCharacterOfPosition(node.getStart(parsed));
|
|
420
|
+
const message = titleCanFix
|
|
421
|
+
? `${kind.element} has no accessible name; copy its non-empty title into aria-label.`
|
|
422
|
+
: `${kind.element} has no accessible name; add static text, an ARIA name, or an associated label.`;
|
|
423
|
+
findings.push({ file: displayPath(cfg, file), line: position.line + 1, column: position.character + 1, element: kind.element, message, fixable: titleCanFix });
|
|
424
|
+
if (name.title?.state === 'static') {
|
|
425
|
+
const opening = ts.isJsxElement(node) ? node.openingElement : node;
|
|
426
|
+
candidates.push({ parsed, opening, title: name.title, emptyAriaLabel: name.emptyAriaLabel });
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
else if (name.state === 'named') {
|
|
430
|
+
for (const icon of decorativeIcons(node)) {
|
|
431
|
+
const opening = ts.isJsxElement(icon) ? icon.openingElement : icon;
|
|
432
|
+
const position = parsed.getLineAndCharacterOfPosition(icon.getStart(parsed));
|
|
433
|
+
findings.push({
|
|
434
|
+
file: displayPath(cfg, file),
|
|
435
|
+
line: position.line + 1,
|
|
436
|
+
column: position.character + 1,
|
|
437
|
+
element: '<svg>',
|
|
438
|
+
message: 'Decorative SVG inside an already named control is exposed to assistive technology; add aria-hidden="true".',
|
|
439
|
+
fixable: true,
|
|
440
|
+
});
|
|
441
|
+
decorativeCandidates.push({ parsed, opening });
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
ts.forEachChild(node, (child) => visit(child, currentHidden, childLabel));
|
|
446
|
+
return;
|
|
447
|
+
}
|
|
448
|
+
ts.forEachChild(node, (child) => visit(child, hidden, nestedLabel));
|
|
449
|
+
};
|
|
450
|
+
visit(parsed, false, 'empty');
|
|
451
|
+
return { findings, candidates, decorativeCandidates };
|
|
452
|
+
}
|
|
453
|
+
/** Returns configured files that contain JSX syntax supported by this check. */
|
|
454
|
+
function sourceFiles(cfg, analysis) {
|
|
455
|
+
return (analysis?.files ?? srcFiles(cfg)).filter((file) => JSX_EXTS.test(file));
|
|
456
|
+
}
|
|
457
|
+
/** Loads the source and parsed AST from the shared analysis cache when available. */
|
|
458
|
+
function sourceFor(file, analysis) {
|
|
459
|
+
const text = analysis?.texts.get(file) ?? readFileSync(file, 'utf8');
|
|
460
|
+
const parsed = analysis?.sources.get(file) ?? ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(file));
|
|
461
|
+
return { text, parsed };
|
|
462
|
+
}
|
|
463
|
+
/*//////////////////////////////////////////////////
|
|
464
|
+
PUBLIC API
|
|
465
|
+
//////////////////////////////////////////////////*/
|
|
466
|
+
/**
|
|
467
|
+
* Finds JSX native controls and elements with explicit interactive roles that have no known accessible name.
|
|
468
|
+
* Dynamic child output, dynamic ARIA values, hidden controls, and components without explicit roles are skipped.
|
|
469
|
+
*
|
|
470
|
+
* @param cfg Quality configuration selecting source roots and extensions.
|
|
471
|
+
* @param analysis Optional shared parse context for the current quality run.
|
|
472
|
+
*
|
|
473
|
+
* @return Accessible-name findings with a flag for title-based fixes that can be applied safely.
|
|
474
|
+
*/
|
|
475
|
+
export function accessibilityFindings(cfg, analysis) {
|
|
476
|
+
return sourceFiles(cfg, analysis).flatMap((file) => {
|
|
477
|
+
const { parsed } = sourceFor(file, analysis);
|
|
478
|
+
return inspectFile(cfg, file, parsed).findings;
|
|
479
|
+
});
|
|
480
|
+
}
|
|
481
|
+
/**
|
|
482
|
+
* Adds aria-label only when a non-empty literal title is the sole source-evident name for an icon-only control.
|
|
483
|
+
* Existing visible text, labels, ARIA names, and uncertain component output are left unchanged.
|
|
484
|
+
*
|
|
485
|
+
* @param cfg Quality configuration selecting source roots and extensions.
|
|
486
|
+
*
|
|
487
|
+
* @return Result containing the number of aria-label attributes added or repaired.
|
|
488
|
+
*/
|
|
489
|
+
export function fixAccessibleNames(cfg) {
|
|
490
|
+
let fixed = 0;
|
|
491
|
+
for (const file of sourceFiles(cfg)) {
|
|
492
|
+
const { text, parsed } = sourceFor(file);
|
|
493
|
+
const { candidates, decorativeCandidates } = inspectFile(cfg, file, parsed);
|
|
494
|
+
if (!candidates.length && !decorativeCandidates.length)
|
|
495
|
+
continue;
|
|
496
|
+
const edits = candidates.map((candidate) => {
|
|
497
|
+
const text = `aria-label=${candidate.title.source}`;
|
|
498
|
+
if (candidate.emptyAriaLabel)
|
|
499
|
+
return { start: candidate.emptyAriaLabel.getStart(candidate.parsed), end: candidate.emptyAriaLabel.end, text };
|
|
500
|
+
const attributes = candidate.opening.attributes;
|
|
501
|
+
const insertion = attributes.properties.length ? attributes.properties.at(-1).end : candidate.opening.tagName.end;
|
|
502
|
+
return { start: insertion, end: insertion, text: ` ${text}` };
|
|
503
|
+
});
|
|
504
|
+
for (const candidate of decorativeCandidates) {
|
|
505
|
+
const attributes = candidate.opening.attributes;
|
|
506
|
+
const insertion = attributes.properties.length ? attributes.properties.at(-1).end : candidate.opening.tagName.end;
|
|
507
|
+
edits.push({ start: insertion, end: insertion, text: ' aria-hidden="true"' });
|
|
508
|
+
}
|
|
509
|
+
let updated = text;
|
|
510
|
+
for (const edit of edits.sort((a, b) => b.start - a.start))
|
|
511
|
+
updated = `${updated.slice(0, edit.start)}${edit.text}${updated.slice(edit.end)}`;
|
|
512
|
+
const diagnostics = ts.transpileModule(updated, {
|
|
513
|
+
fileName: file,
|
|
514
|
+
reportDiagnostics: true,
|
|
515
|
+
compilerOptions: { allowJs: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.ESNext },
|
|
516
|
+
}).diagnostics;
|
|
517
|
+
if (diagnostics?.length)
|
|
518
|
+
continue;
|
|
519
|
+
writeFileSync(file, updated);
|
|
520
|
+
fixed += edits.length;
|
|
521
|
+
}
|
|
522
|
+
return { fixed };
|
|
523
|
+
}
|
|
524
|
+
//# sourceMappingURL=accessibility.js.map
|