@ngbracket/a11y-devtools 0.1.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duncan Faulkner and Lara Sanz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,34 @@
 # @ngbracket/a11y-devtools
 
 Dev-only, in-app accessibility auditing for Angular that maps each axe violation
-back to **the component that rendered it** — the attribution React overlay tools
-(`@axe-core/react`, `axe-mode`, TanStack a11y) structurally can't do.
+back to **the component that rendered it** — so you get
+`♿ UserCardComponent — 2 issue(s)`, not a wall of CSS selectors.
 
-Report `♿ UserCardComponent — 2 issue(s)` instead of a wall of CSS selectors.
+The React axe tools in this space — [`@axe-core/react`](https://www.npmjs.com/package/@axe-core/react),
+[`axe-mode`](https://github.com/raunofreiberg/axe-mode), the
+[TanStack Devtools a11y plugin](https://tanstack.com/devtools/latest/docs/plugins/a11y)
+— report the DOM node (selector, HTML, rule id) and highlight it, but stop there:
+none tie a violation to the component that rendered it. This does, through
+Angular's **documented** dev debug API (`window.ng`) rather than private framework
+internals.
 
-Part of the `@ngbracket` Angular tooling family. See
-[`docs/findings.md`](docs/findings.md) for the research and scope.
+Part of the `@ngbracket` Angular tooling family.
 
 ## Status
 
-Ships attribution + axe scan + grouped console reporter + the dev-only provider
-+ the visual in-app overlay (severity-coloured highlights, click-to-scroll).
+Ships attribution — component **and** directive-level — + axe scan + grouped
+console reporter (with a summary line) + the dev-only provider + the visual in-app
+overlay (severity-coloured highlights, click-to-scroll).
 
 ## How the attribution works
 
 Angular publishes debug helpers on the `window.ng` global in dev mode.
 `getOwningComponent(node)` returns the component whose view contains a DOM node,
-so any axe-flagged element resolves to its owning component. These helpers exist
-**only in dev builds** — which is exactly right: the tool is dev-only, and the
-global's absence in prod is the signal to no-op.
+so any axe-flagged element resolves to its owning component; `getDirectives(node)`
+adds the directives applied to that node — including those pulled in via
+`hostDirectives` — which are the runtime cases a static ESLint pass can't see.
+These helpers exist **only in dev builds** — which is exactly right: the tool is
+dev-only, and the global's absence in prod is the signal to no-op.
 
 ## Install
 
@@ -56,6 +64,20 @@ provideA11yDevtools({
 });
 ```
 
+Findings are grouped by owning component, led by a summary line, and each node's
+directives are shown inline:
+
+```text
+♿ a11y-devtools: 2 issue(s) across 1 component(s)
+♿ UserCardComponent — 2 issue(s)
+    critical · image-alt: Images must have alternative text [via TooltipDirective]
+      img
+      https://dequeuniversity.com/rules/axe/4.13/image-alt
+    serious · color-contrast: Elements must meet minimum contrast
+      button.save
+      https://dequeuniversity.com/rules/axe/4.13/color-contrast
+```
+
 You can also scan on demand:
 
 ```ts
@@ -88,9 +110,7 @@ npm run build   # tsc -> dist/ (ESM + .d.ts)
 
 ## Roadmap
 
-- **`host` / `hostDirectives` a11y** via `getDirectives(el)` — the runtime cases
-  the item-2 lint plugin can't see statically.
-- Per-component filtering and a violation count badge.
+- Per-component filtering and a violation-count badge.
 
-Done: attribution · axe scan · grouped console reporter · dev-only provider ·
-in-app overlay · CI prod-weight guard.
+Done: component attribution · directive / `hostDirectives` attribution · axe scan ·
+grouped console reporter · dev-only provider · in-app overlay · CI prod-weight guard.

package/dist/attribution.d.ts

@@ -12,6 +12,13 @@
 export interface NgDebugGlobal {
     getComponent(element: Element): unknown;
     getOwningComponent(element: Element | object): unknown;
+    getDirectives(element: Element | object): unknown[];
 }
 export declare function ngDebug(): NgDebugGlobal | undefined;
 export declare function resolveOwningComponentName(node: Element): string | null;
+/**
+ * Names of the directives applied directly to `node`, including those attached
+ * via `hostDirectives` — the runtime-only a11y cases the static lint plugin
+ * can't see. Empty when the debug global is absent or the node has none.
+ */
+export declare function resolveDirectiveNames(node: Element): string[];

package/dist/attribution.js

@@ -1,10 +1,19 @@
 export function ngDebug() {
     return globalThis.ng;
 }
+/**
+ * Angular's dev output can emit class names with a leading underscore
+ * (e.g. `_Login` for `Login`); strip it so attribution shows the authored name.
+ */
+function cleanName(name) {
+    if (!name)
+        return null;
+    return name.replace(/^_+/, '') || null;
+}
 function nameOf(instance) {
     if (!instance || typeof instance !== 'object')
         return null;
-    return instance.constructor.name ?? null;
+    return cleanName(instance.constructor.name ?? null);
 }
 export function resolveOwningComponentName(node) {
     const ng = ngDebug();
@@ -13,3 +22,27 @@ export function resolveOwningComponentName(node) {
     const component = ng.getComponent(node) ?? ng.getOwningComponent(node);
     return nameOf(component);
 }
+/**
+ * Names of the directives applied directly to `node`, including those attached
+ * via `hostDirectives` — the runtime-only a11y cases the static lint plugin
+ * can't see. Empty when the debug global is absent or the node has none.
+ */
+export function resolveDirectiveNames(node) {
+    const ng = ngDebug();
+    if (!ng?.getDirectives)
+        return [];
+    let directives;
+    try {
+        directives = ng.getDirectives(node) ?? [];
+    }
+    catch {
+        return []; // node isn't part of a live view
+    }
+    const names = [];
+    for (const directive of directives) {
+        const name = nameOf(directive);
+        if (name)
+            names.push(name);
+    }
+    return names;
+}

package/dist/report.js

@@ -17,10 +17,12 @@ export function logFindings(findings, logger = console) {
         else
             byComponent.set(key, [finding]);
     }
+    logger.info(`♿ a11y-devtools: ${findings.length} issue(s) across ${byComponent.size} component(s)`);
     for (const [component, items] of byComponent) {
         logger.groupCollapsed(`♿ ${component} — ${items.length} issue(s)`);
         for (const finding of items) {
-            logger.warn(`${finding.impact ?? 'n/a'} · ${finding.id}: ${finding.help}`, `\n  ${finding.target}\n  ${finding.helpUrl}`);
+            const via = finding.directives.length ? ` [via ${finding.directives.join(', ')}]` : '';
+            logger.warn(`${finding.impact ?? 'n/a'} · ${finding.id}: ${finding.help}${via}`, `\n  ${finding.target}\n  ${finding.helpUrl}`);
         }
         logger.groupEnd();
     }

package/dist/scan.d.ts

@@ -9,6 +9,8 @@ export interface A11yFinding {
     helpUrl: string;
     /** Owning component name, or null when attribution isn't available (prod). */
     component: string | null;
+    /** Directives on the flagged node (incl. hostDirectives); [] when none/unavailable. */
+    directives: string[];
     /** CSS selector axe reported for the node. */
     target: string;
     html: string;

package/dist/scan.js

@@ -1,4 +1,4 @@
-import { resolveOwningComponentName } from './attribution.js';
+import { resolveDirectiveNames, resolveOwningComponentName } from './attribution.js';
 import { OVERLAY_EXCLUDE_SELECTOR } from './overlay.js';
 // axe-core is a singleton and throws if a run starts while another is in flight.
 // Chain runs so overlapping callers (e.g. rapid rescans) serialize safely.
@@ -37,6 +37,7 @@ async function runAxeOnce(root, options) {
                 help: violation.help,
                 helpUrl: violation.helpUrl,
                 component: element ? resolveOwningComponentName(element) : null,
+                directives: element ? resolveDirectiveNames(element) : [],
                 target,
                 html: node.html,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngbracket/a11y-devtools",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Dev-only in-app accessibility auditing for Angular that maps each axe violation back to the component that rendered it — the attribution React overlay tools can't do.",
   "license": "MIT",
   "author": "Duncan Faulkner",